Represents an interface to a group of hardware related digital GPIO lines. More...

#include <DigitalPort.hpp>

Inheritance diagram for duds::hardware::interface::DigitalPort:

Collaboration diagram for duds::hardware::interface::DigitalPort:

Classes
struct	PinEntry
	Data stored for each pin controlled by the port. More...

Public Member Functions
virtual	~DigitalPort ()
	Derived classes should call shutdown() early in their destructors. More...

void	access (const unsigned int pins, const unsigned int len, std::unique_ptr< DigitalPinAccess > acc)
	Obtain access objects to use a set of pins. More...

template<std::size_t Len>
void	access (const unsigned int pins[Len], std::unique_ptr< DigitalPinAccess > acc[Len])

std::unique_ptr< DigitalPinAccess >	access (const unsigned int pin)

void	access (const unsigned int pins, const unsigned int len, DigitalPinAccess acc)
	Obtain access objects to use a set of pins. More...

void	access (const std::vector< unsigned int > &pins, DigitalPinAccess *acc)

template<std::size_t alen, std::size_t plen>
void	access (const unsigned int pins[plen], DigitalPinAccess acc[alen])
	This is a nice idea that may fail at compile time. More...

void	access (const unsigned int *pins, const unsigned int len, DigitalPinSetAccess &acc)
	Obtain access objects to use a set of pins. More...

void	access (const unsigned int begin, const unsigned int end, DigitalPinSetAccess &acc)

void	access (const std::vector< unsigned int > &pins, DigitalPinSetAccess &acc)

std::unique_ptr< DigitalPinSetAccess >	access (const std::vector< unsigned int > &pins)

template<class InputIter >
void	access (const InputIter &begin, const InputIter &end, DigitalPinSetAccess &acc)

DigitalPinCap	capabilities (unsigned int globalPinId) const
	Returns the capabilities of a pin. More...

std::vector< DigitalPinCap >	capabilities () const
	Returns the capabilities of all pins in the port. More...

std::vector< DigitalPinCap >	capabilities (const std::vector< unsigned int > &pvec) const
	Returns the capabilities of all the pins requested by global ID. More...

std::vector< DigitalPinCap >	capabilitiesLocalIds (const std::vector< unsigned int > &pvec) const
	Returns the capabilities of all the pins requested by local ID. More...

DigitalPinConfig	configuration (unsigned int globalPinId) const
	Returns the current configuration of a pin. More...

std::vector< DigitalPinConfig >	configuration () const
	Returns the configuration of all pins in the port. More...

std::vector< DigitalPinConfig >	configuration (const std::vector< unsigned int > &pvec) const
	Returns the configuration of all the pins requested by global ID. More...

std::vector< DigitalPinConfig >	configurationLocalIds (const std::vector< unsigned int > &pvec) const
	Returns the configuration of all the pins requested by local ID. More...

bool	exists (unsigned int gid) const
	Returns true if the pin exists in this port. More...

unsigned int	globalId (unsigned int localId) const
	Returns the global ID for a pin given the local ID. More...

std::vector< unsigned int >	globalIds (const std::vector< unsigned int > &localIds) const
	Converts the provided local pin IDs to global pin IDs. More...

virtual bool	independentConfig (unsigned int gid, const DigitalPinConfig &newcfg, const DigitalPinConfig &initcfg) const =0
	Returns true if the given configuration for the given pin does not affect any other pins in the port. More...

virtual bool	independentConfig () const =0
	Returns true if all pins always have an independent configuration from all other pins. More...

unsigned int	localId (unsigned int globalId) const
	Returns the local ID for a pin given the global ID. More...

std::vector< unsigned int >	localIds (const std::vector< unsigned int > &globalIds) const
	Converts the provided global pin IDs to local pin IDs. More...

unsigned int	offset () const
	Returns the offset for the port's pins. More...

void	poll ()

void	pollInput ()

void	pollSignal ()

DigitalPinRejectedConfiguration::Reason	proposeConfig (unsigned int gid, DigitalPinConfig &pconf, DigitalPinConfig &iconf) const
	Proposes a configuration change for a single pin. More...

DigitalPinRejectedConfiguration::Reason	proposeConfig (unsigned int gid, DigitalPinConfig &pconf) const
	Proposes a configuration change for a single pin from the port's current configuration. More...

bool	proposeConfig (const std::vector< unsigned int > &globalPinIds, std::vector< DigitalPinConfig > &propConf, std::vector< DigitalPinConfig > &initConf, std::function< void(DigitalPinRejectedConfiguration::Reason)> insertReason=std::function< void(DigitalPinRejectedConfiguration::Reason)>()) const

bool	proposeConfig (const std::vector< unsigned int > &pins, std::vector< DigitalPinConfig > &propConf, std::function< void(DigitalPinRejectedConfiguration::Reason)> insertReason=std::function< void(DigitalPinRejectedConfiguration::Reason)>()) const

bool	proposeConfigLocalIds (const std::vector< unsigned int > &localPinIds, std::vector< DigitalPinConfig > &propConf, std::vector< DigitalPinConfig > &initConf, std::function< void(DigitalPinRejectedConfiguration::Reason)> insertReason=std::function< void(DigitalPinRejectedConfiguration::Reason)>()) const

bool	proposeConfigLocalIds (const std::vector< unsigned int > &pins, std::vector< DigitalPinConfig > &propConf, std::function< void(DigitalPinRejectedConfiguration::Reason)> insertReason=std::function< void(DigitalPinRejectedConfiguration::Reason)>()) const

bool	proposeFullConfig (std::vector< DigitalPinConfig > &propConf, std::vector< DigitalPinConfig > &initConf, std::function< void(DigitalPinRejectedConfiguration::Reason)> insertReason=std::function< void(DigitalPinRejectedConfiguration::Reason)>()) const

virtual bool	simultaneousOperations () const =0
	True if the implementation supports operating on multiple pins simultaneously. More...

unsigned int	size () const
	The maximum number of pins on the port. More...

Protected Types
typedef std::vector< PinEntry >	PinVector

Protected Member Functions
	DigitalPort (unsigned int numpins, unsigned int firstid)
	Initializes internal data. More...

std::vector< DigitalPinCap >	capabilities (const std::vector< unsigned int > &pvec, bool global) const

const DigitalPinConfig &	configRef (unsigned int localPinId) const
	Returns a reference to a pin's configuration on behalf of an access object. More...

std::vector< DigitalPinConfig >	configuration (const std::vector< unsigned int > &pvec, bool global) const

std::vector< DigitalPinConfig >	configurationImpl () const
	Returns the configuration of all pins in the port. More...

virtual void	configurePort (unsigned int localPinId, const DigitalPinConfig &cfg, DigitalPinAccessBase::PortData *pdata)=0
	Changes the hardware configuration for a single pin. More...

virtual void	configurePort (const std::vector< DigitalPinConfig > &cfgs, DigitalPinAccessBase::PortData *pdata)=0
	Changes the hardware configuration for the whole port. More...

bool	input (unsigned int gid, DigitalPinAccessBase::PortData *pdata)
	Does error checking in advance of calling inputImpl(unsigned int) to read the input of the given pin. More...

std::vector< bool >	input (const std::vector< unsigned int > &pvec, DigitalPinAccessBase::PortData *pdata)
	Does error checking in advance of calling inputImpl(const std::vector<unsigned int> &) to read the input of a set of pins. More...

virtual bool	inputImpl (unsigned int gid, DigitalPinAccessBase::PortData *pdata)=0
	Reads input from the given pin. More...

virtual std::vector< bool >	inputImpl (const std::vector< unsigned int > &pvec, DigitalPinAccessBase::PortData *pdata)
	Reads input from the requested pins. More...

