Backend for subdevices which are passed through some register or area of another device (subsequently called target device). More...

#include <SubdeviceBackend.h>

Inheritance diagram for ChimeraTK::SubdeviceBackend:

Collaboration diagram for ChimeraTK::SubdeviceBackend:

Public Member Functions
	SubdeviceBackend (std::map< std::string, std::string > parameters)

void	open () override
	Open the device.

void	close () override
	Close the device.

std::string	readDeviceInfo () override
	Return a device information string containing hardware details like the firmware version number or the slot number used by the board.

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

MetadataCatalogue	getMetadataCatalogue () const override
	Return the device metadata catalogue.

std::set< DeviceBackend::BackendID >	getInvolvedBackendIDs () override
	Get the backend IDs of all involved backends.

Public Member Functions inherited from ChimeraTK::DeviceBackendImpl
bool	isOpen () override
	Return whether a device has been opened or not.

bool	isConnected () final
	Deprecated since 2022-03-03.

void	checkActiveException () final
	Function to be called by backends when needing to check for an active exception.

void	setException (const std::string &message) noexcept final
	Set the backend into an exception state.

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

std::string	getActiveExceptionMessage () noexcept

ChimeraTK::VersionNumber	getVersionOnOpen () const override
	Get the version number which was set during the open process.

Public Member Functions inherited from ChimeraTK::DeviceBackend
virtual	~DeviceBackend ()=default
	Every virtual class needs a virtual desctructor.

template<typename UserType >
boost::shared_ptr< NDRegisterAccessor< UserType > >	getRegisterAccessor (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)
	Get a NDRegisterAccessor object from the register name.

	DEFINE_VIRTUAL_FUNCTION_TEMPLATE_VTABLE (getRegisterAccessor_impl, boost::shared_ptr< NDRegisterAccessor< T > >(const RegisterPath &, size_t, size_t, AccessModeFlags))

BackendID	getBackendID ()
	Get a unique ID for this backend instance.

Static Public Member Functions
static boost::shared_ptr< DeviceBackend >	createInstance (std::string address, std::map< std::string, std::string > parameters)

Protected Types
enum class	Type { area , threeRegisters , twoRegisters , areaHandshake , registerWindow }

using	BusyRegisterKey = std::pair< DeviceBackend *, RegisterPath >

Protected Member Functions
void	verifyRegisterAccessorSize (const NumericAddressedRegisterInfo &info, size_t &numberOfWords, size_t wordOffsetInRegister, bool enforceAlignment)
	Check consistency of the passed sizes and offsets against the information in the map file Will adjust numberOfWords to the default value if 0.

template<typename UserType >
boost::shared_ptr< NDRegisterAccessor< UserType > >	getRegisterAccessor_impl (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)

	DEFINE_VIRTUAL_FUNCTION_TEMPLATE_VTABLE_FILLER (SubdeviceBackend, getRegisterAccessor_impl, 4)

template<typename UserType >
boost::shared_ptr< NDRegisterAccessor< UserType > >	getAreaRegisterAccessor (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)
	getRegisterAccessor implementation for area types

template<typename UserType >
boost::shared_ptr< NDRegisterAccessor< UserType > >	getSynchronisedRegisterAccessor (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, const AccessModeFlags &flags)
	getRegisterAccessor implementation for threeRegisters types

template<typename UserType >
boost::shared_ptr< NDRegisterAccessor< UserType > >	getRegisterWindowAccessor (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, const AccessModeFlags &flags)

void	obtainTargetBackend ()
	obtain the target backend if not yet done

void	setExceptionImpl () noexcept override
	Function to be (optionally) implemented by backends if additional actions are needed when switching to the exception state.

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

bool	needAreaParam ()

bool	needStatusParam ()

boost::shared_ptr< SubdeviceRegisterAccessor >	accessorCreationHelper (const NumericAddressedRegisterInfo &info, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)

