digital_io.h

// Copyright 2021 The Pigweed Authors
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy of
// the License at
//
//     https://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
#pragma once
 
#include "pw_assert/check.h"
#include "pw_digital_io/internal/conversions.h"
#include "pw_function/function.h"
#include "pw_result/result.h"
#include "pw_status/status.h"
#include "pw_status/try.h"
 
namespace pw::digital_io {
 
// The logical state of a digital line.
enum class State : bool {
  kActive = true,
  kInactive = false,
};
 
// The triggering configuration for an interrupt handler.
enum class InterruptTrigger : int {
  // Trigger on transition from kInactive to kActive.
  kActivatingEdge,
  // Trigger on transition from kActive to kInactive.
  kDeactivatingEdge,
  // Trigger on any state transition between kActive and kInactive.
  kBothEdges,
};
 
// Interrupt handling function. The argument contains the latest known state of
// the line. It is backend-specific if, when, and how this state is updated.
using InterruptHandler = ::pw::Function<void(State sampled_state)>;
 
class DigitalIoOptional {
 public:
  virtual ~DigitalIoOptional() = default;
 
  constexpr bool provides_input() const { return config_.input; }
  constexpr bool provides_output() const { return config_.output; }
  constexpr bool provides_interrupt() const { return config_.interrupt; }
 
  Result<State> GetState() { return DoGetState(); }
 
  Status SetState(State state) { return DoSetState(state); }
 
  Result<bool> IsStateActive() {
    PW_TRY_ASSIGN(const State state, GetState());
    return state == State::kActive;
  }
 
  Status SetStateActive() { return SetState(State::kActive); }
 
  Status SetStateInactive() { return SetState(State::kInactive); }
 
  Status SetInterruptHandler(InterruptTrigger trigger,
                             InterruptHandler&& handler) {
    if (handler == nullptr) {
      return Status::InvalidArgument();
    }
    return DoSetInterruptHandler(trigger, std::move(handler));
  }
 
  Status ClearInterruptHandler() {
    PW_TRY(DisableInterruptHandler());
    return DoSetInterruptHandler(InterruptTrigger::kActivatingEdge, nullptr);
  }
 
  Status EnableInterruptHandler() { return DoEnableInterruptHandler(true); }
 
  Status DisableInterruptHandler() { return DoEnableInterruptHandler(false); }
 
  Status Enable() { return DoEnable(true); }
 
  Status Disable() {
    if (provides_interrupt()) {
      PW_TRY(DisableInterruptHandler());
    }
    return DoEnable(false);
  }
 
 private:
  friend class DigitalInterrupt;
  friend class DigitalIn;
  friend class DigitalInInterrupt;
  friend class DigitalOut;
  friend class DigitalOutInterrupt;
  friend class DigitalInOut;
  friend class DigitalInOutInterrupt;
 
  // Private constructor so that only friends can extend us.
  constexpr DigitalIoOptional(internal::Provides config) : config_(config) {}
 
  virtual Status DoEnable(bool enable) = 0;
 
  virtual Result<State> DoGetState() = 0;
 
  virtual Status DoSetState(State level) = 0;
 
  virtual Status DoSetInterruptHandler(InterruptTrigger trigger,
                                       InterruptHandler&& handler) = 0;
 
  virtual Status DoEnableInterruptHandler(bool enable) = 0;
 
