Parses configuration data for DigitalPort, DigitalPin, DigitalPinSet, ChipSelectManager, and ChipSelect objects. More...

#include <PinConfiguration.hpp>

Collaboration diagram for duds::hardware::interface::PinConfiguration:

[legend]

Classes
struct	ChipSel
	Holds configuration data for a single chip select. More...

struct	index_gid
	Index in type Pins that is sorted by pin global ID. More...

struct	index_name
	Index in type Pins that is sorted by the optional pin name. More...

struct	index_pid
	Index in type Pins that is sorted by pin port ID. More...

struct	index_seq
	Index in type Pins that is maintained by parsing order. More...

struct	Pin
	Holds configuration data for a single digital I/O pin. More...

struct	PinSet
	Holds configuration data for a single digital pin set. More...

struct	Port
	Holds configuration data for a single digital port. More...

struct	SelMgr
	Holds configuration data for a single chip select manager. More...

Public Types
typedef std::unordered_map< std::string, ChipSel >	ChipSelMap

typedef boost::multi_index::multi_index_container< Pin, boost::multi_index::indexed_by< boost::multi_index::ordered_non_unique< boost::multi_index::tag< index_gid >, boost::multi_index::member< Pin, unsigned int, &Pin::gid > >, boost::multi_index::ordered_non_unique< boost::multi_index::tag< index_pid >, boost::multi_index::member< Pin, unsigned int, &Pin::pid > >, boost::multi_index::hashed_non_unique< boost::multi_index::tag< index_name >, boost::multi_index::member< Pin, std::string, &Pin::name > >, boost::multi_index::sequenced< boost::multi_index::tag< index_seq > > > >	Pins
	Holds the configuration data for digital pins indexed by global ID, port ID, arbitrary name, and order in the configuration file. More...

typedef std::unordered_map< std::string, PinSet >	PinSetMap

typedef std::unordered_map< std::string, Port >	PortMap

typedef std::unordered_map< std::string, SelMgr >	SelMgrMap

Public Member Functions
	PinConfiguration ()=default
	Make an empty configuration. More...

	PinConfiguration (const boost::property_tree::ptree &pt)
	Constructs and parses the pin configuration that starts at the given subtree. More...

void	attachPort (const std::shared_ptr< DigitalPort > &dp, const std::string &name="default")
	Attaches the given DigitalPort to the named port in the configuration. More...

const ChipSel &	chipSelect (const std::string &name) const
	Finds the configuration data for the named ChipSelect. More...

DigitalPin	getPin (const std::string &pinName) const
	Makes a DigitalPin object for the named pin in the configuration. More...

bool	getPin (DigitalPin &dest, const std::string &pinName) const
	Changes a DigitalPin object to represent the named pin in the configuration. More...

const DigitalPinSet &	getPinSet (const std::string &setName) const
	Gets the DigitalPinSet object named in the configuration. More...

void	getPinSetAndSelect (DigitalPinSet &dpset, ChipSelect &sel, const std::string &setName) const
	Gets the DigitalPinSet and ChipSelect objects that are attached to the named set configuration. More...

const ChipSelect &	getSelect (const std::string &selName) const
	Gets the ChipSelect object named in the configuration. More...

bool	haveChipSelect (const std::string &name) const
	True if the named chip select has been found in the already parsed configuration. More...

bool	havePin (const std::string &pinName) const
	Returns true if the named pin is in the configuration. More...

void	parse (const boost::property_tree::ptree &pt)
	Parses the pin configuration that starts at the given subtree. More...

const Pin &	pin (const std::string &str) const
	Finds the pin from the given name or global ID according to this pin configuration. More...

unsigned int	pinGlobalId (const std::string &str) const
	Finds the global ID of the given pin according to this pin configuration. More...

const PinSet &	pinSet (const std::string &name) const
	Finds the configuration data for the named DigitalPinSet. More...

PinSetMap::const_iterator	pinSetsBegin () const
	Begining iterator to inspect the pin sets in the configuration. More...