virtual void	madeAccess (DigitalPinAccess &acc)
	Called after a new access object is made to allow a port implementation to take further action. More...

virtual void	madeAccess (DigitalPinSetAccess &acc)
	Called after a new access object is made to allow a port implementation to take further action. More...

DigitalPinConfig	modifyConfig (unsigned int globalPinId, const DigitalPinConfig &cfg, DigitalPinAccessBase::PortData *pdata)
	Modifies the configuration of a single pin with an independent configuration. More...

void	modifyConfig (std::vector< DigitalPinConfig > &cfgs, DigitalPinAccessBase::PortData *pdata)
	Modifies the configuration of multiple pins. More...

void	modifyConfig (const std::vector< unsigned int > &pvec, std::vector< DigitalPinConfig > &cfgs, DigitalPinAccessBase::PortData *pdata)

void	modifyFullConfig (std::vector< DigitalPinConfig > &propConf, std::vector< DigitalPinConfig > &initConf, DigitalPinAccessBase::PortData *pdata)
	Does the work of the modifyConfig() functions in the case that the whole port configuration must be considered for possible changes. More...

void	output (unsigned int gid, bool state, DigitalPinAccessBase::PortData *pdata)
	Does error checking in advance of calling outputImpl(unsigned int, bool) to change the output of the given pin. More...

void	output (const std::vector< unsigned int > &pvec, const std::vector< bool > &state, DigitalPinAccessBase::PortData *pdata)
	Does error checking in advance of calling outputImpl(const std::vector<unsigned int> &,const std::vector<bool> &) to change the output of a set of pins. More...

virtual void	outputImpl (unsigned int lid, bool state, DigitalPinAccessBase::PortData *pdata)=0
	Changes the output state of the given pin. More...

virtual void	outputImpl (const std::vector< unsigned int > &pvec, const std::vector< bool > &state, DigitalPinAccessBase::PortData *pdata)
	Changes the outputs of several pins. More...

virtual DigitalPinRejectedConfiguration::Reason	proposeConfigImpl (unsigned int gid, DigitalPinConfig &pconf, DigitalPinConfig &iconf) const =0

virtual bool	proposeConfigImpl (const std::vector< unsigned int > &localPinIds, std::vector< DigitalPinConfig > &propConf, std::vector< DigitalPinConfig > &initConf, std::function< void(DigitalPinRejectedConfiguration::Reason)> insertReason=std::function< void(DigitalPinRejectedConfiguration::Reason)>()) const =0

virtual bool	proposeFullConfigImpl (std::vector< DigitalPinConfig > &propConf, std::vector< DigitalPinConfig > &initConf, std::function< void(DigitalPinRejectedConfiguration::Reason)> insertReason=std::function< void(DigitalPinRejectedConfiguration::Reason)>()) const =0

virtual void	retiredAccess (const DigitalPinAccess &acc) noexcept
	Called just before an access object is retired to allow a port implementation to take further action. More...

virtual void	retiredAccess (const DigitalPinSetAccess &acc) noexcept
	Called just before an access object is retired to allow a port implementation to take further action. More...

void	shutdown ()
	Waits for access to all pins so that any user of access objects may finish with their operation, then destroys all pin data and awakens threads waiting on access, but they will not receive access. More...

Static Protected Member Functions
static DigitalPinAccessBase::PortData &	portData (const DigitalPinAccessBase &acc)
	Returns a reference to the port specific data in the given DigitalPinAccessBase object. More...

template<typename T >
static void	portDataPtr (const DigitalPinAccessBase &acc, T **ptr)
	Provides a pointer to type T stored in the port specific data of the given DigitalPinAccessBase object. More...

Protected Attributes
PinVector	pins
	Data on each pin handled by the port. More...

Private Member Functions
bool	areAvailable (const unsigned int *reqpins, std::size_t len)
	Checks a set of pins to see if they are all currently available. More...

void	shutdownAccessRequests ()
	Used by the shutdown functions to force any thread waiting on access to pins to quit waiting and fail to get access. More...

void	updateAccess (const DigitalPinAccess &oldAcc, DigitalPinAccess *newAcc)
	Transfers or relinquishes access to pins. More...

void	updateAccess (const DigitalPinSetAccess &oldAcc, DigitalPinSetAccess *newAcc)
	Transfers or relinquishes access to pins. More...

void	waitForAvailability (std::unique_lock< std::mutex > &lock, const unsigned int *const reqpins, const std::size_t len)
	Waits for all pins to become available. More...

Private Attributes
std::mutex	block
	Used to serialize access to internal data for thread-safe operation. More...

friend	DigitalPinAccess

friend	DigitalPinSetAccess

unsigned int	idOffset
	An offset used to translate pin identification numbers between global scope and local scope. More...

std::condition_variable	pinwait
	Used to efficently wait for resources to become available. More...

int	waiting
	A count of the threads waiting to access pins. More...

Detailed Description

Represents an interface to a group of hardware related digital GPIO lines.

Derived classes will implement actual use of GPIO hardware.

All derived non-abstract classes should call shutdown() in their destructors. This function will first wait for all pins to become available so that any users of the pins may finish. Then it waits on any threads that might be hoping to obtain pin access to realize that it won't happen. It is safest to de-initialize hardware after the shutdown function returns.

Some functions come in pairs where one function has "Impl" at the end of its name. The "Impl" functions contain the actual implementation, are not public, and do not lock the port's block mutex. The non-Impl functions may be public, and lock block before calling the corresponding Impl function.

Todo:: Investigate ways to limit the locking of block before using pins. Some read operations likely do not need a lock if certain conditions can be met.

Author: Jeff Jackowski

Definition at line 47 of file DigitalPort.hpp.

Member Typedef Documentation

◆ PinVector

typedef std::vector<PinEntry> duds::hardware::interface::DigitalPort::PinVector

protected

Definition at line 109 of file DigitalPort.hpp.

Constructor & Destructor Documentation

◆ DigitalPort()

duds::hardware::interface::DigitalPort::DigitalPort	(	unsigned int	numpins,
		unsigned int	firstid
	)

protected

Initializes internal data.

Parameters

numpins	The number of pre-allocated elements to make in pins.
firstid	The global ID of the pin at index zero of pins.

Definition at line 15 of file DigitalPort.cpp.

◆ ~DigitalPort()

duds::hardware::interface::DigitalPort::~DigitalPort ( )

virtual

Derived classes should call shutdown() early in their destructors.

That will assure no pins are in use.

Definition at line 18 of file DigitalPort.cpp.

Member Function Documentation

◆ access() [1/11]

void duds::hardware::interface::DigitalPort::access	(	const unsigned int *	pins,
		const unsigned int	len,
		std::unique_ptr< DigitalPinAccess > *	acc
	)

Obtain access objects to use a set of pins.

The access objects to all requested pins are either all obtained, or not obtained. If not all the access objects can be obtained, and no exception is thrown, the calling thread will block and attempt to get the access objects later when they might all be available. Barring an exception or destruction of the PinStore, the thread will continue to block until the access objects are obtained.

While the access objects will be obtained simultaneously, they are all independent from each other. They do not have to be relinquished at the same time, and can be relinquished in any order.

This form is intended for use with arrays allocated on the stack, and with constant arrays for the requested pins. They might not be the safest of data structures, but they are fast.

Parameters

pins	An array of pin id values. All values must be for pins in the port, and values must not be repeated. The value -1 will be skipped over; the corresponding item in acc will not be changed.
len	The length of both the acc and pins arrays.
acc	An array of unique pointers that will be assigned to the access objects of the requested pins.

