Class allows to read/write registers from device. More...

#include <Device.h>

Inheritance diagram for ChimeraTK::Device:

Public Member Functions
	Device ()=default
	Create device instance without associating a backend yet. More...

	Device (const std::string &aliasName)
	Initialize device and accociate a backend. More...

void	open (std::string const &aliasName)
	Open a device by the given alias name from the DMAP file. More...

void	open ()
	Re-open the device after previously closeing it by calling close(), or when it was constructed with a given aliasName. More...

void	close ()
	Close the device. More...

template<typename UserType >
ScalarRegisterAccessor< UserType >	getScalarRegisterAccessor (const RegisterPath &registerPathName, size_t wordOffsetInRegister=0, const AccessModeFlags &flags=AccessModeFlags({})) const
	Get a ScalarRegisterObject object for the given register. More...

VoidRegisterAccessor	getVoidRegisterAccessor (const RegisterPath &registerPathName, const AccessModeFlags &flags=AccessModeFlags({})) const
	Get a VoidRegisterAccessor object for the given register. More...

template<typename UserType >
OneDRegisterAccessor< UserType >	getOneDRegisterAccessor (const RegisterPath &registerPathName, size_t numberOfWords=0, size_t wordOffsetInRegister=0, const AccessModeFlags &flags=AccessModeFlags({})) const
	Get a OneDRegisterAccessor object for the given register. More...

template<typename UserType >
TwoDRegisterAccessor< UserType >	getTwoDRegisterAccessor (const RegisterPath &registerPathName, size_t numberOfElements=0, size_t elementsOffset=0, const AccessModeFlags &flags=AccessModeFlags({})) const
	Get a TwoDRegisterAccessor object for the given register. More...

RegisterCatalogue	getRegisterCatalogue () const
	Return the register catalogue with detailed information on all registers. More...

MetadataCatalogue	getMetadataCatalogue () const
	Return the register catalogue with detailed information on all registers. More...

std::string	readDeviceInfo () const
	Return a device information string. More...

bool	isOpened () const
	Check if the device is currently opened. More...

bool	isFunctional () const
	Return wether a device is working as intended, usually this means it is opened and does not have any errors. More...

void	activateAsyncRead () noexcept
	Activate asyncronous read for all transfer elements where AccessMode::wait_for_new_data is set. More...

void	setException (const std::string &message)
	Set the device into an exception state. More...

boost::shared_ptr< DeviceBackend >	getBackend ()
	Obtain the backend. More...

template<typename UserType >
UserType	read (const RegisterPath &registerPathName, const AccessModeFlags &flags=AccessModeFlags({})) const
	Inefficient convenience function to read a single-word register without obtaining an accessor. More...

template<typename UserType >
std::vector< UserType >	read (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister=0, const AccessModeFlags &flags=AccessModeFlags({})) const
	Inefficient convenience function to read a multi-word register without obtaining an accessor. More...

template<typename UserType >
void	write (const RegisterPath &registerPathName, UserType value, const AccessModeFlags &flags=AccessModeFlags({}))
	Inefficient convenience function to write a single-word register without obtaining an accessor. More...

template<typename UserType >
void	write (const RegisterPath &registerPathName, const std::vector< UserType > &vector, size_t wordOffsetInRegister=0, const AccessModeFlags &flags=AccessModeFlags({}))
	Inefficient convenience function to write a multi-word register without obtaining an accessor. More...

Protected Member Functions
void	checkPointersAreNotNull () const

Protected Attributes
boost::shared_ptr< DeviceBackend >	_deviceBackendPointer

Detailed Description

Class allows to read/write registers from device.

Todo:: update documentation Allows to read/write registers from device by passing the name of the register instead of offset from the beginning of address space. Type of the object used to control access to device must be passed as a template parameter and must be an type defined in libdev class.

The device can open and close a device for you. If you let the Device open the device you will not be able to get a handle to this device directly, you can only close it with the Device. Should you create RegisterAccessor objects, which contain shared pointers to this device, the device will stay opened and functional even if the Device object which created the RegisterAccessor goes out of scope. In this case you cannot close the device. It will finally be closed when the the last RegisterAccessor pointing to it goes out of scope. The same holds if you open another device with the same Device: You lose direct access to the previous device, which stays open as long as there are RegisterAccessors pointing to it.

