#include <digital_io.h>

Inheritance diagram for pw::digital_io::DigitalIoOptional:

Public Member Functions
constexpr bool	provides_input () const

constexpr bool	provides_output () const

constexpr bool	provides_interrupt () const

Result< State >	GetState ()

Status	SetState (State state)

Result< bool >	IsStateActive ()

Status	SetStateActive ()

Status	SetStateInactive ()

Status	SetInterruptHandler (InterruptTrigger trigger, InterruptHandler &&handler)

Status	ClearInterruptHandler ()

Status	EnableInterruptHandler ()

Status	DisableInterruptHandler ()

Status	Enable ()

Status	Disable ()

Private Member Functions
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

Friends
class	DigitalInterrupt

class	DigitalIn

class	DigitalInInterrupt

class	DigitalOut

class	DigitalOutInterrupt

class	DigitalInOut

class	DigitalInOutInterrupt

Detailed Description

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.

Member Function Documentation

◆ ClearInterruptHandler()

Status pw::digital_io::DigitalIoOptional::ClearInterruptHandler ( )

inline

Clears the interrupt handler and disables any existing interrupts that are enabled.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The interrupt handler was cleared.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ Disable()

Status pw::digital_io::DigitalIoOptional::Disable ( )

inline

Disables 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.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The line is disabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ DisableInterruptHandler()

Status pw::digital_io::DigitalIoOptional::DisableInterruptHandler ( )

inline

Disables 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

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The interrupt handler was disabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ DoEnable()

virtual Status pw::digital_io::DigitalIoOptional::DoEnable ( bool enable )

privatepure virtual

Enables the line to initialize it into the default state as determined by the backend or disables the line to power down any pull-up/down resistors and disconnect from any voltage sources.

This may enable pull-up/down resistors, drive the line high/low, etc. The line must be enabled before getting/setting the state or enabling interrupts. Callers are responsible for waiting for the voltage level to settle after this call returns.

Calling DoEnable(true) on an already-enabled line should be a no-op, it shouldn't reset the line back to the "default state".

Calling DoEnable(false) should force the line into the disabled state, If the line was not initialized at object construction time.

Precondition: This method cannot be used in interrupt contexts.; When disabling, the interrupt handler must already be disabled.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The line is enabled and ready for use.
* 
*  Returns other status codes as defined by the backend.
* 
*

Implemented in pw::digital_io::McuxpressoDigitalOut, pw::digital_io::McuxpressoDigitalIn, pw::digital_io::McuxpressoDigitalInOutInterrupt, pw::digital_io::McuxpressoPintInterrupt, and pw::digital_io::DigitalInOutMockImpl.

◆ DoEnableInterruptHandler()

virtual Status pw::digital_io::DigitalIoOptional::DoEnableInterruptHandler ( bool enable )

privatepure virtual

Enables or disables interrupts which will trigger the interrupt handler.

Warning: This interrupt handler disabling must be both thread-safe and, interrupt-safe, however enabling is not interrupt-safe and not thread-safe.

Precondition: When enabling, a handler must have been set using DoSetInterruptHandler().; Interrupt handler enabling cannot be used in interrupt contexts.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The interrupt handler was configured.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

Implemented in pw::digital_io::McuxpressoDigitalInOutInterrupt, pw::digital_io::McuxpressoPintInterrupt, pw::digital_io::DigitalIn, pw::digital_io::DigitalOut, and pw::digital_io::DigitalInOut.

◆ DoGetState()

virtual Result< State > pw::digital_io::DigitalIoOptional::DoGetState ( )

privatepure virtual

Gets the state of the line.

Precondition: This method cannot be used in interrupt contexts.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: An active or inactive state.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

Implemented in pw::digital_io::DigitalInterrupt, pw::digital_io::DigitalOut, pw::digital_io::DigitalOutInterrupt, pw::digital_io::DigitalInOutMockImpl, pw::digital_io::McuxpressoDigitalIn, and pw::digital_io::McuxpressoDigitalInOutInterrupt.

◆ DoSetInterruptHandler()

virtual Status pw::digital_io::DigitalIoOptional::DoSetInterruptHandler	(	InterruptTrigger	trigger,
		InterruptHandler &&	handler
	)

privatepure virtual

Sets or clears an interrupt handler to execute when an interrupt is triggered, and configures 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.

The implementation is expected to provide the handler the last known state of the input. The intention is to either sample the current state and provide that or if not possible provide the state which triggerred the interrupt (e.g. active for activating edge, and inactive for deactivating edge).

The handler is cleared by passing an empty handler, this can be checked by comparing the handler to a nullptr. The implementation must guarantee that the handler is not currently executing and (and will never execute again) after returning from DoSetInterruptHandler(_, nullptr).

