The base class for all chip selection managers, the classes that handle the output state to select a chip. More...

#include <ChipSelectManager.hpp>

Inheritance diagram for duds::hardware::interface::ChipSelectManager:

Collaboration diagram for duds::hardware::interface::ChipSelectManager:

Public Member Functions
	ChipSelectManager ()

virtual	~ChipSelectManager ()=0
	Derived non-abstract classes must call shutdown() in thier destructor. More...

std::unique_ptr< ChipAccess >	access (int chipId)
	Acquires access to the requested chip and issues a ChipAccess object. More...

void	access (ChipAccess &acc, int chipId)
	Acquires access to the requested chip and modifies an existing ChipAccess object to provide that access. More...

bool	inUse () const
	Returns true if an access object provided by this manager exists. More...

std::unique_ptr< ChipAccess >	select (int chipId)
	Selects the requested chip and issues a ChipAccess object. More...

void	select (ChipAccess &acc, int chipId)
	Selects the requested chip and modifies a ChipAccess object to further control chip selection. More...

virtual bool	validChip (int chipId) const noexcept=0
	Returns true if chipId references a valid chip for this manager. More...

Protected Member Functions
void	baseAccess (std::unique_lock< std::mutex > &lock, int chipId)
	Obtains the resources for providing an access object, but does not make an access object. More...

void	changeChip (int chipId)
	Changes the chip in use while continuing to use an existing access object. More...

virtual void	deselect ()=0
	Deselects the chip identified by cid. More...

virtual void	select ()=0
	Selects the chip identified by cid. More...

void	shutdown ()
	Waits on a ChipAccess object if one is in use, then begins forcing any threads waiting on access to wake up and throw exceptions. More...

Protected Attributes
std::mutex	block
	Used to synchonize access. More...

int	cid
	Selected chip ID, or -1 to terminate. More...

Private Member Functions
void	retire (ChipAccess *ca)
	Called by ChipAccess::~ChipAccess() to indicate that the access object is no longer in use, freeing the manager to offer access to other users. More...

Private Attributes
ChipAccess *	curacc
	The currently in use access object, or nullptr. More...

std::condition_variable	selwait
	Used to awaken threads waiting on a chip select. More...

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

Friends
class	ChipAccess
	The access object calls select(), deselect(), and retire(ChipAccess *). More...

Detailed Description

The base class for all chip selection managers, the classes that handle the output state to select a chip.

Each manager can select no more than one chip at a time. They must be thread-safe. They must either be able to select no chip, or designate a default chip. When destructed, they must select the default chip or deselect all chips. A chip identifier must be either invalid or have a 1-to-1 relation with the valid chips. Valid chip identifiers must have a value of zero or greater; negative values are reserved to signal manager termination and other conditions. Any changes to the set of valid chips or to which chip an identifier references must not happen while an access object is active; see ChipPinSelectManager for an implementation example.

Warning: Any required DigitalPinAccess objects for an operation should be acquired before any ChipAccess objects are needed for a single operation. This ordering is used by this library. Using a different ordering risks a deadlock.

Author: Jeff Jackowski

Definition at line 42 of file ChipSelectManager.hpp.

Constructor & Destructor Documentation

◆ ChipSelectManager()

duds::hardware::interface::ChipSelectManager::ChipSelectManager ( )

Definition at line 16 of file ChipSelectManager.cpp.

◆ ~ChipSelectManager()

duds::hardware::interface::ChipSelectManager::~ChipSelectManager ( )

pure virtual

Derived non-abstract classes must call shutdown() in thier destructor.

This destructor only exists to avoid great badness and does nothing itself.

Definition at line 18 of file ChipSelectManager.cpp.

Member Function Documentation

◆ access() [1/2]

std::unique_ptr< ChipAccess > duds::hardware::interface::ChipSelectManager::access ( int chipId )

Acquires access to the requested chip and issues a ChipAccess object.

The chip is not selected; use ChipAccess::select() to select the chip. If another chip is currently in use, this function will block until the associated ChipAccess object is destroyed.

Warning: Attempting to select two chips from the same ChipSelectManager on the same thread will cause a deadlock.

Parameters

chipId The number identifying the chip to select.

Returns: A ChipAccess object intended for use like a scoped lock object; when it is destroyed, the chip will be deselected.

Exceptions

ChipSelectInvalidChip	The given chipId is invalid. The exception will include the ChipSelectId attribute with the requested chip ID.
ObjectDestructedError	The manager object was destructed before the access object could be obtained.

Definition at line 98 of file ChipSelectManager.cpp.

Referenced by inUse(), and select().

◆ access() [2/2]

void duds::hardware::interface::ChipSelectManager::access	(	ChipAccess &	acc,
		int	chipId
	)

Acquires access to the requested chip and modifies an existing ChipAccess object to provide that access.