Examples: accessor1D.cpp, accessor2D.cpp, accessor2D_multiplexed.cpp, basic.cpp, and read_temperature_doocs_zmq.cpp.

Definition at line 39 of file Device.h.

Constructor & Destructor Documentation

◆ Device() [1/2]

ChimeraTK::Device::Device ( )

default

Create device instance without associating a backend yet.

A backend has to be explicitly associated using open method which has the alias or CDD as argument.

Usage:

Device d();

d.open("(pci:pciedevs5?map=mps_v00.07.map)");

◆ Device() [2/2]

ChimeraTK::Device::Device ( const std::string & aliasName )

explicit

Initialize device and accociate a backend.

The device is not opened yet.

Usage:

Device d("(pci:pciedevs5?map=mps_v00.07.map)");

d.open();

Parameters

aliasName The ChimeraTK device descriptor for the device.

Definition at line 15 of file Device.cc.

Member Function Documentation

◆ activateAsyncRead()

void ChimeraTK::Device::activateAsyncRead ( )

noexcept

Activate asyncronous read for all transfer elements where AccessMode::wait_for_new_data is set.

If Device::activateAsyncRead() is called while the device is not opened or has an error, this call has no effect. If it is called when no deactivated transfer element exists, this call also has no effect. When Device::activateAsyncRead() returns, it is not guaranteed that all initial values have been received already.

For more details, see Technical specification: TransferElement B.8.5.

Examples: read_temperature_doocs_zmq.cpp.

Definition at line 91 of file Device.cc.

Here is the caller graph for this function:

◆ checkPointersAreNotNull()

void ChimeraTK::Device::checkPointersAreNotNull ( ) const

protected

Definition at line 43 of file Device.cc.

Here is the caller graph for this function:

◆ close()

void ChimeraTK::Device::close ( )

Close the device.

The connection with the alias name is kept so the device can be re-opened using the open() function without argument.

Examples: accessor1D.cpp, accessor2D.cpp, accessor2D_multiplexed.cpp, and basic.cpp.

Definition at line 66 of file Device.cc.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getBackend()

boost::shared_ptr< DeviceBackend > ChimeraTK::Device::getBackend ( )

Obtain the backend.

Note: using the backend in normal application code likely breaks the abstraction.

Definition at line 111 of file Device.cc.

Here is the caller graph for this function:

◆ getMetadataCatalogue()

MetadataCatalogue ChimeraTK::Device::getMetadataCatalogue ( ) const

Return the register catalogue with detailed information on all registers.

Definition at line 29 of file Device.cc.

Here is the call graph for this function:

◆ getOneDRegisterAccessor()

template<typename UserType >

OneDRegisterAccessor< UserType > ChimeraTK::Device::getOneDRegisterAccessor	(	const RegisterPath &	registerPathName,
		size_t	numberOfWords = `0`,
		size_t	wordOffsetInRegister = `0`,
		const AccessModeFlags &	flags = `AccessModeFlags({})`
	)		const

Get a OneDRegisterAccessor object for the given register.

The OneDRegisterAccessor allows to read and write registers transparently by using the accessor object like a vector of the type UserType. If needed, the conversion to and from the UserType will be handled by a data converter matching the register description in e.g. a map file.

The optional arguments numberOfWords and wordOffsetInRegister allow to limit the accessor to a part of the register.

The last optional argument flags allows to control certain details how the register is accessed. It allows e.g. to enable raw access. See AccessMode documentation for more details. Passing an access mode flag which is not supported by the backend or the given register will raise a NOT_IMPLEMENTED DeviceException.

Hint: when passing the AccessModeFlags, just enclose the wanted flags in a brace initialiser list without "AccessModeFlags", e.g.: getOneDRegisterAccessor<int32_t>("reg",0,0,{AccessMode::raw})

Examples: accessor1D.cpp, and accessor2D_multiplexed.cpp.

Definition at line 273 of file Device.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getRegisterCatalogue()

RegisterCatalogue ChimeraTK::Device::getRegisterCatalogue ( ) const