template<>
boost::shared_ptr< NDRegisterAccessor< int32_t > >	getAreaRegisterAccessor (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)

Protected Member Functions inherited from ChimeraTK::DeviceBackendImpl
void	setOpenedAndClearException () noexcept
	Backends should call this function at the end of a (successful) open() call.

Protected Attributes
std::shared_ptr< std::mutex >	_mutex

Type	_type
	type of the subdevice

size_t	_timeout {10000}
	timeout (in milliseconds), used in threeRegisters to throw a runtime_error if status register stuck at 1

std::string	_targetAlias
	the target device name

boost::shared_ptr< ChimeraTK::DeviceBackend >	_targetDevice
	The target device backend itself.

std::string	_targetArea
	for type == area: the name of the target register

std::string	_targetAddress
	for type == registerWindow, threeRegisters or twoRegisters: the names of the basic target registers

std::string	_targetWriteData

std::string	_targetControl

std::map< std::string, std::string >	_parameters
	currently only used for type == registerWindow: the whole set of parameters

size_t	_sleepTime {100}
	for type == registerWindow, threeRegisters or twoRegisters: sleep time of polling loop resp.

size_t	_addressToDataDelay {0}
	for type == registerWindow, threeRegisters or twoRegisters: sleep time between address and data write

size_t	_chipIndex {0}
	for type == registerWindow: chip index

NumericAddressedRegisterCatalogue	_registerMap
	map from register names to addresses

MetadataCatalogue	_metadataCatalogue

Protected Attributes inherited from ChimeraTK::DeviceBackendImpl
std::atomic< bool >	_opened {false}
	flag if backend is opened

async::DomainsContainer	_asyncDomainsContainer
	Container for async::Domains to support wait_for_new_data.

Static Protected Attributes
static std::map< BusyRegisterKey, std::shared_ptr< std::mutex > >	_mutexes
	Mutex to protext concurrent access to the target registers.

static std::mutex	_mutexMapMutex

Friends
class	SubdeviceRegisterAccessor

template<typename RegisterRawType , typename WriteDataType >
class	SubdeviceRegisterWindowAccessor

Additional Inherited Members
Public Types inherited from ChimeraTK::DeviceBackend
using	BackendID = std::uintptr_t

Detailed Description

Backend for subdevices which are passed through some register or area of another device (subsequently called target device).

The subdevice is close to a numeric addressed backend and has a map file of the same format (but BARs other than 0 are not supported). The target device may be of any type.

The sdm URI syntax for setting up the subdevice depends on the protocol used to pass through the registers. The following pass-trough types are supported:

"area" type: use a 1D register as an address space.
URI scheme:

(subdevice?type=area&device=<targetDevice>&area=<targetRegister>&map=mapFile>)

"3regs" type: use three scalar registers: address, (write) data and status. Before access, a value of 0 in the status register is awaited. Next, the address is written to the address register. The value is then written to resp. read from the data register.
URI scheme:
```
(subdevice?type=3regs&device=<targetDevice>&address=<addressRegister>&data=<dataRegister>&status=<statusRegister>&sleep=<usecs>&map=<mapFile>)
```
The sleep parameter is optional and defaults to 100 usecs. It sets the polling interval for the status register in microseconds. Another optional parameter "dataDelay" can be used to configure an additional delay in microseconds between the write of the address and the data registers (defaults to 0 usecs).
"2regs" type: same as "3regs" but without a status register. Instead the sleep parameter is mandatory and specifies the fixed sleep time before each operation.
"areaHandshake" type: mapped area, but before write operations to registers inside the map, waits for value 0 in the status register like in 3regs mode. The sleep parameter is optional.
URI scheme:
```
(subdevice?type=areaHandshake&device=<targetDevice>&area=<targetRegister>&map=mapFile&status=<statusRegister>&sleep=<usecs>)
```
"regWindow" type: extension of the "3reg" interface for reading and addressing multiple chips/sub-devices through the same register set. In addition to the address, writeData (data) and busy (status) parameters there is readRequest, readData, chipSelectRegister and chipIndex.
read sequence: the backend writes into the (void type) "readRequest" register and waits until the status(busy) flag turns back off. It then reads the data from the "readResponse" register.
URI scheme:
```
(subdevice?type=regWindow&device=<targetDevice>&address=<addressRegister>&writeData=<writeDataRegister>&busy=<busyRegister>&readRequest=<readRequestRegister>&readData=<readDataRegister>&chipSelectRegister=<chipSelectRegister>&chipIndex=<chipIndex>&map=<mapFile>)
```
The "chipIndex" parameter is optional and defaults to 0. For compatibility with the 3reg-mode, 'data' can be used instead of 'readData', and 'status' instead of 'busy'