PinSetMap::const_iterator	pinSetsEnd () const
	Ending iterator to inspect the pin sets in the configuration. More...

const Port &	port (const std::string &name="default") const
	Finds the configuration data for the named DigitalPort. More...

PortMap::const_iterator	portsBegin () const
	Begining iterator to inspect the ports in the configuration. More...

PortMap::const_iterator	portsEnd () const
	Ending iterator to inspect the ports in the configuration. More...

const SelMgr &	selectManager (const std::string &name) const
	Finds the configuration data for the named ChipSelectManager. More...

SelMgrMap::const_iterator	selectManagersBegin () const
	Begining iterator to inspect the select managers in the configuration. More...

SelMgrMap::const_iterator	selectManagersEnd () const
	Ending iterator to inspect the select managers in the configuration. More...

ChipSelMap::const_iterator	selectsBegin () const
	Begining iterator to inspect the chip selects in the configuration. More...

ChipSelMap::const_iterator	selectsEnd () const
	Ending iterator to inspect the chip selects in the configuration. More...

Private Attributes
Pins	allpins
	All pins mentioned in the confiuration across all ports. More...

ChipSelMap	chipSels
	Chip select configurations stored by name. More...

PinSetMap	pinSets
	Pin set configurations stored by name. More...

PortMap	ports
	Port configurations stored by name. More...

SelMgrMap	selMgrs
	Select manager configurations stored by name. More...

Detailed Description

Parses configuration data for DigitalPort, DigitalPin, DigitalPinSet, ChipSelectManager, and ChipSelect objects.

The configuration data can be inspected without creating any of the objects to be configured, and thus without accessing the hardware affected by the configuration. Separate from this object, a DigitalPort must be created. The port to configure must be attached to this configuration by a call to attachPort(). This will create all the other objects listed in the configuration. Those objects can be found by querying for their name.

The configuration tree is documented in Property tree file data.

Intended usage follows this order:

Parse a configuration file with boost::property_tree.
Construct a PinConfiguration and give it a subtree from the parsed configuration.
Make a suitable DigitalPort object.
Attach the DigitalPort to the PinConfiguration.
Query the PinConfiguration for the needed objects by name.
The PinConfiguration may be destroyed when it no longer needs to be queried.

Boost property tree is used to parse and represnt data prior to passing that data to this object. See the Digital Pin Configuration page for detailed documentation on what is expected of the property tree.

This object is not thread-safe during parsing. When parsing is not underway, all queries are thread-safe.

Author: Jeff Jackowski

Examples:: bppmenu.cpp, clockLCD.cpp, pinconfig.cpp, rendertext.cpp, and st7920.cpp.

Definition at line 187 of file PinConfiguration.hpp.

Member Typedef Documentation

◆ ChipSelMap

typedef std::unordered_map<std::string, ChipSel> duds::hardware::interface::PinConfiguration::ChipSelMap

Definition at line 433 of file PinConfiguration.hpp.

◆ Pins

typedef boost::multi_index::multi_index_container< Pin, boost::multi_index::indexed_by< boost::multi_index::ordered_non_unique< boost::multi_index::tag<index_gid>, boost::multi_index::member<Pin, unsigned int, &Pin::gid> >, boost::multi_index::ordered_non_unique< boost::multi_index::tag<index_pid>, boost::multi_index::member<Pin, unsigned int, &Pin::pid> >, boost::multi_index::hashed_non_unique< boost::multi_index::tag<index_name>, boost::multi_index::member<Pin, std::string, &Pin::name> >, boost::multi_index::sequenced< boost::multi_index::tag<index_seq> > > > duds::hardware::interface::PinConfiguration::Pins

Holds the configuration data for digital pins indexed by global ID, port ID, arbitrary name, and order in the configuration file.

Definition at line 285 of file PinConfiguration.hpp.

◆ PinSetMap

typedef std::unordered_map<std::string, PinSet> duds::hardware::interface::PinConfiguration::PinSetMap