Return the register catalogue with detailed information on all registers.

Definition at line 22 of file Device.cc.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getScalarRegisterAccessor()

template<typename UserType >

ScalarRegisterAccessor< UserType > ChimeraTK::Device::getScalarRegisterAccessor	(	const RegisterPath &	registerPathName,
		size_t	wordOffsetInRegister = `0`,
		const AccessModeFlags &	flags = `AccessModeFlags({})`
	)		const

Get a ScalarRegisterObject object for the given register.

The ScalarRegisterObject allows to read and write registers transparently by using the accessor object like a variable of the type UserType. If needed, the conversion to and from the UserType will be handled by a data converter matching the register description in e.g. a map file.

The optional argument wordOffsetInRegister allows to access another but the first word of a larger register.

The last optional argument flags allows to control certain details how the register is accessed. It allows e.g. to enable raw access. See AccessMode documentation for more details. Passing an access mode flag which is not supported by the backend or the given register will raise a ChimeraTK::logic_error.

Examples: basic.cpp, and read_temperature_doocs_zmq.cpp.

Definition at line 263 of file Device.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getTwoDRegisterAccessor()

template<typename UserType >

TwoDRegisterAccessor< UserType > ChimeraTK::Device::getTwoDRegisterAccessor	(	const RegisterPath &	registerPathName,
		size_t	numberOfElements = `0`,
		size_t	elementsOffset = `0`,
		const AccessModeFlags &	flags = `AccessModeFlags({})`
	)		const

Get a TwoDRegisterAccessor object for the given register.

This allows to read and write transparently 2-dimensional registers. The register accessor is similar to the 1-dimensional BufferingRegisterAccessor.

The optional arguments allow to restrict the accessor to a region of interest in the 2D register: numberOfElements specifies the number of elements per channel to read from the register. elementsOffset is the first element index for each channel to read.

TODO: Currently only the restriction to a smaller region of interest is only possible in one dimension. Support for the second dimension should be added as well, but it will involve an internal interface change. Since all current backends will not be able to optimise the performance when reducing the number of channels, this change is postponed.

Examples: accessor2D.cpp, and accessor2D_multiplexed.cpp.

Definition at line 283 of file Device.h.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ getVoidRegisterAccessor()

VoidRegisterAccessor ChimeraTK::Device::getVoidRegisterAccessor	(	const RegisterPath &	registerPathName,
		const AccessModeFlags &	flags = `AccessModeFlags({})`
	)		const

Get a VoidRegisterAccessor object for the given register.

Definition at line 103 of file Device.cc.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ isFunctional()

bool ChimeraTK::Device::isFunctional ( ) const

Return wether a device is working as intended, usually this means it is opened and does not have any errors.

If a backend does not implement any error reporting, this functions id equivalent to isOpened().

Definition at line 82 of file Device.cc.

Here is the caller graph for this function:

◆ isOpened()

bool ChimeraTK::Device::isOpened ( ) const

Check if the device is currently opened.

Definition at line 73 of file Device.cc.

Here is the caller graph for this function:

◆ open() [1/2]

void ChimeraTK::Device::open ( )

Re-open the device after previously closeing it by calling close(), or when it was constructed with a given aliasName.

Definition at line 51 of file Device.cc.

Here is the call graph for this function:

◆ open() [2/2]

void ChimeraTK::Device::open ( std::string const & aliasName )

Open a device by the given alias name from the DMAP file.

Examples: accessor1D.cpp, accessor2D.cpp, accessor2D_multiplexed.cpp, basic.cpp, and read_temperature_doocs_zmq.cpp.

Definition at line 58 of file Device.cc.

Here is the caller graph for this function:

◆ read() [1/2]

template<typename UserType >

UserType ChimeraTK::Device::read	(	const RegisterPath &	registerPathName,
		const AccessModeFlags &	flags = `AccessModeFlags({})`
	)		const

Inefficient convenience function to read a single-word register without obtaining an accessor.

Warning: This function is inefficient as it creates and discards a register accessor in each call of the function. For a better performance, use register accessors instead (see Device::getScalarRegisterAccessor).