Precondition: This method cannot be used in interrupt contexts.; If setting a handler, no handler is permitted to be currently set.; When cleaing a handler, the interrupt handler must be disabled.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The interrupt handler was configured.
* 
*  Returns other status codes as defined by the backend.
* 
*

Implemented in pw::digital_io::DigitalIn, pw::digital_io::DigitalOut, pw::digital_io::DigitalInOut, pw::digital_io::McuxpressoDigitalInOutInterrupt, and pw::digital_io::McuxpressoPintInterrupt.

◆ DoSetState()

virtual Status pw::digital_io::DigitalIoOptional::DoSetState ( State level )

privatepure virtual

Sets the state of the line.

Callers are responsible to wait for the voltage level to settle after this call returns.

Precondition: This method cannot be used in interrupt contexts.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The state has been set.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

Implemented in pw::digital_io::McuxpressoDigitalOut, pw::digital_io::McuxpressoDigitalInOutInterrupt, pw::digital_io::DigitalInOutMockImpl, pw::digital_io::DigitalInterrupt, pw::digital_io::DigitalIn, and pw::digital_io::DigitalInInterrupt.

◆ Enable()

Status pw::digital_io::DigitalIoOptional::Enable ( )

inline

Enables 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/low, etc. The line must be enabled before getting/setting the state or enabling interrupts. Callers are responsible for waiting for the voltage level to settle after this call returns.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The line is enabled and ready for use.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ EnableInterruptHandler()

Status pw::digital_io::DigitalIoOptional::EnableInterruptHandler ( )

inline

Enables interrupts which will trigger the interrupt handler.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Precondition: A handler has been set using SetInterruptHandler().

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The interrupt handler was configured.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ GetState()

Result< State > pw::digital_io::DigitalIoOptional::GetState ( )

inline

Gets the state of the line.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: Returns an active or inactive state.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns Other status codes as defined by the backend.
* 
*

◆ IsStateActive()

Result< bool > pw::digital_io::DigitalIoOptional::IsStateActive ( )

inline

Checks if the line is in the active state.

The line is in the active state when GetState() returns State::kActive.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: ``true`` if the line is in the active state, otherwise ``false``.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ provides_input()

constexpr bool pw::digital_io::DigitalIoOptional::provides_input ( ) const

inlineconstexpr

Returns: true if input (getting state) is supported.

◆ provides_interrupt()

constexpr bool pw::digital_io::DigitalIoOptional::provides_interrupt ( ) const

inlineconstexpr

Returns: true if interrupt handlers can be registered.

◆ provides_output()

constexpr bool pw::digital_io::DigitalIoOptional::provides_output ( ) const

inlineconstexpr

Returns: true if output (setting state) is supported.

◆ SetInterruptHandler()

Status pw::digital_io::DigitalIoOptional::SetInterruptHandler	(	InterruptTrigger	trigger,
		InterruptHandler &&	handler
	)

inline

Sets an interrupt handler to execute when an interrupt is triggered, and configures 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.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Precondition: No handler is currently set.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The interrupt handler was configured.
* 
*     INVALID_ARGUMENT: The handler is empty.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ SetState()

Status pw::digital_io::DigitalIoOptional::SetState ( State state )

inline

Sets the state of the line.

Callers are responsible to wait for the voltage level to settle after this call returns.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The state has been set.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ SetStateActive()

Status pw::digital_io::DigitalIoOptional::SetStateActive ( )

inline

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.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The state has been set.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

◆ SetStateInactive()

Status pw::digital_io::DigitalIoOptional::SetStateInactive ( )

inline

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.

Warning: This method is not thread-safe and cannot be used in interrupt handlers.

Returns

embed:rst:leading-asterisk
 
* 
*  .. pw-status-codes::
* 
*     OK: The state has been set.
* 
*     FAILED_PRECONDITION: The line has not been enabled.
* 
*  Returns other status codes as defined by the backend.
* 
*

The documentation for this class was generated from the following file:

pw_digital_io/public/pw_digital_io/digital_io.h

Public Member Functions

Private Member Functions

Friends

Detailed Description

Member Function Documentation

◆ ClearInterruptHandler()

◆ Disable()

◆ DisableInterruptHandler()

◆ DoEnable()

◆ DoEnableInterruptHandler()

◆ DoGetState()

◆ DoSetInterruptHandler()

◆ DoSetState()

◆ Enable()

◆ EnableInterruptHandler()

◆ GetState()

◆ IsStateActive()

◆ provides_input()

◆ provides_interrupt()

◆ provides_output()

◆ SetInterruptHandler()

◆ SetState()

◆ SetStateActive()

◆ SetStateInactive()