Precondition: acc contains constructed unique pointers.

Exceptions

PinEmptyAccessRequest
PinDoesNotExist	A requested pin does not exist within this port.
ObjectDestructedError	The PinStore object was destructed before the request could be fullfilled.
PinInUse	A pin was requested twice or more; there is a repeated value in pins. If thrown, acc may be modified.

Definition at line 160 of file DigitalPort.cpp.

Referenced by access(), areAvailable(), and updateAccess().

◆ access() [2/11]

template<std::size_t Len>

void duds::hardware::interface::DigitalPort::access	(	const unsigned int	pins[Len],
		std::unique_ptr< DigitalPinAccess >	acc[Len]
	)

inline

Definition at line 882 of file DigitalPort.hpp.

◆ access() [3/11]

std::unique_ptr< DigitalPinAccess > duds::hardware::interface::DigitalPort::access ( const unsigned int pin )

Definition at line 299 of file DigitalPort.cpp.

◆ access() [4/11]

void duds::hardware::interface::DigitalPort::access	(	const unsigned int *	pins,
		const unsigned int	len,
		DigitalPinAccess *	acc
	)

Obtain access objects to use a set of pins.

The access objects to all requested pins are either all obtained, or not obtained. If not all the access objects can be obtained, and no exception is thrown, the calling thread will block and attempt to get the access objects later when they might all be available. Barring an exception or destruction of the PinStore, the thread will continue to block until the access objects are obtained.

While the access objects will be obtained simultaneously, they are all independent from each other. They do not have to be relinquished at the same time, and can be relinquished in any order.

Parameters

pins	An array of pin id values. All values must be for pins in the port, and values must not be repeated. The value -1 will be skipped over; the corresponding object in acc will be made using the default constructor.
len	The length of both the acc and pins arrays.
acc	An array of DigitalPinAccess objects.

Precondition

acc contains one of:

An allocated array of default constructed unused DigitalPinAccess objects of length len.
An allocated but uninitialized array long enough for len DigitalPinAccess objects.
An allocated array of destructed DigitalPinAccess objects of length len.

Warning: No check is performed to assure any supplied constructed access object is not already in use. If constructed, the object's havePin() function must return false. If this condition is not met, some pins may be considered to be in-use as long as the process continues to run, much like a memory leak.

Postcondition: If a PinDoesNotExist or ObjectDestructedError exception is thrown, acc will not be modified. Any other exception may be thrown after acc is modified.

Exceptions

PinEmptyAccessRequest
PinDoesNotExist	A requested pin does not exist within this port.
ObjectDestructedError	The PinStore object was destructed before the request could be fullfilled.
PinInUse	A pin was requested twice or more; there is a repeated value in pins. If thrown, acc may be modified.

Definition at line 250 of file DigitalPort.cpp.

◆ access() [5/11]

void duds::hardware::interface::DigitalPort::access	(	const std::vector< unsigned int > &	pins,
		DigitalPinAccess *	acc
	)

inline

Definition at line 987 of file DigitalPort.hpp.

◆ access() [6/11]

template<std::size_t alen, std::size_t plen>

void duds::hardware::interface::DigitalPort::access	(	const unsigned int	pins[plen],
		DigitalPinAccess	acc[alen]
	)

inline

This is a nice idea that may fail at compile time.

Definition at line 997 of file DigitalPort.hpp.

◆ access() [7/11]

void duds::hardware::interface::DigitalPort::access	(	const unsigned int *	pins,
		const unsigned int	len,
		DigitalPinSetAccess &	acc
	)

Obtain access objects to use a set of pins.

The access object will be granted use of all requested pins simultaneously. The thread will block until all pins can be acquired. If the access object already has pins, the requested pins will be appended. If a requested pin is already available through the given access object, the calling thread will be deadlocked.

Parameters

pins	An array of global pin ID values. All values must be for pins in the port, and values must not be repeated. The value -1 will be skipped over; the corresponding spot in acc will be given -1 and will not represent a usable pin.

Precondition: None of the pins specified in the pins array are already available through acc. Failure to meet this requirement will cause the calling thread to be deadlocked.

Parameters

len	The length of the pins array.
acc	A DigitalPinSetAccess object.

Postcondition: If a PinDoesNotExist, PinSetWrongPort, or ObjectDestructedError exception is thrown, acc will not be modified. Any other exception may be thrown after acc is modified. Any modification will leave acc in a valid state, and may give it access to a subset of the requested pins.

Exceptions

PinEmptyAccessRequest
PinDoesNotExist	A requested pin does not exist within this port.
PinSetWrongPort	The given access object has already been used with another port.
ObjectDestructedError	The PinStore object was destructed before the request could be fullfilled.
PinInUse	A pin was requested twice or more; there is a repeated value in pins. If thrown, acc may be modified.

Definition at line 305 of file DigitalPort.cpp.

◆ access() [8/11]

void duds::hardware::interface::DigitalPort::access	(	const unsigned int *	begin,
		const unsigned int *	end,
		DigitalPinSetAccess &	acc
	)

inline

Definition at line 1042 of file DigitalPort.hpp.

◆ access() [9/11]

void duds::hardware::interface::DigitalPort::access	(	const std::vector< unsigned int > &	pins,
		DigitalPinSetAccess &	acc
	)

inline

Definition at line 1049 of file DigitalPort.hpp.

◆ access() [10/11]

std::unique_ptr< DigitalPinSetAccess > duds::hardware::interface::DigitalPort::access ( const std::vector< unsigned int > & pins )

Definition at line 361 of file DigitalPort.cpp.

◆ access() [11/11]

template<class InputIter >

void duds::hardware::interface::DigitalPort::access	(	const InputIter &	begin,
		const InputIter &	end,
		DigitalPinSetAccess &	acc
	)

inline

Definition at line 1061 of file DigitalPort.hpp.

◆ areAvailable()

bool duds::hardware::interface::DigitalPort::areAvailable	(	const unsigned int *	reqpins,
		std::size_t	len
	)

private

Checks a set of pins to see if they are all currently available.

Precondition: block is locked.

Returns: True if all pins are available; false otherwise.

Definition at line 104 of file DigitalPort.cpp.

Referenced by waitForAvailability().

◆ capabilities() [1/4]

std::vector< DigitalPinCap > duds::hardware::interface::DigitalPort::capabilities	(	const std::vector< unsigned int > &	pvec,
		bool	global
	)		const

protected

Definition at line 489 of file DigitalPort.cpp.

Referenced by duds::hardware::interface::DigitalPinAccess::capabilities(), and duds::hardware::interface::DigitalPinSetAccess::capabilities().

◆ capabilities() [2/4]

DigitalPinCap duds::hardware::interface::DigitalPort::capabilities ( unsigned int globalPinId ) const

Returns the capabilities of a pin.

Parameters

globalPinId The global ID of the pin to query.

Returns: A copy of the capabilities.

Exceptions

PinDoesNotExist The requested pin does not exist within this port.

Definition at line 464 of file DigitalPort.cpp.

◆ capabilities() [3/4]

std::vector< DigitalPinCap > duds::hardware::interface::DigitalPort::capabilities ( ) const

Returns the capabilities of all pins in the port.

Returns: A copy of the capabilities.

Definition at line 477 of file DigitalPort.cpp.

Referenced by capabilities(), capabilitiesLocalIds(), and configRef().

◆ capabilities() [4/4]

std::vector<DigitalPinCap> duds::hardware::interface::DigitalPort::capabilities ( const std::vector< unsigned int > & pvec ) const

inline

Returns the capabilities of all the pins requested by global ID.

Parameters