If a multi-word register is read, only the first element is returned. This function only works for 1D registers.

Definition at line 293 of file Device.h.

Here is the caller graph for this function:

◆ read() [2/2]

template<typename UserType >

std::vector< UserType > ChimeraTK::Device::read	(	const RegisterPath &	registerPathName,
		size_t	numberOfWords,
		size_t	wordOffsetInRegister = `0`,
		const AccessModeFlags &	flags = `AccessModeFlags({})`
	)		const

Inefficient convenience function to read a multi-word register without obtaining an accessor.

Warning: This function is inefficient as it creates and discards a register accessor in each call of the function. For a better performance, use register accessors instead (see Device::getOneDRegisterAccessor).

The function only works for 1D registers. For 2D registers, see Device::getTwoDRegisterAccessor. The argument numberOfWords specifies how many elements are read. The returned vector will have a length of numberOfWords or shorter. numberOfWords must not exceed the size of the register. The optional argument wordOffsetInRegister allows to skip the first wordOffsetInRegister elements of the register.

Definition at line 302 of file Device.h.

◆ readDeviceInfo()

std::string ChimeraTK::Device::readDeviceInfo ( ) const

Return a device information string.

Format depends on the backend, use for display only.

Definition at line 36 of file Device.cc.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setException()

void ChimeraTK::Device::setException ( const std::string & message )

Set the device into an exception state.

All asynchronous reads will be deactivated. Transfer elements with asynchronous read will reveice a ChimeraTK::runtime_error.
All write and synchronous read operations will see a ChimeraTK::runtime_error.
The exception state stays until open() has successfully been called again.

Definition at line 97 of file Device.cc.

Here is the caller graph for this function:

◆ write() [1/2]

template<typename UserType >

void ChimeraTK::Device::write	(	const RegisterPath &	registerPathName,
		const std::vector< UserType > &	vector,
		size_t	wordOffsetInRegister = `0`,
		const AccessModeFlags &	flags = `AccessModeFlags({})`
	)

Inefficient convenience function to write a multi-word register without obtaining an accessor.

Warning: This function is inefficient as it creates and discards a register accessor in each call of the function. For a better performance, use register accessors instead (see Device::getOneDRegisterAccessor).

The function only works for 1D registers. For 2D registers, see Device::getTwoDRegisterAccessor. The optional argument wordOffsetInRegister allows to skip the first wordOffsetInRegister elements of the register.

Definition at line 323 of file Device.h.

◆ write() [2/2]

template<typename UserType >

void ChimeraTK::Device::write	(	const RegisterPath &	registerPathName,
		UserType	value,
		const AccessModeFlags &	flags = `AccessModeFlags({})`
	)

Inefficient convenience function to write a single-word register without obtaining an accessor.

Warning: This function is inefficient as it creates and discards a register accessor in each call of the function. For a better performance, use register accessors instead (see Device::getScalarRegisterAccessor).

If a multi-word register is read, only the first element is written. This function only works for 1D registers

Definition at line 314 of file Device.h.

Here is the caller graph for this function:

Member Data Documentation

◆ _deviceBackendPointer

boost::shared_ptr<DeviceBackend> ChimeraTK::Device::_deviceBackendPointer

protected

Definition at line 255 of file Device.h.

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

/scratch/dragon/sources/ChimeraTK-DeviceAccess/include/Device.h
/scratch/dragon/sources/ChimeraTK-DeviceAccess/src/Device.cc

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Device() [1/2]

◆ Device() [2/2]

Member Function Documentation

◆ activateAsyncRead()

◆ checkPointersAreNotNull()

◆ close()

◆ getBackend()

◆ getMetadataCatalogue()

◆ getOneDRegisterAccessor()

◆ getRegisterCatalogue()

◆ getScalarRegisterAccessor()

◆ getTwoDRegisterAccessor()

◆ getVoidRegisterAccessor()

◆ isFunctional()

◆ isOpened()

◆ open() [1/2]

◆ open() [2/2]

◆ read() [1/2]

◆ read() [2/2]

◆ readDeviceInfo()

◆ setException()

◆ write() [1/2]

◆ write() [2/2]

Member Data Documentation

◆ _deviceBackendPointer