Example: We like to use the register "APP.0.EXT_PZ16M" of the device with the alias name "TCK7_0" in our dmap file as a target and the file piezo_pz16m_acc1_r0.mapp as a map file. The file contains addresses relative to the beginning of the register "APP.0.EXT_PZ16M". The URI then looks like this:

(subdevice?type=area&device=TCK7_0&area=APP.0.EXT_PZ16M&map=piezo_pz16m_acc1_r0.mapp)

Warning: The protocol for the types "3regs" and "2regs" is not yet finalised. In particular read transfers might change in future. Please do not use these for reading in production code!

Definition at line 70 of file SubdeviceBackend.h.

Member Typedef Documentation

◆ BusyRegisterKey

using ChimeraTK::SubdeviceBackend::BusyRegisterKey = std::pair<DeviceBackend*, RegisterPath>

protected

Definition at line 106 of file SubdeviceBackend.h.

Member Enumeration Documentation

◆ Type

enum class ChimeraTK::SubdeviceBackend::Type

strongprotected

Enumerator
area
threeRegisters
twoRegisters
areaHandshake
registerWindow

Definition at line 96 of file SubdeviceBackend.h.

Constructor & Destructor Documentation

◆ SubdeviceBackend()

ChimeraTK::SubdeviceBackend::SubdeviceBackend ( std::map< std::string, std::string > parameters )

explicit

Definition at line 57 of file SubdeviceBackend.cc.

Member Function Documentation

◆ accessorCreationHelper()

boost::shared_ptr< SubdeviceRegisterAccessor > ChimeraTK::SubdeviceBackend::accessorCreationHelper	(	const NumericAddressedRegisterInfo &	info,
		size_t	numberOfWords,
		size_t	wordOffsetInRegister,
		AccessModeFlags	flags
	)

protected

Definition at line 390 of file SubdeviceBackend.cc.

◆ activateAsyncRead()

void ChimeraTK::SubdeviceBackend::activateAsyncRead ( )

overrideprotectedvirtualnoexcept

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.

Reimplemented from ChimeraTK::DeviceBackend.

Definition at line 584 of file SubdeviceBackend.cc.

◆ close()

void ChimeraTK::SubdeviceBackend::close ( )

overridevirtual

Close the device.

Implements ChimeraTK::DeviceBackend.

Definition at line 256 of file SubdeviceBackend.cc.

◆ createInstance()

boost::shared_ptr< DeviceBackend > ChimeraTK::SubdeviceBackend::createInstance	(	std::string	address,
		std::map< std::string, std::string >	parameters
	)

static

Definition at line 28 of file SubdeviceBackend.cc.

◆ DEFINE_VIRTUAL_FUNCTION_TEMPLATE_VTABLE_FILLER()

ChimeraTK::SubdeviceBackend::DEFINE_VIRTUAL_FUNCTION_TEMPLATE_VTABLE_FILLER	(	SubdeviceBackend	,
		getRegisterAccessor_impl	,
		4
	)

protected

◆ getAreaRegisterAccessor() [1/2]