pvec	A vector of global pin IDs.

Returns: A vector of pin capabilities ordered the same as pvec. If there are any gaps in pvec (an element with -1), the corresponding capability will be NonexistentDigitalPin.

Exceptions

PinDoesNotExist One of the pin IDs in pvec is for a pin that is not in this port.

Definition at line 572 of file DigitalPort.hpp.

◆ capabilitiesLocalIds()

std::vector<DigitalPinCap> duds::hardware::interface::DigitalPort::capabilitiesLocalIds ( const std::vector< unsigned int > & pvec ) const

inline

Returns the capabilities of all the pins requested by local ID.

Parameters

pvec	A vector of local pin IDs.

Returns: A vector of pin capabilities ordered the same as pvec. If there are any gaps in pvec (an element with -1), the corresponding capability will be NonexistentDigitalPin.

Exceptions

PinDoesNotExist One of the pin IDs in pvec is for a pin that is not in this port.

Note: Most public functions of this class take global pin IDs, which is why this one has a name making it explicit that it takes local pin IDs. This is needed to support DigitalPinSetAccess.

Definition at line 590 of file DigitalPort.hpp.

Referenced by duds::hardware::interface::DigitalPinSetAccess::capabilities().

◆ configRef()

const DigitalPinConfig& duds::hardware::interface::DigitalPort::configRef ( unsigned int localPinId ) const

inlineprotected

Returns a reference to a pin's configuration on behalf of an access object.

Parameters

localPinId The local ID of the pin to query.

Todo:: Check fot use of this function.

Definition at line 217 of file DigitalPort.hpp.

◆ configuration() [1/4]

std::vector< DigitalPinConfig > duds::hardware::interface::DigitalPort::configuration	(	const std::vector< unsigned int > &	pvec,
		bool	global
	)		const

protected

Definition at line 541 of file DigitalPort.cpp.

Referenced by duds::hardware::interface::DigitalPinAccess::configuration(), and duds::hardware::interface::DigitalPinSetAccess::configuration().

◆ configuration() [2/4]

DigitalPinConfig duds::hardware::interface::DigitalPort::configuration ( unsigned int globalPinId ) const

Returns the current configuration of a pin.

Parameters

globalPinId The global ID of the pin to query.

Returns: A copy of the current configuration. The configuration could change on the request of another thread, so a reference cannot be used.

Exceptions

PinDoesNotExist The requested pin does not exist within this port.

Definition at line 434 of file DigitalPort.cpp.

◆ configuration() [3/4]

std::vector< DigitalPinConfig > duds::hardware::interface::DigitalPort::configuration ( ) const

Returns the configuration of all pins in the port.

Returns: A copy of the current configuration.

Definition at line 535 of file DigitalPort.cpp.

Referenced by capabilitiesLocalIds(), configRef(), configuration(), and configurationLocalIds().

◆ configuration() [4/4]

std::vector<DigitalPinConfig> duds::hardware::interface::DigitalPort::configuration ( const std::vector< unsigned int > & pvec ) const

inline

Returns the configuration of all the pins requested by global ID.

Parameters

pvec	A vector of global pin IDs.

Returns: A vector of pin configurations ordered the same as pvec. If there are any gaps in pvec (an element with -1), the corresponding configuration will be DigitalPinConfig::OperationNoChange.

Exceptions

PinDoesNotExist One of the pin IDs in pvec is for a pin that is not in this port.

Definition at line 620 of file DigitalPort.hpp.

◆ configurationImpl()

std::vector< DigitalPinConfig > duds::hardware::interface::DigitalPort::configurationImpl ( ) const

protected

Returns the configuration of all pins in the port.

Returns: A copy of the current configuration.

Precondition: The thread has a lock on block.

Definition at line 525 of file DigitalPort.cpp.

Referenced by configRef(), configuration(), modifyConfig(), duds::hardware::interface::DigitalPortIndependentPins::proposeFullConfigImpl(), and duds::hardware::interface::DigitalPortDependentPins::proposeFullConfigImpl().

◆ configurationLocalIds()

std::vector<DigitalPinConfig> duds::hardware::interface::DigitalPort::configurationLocalIds ( const std::vector< unsigned int > & pvec ) const

inline

Returns the configuration of all the pins requested by local ID.

Parameters

pvec	A vector of local pin IDs.

Returns: A vector of pin configurations ordered the same as pvec. If there are any gaps in pvec (an element with -1), the corresponding configuration will be DigitalPinConfig::OperationNoChange.

Exceptions

PinDoesNotExist One of the pin IDs in pvec is for a pin that is not in this port.

Note: Most public functions of this class take global pin IDs, which is why this one has a name making it explicit that it takes local pin IDs. This is needed to support DigitalPinSetAccess.

Definition at line 638 of file DigitalPort.hpp.

Referenced by duds::hardware::interface::DigitalPinSetAccess::configuration().

◆ configurePort() [1/2]

virtual void duds::hardware::interface::DigitalPort::configurePort	(	unsigned int	localPinId,
		const DigitalPinConfig &	cfg,
		DigitalPinAccessBase::PortData *	pdata
	)

protectedpure virtual

Changes the hardware configuration for a single pin.

If this function does not throw, its caller will record the configuration change inside pins. It is only called after error checking is performed on its parameters.

Parameters

cfg	The new configuration.
localPinId	The local ID for the pin to modify.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Implemented in duds::hardware::interface::linux::GpioDevPort, duds::hardware::interface::linux::SysFsPort, duds::hardware::interface::test::VirtualPort, and duds::hardware::interface::DigitalPortIndependentPins.

Referenced by configRef(), modifyConfig(), and modifyFullConfig().

◆ configurePort() [2/2]

virtual void duds::hardware::interface::DigitalPort::configurePort	(	const std::vector< DigitalPinConfig > &	cfgs,
		DigitalPinAccessBase::PortData *	pdata
	)

protectedpure virtual

Changes the hardware configuration for the whole port.

If this function does not throw, its caller will record the configuration change inside pins. It is only called after error checking is performed on its parameters.

Parameters

cfgs	The new configuration. The indices are the local pin IDs. The size must match the size of pins.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Implemented in duds::hardware::interface::DigitalPortIndependentPins.

◆ exists()

bool duds::hardware::interface::DigitalPort::exists ( unsigned int gid ) const

Returns true if the pin exists in this port.

Parameters

gid	The global pin ID to check.

Definition at line 50 of file DigitalPort.cpp.

Referenced by size().

◆ globalId()

unsigned int duds::hardware::interface::DigitalPort::globalId ( unsigned int localId ) const

inline

Returns the global ID for a pin given the local ID.

The global ID is the one used to identify a specific pin on the hardware among all DigitalPort objects.

Parameters

localId The local pin ID; the one used to index into vectors of pins or related information.

Exceptions

duds::general::ObjectDestructedError

Definition at line 775 of file DigitalPort.hpp.

Referenced by capabilities(), configuration(), duds::hardware::interface::linux::SysFsPort::configurePort(), duds::hardware::interface::linux::GpioDevPort::configurePort(), duds::hardware::interface::DigitalPinSetAccess::globalId(), duds::hardware::interface::linux::GpioDevPort::initPin(), input(), inputImpl(), output(), duds::hardware::interface::linux::SysFsPort::outputImpl(), duds::hardware::interface::linux::GpioDevPort::outputImpl(), duds::hardware::interface::DigitalPortDependentPins::proposeConfigImpl(), and duds::hardware::interface::DigitalPortDependentPins::proposeFullConfigImpl().

◆ globalIds()

std::vector< unsigned int > duds::hardware::interface::DigitalPort::globalIds ( const std::vector< unsigned int > & localIds ) const