Definition at line 476 of file PinConfiguration.hpp.

◆ PortMap

typedef std::unordered_map<std::string, Port> duds::hardware::interface::PinConfiguration::PortMap

Definition at line 341 of file PinConfiguration.hpp.

◆ SelMgrMap

typedef std::unordered_map<std::string, SelMgr> duds::hardware::interface::PinConfiguration::SelMgrMap

Definition at line 411 of file PinConfiguration.hpp.

Constructor & Destructor Documentation

◆ PinConfiguration() [1/2]

duds::hardware::interface::PinConfiguration::PinConfiguration ( )

default

Make an empty configuration.

◆ PinConfiguration() [2/2]

duds::hardware::interface::PinConfiguration::PinConfiguration ( const boost::property_tree::ptree & pt )

Constructs and parses the pin configuration that starts at the given subtree.

Boost property tree is used to parse and represnt data prior to passing that data to this object. See the Digital Pin Configuration page for detailed documentation on what is expected of the property tree.

Parameters

pt	The property tree node that is the parent of all the pin configuration nodes. No boost::property_tree::ptree objects are retained in this class.

Exceptions

PortDuplicateError
SelectManagerDuplicateError
SetDuplicateError
PinBadIdError
PortDuplicatePinIdError
SelectBadStateError
SelectManagerUnknownTypeError
SelectDuplicateError
SelectNoPinsError
SelectMultiplePortsError
SetMultiplePortsError
SelectDoesNotExistError

Definition at line 394 of file PinConfiguration.cpp.

Member Function Documentation

◆ attachPort()

void duds::hardware::interface::PinConfiguration::attachPort	(	const std::shared_ptr< DigitalPort > &	dp,
		const std::string &	name = `"default"`
	)

Attaches the given DigitalPort to the named port in the configuration.

The port must be configured to have or not have the pins explicitly listed in the configuration. After checking that, objects in the configuration that need the port are created.

Precondition: Configuration parsing has already been done successfully.

Parameters

dp	The DigitalPort to attach to the configuration.
name	The name given to the port in the configuration.

Exceptions

DigitalPortDoesNotExistError	dp is empty.
PortDoesNotExistError	The configuration does not have a port with the given name.
DigitalPortHasPinError	A pin configured with the port ID of "none" exists in the given port.
DigitalPortLacksPinError	A pin configured to exist is missing from the given port.

Definition at line 471 of file PinConfiguration.cpp.

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

◆ chipSelect()

const PinConfiguration::ChipSel & duds::hardware::interface::PinConfiguration::chipSelect ( const std::string & name ) const

Finds the configuration data for the named ChipSelect.

Parameters

name	The name given to the chip select in the configuration.

Precondition: Configuration parsing has already been done successfully. ChipSel::sel will only be valid after its required port has been attached.

Exceptions

SelectDoesNotExistError The requested chip select is not defined in the configuration data.

Definition at line 599 of file PinConfiguration.cpp.

◆ getPin() [1/2]

DigitalPin duds::hardware::interface::PinConfiguration::getPin ( const std::string & pinName ) const

Makes a DigitalPin object for the named pin in the configuration.

Precondition: A configuration has been successfully parsed, and the DigitalPort object that handles the pin has been attached.

Parameters

pinName The name of the pin in the configuration.

Returns: The new DigitalPin object.

Exceptions

PinBadIdError	The configuration does not define a pin with the given name.
PortDoesNotExistError	The port that supplies the pin has not been attached to this configuration.
PinDoesNotExist	The attched DigitalPort object claims to not have the pin.

Definition at line 680 of file PinConfiguration.cpp.

◆ getPin() [2/2]

bool duds::hardware::interface::PinConfiguration::getPin	(	DigitalPin &	dest,
		const std::string &	pinName
	)		const

Changes a DigitalPin object to represent the named pin in the configuration.

Precondition: A configuration has been successfully parsed, and the DigitalPort object that handles the pin has been attached.

