pw_digital_io/public/pw_digital_io/digital_io.h - pigweed/pigweed - Git at Google

 // 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)>;

 // A digital I/O line that may support input, output, and interrupts, but makes
 // no guarantees about whether any operations are supported. You must check the
 // various provides_* flags before calling optional methods. Unsupported methods
 // invoke PW_CRASH.
 //
 // All methods are potentially blocking. Unless otherwise specified, access from
 // multiple threads to a single line must be externally synchronized - for
 // example using pw::Borrowable. Unless otherwise specified, none of the methods
 // are safe to call from an interrupt handler. Therefore, this abstraction may
 // not be suitable for bitbanging and other low-level uses of GPIO.
 //
 // Note that the initial state of a line is not guaranteed to be consistent with
 // either the "enabled" or "disabled" state. Users of the API who need to ensure
 // the line is disabled (ex. output not driving the line) should call Disable.
 //
 // This class should almost never be used in APIs directly. Instead, use one of
 // the derived classes that explicitly supports the functionality that your
 // API needs.
 //
 // This class cannot be extended directly. Instead, extend one of the
 // derived classes that explicitly support the functionality that you want to
 // implement.
 //
 class DigitalIoOptional {
  public:
   virtual ~DigitalIoOptional() = default;

   // True if input (getting state) is supported.
   constexpr bool provides_input() const { return config_.input; }
   // True if output (setting state) is supported.
   constexpr bool provides_output() const { return config_.output; }
   // True if interrupt handlers can be registered.
   constexpr bool provides_interrupt() const { return config_.interrupt; }

   // Get the state of the line.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Returns:
   //
   //   OK - an active or inactive state.
   //   FAILED_PRECONDITION - The line has not been enabled.
   //   Other status codes as defined by the backend.
   //
   Result<State> GetState() { return DoGetState(); }

   // Set the state of the line.
   //
   // Callers are responsible to wait for the voltage level to settle after this
   // call returns.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Returns:
   //
   //   OK - the state has been set.
   //   FAILED_PRECONDITION - The line has not been enabled.
   //   Other status codes as defined by the backend.
   //
   Status SetState(State state) { return DoSetState(state); }

   // Check if the line is in the active state.
   //
   // The line is in the active state when GetState() returns State::kActive.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Returns:
   //
   //   OK - true if the line is in the active state, otherwise false.
   //   FAILED_PRECONDITION - The line has not been enabled.
   //   Other status codes as defined by the backend.
   //
   Result<bool> IsStateActive() {
     PW_TRY_ASSIGN(const State state, GetState());
     return state == State::kActive;
   }

   // Sets the line to the active state. Equivalent to SetState(State::kActive).
   //
   // Callers are responsible to wait for the voltage level to settle after this
   // call returns.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Returns:
   //
   //   OK - the state has been set.
   //   FAILED_PRECONDITION - The line has not been enabled.
   //   Other status codes as defined by the backend.
   //
   Status SetStateActive() { return SetState(State::kActive); }

   // Sets the line to the inactive state. Equivalent to
   // SetState(State::kInactive).
   //
   // Callers are responsible to wait for the voltage level to settle after this
   // call returns.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Returns:
   //
   //   OK - the state has been set.
   //   FAILED_PRECONDITION - The line has not been enabled.
   //   Other status codes as defined by the backend.
   //
   Status SetStateInactive() { return SetState(State::kInactive); }

   // Set an interrupt handler to execute when an interrupt is triggered, and
   // Configure the condition for triggering the interrupt.
   //
   // The handler is executed in a backend-specific context - this may be a
   // system interrupt handler or a shared notification thread. Do not do any
   // blocking or expensive work in the handler. The only universally safe
   // operations are the IRQ-safe functions on pw_sync primitives.
   //
   // In particular, it is NOT safe to get the state of a DigitalIo line - either
   // from this line or any other DigitalIoOptional instance - inside the
   // handler.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Precondition: no handler is currently set.
   //
   // Returns:
   //   OK - the interrupt handler was configured.
   //   INVALID_ARGUMENT - handler is empty.
   //   Other status codes as defined by the backend.
   //
   Status SetInterruptHandler(InterruptTrigger trigger,
                              InterruptHandler&& handler) {
     if (handler == nullptr) {
       return Status::InvalidArgument();
     }
     return DoSetInterruptHandler(trigger, std::move(handler));
   }

   // Clear the interrupt handler and disable interrupts if enabled.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Returns:
   //   OK - the itnerrupt handler was cleared.
   //   Other status codes as defined by the backend.
   //
   Status ClearInterruptHandler() {
     return DoSetInterruptHandler(InterruptTrigger::kActivatingEdge, nullptr);
   }

   // Enable interrupts which will trigger the interrupt handler.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Precondition: a handler has been set using SetInterruptHandler.
   //
   // Returns:
   //   OK - the interrupt handler was configured.
   //   FAILED_PRECONDITION - The line has not been enabled.
   //   Other status codes as defined by the backend.
   //
   Status EnableInterruptHandler() { return DoEnableInterruptHandler(true); }

   // Disable the interrupt handler. This is a no-op if interrupts are disabled.
   //
   // This method can be called inside the interrupt handler for this line
   // without any external synchronization. However, the exact behavior is
   // backend-specific. There may be queued events that will trigger the handler
   // again after this call returns.
   //
   // Returns:
   //   OK - the interrupt handler was configured.
   //   Other status codes as defined by the backend.
   //
   Status DisableInterruptHandler() { return DoEnableInterruptHandler(false); }

   // Enable the line to initialize it into the default state as determined by
   // the backend. This may enable pull-up/down resistors, drive the line high or
   // low, etc. The line must be enabled before getting/setting the state
   // or enabling interrupts.
   //
   // Callers are responsible to wait for the voltage level to settle after this
   // call returns.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Returns:
   //   OK - the line is enabled and ready for use.
   //   Other status codes as defined by the backend.
   //
   Status Enable() { return DoEnable(true); }

   // Disable the line to power down any pull-up/down resistors and disconnect
   // from any voltage sources. This is usually done to save power. Interrupt
   // handlers are automatically disabled.
   //
   // This method is not thread-safe and cannot be used in interrupt handlers.
   //
   // Returns:
   //   OK - the line is disabled.
   //   Other status codes as defined by the backend.
   //
   Status Disable() { 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) {}

   // Implemented by derived classes to provide different functionality.
   // See the documentation of the public functions for requirements.
   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
	// 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)>;

	// A digital I/O line that may support input, output, and interrupts, but makes
	// no guarantees about whether any operations are supported. You must check the
	// various provides_* flags before calling optional methods. Unsupported methods
	// invoke PW_CRASH.
	//
	// All methods are potentially blocking. Unless otherwise specified, access from
	// multiple threads to a single line must be externally synchronized - for
	// example using pw::Borrowable. Unless otherwise specified, none of the methods
	// are safe to call from an interrupt handler. Therefore, this abstraction may
	// not be suitable for bitbanging and other low-level uses of GPIO.
	//
	// Note that the initial state of a line is not guaranteed to be consistent with
	// either the "enabled" or "disabled" state. Users of the API who need to ensure
	// the line is disabled (ex. output not driving the line) should call Disable.
	//
	// This class should almost never be used in APIs directly. Instead, use one of
	// the derived classes that explicitly supports the functionality that your
	// API needs.
	//
	// This class cannot be extended directly. Instead, extend one of the
	// derived classes that explicitly support the functionality that you want to
	// implement.
	//
	class DigitalIoOptional {
	public:
	virtual ~DigitalIoOptional() = default;

	// True if input (getting state) is supported.
	constexpr bool provides_input() const { return config_.input; }
	// True if output (setting state) is supported.
	constexpr bool provides_output() const { return config_.output; }
	// True if interrupt handlers can be registered.
	constexpr bool provides_interrupt() const { return config_.interrupt; }

	// Get the state of the line.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Returns:
	//
	// OK - an active or inactive state.
	// FAILED_PRECONDITION - The line has not been enabled.
	// Other status codes as defined by the backend.
	//
	Result<State> GetState() { return DoGetState(); }

	// Set the state of the line.
	//
	// Callers are responsible to wait for the voltage level to settle after this
	// call returns.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Returns:
	//
	// OK - the state has been set.
	// FAILED_PRECONDITION - The line has not been enabled.
	// Other status codes as defined by the backend.
	//
	Status SetState(State state) { return DoSetState(state); }

	// Check if the line is in the active state.
	//
	// The line is in the active state when GetState() returns State::kActive.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Returns:
	//
	// OK - true if the line is in the active state, otherwise false.
	// FAILED_PRECONDITION - The line has not been enabled.
	// Other status codes as defined by the backend.
	//
	Result<bool> IsStateActive() {
	PW_TRY_ASSIGN(const State state, GetState());
	return state == State::kActive;
	}

	// Sets the line to the active state. Equivalent to SetState(State::kActive).
	//
	// Callers are responsible to wait for the voltage level to settle after this
	// call returns.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Returns:
	//
	// OK - the state has been set.
	// FAILED_PRECONDITION - The line has not been enabled.
	// Other status codes as defined by the backend.
	//
	Status SetStateActive() { return SetState(State::kActive); }

	// Sets the line to the inactive state. Equivalent to
	// SetState(State::kInactive).
	//
	// Callers are responsible to wait for the voltage level to settle after this
	// call returns.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Returns:
	//
	// OK - the state has been set.
	// FAILED_PRECONDITION - The line has not been enabled.
	// Other status codes as defined by the backend.
	//
	Status SetStateInactive() { return SetState(State::kInactive); }

	// Set an interrupt handler to execute when an interrupt is triggered, and
	// Configure the condition for triggering the interrupt.
	//
	// The handler is executed in a backend-specific context - this may be a
	// system interrupt handler or a shared notification thread. Do not do any
	// blocking or expensive work in the handler. The only universally safe
	// operations are the IRQ-safe functions on pw_sync primitives.
	//
	// In particular, it is NOT safe to get the state of a DigitalIo line - either
	// from this line or any other DigitalIoOptional instance - inside the
	// handler.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Precondition: no handler is currently set.
	//
	// Returns:
	// OK - the interrupt handler was configured.
	// INVALID_ARGUMENT - handler is empty.
	// Other status codes as defined by the backend.
	//
	Status SetInterruptHandler(InterruptTrigger trigger,
	InterruptHandler&& handler) {
	if (handler == nullptr) {
	return Status::InvalidArgument();
	}
	return DoSetInterruptHandler(trigger, std::move(handler));
	}

	// Clear the interrupt handler and disable interrupts if enabled.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Returns:
	// OK - the itnerrupt handler was cleared.
	// Other status codes as defined by the backend.
	//
	Status ClearInterruptHandler() {
	return DoSetInterruptHandler(InterruptTrigger::kActivatingEdge, nullptr);
	}

	// Enable interrupts which will trigger the interrupt handler.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Precondition: a handler has been set using SetInterruptHandler.
	//
	// Returns:
	// OK - the interrupt handler was configured.
	// FAILED_PRECONDITION - The line has not been enabled.
	// Other status codes as defined by the backend.
	//
	Status EnableInterruptHandler() { return DoEnableInterruptHandler(true); }

	// Disable the interrupt handler. This is a no-op if interrupts are disabled.
	//
	// This method can be called inside the interrupt handler for this line
	// without any external synchronization. However, the exact behavior is
	// backend-specific. There may be queued events that will trigger the handler
	// again after this call returns.
	//
	// Returns:
	// OK - the interrupt handler was configured.
	// Other status codes as defined by the backend.
	//
	Status DisableInterruptHandler() { return DoEnableInterruptHandler(false); }

	// Enable the line to initialize it into the default state as determined by
	// the backend. This may enable pull-up/down resistors, drive the line high or
	// low, etc. The line must be enabled before getting/setting the state
	// or enabling interrupts.
	//
	// Callers are responsible to wait for the voltage level to settle after this
	// call returns.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Returns:
	// OK - the line is enabled and ready for use.
	// Other status codes as defined by the backend.
	//
	Status Enable() { return DoEnable(true); }

	// Disable the line to power down any pull-up/down resistors and disconnect
	// from any voltage sources. This is usually done to save power. Interrupt
	// handlers are automatically disabled.
	//
	// This method is not thread-safe and cannot be used in interrupt handlers.
	//
	// Returns:
	// OK - the line is disabled.
	// Other status codes as defined by the backend.
	//
	Status Disable() { 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) {}

	// Implemented by derived classes to provide different functionality.
	// See the documentation of the public functions for requirements.
	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