The chip is not selected; use ChipAccess::select() to select the chip. If another chip is currently in use, this function will block until the associated ChipAccess object is destroyed.

Precondition: acc is not providing access to any ChipSelectManager.

Warning: Attempting to select two chips from the same ChipSelectManager on the same thread will cause a deadlock.

Parameters

acc	The ChipAccess object that will be modified to provide access to chip selection.
chipId	The number identifying the chip to select.

Exceptions

ChipSelectAccessInUse	The given ChipAccess object, acc, is already providing access to a ChipSelectManager.
ChipSelectInvalidChip	The given chipId is invalid. The exception will include the ChipSelectId attribute with the requested chip ID.
ObjectDestructedError	The manager object was destructed before the access object could be obtained.

Definition at line 108 of file ChipSelectManager.cpp.

◆ baseAccess()

void duds::hardware::interface::ChipSelectManager::baseAccess	(	std::unique_lock< std::mutex > &	lock,
		int	chipId
	)

protected

Obtains the resources for providing an access object, but does not make an access object.

Precondition: The caller has a lock on block.

Definition at line 74 of file ChipSelectManager.cpp.

Referenced by access().

◆ changeChip()

void duds::hardware::interface::ChipSelectManager::changeChip ( int chipId )

protected

Changes the chip in use while continuing to use an existing access object.

If the chip is the same as the one already in use, nothing happens. If it is different, the validity of the new ID is checked, and if good, deselect() is called to deselect the current chip, then the new ID is recorded.

Parameters

chipId The ID of the chip to use.

Exceptions

ChipSelectInvalidChip	The given chipId is invalid. The exception will include the ChipSelectId attribute with the requested chip ID. No changes will be made to the current chip selection state.
ChipSelectInvalidAccess	There is currently no access object for this manager.

Definition at line 54 of file ChipSelectManager.cpp.

◆ deselect()

virtual void duds::hardware::interface::ChipSelectManager::deselect ( )

protectedpure virtual

Deselects the chip identified by cid.

If the chip is already deselected, it must remain deselected.

Note: There is no need for thread synchronization in this function.

Implemented in duds::hardware::interface::ChipPinSelectManager, duds::hardware::interface::ChipBinarySelectManager, duds::hardware::interface::ChipPinSetSelectManager, and duds::hardware::interface::ChipMultiplexerSelectManager.

Referenced by changeChip(), and retire().

◆ inUse()

bool duds::hardware::interface::ChipSelectManager::inUse ( ) const

inline

Returns true if an access object provided by this manager exists.

Definition at line 136 of file ChipSelectManager.hpp.

Referenced by duds::hardware::interface::ChipMultiplexerSelectManager::releaseAccess(), duds::hardware::interface::ChipMultiplexerSelectManager::setAccess(), duds::hardware::interface::ChipBinarySelectManager::setSelectPin(), duds::hardware::interface::ChipPinSelectManager::setSelectPin(), and duds::hardware::interface::ChipPinSetSelectManager::setSelectPins().

◆ retire()

void duds::hardware::interface::ChipSelectManager::retire ( ChipAccess * ca )

private

Called by ChipAccess::~ChipAccess() to indicate that the access object is no longer in use, freeing the manager to offer access to other users.

Exceptions

ChipSelectInvalidAccess The given access object, ca, is not the active one for this manager, curacc.

Definition at line 40 of file ChipSelectManager.cpp.

◆ select() [1/3]

virtual void duds::hardware::interface::ChipSelectManager::select ( )

protectedpure virtual

Selects the chip identified by cid.

If the chip is already selected, it must remain selected.

Note: There is no need for thread synchronization in this function.

Implemented in duds::hardware::interface::ChipPinSelectManager, duds::hardware::interface::ChipBinarySelectManager, duds::hardware::interface::ChipPinSetSelectManager, and duds::hardware::interface::ChipMultiplexerSelectManager.

Referenced by inUse(), and select().

◆ select() [2/3]

std::unique_ptr< ChipAccess > duds::hardware::interface::ChipSelectManager::select ( int chipId )

Selects the requested chip and issues a ChipAccess object.

If another chip is currently in use, this function will block until the associated ChipAccess object is destroyed.

Warning: Attempting to select two chips from the same ChipSelectManager on the same thread will cause a deadlock.

Parameters

chipId The number identifying the chip to select.

Returns: A ChipAccess object intended for use like a scoped lock object; when it is destroyed, the chip will be deselected.

Exceptions

ChipSelectInvalidChip	The given chipId is invalid. The exception will include the ChipSelectId attribute with the requested chip ID.
ObjectDestructedError	The manager object was destructed before the access object could be obtained.

Definition at line 120 of file ChipSelectManager.cpp.

◆ select() [3/3]