Parameters

dest	The DigitalPin to update. It will not represent any pin if the pin is not found.
pinName	The name of the pin in the configuration.

Returns: True if the nanmed pin was found, false otherwise.

Definition at line 696 of file PinConfiguration.cpp.

◆ getPinSet()

const DigitalPinSet & duds::hardware::interface::PinConfiguration::getPinSet ( const std::string & setName ) const

Gets the DigitalPinSet object named in the configuration.

Precondition: A configuration has been successfully parsed, and the DigitalPort object needed for the set has been attached.

Parameters

setName The name given to the pin set in the configuration.

Exceptions

SetDoesNotExistError	The requested set is not defined in the configuration data.
SetNotCreatedError	The requested set has not yet been created. This most likely means that the port providing its pins hasn't been attached by a call to attachPort().

Definition at line 654 of file PinConfiguration.cpp.

◆ getPinSetAndSelect()

void duds::hardware::interface::PinConfiguration::getPinSetAndSelect	(	DigitalPinSet &	dpset,
		ChipSelect &	sel,
		const std::string &	setName
	)		const

Gets the DigitalPinSet and ChipSelect objects that are attached to the named set configuration.

Precondition: A configuration has been successfully parsed, and the DigitalPort object(s) needed for the set have been attached.

Parameters

dpset	The object that will receive the DigitalPinSet configuration.
sel	The object that will receive the associated ChipSelect object. If there is no configured chip select, the object's configured() function will return false.
setName	The name given to the pin set in the configuration.

Exceptions

SetDoesNotExistError	The requested set is not defined in the configuration data.
SelectDoesNotExistError	The requested chip select is not defined in the configuration data.
SetNotCreatedError	The requested set has not yet been created. This most likely means that the port providing its pins hasn't been attached by a call to attachPort().
SelectManagerNotCreated	The requested manager for the chip select has not yet been created. This most likely means that the port providing its pins hasn't been attached by a call to attachPort().

Examples:: bppmenu.cpp, clockLCD.cpp, rendertext.cpp, and st7920.cpp.

Definition at line 623 of file PinConfiguration.cpp.

◆ getSelect()

const ChipSelect & duds::hardware::interface::PinConfiguration::getSelect ( const std::string & selName ) const

Gets the ChipSelect object named in the configuration.

Precondition: A configuration has been successfully parsed, and the DigitalPort object needed for the set has been attached.

Parameters

selName The name given to the chip select in the configuration.

Exceptions

SelectDoesNotExistError	The requested chip select is not defined in the configuration data.
SelectManagerNotCreated	The requested manager for the chip select has not yet been created. This most likely means that the port providing its pins hasn't been attached by a call to attachPort().

Definition at line 667 of file PinConfiguration.cpp.

◆ haveChipSelect()

bool duds::hardware::interface::PinConfiguration::haveChipSelect ( const std::string & name ) const

inline

True if the named chip select has been found in the already parsed configuration.

This is used inside the parsing code, but can be used elsewhere.

Parameters

name	The name given to the chip select in the configuration.

Definition at line 729 of file PinConfiguration.hpp.

Referenced by duds::hardware::interface::PinConfiguration::ChipSel::ChipSel(), and duds::hardware::interface::ParseState().

◆ havePin()

bool duds::hardware::interface::PinConfiguration::havePin ( const std::string & pinName ) const

Returns true if the named pin is in the configuration.

Precondition: A configuration has been successfully parsed, and the DigitalPort object that handles the pin has been attached.

Parameters

pinName The name of the pin in the configuration.

Definition at line 712 of file PinConfiguration.cpp.

◆ parse()

void duds::hardware::interface::PinConfiguration::parse ( const boost::property_tree::ptree & pt )

Parses the pin configuration that starts at the given subtree.

Boost property tree is used to parse and represnt data prior to passing that data to this function. See the Digital Pin Configuration page for detailed documentation on what is expected of the property tree.

Parameters