Converts the provided local pin IDs to global pin IDs.

Any gaps, or IDs of -1, are retained.

Definition at line 78 of file DigitalPort.cpp.

Referenced by globalId(), duds::hardware::interface::DigitalPinSetAccess::globalIds(), and localId().

◆ independentConfig() [1/2]

virtual bool duds::hardware::interface::DigitalPort::independentConfig	(	unsigned int	gid,
		const DigitalPinConfig &	newcfg,
		const DigitalPinConfig &	initcfg
	)		const

pure virtual

Returns true if the given configuration for the given pin does not affect any other pins in the port.

When true, the functions to change pin configurations will use simpler and faster code. When false, more complex logic will be used to assure the dependent configurations will still meet their requirements.

Parameters

gid	The global pin ID.
newcfg	The proposed configuration to check.
initcfg	The initial configuration for the pin.

Exceptions

PinDoesNotExist The specified pin does not exist within this port.

Implemented in duds::hardware::interface::DigitalPortDependentPins, and duds::hardware::interface::DigitalPortIndependentPins.

Referenced by duds::hardware::interface::DigitalPinSetAccess::independentConfig().

◆ independentConfig() [2/2]

virtual bool duds::hardware::interface::DigitalPort::independentConfig ( ) const

pure virtual

Returns true if all pins always have an independent configuration from all other pins.

If so, independentConfig(unsigned int, const DigitalPinConfig &) must always return true for all valid inputs.

Implemented in duds::hardware::interface::DigitalPortDependentPins, and duds::hardware::interface::DigitalPortIndependentPins.

Referenced by modifyConfig(), and size().

◆ input() [1/2]

bool duds::hardware::interface::DigitalPort::input	(	unsigned int	gid,
		DigitalPinAccessBase::PortData *	pdata
	)

protected

Does error checking in advance of calling inputImpl(unsigned int) to read the input of the given pin.

Parameters

gid	The global ID of the pin to read.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Exceptions

PinDoesNotExist	The requested pin is not handled by this port.
PinWrongDirection	The pin is not configured as an input.

Todo:: Are these required? A -1 could get through an access object.

Definition at line 744 of file DigitalPort.cpp.

Referenced by configRef(), duds::hardware::interface::DigitalPinAccess::input(), and duds::hardware::interface::DigitalPinSetAccess::input().

◆ input() [2/2]

std::vector< bool > duds::hardware::interface::DigitalPort::input	(	const std::vector< unsigned int > &	pvec,
		DigitalPinAccessBase::PortData *	pdata
	)

protected

Does error checking in advance of calling inputImpl(const std::vector<unsigned int> &) to read the input of a set of pins.

Parameters

pvec	The local IDs of the pins to read.
pdata	A pointer to the port specific data stored in the corresponding access object for the pins.

Exceptions

PinDoesNotExist	A requested pin is not handled by this port.
PinWrongDirection	A pin is not configured as an input.

Returns: The input from the pins.

Todo:: Are these required? A -1 could get through an access object.

Definition at line 765 of file DigitalPort.cpp.

◆ inputImpl() [1/2]

virtual bool duds::hardware::interface::DigitalPort::inputImpl	(	unsigned int	gid,
		DigitalPinAccessBase::PortData *	pdata
	)

protectedpure virtual

Reads input from the given pin.

Precondition: The pin is configured as an input.

Parameters

gid	The global ID of the pin to read.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Implemented in duds::hardware::interface::linux::GpioDevPort, duds::hardware::interface::linux::SysFsPort, and duds::hardware::interface::test::VirtualPort.

Referenced by configRef(), input(), and inputImpl().

◆ inputImpl() [2/2]

std::vector< bool > duds::hardware::interface::DigitalPort::inputImpl	(	const std::vector< unsigned int > &	pvec,
		DigitalPinAccessBase::PortData *	pdata
	)

protectedvirtual

Reads input from the requested pins.

The implementation in DigitalPort calls input(unsigned int). This only makes sense for ports that do not support simultaneous operations. An assertion exists to prevent such misuse.

Precondition: All the pins are configured as inputs.

Parameters

pvec	The global IDs of the pins to read.
pdata	A pointer to the port specific data stored in the corresponding access object for the pins.

Returns: The input from the pins.

Reimplemented in duds::hardware::interface::linux::GpioDevPort, and duds::hardware::interface::test::VirtualPort.

Definition at line 793 of file DigitalPort.cpp.

◆ localId()

unsigned int duds::hardware::interface::DigitalPort::localId ( unsigned int globalId ) const

inline

Returns the local ID for a pin given the global ID.

The local ID is the one used to index into vectors of pins or related information.

Parameters

globalId The global pin ID; the one used to identify the pin among all the pins available.

Definition at line 757 of file DigitalPort.hpp.

Referenced by access(), areAvailable(), capabilities(), configuration(), exists(), globalIds(), input(), duds::hardware::interface::test::VirtualPort::inputImpl(), duds::hardware::interface::linux::SysFsPort::inputImpl(), duds::hardware::interface::linux::GpioDevPort::inputImpl(), duds::hardware::interface::DigitalPinAccess::localId(), localIds(), modifyConfig(), output(), duds::hardware::interface::DigitalPortIndependentPins::proposeConfigImpl(), and duds::hardware::interface::DigitalPortDependentPins::proposeConfigImpl().

◆ localIds()

std::vector< unsigned int > duds::hardware::interface::DigitalPort::localIds ( const std::vector< unsigned int > & globalIds ) const

Converts the provided global pin IDs to local pin IDs.

Any gaps, or IDs of -1, are retained.

Definition at line 60 of file DigitalPort.cpp.

Referenced by localId(), and proposeConfig().

◆ madeAccess() [1/2]

void duds::hardware::interface::DigitalPort::madeAccess ( DigitalPinAccess & acc )

protectedvirtual

Called after a new access object is made to allow a port implementation to take further action.

The call is made while there is a lock on block. The default implementation does nothing.

Parameters

acc	The newly made access object.

Exceptions

exception Any thrown exception will cause the access object to be retired and then the exception will be rethrown.

Reimplemented in duds::hardware::interface::linux::GpioDevPort.

Definition at line 152 of file DigitalPort.cpp.

Referenced by access(), and configRef().

◆ madeAccess() [2/2]

void duds::hardware::interface::DigitalPort::madeAccess ( DigitalPinSetAccess & acc )

protectedvirtual

Called after a new access object is made to allow a port implementation to take further action.

The call is made while there is a lock on block. The default implementation does nothing.

Parameters

acc	The newly made access object.

Exceptions

exception Any thrown exception will cause the access object to be retired and then the exception will be rethrown.

Reimplemented in duds::hardware::interface::linux::GpioDevPort.

Definition at line 154 of file DigitalPort.cpp.

◆ modifyConfig() [1/3]

DigitalPinConfig duds::hardware::interface::DigitalPort::modifyConfig	(	unsigned int	globalPinId,
		const DigitalPinConfig &	cfg,
		DigitalPinAccessBase::PortData *	pdata
	)

protected

Modifies the configuration of a single pin with an independent configuration.

Unless the implementation considers all configurations to be dependent, and configurations are always modified one pin at a time, then this function must be implemented.

Parameters

globalPinId	The global pin ID; matches the index in the pins and proposed vectors.
cfg	The requested new configuration.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Returns: The actual new configuration.

Definition at line 621 of file DigitalPort.cpp.

Referenced by configRef(), duds::hardware::interface::DigitalPinAccess::modifyConfig(), and duds::hardware::interface::DigitalPinSetAccess::modifyConfig().