  // The configuration of this line.
  const internal::Provides config_;
};
 
// A digital I/O line that supports only interrupts.
//
// The input and output methods are hidden and must not be called.
//
// Use this class in APIs when only interrupt functionality is required.
// Extend this class to implement a line that only supports interrupts.
//
class DigitalInterrupt
    : public DigitalIoOptional,
      public internal::Conversions<DigitalInterrupt, DigitalIoOptional> {
 public:
  // Available functionality
  using DigitalIoOptional::ClearInterruptHandler;
  using DigitalIoOptional::DisableInterruptHandler;
  using DigitalIoOptional::EnableInterruptHandler;
  using DigitalIoOptional::SetInterruptHandler;
 
 protected:
  constexpr DigitalInterrupt()
      : DigitalIoOptional(internal::AlwaysProvidedBy<DigitalInterrupt>()) {}
 
 private:
  // Unavailable functionality
  using DigitalIoOptional::provides_input;
  using DigitalIoOptional::provides_interrupt;
  using DigitalIoOptional::provides_output;
 
  using DigitalIoOptional::GetState;
  using DigitalIoOptional::IsStateActive;
  using DigitalIoOptional::SetState;
  using DigitalIoOptional::SetStateActive;
  using DigitalIoOptional::SetStateInactive;
 
  // These overrides invoke PW_CRASH.
  Status DoSetState(State) final;
  Result<State> DoGetState() final;
};
 
// A digital I/O line that supports only input (getting state).
//
// The output and interrupt methods are hidden and must not be called.
//
// Use this class in APIs when only input functionality is required.
// Extend this class to implement a line that only supports getting state.
//
class DigitalIn : public DigitalIoOptional,
                  public internal::Conversions<DigitalIn, DigitalIoOptional> {
 public:
  // Available functionality
  using DigitalIoOptional::GetState;
  using DigitalIoOptional::IsStateActive;
 
 protected:
  constexpr DigitalIn()
      : DigitalIoOptional(internal::AlwaysProvidedBy<DigitalIn>()) {}
 
 private:
  // Unavailable functionality
  using DigitalIoOptional::provides_input;
  using DigitalIoOptional::provides_interrupt;
  using DigitalIoOptional::provides_output;
 
  using DigitalIoOptional::ClearInterruptHandler;
  using DigitalIoOptional::DisableInterruptHandler;
  using DigitalIoOptional::EnableInterruptHandler;
  using DigitalIoOptional::SetInterruptHandler;
  using DigitalIoOptional::SetState;
  using DigitalIoOptional::SetStateActive;
  using DigitalIoOptional::SetStateInactive;
 
  // These overrides invoke PW_CRASH.
  Status DoSetState(State) final;
  Status DoSetInterruptHandler(InterruptTrigger, InterruptHandler&&) final;
  Status DoEnableInterruptHandler(bool) final;
};
 
// An input line that supports interrupts.
//
// The output methods are hidden and must not be called.
//
// Use in APIs when input and interrupt functionality is required.
//
// Extend this class to implement a line that supports input (getting state) and
// listening for interrupts at the same time.
//
class DigitalInInterrupt
    : public DigitalIoOptional,
      public internal::Conversions<DigitalInInterrupt, DigitalIoOptional> {
 public:
  // Available functionality
  using DigitalIoOptional::ClearInterruptHandler;
  using DigitalIoOptional::DisableInterruptHandler;
  using DigitalIoOptional::EnableInterruptHandler;
  using DigitalIoOptional::GetState;
  using DigitalIoOptional::IsStateActive;
  using DigitalIoOptional::SetInterruptHandler;
 
 protected:
  constexpr DigitalInInterrupt()
      : DigitalIoOptional(internal::AlwaysProvidedBy<DigitalInInterrupt>()) {}
 
 private:
  // Unavailable functionality
  using DigitalIoOptional::provides_input;
  using DigitalIoOptional::provides_interrupt;
  using DigitalIoOptional::provides_output;
 
  using DigitalIoOptional::SetState;
  using DigitalIoOptional::SetStateActive;
  using DigitalIoOptional::SetStateInactive;
 
  // These overrides invoke PW_CRASH.
  Status DoSetState(State) final;
};
 
// A digital I/O line that supports only output (setting state).
//
// Input and interrupt functions are hidden and must not be called.
//
// Use in APIs when only output functionality is required.
// Extend this class to implement a line that supports output only.
//
class DigitalOut : public DigitalIoOptional,
                   public internal::Conversions<DigitalOut, DigitalIoOptional> {
 public:
  // Available functionality
  using DigitalIoOptional::SetState;
  using DigitalIoOptional::SetStateActive;
  using DigitalIoOptional::SetStateInactive;
 
 protected:
  constexpr DigitalOut()
      : DigitalIoOptional(internal::AlwaysProvidedBy<DigitalOut>()) {}
 
 private:
  // Unavailable functionality
  using DigitalIoOptional::provides_input;
  using DigitalIoOptional::provides_interrupt;
  using DigitalIoOptional::provides_output;
 
  using DigitalIoOptional::ClearInterruptHandler;
  using DigitalIoOptional::DisableInterruptHandler;
  using DigitalIoOptional::EnableInterruptHandler;
  using DigitalIoOptional::GetState;
  using DigitalIoOptional::IsStateActive;
  using DigitalIoOptional::SetInterruptHandler;
 
  // These overrides invoke PW_CRASH.
  Result<State> DoGetState() final;
  Status DoSetInterruptHandler(InterruptTrigger, InterruptHandler&&) final;
  Status DoEnableInterruptHandler(bool) final;
};
 
// A digital I/O line that supports output and interrupts.
//
// Input methods are hidden and must not be called.
//
// Use in APIs when output and interrupt functionality is required. For
// example, to represent a two-way signalling line.
//
// Extend this class to implement a line that supports both output and
// listening for interrupts at the same time.
//
class DigitalOutInterrupt
    : public DigitalIoOptional,
      public internal::Conversions<DigitalOutInterrupt, DigitalIoOptional> {
 public:
  // Available functionality
  using DigitalIoOptional::ClearInterruptHandler;
  using DigitalIoOptional::DisableInterruptHandler;
  using DigitalIoOptional::EnableInterruptHandler;
  using DigitalIoOptional::SetInterruptHandler;
  using DigitalIoOptional::SetState;
  using DigitalIoOptional::SetStateActive;
  using DigitalIoOptional::SetStateInactive;
 
 protected:
  constexpr DigitalOutInterrupt()
      : DigitalIoOptional(internal::AlwaysProvidedBy<DigitalOutInterrupt>()) {}
 
 private:
  // Unavailable functionality
  using DigitalIoOptional::provides_input;
  using DigitalIoOptional::provides_interrupt;
  using DigitalIoOptional::provides_output;
 
  using DigitalIoOptional::GetState;
  using DigitalIoOptional::IsStateActive;
 
  // These overrides invoke PW_CRASH.
  Result<State> DoGetState() final;
};
 
// A digital I/O line that supports both input and output.
//
// Use in APIs when both input and output functionality is required. For
// example, to represent a line which is shared by multiple controllers.
//
// Extend this class to implement a line that supports both input and output at
// the same time.
//
class DigitalInOut
    : public DigitalIoOptional,
      public internal::Conversions<DigitalInOut, DigitalIoOptional> {
 public:
  // Available functionality
  using DigitalIoOptional::GetState;
  using DigitalIoOptional::IsStateActive;
  using DigitalIoOptional::SetState;
  using DigitalIoOptional::SetStateActive;
  using DigitalIoOptional::SetStateInactive;
 
 protected:
  constexpr DigitalInOut()
      : DigitalIoOptional(internal::AlwaysProvidedBy<DigitalInOut>()) {}
 
 private:
  // Unavailable functionality
  using DigitalIoOptional::provides_input;
  using DigitalIoOptional::provides_interrupt;
  using DigitalIoOptional::provides_output;
 
  using DigitalIoOptional::ClearInterruptHandler;
  using DigitalIoOptional::DisableInterruptHandler;
  using DigitalIoOptional::EnableInterruptHandler;
  using DigitalIoOptional::SetInterruptHandler;
 
  // These overrides invoke PW_CRASH.
  Status DoSetInterruptHandler(InterruptTrigger, InterruptHandler&&) final;
  Status DoEnableInterruptHandler(bool) final;
};
 
// A line that supports input, output, and interrupts.
//
// Use in APIs when input, output, and interrupts are required. For example to
// represent a two-way shared line with state transition notifications.
//
// Extend this class to implement a line that supports all the functionality at
// the same time.
//
class DigitalInOutInterrupt
    : public DigitalIoOptional,
      public internal::Conversions<DigitalInOutInterrupt, DigitalIoOptional> {
 public:
  // Available functionality
  using DigitalIoOptional::ClearInterruptHandler;
  using DigitalIoOptional::DisableInterruptHandler;
  using DigitalIoOptional::EnableInterruptHandler;
  using DigitalIoOptional::GetState;
  using DigitalIoOptional::IsStateActive;
  using DigitalIoOptional::SetInterruptHandler;
  using DigitalIoOptional::SetState;
  using DigitalIoOptional::SetStateActive;
  using DigitalIoOptional::SetStateInactive;
 
 protected:
  constexpr DigitalInOutInterrupt()
      : DigitalIoOptional(internal::AlwaysProvidedBy<DigitalInOutInterrupt>()) {
  }
 
 private:
  // Unavailable functionality
  using DigitalIoOptional::provides_input;
  using DigitalIoOptional::provides_interrupt;
  using DigitalIoOptional::provides_output;
};
 
}  // namespace pw::digital_io