pt	The property tree node that is the parent of all the pin configuration nodes. No boost::property_tree::ptree objects are retained in this class.

Exceptions

PortDuplicateError
SelectManagerDuplicateError
SetDuplicateError
PinBadIdError
PortDuplicatePinIdError
SelectBadStateError
SelectManagerUnknownTypeError
SelectDuplicateError
SelectNoPinsError
SelectMultiplePortsError
SetMultiplePortsError
SelectDoesNotExistError

Examples:: bppmenu.cpp, and rendertext.cpp.

Definition at line 398 of file PinConfiguration.cpp.

Referenced by PinConfiguration().

◆ pin()

const PinConfiguration::Pin & duds::hardware::interface::PinConfiguration::pin ( const std::string & str ) const

Finds the pin from the given name or global ID according to this pin configuration.

The result is independent of any DigitalPort objects.

Precondition: Configuration parsing has already been done successfully.

Parameters

str	A string with either an arbitrary name or a number with a global ID.

Returns: The Pin object that corresponds to the requested pin.

Definition at line 116 of file PinConfiguration.cpp.

Referenced by attachPort(), duds::hardware::interface::PinConfiguration::ChipSel::ChipSel(), and duds::hardware::interface::ParseState().

◆ pinGlobalId()

unsigned int duds::hardware::interface::PinConfiguration::pinGlobalId ( const std::string & str ) const

inline

Finds the global ID of the given pin according to this pin configuration.

The result is independent of any DigitalPort objects.

Precondition: Configuration parsing has already been done successfully.

Parameters

str	A string with either an arbitrary name or a number with a global ID.

Returns: The global ID of the requested pin.

Exceptions

PortBadPinIdError The requested pin does not exist.

Definition at line 592 of file PinConfiguration.hpp.

◆ pinSet()

const PinConfiguration::PinSet & duds::hardware::interface::PinConfiguration::pinSet ( const std::string & name ) const

Finds the configuration data for the named DigitalPinSet.

Parameters

name	The name given to the pin set in the configuration.

Precondition: Configuration parsing has already been done successfully. PinSet::dpSet will only be valid after its required port has been attached.

Exceptions

SetDoesNotExistError The requested set is not defined in the configuration data.

Definition at line 587 of file PinConfiguration.cpp.

◆ pinSetsBegin()

PinSetMap::const_iterator duds::hardware::interface::PinConfiguration::pinSetsBegin ( ) const

inline

Begining iterator to inspect the pin sets in the configuration.

Examples:: pinconfig.cpp.

Definition at line 771 of file PinConfiguration.hpp.

◆ pinSetsEnd()

PinSetMap::const_iterator duds::hardware::interface::PinConfiguration::pinSetsEnd ( ) const

inline

Ending iterator to inspect the pin sets in the configuration.

Examples:: pinconfig.cpp.

Definition at line 777 of file PinConfiguration.hpp.

◆ port()

const PinConfiguration::Port & duds::hardware::interface::PinConfiguration::port ( const std::string & name = "default" ) const

Finds the configuration data for the named DigitalPort.

Parameters

name	The name given to the port in the configuration.

Precondition: Configuration parsing has already been done successfully.

Exceptions

PortDoesNotExistError

Definition at line 575 of file PinConfiguration.cpp.

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

◆ portsBegin()

PortMap::const_iterator duds::hardware::interface::PinConfiguration::portsBegin ( ) const

inline

Begining iterator to inspect the ports in the configuration.

Examples:: pinconfig.cpp.

Definition at line 735 of file PinConfiguration.hpp.

◆ portsEnd()

PortMap::const_iterator duds::hardware::interface::PinConfiguration::portsEnd ( ) const

inline

Ending iterator to inspect the ports in the configuration.

Examples:: pinconfig.cpp.

Definition at line 741 of file PinConfiguration.hpp.

◆ selectManager()

const PinConfiguration::SelMgr & duds::hardware::interface::PinConfiguration::selectManager ( const std::string & name ) const