template<typename UserType >

boost::shared_ptr< NDRegisterAccessor< UserType > > ChimeraTK::SubdeviceBackend::getAreaRegisterAccessor	(	const RegisterPath &	registerPathName,
		size_t	numberOfWords,
		size_t	wordOffsetInRegister,
		AccessModeFlags	flags
	)

protected

getRegisterAccessor implementation for area types

Definition at line 362 of file SubdeviceBackend.cc.

◆ getAreaRegisterAccessor() [2/2]

template<>

boost::shared_ptr< NDRegisterAccessor< int32_t > > ChimeraTK::SubdeviceBackend::getAreaRegisterAccessor	(	const RegisterPath &	registerPathName,
		size_t	numberOfWords,
		size_t	wordOffsetInRegister,
		AccessModeFlags	flags
	)

protected

Definition at line 458 of file SubdeviceBackend.cc.

◆ getInvolvedBackendIDs()

std::set< DeviceBackend::BackendID > ChimeraTK::SubdeviceBackend::getInvolvedBackendIDs ( )

overridevirtual

Get the backend IDs of all involved backends.

For meta backends like the LogicalNameMappingBackend or the SubDeviceBackend this contains the ID of all target backend, in addition to this backend's ID.

Reimplemented from ChimeraTK::DeviceBackendImpl.

Definition at line 590 of file SubdeviceBackend.cc.

◆ getMetadataCatalogue()

MetadataCatalogue ChimeraTK::SubdeviceBackend::getMetadataCatalogue ( ) const

overridevirtual

Return the device metadata catalogue.

Reimplemented from ChimeraTK::DeviceBackendImpl.

Definition at line 270 of file SubdeviceBackend.cc.

◆ getRegisterAccessor_impl()

template<typename UserType >

boost::shared_ptr< NDRegisterAccessor< UserType > > ChimeraTK::SubdeviceBackend::getRegisterAccessor_impl	(	const RegisterPath &	registerPathName,
		size_t	numberOfWords,
		size_t	wordOffsetInRegister,
		AccessModeFlags	flags
	)

protected

Definition at line 277 of file SubdeviceBackend.cc.

◆ getRegisterCatalogue()

RegisterCatalogue ChimeraTK::SubdeviceBackend::getRegisterCatalogue ( ) const

overridevirtual

Return the register catalogue with detailed information on all registers.

Implements ChimeraTK::DeviceBackend.

Definition at line 264 of file SubdeviceBackend.cc.

◆ getRegisterWindowAccessor()

template<typename UserType >

boost::shared_ptr< NDRegisterAccessor< UserType > > ChimeraTK::SubdeviceBackend::getRegisterWindowAccessor	(	const RegisterPath &	registerPathName,
		size_t	numberOfWords,
		size_t	wordOffsetInRegister,
		const AccessModeFlags &	flags
	)

protected

Definition at line 458 of file SubdeviceBackend.cc.

◆ getSynchronisedRegisterAccessor()

template<typename UserType >

boost::shared_ptr< NDRegisterAccessor< UserType > > ChimeraTK::SubdeviceBackend::getSynchronisedRegisterAccessor	(	const RegisterPath &	registerPathName,
		size_t	numberOfWords,
		size_t	wordOffsetInRegister,
		const AccessModeFlags &	flags
	)

protected

getRegisterAccessor implementation for threeRegisters types

Definition at line 434 of file SubdeviceBackend.cc.

◆ needAreaParam()

bool ChimeraTK::SubdeviceBackend::needAreaParam ( )

inlineprotected

Definition at line 185 of file SubdeviceBackend.h.

◆ needStatusParam()

bool ChimeraTK::SubdeviceBackend::needStatusParam ( )

inlineprotected

Definition at line 186 of file SubdeviceBackend.h.

◆ obtainTargetBackend()

void ChimeraTK::SubdeviceBackend::obtainTargetBackend ( )