◆ modifyConfig() [2/3]

void duds::hardware::interface::DigitalPort::modifyConfig	(	std::vector< DigitalPinConfig > &	cfgs,
		DigitalPinAccessBase::PortData *	pdata
	)

protected

Modifies the configuration of multiple pins.

This is used to support changing multiple configurations without requiring the DigitalPort user to make calls for each pin individually, and to handle dependent configurations.

Parameters

cfgs	The new configurations for each pin using local indexing (matches pins). Will be changed to match the size of pins and to hold the finialized configurations.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Note: The implementation should lock block prior to accessing internal data, like pins.

Definition at line 703 of file DigitalPort.cpp.

◆ modifyConfig() [3/3]

void duds::hardware::interface::DigitalPort::modifyConfig	(	const std::vector< unsigned int > &	pvec,
		std::vector< DigitalPinConfig > &	cfgs,
		DigitalPinAccessBase::PortData *	pdata
	)

protected

Definition at line 715 of file DigitalPort.cpp.

◆ modifyFullConfig()

void duds::hardware::interface::DigitalPort::modifyFullConfig	(	std::vector< DigitalPinConfig > &	propConf,
		std::vector< DigitalPinConfig > &	initConf,
		DigitalPinAccessBase::PortData *	pdata
	)

protected

Does the work of the modifyConfig() functions in the case that the whole port configuration must be considered for possible changes.

If proposeConfigImpl() reports the configuration is good, configurePort(const std::vector<DigitalPinConfig> &) will be called.

Precondition: There is already a lock on the port's internal data.

Parameters

propConf	The new proposed configuration. It must be the same size as pins. The values will be modified to be the actual applied configuration. Modification can occur even if an exception is thrown.
initConf	The initial and current configuration. It must be the result of configurationImpl(). Included here to allow modifyConfig(DigitalPinConfig &, unsigned int) to fill the vector and use it as the starting point for propConf while avoiding a second call to configurationImpl() since a vector copy will be faster.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Definition at line 672 of file DigitalPort.cpp.

Referenced by configRef(), and modifyConfig().

◆ offset()

unsigned int duds::hardware::interface::DigitalPort::offset ( ) const

inline

Returns the offset for the port's pins.

The value is the same as the global ID of the port's first pin, which has local ID zero. The value will not change for the lifetime of the DigitalPort object.

Definition at line 748 of file DigitalPort.hpp.

Referenced by duds::hardware::interface::linux::GpioDevPort::initPin().

◆ output() [1/2]

void duds::hardware::interface::DigitalPort::output	(	unsigned int	gid,
		bool	state,
		DigitalPinAccessBase::PortData *	pdata
	)

protected

Does error checking in advance of calling outputImpl(unsigned int, bool) to change the output of the given pin.

Parameters

gid	The global ID of the pin to change.
state	The new output state.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Exceptions

PinDoesNotExist	The requested pin is not handled by this port.
DigitalPinCannotOutputError	The pin cannot be configured as an output.

Todo:: Are these required? A -1 could get through an access object.

Definition at line 809 of file DigitalPort.cpp.

Referenced by configRef(), duds::hardware::interface::DigitalPinAccess::output(), duds::hardware::interface::DigitalPinSetAccess::output(), duds::hardware::interface::linux::SysFsPort::FsPin::setDirection(), and duds::hardware::interface::DigitalPinSetAccess::write().

◆ output() [2/2]

void duds::hardware::interface::DigitalPort::output	(	const std::vector< unsigned int > &	pvec,
		const std::vector< bool > &	state,
		DigitalPinAccessBase::PortData *	pdata
	)

protected

Does error checking in advance of calling outputImpl(const std::vector<unsigned int> &,const std::vector<bool> &) to change the output of a set of pins.

Parameters

pvec	The local IDs of the pins to change.
state	The new output state.
pdata	A pointer to the port specific data stored in the corresponding access object for the pins.

Exceptions

DigitalPinConfigRangeError	The pvec and state vectors are different sizes.
PinDoesNotExist	A requested pin is not handled by this port.
DigitalPinCannotOutputError	One of the pins cannot be configured as an output.

Todo:: Are these required? A -1 could get through an access object.

Definition at line 835 of file DigitalPort.cpp.

◆ outputImpl() [1/2]

virtual void duds::hardware::interface::DigitalPort::outputImpl	(	unsigned int	lid,
		bool	state,
		DigitalPinAccessBase::PortData *	pdata
	)

protectedpure virtual

Changes the output state of the given pin.

If the pin is not configured as an output, its configuration will not change. However, this new state will be the output state once the configuration is changed to output.

Precondition: The pin is capable of output.

Parameters

lid	The local ID of the pin to change.
state	The new output state.
pdata	A pointer to the port specific data stored in the corresponding access object for the pin.

Implemented in duds::hardware::interface::linux::GpioDevPort, duds::hardware::interface::linux::SysFsPort, and duds::hardware::interface::test::VirtualPort.

Referenced by configRef(), output(), and outputImpl().

◆ outputImpl() [2/2]

void duds::hardware::interface::DigitalPort::outputImpl	(	const std::vector< unsigned int > &	pvec,
		const std::vector< bool > &	state,
		DigitalPinAccessBase::PortData *	pdata
	)

protectedvirtual

Changes the outputs of several pins.

If any of the pins are not configured as an output, thier configuration will not change. However, this new state will be the output state once the configuration is changed to output.

The implementation in DigitalPort calls output(unsigned int, bool). This only makes sense for ports that do not support simultaneous operations. An assertion exists to prevent such misuse.

Precondition: For all implementations: the vector parameters are the same size.; For all implementations: The pins are capable of output.; For this implementation only: simultaneous operations are not supported.

Parameters

pvec	The local ID of the pins to alter.
state	The new output states.
pdata	A pointer to the port specific data stored in the corresponding access object for the pins.

Reimplemented in duds::hardware::interface::linux::GpioDevPort, and duds::hardware::interface::test::VirtualPort.

Definition at line 869 of file DigitalPort.cpp.

◆ poll()

void duds::hardware::interface::DigitalPort::poll ( )

Referenced by size().

◆ pollInput()

void duds::hardware::interface::DigitalPort::pollInput ( )

Referenced by size().

◆ pollSignal()

void duds::hardware::interface::DigitalPort::pollSignal ( )

Referenced by size().

◆ portData()

static DigitalPinAccessBase::PortData& duds::hardware::interface::DigitalPort::portData ( const DigitalPinAccessBase & acc )

inlinestaticprotected

Returns a reference to the port specific data in the given DigitalPinAccessBase object.

Allows classes derived from DigitalPort access to the DigitalPinAccessBase::portdata member.

Parameters

acc	The access object with the desired data.

Returns: A reference to the port specific data. Modifications are allowed.

Definition at line 517 of file DigitalPort.hpp.

Referenced by duds::hardware::interface::linux::GpioDevPort::madeAccess().

◆ portDataPtr()

template<typename T >

static void duds::hardware::interface::DigitalPort::portDataPtr	(	const DigitalPinAccessBase &	acc,
		T **	ptr
	)

inlinestaticprotected

Provides a pointer to type T stored in the port specific data of the given DigitalPinAccessBase object.

No type checking is performed.

Template Parameters

T	The requested data type. This can normally be inferred from the ptr parameter.

Parameters

acc	The access object with the desired data.
ptr	A pointer to the pointer that will be given a copy of the pointer stored in acc.

Definition at line 532 of file DigitalPort.hpp.

Referenced by duds::hardware::interface::linux::GpioDevPort::retiredAccess().

◆ proposeConfig() [1/4]