Finds the configuration data for the named ChipSelectManager.

Parameters

name	The name given to the manager in the configuration.

Precondition: Configuration parsing has already been done successfully. SelMgr::csm will only be valid after its required port has been attached.

Exceptions

SelectManagerDoesNotExistError The requested chip select manager is not defined in the configuration data.

Definition at line 611 of file PinConfiguration.cpp.

◆ selectManagersBegin()

SelMgrMap::const_iterator duds::hardware::interface::PinConfiguration::selectManagersBegin ( ) const

inline

Begining iterator to inspect the select managers in the configuration.

Examples:: pinconfig.cpp.

Definition at line 747 of file PinConfiguration.hpp.

◆ selectManagersEnd()

SelMgrMap::const_iterator duds::hardware::interface::PinConfiguration::selectManagersEnd ( ) const

inline

Ending iterator to inspect the select managers in the configuration.

Examples:: pinconfig.cpp.

Definition at line 753 of file PinConfiguration.hpp.

◆ selectsBegin()

ChipSelMap::const_iterator duds::hardware::interface::PinConfiguration::selectsBegin ( ) const

inline

Begining iterator to inspect the chip selects in the configuration.

Examples:: pinconfig.cpp.

Definition at line 759 of file PinConfiguration.hpp.

◆ selectsEnd()

ChipSelMap::const_iterator duds::hardware::interface::PinConfiguration::selectsEnd ( ) const

inline

Ending iterator to inspect the chip selects in the configuration.

Examples:: pinconfig.cpp.

Definition at line 765 of file PinConfiguration.hpp.

Member Data Documentation

◆ allpins

Pins duds::hardware::interface::PinConfiguration::allpins

private

All pins mentioned in the confiuration across all ports.

Definition at line 481 of file PinConfiguration.hpp.

Referenced by getPin(), havePin(), parse(), and pin().

◆ chipSels

ChipSelMap duds::hardware::interface::PinConfiguration::chipSels

private

Chip select configurations stored by name.

Definition at line 493 of file PinConfiguration.hpp.

Referenced by attachPort(), chipSelect(), getPinSetAndSelect(), getSelect(), and parse().

◆ pinSets

PinSetMap duds::hardware::interface::PinConfiguration::pinSets

private

Pin set configurations stored by name.

Definition at line 497 of file PinConfiguration.hpp.

Referenced by attachPort(), getPinSet(), getPinSetAndSelect(), parse(), and pinSet().

◆ ports

PortMap duds::hardware::interface::PinConfiguration::ports

private

Port configurations stored by name.

Definition at line 485 of file PinConfiguration.hpp.

Referenced by attachPort(), parse(), and port().

◆ selMgrs

SelMgrMap duds::hardware::interface::PinConfiguration::selMgrs

private

Select manager configurations stored by name.

Definition at line 489 of file PinConfiguration.hpp.

Referenced by attachPort(), parse(), and selectManager().

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

Classes

Public Types

Public Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ ChipSelMap

◆ Pins

◆ PinSetMap

◆ PortMap

◆ SelMgrMap

Constructor & Destructor Documentation

◆ PinConfiguration() [1/2]

◆ PinConfiguration() [2/2]

Member Function Documentation

◆ attachPort()

◆ chipSelect()

◆ getPin() [1/2]

◆ getPin() [2/2]

◆ getPinSet()

◆ getPinSetAndSelect()

◆ getSelect()

◆ haveChipSelect()

◆ havePin()

◆ parse()

◆ pin()

◆ pinGlobalId()

◆ pinSet()

◆ pinSetsBegin()

◆ pinSetsEnd()

◆ port()

◆ portsBegin()

◆ portsEnd()

◆ selectManager()

◆ selectManagersBegin()

◆ selectManagersEnd()

◆ selectsBegin()

◆ selectsEnd()

Member Data Documentation

◆ allpins

◆ chipSels

◆ pinSets

◆ ports

◆ selMgrs