protected

obtain the target backend if not yet done

Definition at line 225 of file SubdeviceBackend.cc.

◆ open()

void ChimeraTK::SubdeviceBackend::open ( )

overridevirtual

Open the device.

Implements ChimeraTK::DeviceBackend.

Definition at line 247 of file SubdeviceBackend.cc.

◆ readDeviceInfo()

std::string ChimeraTK::SubdeviceBackend::readDeviceInfo ( )

inlineoverridevirtual

Return a device information string containing hardware details like the firmware version number or the slot number used by the board.

The format and contained information of this string is completely backend implementation dependent, so the string may only be printed to the user as an informational output. Do not try to parse this string or extract information from it programmatically.

Todo:: extend information

Implements ChimeraTK::DeviceBackend.

Definition at line 78 of file SubdeviceBackend.h.

◆ setExceptionImpl()

void ChimeraTK::SubdeviceBackend::setExceptionImpl ( )

overrideprotectedvirtualnoexcept

Function to be (optionally) implemented by backends if additional actions are needed when switching to the exception state.

Reimplemented from ChimeraTK::DeviceBackendImpl.

Definition at line 577 of file SubdeviceBackend.cc.

◆ verifyRegisterAccessorSize()

void ChimeraTK::SubdeviceBackend::verifyRegisterAccessorSize	(	const NumericAddressedRegisterInfo &	info,
		size_t &	numberOfWords,
		size_t	wordOffsetInRegister,
		bool	enforceAlignment
	)

protected

Check consistency of the passed sizes and offsets against the information in the map file Will adjust numberOfWords to the default value if 0.

Definition at line 301 of file SubdeviceBackend.cc.

Friends And Related Symbol Documentation

◆ SubdeviceRegisterAccessor

friend class SubdeviceRegisterAccessor

friend

Definition at line 92 of file SubdeviceBackend.h.

◆ SubdeviceRegisterWindowAccessor

template<typename RegisterRawType , typename WriteDataType >

friend class SubdeviceRegisterWindowAccessor

friend

Definition at line 94 of file SubdeviceBackend.h.

Member Data Documentation

◆ _addressToDataDelay

size_t ChimeraTK::SubdeviceBackend::_addressToDataDelay {0}

protected

for type == registerWindow, threeRegisters or twoRegisters: sleep time between address and data write

Definition at line 143 of file SubdeviceBackend.h.

◆ _chipIndex

size_t ChimeraTK::SubdeviceBackend::_chipIndex {0}

protected

for type == registerWindow: chip index

Definition at line 146 of file SubdeviceBackend.h.

◆ _metadataCatalogue

MetadataCatalogue ChimeraTK::SubdeviceBackend::_metadataCatalogue

protected

Definition at line 150 of file SubdeviceBackend.h.

◆ _mutex

std::shared_ptr<std::mutex> ChimeraTK::SubdeviceBackend::_mutex

protected

Definition at line 114 of file SubdeviceBackend.h.

◆ _mutexes

std::map< SubdeviceBackend::BusyRegisterKey, std::shared_ptr< std::mutex > > ChimeraTK::SubdeviceBackend::_mutexes

staticprotected

Mutex to protext concurrent access to the target registers.

The mutex must be shared with all backends that use the same busy register. There might be multiple instances of the SubdeviceBackend with different ChipIDs.

Definition at line 111 of file SubdeviceBackend.h.

◆ _mutexMapMutex

std::mutex ChimeraTK::SubdeviceBackend::_mutexMapMutex

staticprotected

Definition at line 112 of file SubdeviceBackend.h.

◆ _parameters

std::map<std::string, std::string> ChimeraTK::SubdeviceBackend::_parameters

protected

currently only used for type == registerWindow: the whole set of parameters

Definition at line 136 of file SubdeviceBackend.h.

◆ _registerMap