void duds::hardware::interface::ChipSelectManager::select	(	ChipAccess &	acc,
		int	chipId
	)

Selects the requested chip and modifies a ChipAccess object to further control chip selection.

If another chip is currently in use, this function will block until the associated ChipAccess object is destroyed.

Precondition: acc is not providing access to any ChipSelectManager.

Warning: Attempting to select two chips from the same ChipSelectManager on the same thread will cause a deadlock.

Parameters

acc	The ChipAccess object that will be modified to provide access to chip selection.
chipId	The number identifying the chip to select.

Exceptions

ChipSelectAccessInUse	The given ChipAccess object, acc, is already providing access to a ChipSelectManager.
ChipSelectInvalidChip	The given chipId is invalid. The exception will include the ChipSelectId attribute with the requested chip ID.
ObjectDestructedError	The manager object was destructed before the access object could be obtained.

Definition at line 126 of file ChipSelectManager.cpp.

◆ shutdown()

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

protected

Waits on a ChipAccess object if one is in use, then begins forcing any threads waiting on access to wake up and throw exceptions.

This must be called in the destructor of non-abstract implementations of ChipSelectManager.

Definition at line 20 of file ChipSelectManager.cpp.

Referenced by duds::hardware::interface::ChipBinarySelectManager::~ChipBinarySelectManager(), duds::hardware::interface::ChipPinSelectManager::~ChipPinSelectManager(), and duds::hardware::interface::ChipPinSetSelectManager::~ChipPinSetSelectManager().

◆ validChip()

virtual bool duds::hardware::interface::ChipSelectManager::validChip ( int chipId ) const

pure virtualnoexcept

Returns true if chipId references a valid chip for this manager.

All negative values must be considered invalid by all managers. Any non-negative value may be considered valid at the manager's discretion.

Warning: This function must not lock block. Doing so will cause access() to hang in a deadlock.

Parameters

chipId The chip identifier that will be checked for validity. The id must either be invalid or reference exactly one chip.

Returns: True if chipId references a chip.

Implemented in duds::hardware::interface::ChipPinSelectManager, duds::hardware::interface::ChipBinarySelectManager, duds::hardware::interface::ChipPinSetSelectManager, and duds::hardware::interface::ChipMultiplexerSelectManager.

Referenced by baseAccess(), changeChip(), and inUse().

Friends And Related Function Documentation

◆ ChipAccess

friend class ChipAccess

friend

The access object calls select(), deselect(), and retire(ChipAccess *).

Definition at line 47 of file ChipSelectManager.hpp.

Referenced by access().

Member Data Documentation

◆ block

std::mutex duds::hardware::interface::ChipSelectManager::block

protected

Used to synchonize access.

Any changes that affect the set of valid chip IDs should occur when this semaphore is locked, or inside a derived class's constructor.

Definition at line 54 of file ChipSelectManager.hpp.

Referenced by access(), changeChip(), duds::hardware::interface::ChipMultiplexerSelectManager::releaseAccess(), duds::hardware::interface::ChipMultiplexerSelectManager::setAccess(), duds::hardware::interface::ChipBinarySelectManager::setSelectPin(), duds::hardware::interface::ChipPinSelectManager::setSelectPin(), duds::hardware::interface::ChipPinSetSelectManager::setSelectPins(), and shutdown().

◆ cid

int duds::hardware::interface::ChipSelectManager::cid

protected

Selected chip ID, or -1 to terminate.

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

Definition at line 83 of file ChipSelectManager.hpp.

◆ curacc

ChipAccess* duds::hardware::interface::ChipSelectManager::curacc

private

The currently in use access object, or nullptr.

I AM CURACC!

Definition at line 64 of file ChipSelectManager.hpp.

Referenced by access(), baseAccess(), changeChip(), inUse(), retire(), and shutdown().

◆ selwait

std::condition_variable duds::hardware::interface::ChipSelectManager::selwait

private

Used to awaken threads waiting on a chip select.

Definition at line 59 of file ChipSelectManager.hpp.

Referenced by baseAccess(), retire(), and shutdown().

◆ waiting

int duds::hardware::interface::ChipSelectManager::waiting

private

A count of the threads waiting to access chips.

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

Definition at line 69 of file ChipSelectManager.hpp.

Referenced by baseAccess(), and shutdown().

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

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ ChipSelectManager()

◆ ~ChipSelectManager()

Member Function Documentation

◆ access() [1/2]

◆ access() [2/2]

◆ baseAccess()

◆ changeChip()

◆ deselect()

◆ inUse()

◆ retire()

◆ select() [1/3]

◆ select() [2/3]

◆ select() [3/3]

◆ shutdown()

◆ validChip()

Friends And Related Function Documentation

◆ ChipAccess

Member Data Documentation

◆ block

◆ cid

◆ curacc

◆ selwait

◆ waiting