DigitalPinRejectedConfiguration::Reason duds::hardware::interface::DigitalPort::proposeConfig	(	unsigned int	gid,
		DigitalPinConfig &	pconf,
		DigitalPinConfig &	iconf
	)		const

Proposes a configuration change for a single pin.

If the port is an implementation of DigitalPortDependentPins, the change may require altering the configuration of other pins.

Parameters

gid	The global ID of the pin to consider.
pconf	The proposed new configuration. It is modified to be what the actual configuration would be.
iconf	The proposed initial configuration. If the value is DigitalPinConfig::OperationNoChange, the current configuration of the port will be used.

Returns: The reason for rejecting the proposal, which may be NotRejected.

Exceptions

DigitalPinConfigurationError Thrown from DigitalPinCap::compatible().

Definition at line 577 of file DigitalPort.cpp.

Referenced by configurationLocalIds(), duds::hardware::interface::DigitalPinAccess::proposeConfig(), duds::hardware::interface::DigitalPinSetAccess::proposeConfig(), and proposeConfig().

◆ proposeConfig() [2/4]

DigitalPinRejectedConfiguration::Reason duds::hardware::interface::DigitalPort::proposeConfig	(	unsigned int	gid,
		DigitalPinConfig &	pconf
	)		const

inline

Proposes a configuration change for a single pin from the port's current configuration.

If the port is an implementation of DigitalPortDependentPins, the change may require altering the configuration of other pins.

Parameters

gid	The global ID of the pin to consider.
pconf	The proposed new configuration.

Returns: The reason for rejecting the proposal, which may be NotRejected.

Exceptions

DigitalPinConfigurationError Thrown from DigitalPinCap::compatible().

Definition at line 675 of file DigitalPort.hpp.

◆ proposeConfig() [3/4]

bool duds::hardware::interface::DigitalPort::proposeConfig	(	const std::vector< unsigned int > &	globalPinIds,
		std::vector< DigitalPinConfig > &	propConf,
		std::vector< DigitalPinConfig > &	initConf,
		std::function< void(DigitalPinRejectedConfiguration::Reason)>	insertReason = `std::function<void(DigitalPinRejectedConfiguration::Reason)>()`
	)		const

Exceptions

DigitalPinConfigRangeError	The number of configurations in propConf or initConf does not match the number of pins in localPinIds. An empty initConf will not cause this exception.
DigitalPinConfigurationError	Thrown from DigitalPinCap::compatible().

Definition at line 587 of file DigitalPort.cpp.

◆ proposeConfig() [4/4]

bool duds::hardware::interface::DigitalPort::proposeConfig	(	const std::vector< unsigned int > &	pins,
		std::vector< DigitalPinConfig > &	propConf,
		std::function< void(DigitalPinRejectedConfiguration::Reason)>	insertReason = `std::function<void(DigitalPinRejectedConfiguration::Reason)>()`
	)		const

inline

Definition at line 706 of file DigitalPort.hpp.

◆ proposeConfigImpl() [1/2]

virtual DigitalPinRejectedConfiguration::Reason duds::hardware::interface::DigitalPort::proposeConfigImpl	(	unsigned int	gid,
		DigitalPinConfig &	pconf,
		DigitalPinConfig &	iconf
	)		const

protectedpure virtual

Implemented in duds::hardware::interface::DigitalPortDependentPins, and duds::hardware::interface::DigitalPortIndependentPins.

Referenced by configRef(), proposeConfig(), and proposeConfigLocalIds().

◆ proposeConfigImpl() [2/2]

virtual bool duds::hardware::interface::DigitalPort::proposeConfigImpl	(	const std::vector< unsigned int > &	localPinIds,
		std::vector< DigitalPinConfig > &	propConf,
		std::vector< DigitalPinConfig > &	initConf,
		std::function< void(DigitalPinRejectedConfiguration::Reason)>	insertReason = `std::function< void(DigitalPinRejectedConfiguration::Reason)>()`
	)		const

protectedpure virtual

Implemented in duds::hardware::interface::DigitalPortDependentPins, and duds::hardware::interface::DigitalPortIndependentPins.

◆ proposeConfigLocalIds() [1/2]

bool duds::hardware::interface::DigitalPort::proposeConfigLocalIds	(	const std::vector< unsigned int > &	localPinIds,
		std::vector< DigitalPinConfig > &	propConf,
		std::vector< DigitalPinConfig > &	initConf,
		std::function< void(DigitalPinRejectedConfiguration::Reason)>	insertReason = `std::function<void(DigitalPinRejectedConfiguration::Reason)>()`
	)		const

Definition at line 600 of file DigitalPort.cpp.

Referenced by duds::hardware::interface::DigitalPinSetAccess::proposeConfig(), proposeConfig(), and proposeConfigLocalIds().

◆ proposeConfigLocalIds() [2/2]

bool duds::hardware::interface::DigitalPort::proposeConfigLocalIds	(	const std::vector< unsigned int > &	pins,
		std::vector< DigitalPinConfig > &	propConf,
		std::function< void(DigitalPinRejectedConfiguration::Reason)>	insertReason = `std::function<void(DigitalPinRejectedConfiguration::Reason)>()`
	)		const

inline

Definition at line 715 of file DigitalPort.hpp.

◆ proposeFullConfig()

bool duds::hardware::interface::DigitalPort::proposeFullConfig	(	std::vector< DigitalPinConfig > &	propConf,
		std::vector< DigitalPinConfig > &	initConf,
		std::function< void(DigitalPinRejectedConfiguration::Reason)>	insertReason = `std::function<void(DigitalPinRejectedConfiguration::Reason)>()`
	)		const

Definition at line 611 of file DigitalPort.cpp.

Referenced by proposeConfigLocalIds().

◆ proposeFullConfigImpl()

virtual bool duds::hardware::interface::DigitalPort::proposeFullConfigImpl	(	std::vector< DigitalPinConfig > &	propConf,
		std::vector< DigitalPinConfig > &	initConf,
		std::function< void(DigitalPinRejectedConfiguration::Reason)>	insertReason = `std::function< void(DigitalPinRejectedConfiguration::Reason)>()`
	)		const

protectedpure virtual

Implemented in duds::hardware::interface::DigitalPortDependentPins, and duds::hardware::interface::DigitalPortIndependentPins.

Referenced by configRef(), modifyFullConfig(), and proposeFullConfig().

◆ retiredAccess() [1/2]

void duds::hardware::interface::DigitalPort::retiredAccess ( const DigitalPinAccess & acc )

protectedvirtualnoexcept

Called just before an access object is retired to allow a port implementation to take further action.

The call is made while there is a lock on block. The default implementation does nothing.

Parameters

acc	The access object that will be retired.

Reimplemented in duds::hardware::interface::linux::GpioDevPort.

Definition at line 156 of file DigitalPort.cpp.

Referenced by configRef(), and updateAccess().

◆ retiredAccess() [2/2]

void duds::hardware::interface::DigitalPort::retiredAccess ( const DigitalPinSetAccess & acc )

protectedvirtualnoexcept

Called just before an access object is retired to allow a port implementation to take further action.

The call is made while there is a lock on block. The default implementation does nothing.

Parameters

acc	The access object that will be retired.

Reimplemented in duds::hardware::interface::linux::GpioDevPort.

Definition at line 158 of file DigitalPort.cpp.

◆ shutdown()

void duds::hardware::interface::DigitalPort::shutdown ( )

protected

Waits for access to all pins so that any user of access objects may finish with their operation, then destroys all pin data and awakens threads waiting on access, but they will not receive access.

This function should be called early, likely first, in the destructors of derived classes. This will allow operations in progress to complete.