NumericAddressedRegisterCatalogue ChimeraTK::SubdeviceBackend::_registerMap

protected

map from register names to addresses

Definition at line 149 of file SubdeviceBackend.h.

◆ _sleepTime

size_t ChimeraTK::SubdeviceBackend::_sleepTime {100}

protected

for type == registerWindow, threeRegisters or twoRegisters: sleep time of polling loop resp.

between operations, in usecs.

Definition at line 140 of file SubdeviceBackend.h.

◆ _targetAddress

std::string ChimeraTK::SubdeviceBackend::_targetAddress

protected

for type == registerWindow, threeRegisters or twoRegisters: the names of the basic target registers

Definition at line 133 of file SubdeviceBackend.h.

◆ _targetAlias

std::string ChimeraTK::SubdeviceBackend::_targetAlias

protected

the target device name

Definition at line 123 of file SubdeviceBackend.h.

◆ _targetArea

std::string ChimeraTK::SubdeviceBackend::_targetArea

protected

for type == area: the name of the target register

Definition at line 130 of file SubdeviceBackend.h.

◆ _targetControl

std::string ChimeraTK::SubdeviceBackend::_targetControl

protected

Definition at line 133 of file SubdeviceBackend.h.

◆ _targetDevice

boost::shared_ptr<ChimeraTK::DeviceBackend> ChimeraTK::SubdeviceBackend::_targetDevice

protected

The target device backend itself.

We are using directly a backend since we want to obtain NDRegisterAccessors which we can directly return in getRegisterAccessor_impl().

Definition at line 127 of file SubdeviceBackend.h.

◆ _targetWriteData

std::string ChimeraTK::SubdeviceBackend::_targetWriteData

protected

Definition at line 133 of file SubdeviceBackend.h.

◆ _timeout

size_t ChimeraTK::SubdeviceBackend::_timeout {10000}

protected

timeout (in milliseconds), used in threeRegisters to throw a runtime_error if status register stuck at 1

Definition at line 120 of file SubdeviceBackend.h.

◆ _type

Type ChimeraTK::SubdeviceBackend::_type

protected

type of the subdevice

Definition at line 117 of file SubdeviceBackend.h.

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

/scratch/dragon/sources/ChimeraTK-DeviceAccess/backends/Subdevice/include/SubdeviceBackend.h
/scratch/dragon/sources/ChimeraTK-DeviceAccess/backends/Subdevice/src/SubdeviceBackend.cc

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ BusyRegisterKey

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ SubdeviceBackend()

Member Function Documentation

◆ accessorCreationHelper()

◆ activateAsyncRead()

◆ close()

◆ createInstance()

◆ DEFINE_VIRTUAL_FUNCTION_TEMPLATE_VTABLE_FILLER()

◆ getAreaRegisterAccessor() [1/2]

◆ getAreaRegisterAccessor() [2/2]

◆ getInvolvedBackendIDs()

◆ getMetadataCatalogue()

◆ getRegisterAccessor_impl()

◆ getRegisterCatalogue()

◆ getRegisterWindowAccessor()

◆ getSynchronisedRegisterAccessor()

◆ needAreaParam()

◆ needStatusParam()

◆ obtainTargetBackend()

◆ open()

◆ readDeviceInfo()

◆ setExceptionImpl()

◆ verifyRegisterAccessorSize()

Friends And Related Symbol Documentation

◆ SubdeviceRegisterAccessor

◆ SubdeviceRegisterWindowAccessor

Member Data Documentation

◆ _addressToDataDelay

◆ _chipIndex

◆ _metadataCatalogue

◆ _mutex

◆ _mutexes

◆ _mutexMapMutex

◆ _parameters

◆ _registerMap

◆ _sleepTime

◆ _targetAddress

◆ _targetAlias

◆ _targetArea

◆ _targetControl

◆ _targetDevice

◆ _targetWriteData

◆ _timeout

◆ _type