This function is not called in ~DigitalPort(). By that time, the derived implementation will have destructed, which will prevent any access object from working properly. The access objects must be destroyed before then to avoid bad behavior, such as a process crash.

Definition at line 20 of file DigitalPort.cpp.

Referenced by duds::hardware::interface::linux::GpioDevPort::~GpioDevPort(), duds::hardware::interface::linux::SysFsPort::~SysFsPort(), and duds::hardware::interface::test::VirtualPort::~VirtualPort().

◆ shutdownAccessRequests()

void duds::hardware::interface::DigitalPort::shutdownAccessRequests ( )

private

Used by the shutdown functions to force any thread waiting on access to pins to quit waiting and fail to get access.

◆ simultaneousOperations()

virtual bool duds::hardware::interface::DigitalPort::simultaneousOperations ( ) const

pure virtual

True if the implementation supports operating on multiple pins simultaneously.

If false, the interfaces for operating on multiple pins will still be available, but the pins may be modified on over a period of time in an implementation defined order.

Implemented in duds::hardware::interface::linux::GpioDevPort, duds::hardware::interface::linux::SysFsPort, and duds::hardware::interface::test::VirtualPort.

Referenced by inputImpl(), outputImpl(), and duds::hardware::interface::DigitalPinSetAccess::simultaneousOperations().

◆ size()

unsigned int duds::hardware::interface::DigitalPort::size ( ) const

inline

The maximum number of pins on the port.

There may be fewer pins because not all pin IDs from offset() to (offset() + size()) may be populated.

Definition at line 789 of file DigitalPort.hpp.

◆ updateAccess() [1/2]

void duds::hardware::interface::DigitalPort::updateAccess	(	const DigitalPinAccess &	oldAcc,
		DigitalPinAccess *	newAcc
	)

private

Transfers or relinquishes access to pins.

Parameters

oldAcc	The access object that still has access.
newAcc	A pointer to the access object to which access will be transfered, or nullptr if access is relinquished.

Postcondition: Internal port data is updated for either newAcc to have access, or the pins to be available. If available, any threads waiting on access will be notified. oldAcc must either be destroyed or modified to no longer claim access. newAcc, if not nullptr, must be updated to claim access.

Definition at line 369 of file DigitalPort.cpp.

Referenced by access(), duds::hardware::interface::DigitalPinAccess::retire(), and duds::hardware::interface::DigitalPinSetAccess::retire().

◆ updateAccess() [2/2]

void duds::hardware::interface::DigitalPort::updateAccess	(	const DigitalPinSetAccess &	oldAcc,
		DigitalPinSetAccess *	newAcc
	)

private

Transfers or relinquishes access to pins.

Parameters

oldAcc	The access object that still has access.
newAcc	A pointer to the access object to which access will be transfered, or nullptr if access is relinquished.

Postcondition: Internal port data is updated for either newAcc to have access, or the pins to be available. If available, any threads waiting on access will be notified. oldAcc must either be destroyed or modified to no longer claim access. newAcc, if not nullptr, must be updated to claim access.

Definition at line 398 of file DigitalPort.cpp.

◆ waitForAvailability()

void duds::hardware::interface::DigitalPort::waitForAvailability	(	std::unique_lock< std::mutex > &	lock,
		const unsigned int *const	reqpins,
		const std::size_t	len
	)

private

Waits for all pins to become available.

Precondition: lock has a lock on block.

Definition at line 136 of file DigitalPort.cpp.

Referenced by access(), and shutdown().

Member Data Documentation

◆ block

std::mutex duds::hardware::interface::DigitalPort::block

mutableprivate

Used to serialize access to internal data for thread-safe operation.

Todo:: Consider blocking access to port config and port I/O separately.

Definition at line 55 of file DigitalPort.hpp.

Referenced by access(), capabilities(), configuration(), exists(), input(), modifyConfig(), output(), proposeConfig(), proposeConfigLocalIds(), proposeFullConfig(), shutdown(), and updateAccess().

◆ DigitalPinAccess

friend duds::hardware::interface::DigitalPort::DigitalPinAccess

private

Definition at line 60 of file DigitalPort.hpp.

Referenced by access().

◆ DigitalPinSetAccess

friend duds::hardware::interface::DigitalPort::DigitalPinSetAccess

private

Definition at line 61 of file DigitalPort.hpp.

Referenced by access().

◆ idOffset

unsigned int duds::hardware::interface::DigitalPort::idOffset

private

An offset used to translate pin identification numbers between global scope and local scope.

The local scope numbers always start at zero.

Definition at line 120 of file DigitalPort.hpp.

Referenced by globalId(), localId(), offset(), and shutdown().

◆ pins

PinVector duds::hardware::interface::DigitalPort::pins

protected

Data on each pin handled by the port.

The index of each pin is the local pin ID.

Definition at line 114 of file DigitalPort.hpp.

◆ pinwait

std::condition_variable duds::hardware::interface::DigitalPort::pinwait

private

Used to efficently wait for resources to become available.

Definition at line 59 of file DigitalPort.hpp.

Referenced by areAvailable(), shutdown(), updateAccess(), and waitForAvailability().

◆ waiting

int duds::hardware::interface::DigitalPort::waiting

private

A count of the threads waiting to access pins.

Note: This should only be modifid when block is locked.

Definition at line 125 of file DigitalPort.hpp.

Referenced by areAvailable(), shutdown(), updateAccess(), and waitForAvailability().

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

Classes

Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ PinVector

Constructor & Destructor Documentation

◆ DigitalPort()

◆ ~DigitalPort()

Member Function Documentation

◆ access() [1/11]

◆ access() [2/11]

◆ access() [3/11]

◆ access() [4/11]

◆ access() [5/11]

◆ access() [6/11]

◆ access() [7/11]

◆ access() [8/11]

◆ access() [9/11]

◆ access() [10/11]

◆ access() [11/11]

◆ areAvailable()

◆ capabilities() [1/4]

◆ capabilities() [2/4]

◆ capabilities() [3/4]

◆ capabilities() [4/4]

◆ capabilitiesLocalIds()

◆ configRef()

◆ configuration() [1/4]

◆ configuration() [2/4]

◆ configuration() [3/4]

◆ configuration() [4/4]

◆ configurationImpl()

◆ configurationLocalIds()

◆ configurePort() [1/2]

◆ configurePort() [2/2]

◆ exists()

◆ globalId()

◆ globalIds()

◆ independentConfig() [1/2]

◆ independentConfig() [2/2]

◆ input() [1/2]

◆ input() [2/2]

◆ inputImpl() [1/2]

◆ inputImpl() [2/2]

◆ localId()

◆ localIds()

◆ madeAccess() [1/2]

◆ madeAccess() [2/2]

◆ modifyConfig() [1/3]

◆ modifyConfig() [2/3]

◆ modifyConfig() [3/3]

◆ modifyFullConfig()

◆ offset()

◆ output() [1/2]

◆ output() [2/2]

◆ outputImpl() [1/2]

◆ outputImpl() [2/2]

◆ poll()

◆ pollInput()

◆ pollSignal()

◆ portData()

◆ portDataPtr()

◆ proposeConfig() [1/4]

◆ proposeConfig() [2/4]

◆ proposeConfig() [3/4]

◆ proposeConfig() [4/4]

◆ proposeConfigImpl() [1/2]

◆ proposeConfigImpl() [2/2]

◆ proposeConfigLocalIds() [1/2]

◆ proposeConfigLocalIds() [2/2]

◆ proposeFullConfig()

◆ proposeFullConfigImpl()

◆ retiredAccess() [1/2]

◆ retiredAccess() [2/2]