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

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 }

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 > >	getRegisterAccessor_area (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)
	getRegisterAccessor implemenation for area types

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

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 >	getRegisterAccessor_helper (const NumericAddressedRegisterInfo &info, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)

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

template<>
boost::shared_ptr< NDRegisterAccessor< int32_t > >	getRegisterAccessor_synchronized (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, const 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::mutex	mutex
	Mutex to deal with concurrent access to the device.

Type	type
	type of the subdeivce

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 == threeRegisters or twoRegisters: the name of the target registers

std::string	targetData

std::string	targetControl

size_t	sleepTime {100}
	for type == threeRegisters or twoRegisters: sleep time of polling loop resp. between operations, in usecs.

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

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.

Friends
class	SubdeviceRegisterAccessor

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, 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>)
```

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 57 of file SubdeviceBackend.h.

Member Enumeration Documentation

◆ Type

enum class ChimeraTK::SubdeviceBackend::Type

strongprotected

Enumerator
area
threeRegisters
twoRegisters
areaHandshake

Definition at line 81 of file SubdeviceBackend.h.

Constructor & Destructor Documentation

◆ SubdeviceBackend()

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

explicit

Definition at line 52 of file SubdeviceBackend.cc.

Member Function Documentation

◆ 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 545 of file SubdeviceBackend.cc.

◆ close()

void ChimeraTK::SubdeviceBackend::close ( )

overridevirtual

Close the device.

Implements ChimeraTK::DeviceBackend.

Definition at line 189 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 23 of file SubdeviceBackend.cc.

◆ DEFINE_VIRTUAL_FUNCTION_TEMPLATE_VTABLE_FILLER()

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

protected

◆ 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 551 of file SubdeviceBackend.cc.

◆ getMetadataCatalogue()

MetadataCatalogue ChimeraTK::SubdeviceBackend::getMetadataCatalogue ( ) const

overridevirtual

Return the device metadata catalogue.

Reimplemented from ChimeraTK::DeviceBackendImpl.

Definition at line 203 of file SubdeviceBackend.cc.

◆ getRegisterAccessor_area() [1/2]

template<typename UserType >

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

protected

getRegisterAccessor implemenation for area types

Definition at line 391 of file SubdeviceBackend.cc.

◆ getRegisterAccessor_area() [2/2]

template<>

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

protected

Definition at line 464 of file SubdeviceBackend.cc.

◆ getRegisterAccessor_helper()

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

protected

Definition at line 421 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 309 of file SubdeviceBackend.cc.

◆ getRegisterAccessor_synchronized() [1/2]

template<typename UserType >

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

protected

getRegisterAccessor implemenation for threeRegisters types

Definition at line 464 of file SubdeviceBackend.cc.

◆ getRegisterAccessor_synchronized() [2/2]

template<>

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

protected

Definition at line 464 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 197 of file SubdeviceBackend.cc.

◆ needAreaParam()

bool ChimeraTK::SubdeviceBackend::needAreaParam ( )

inlineprotected

Definition at line 149 of file SubdeviceBackend.h.

◆ needStatusParam()

bool ChimeraTK::SubdeviceBackend::needStatusParam ( )

inlineprotected

Definition at line 150 of file SubdeviceBackend.h.

◆ obtainTargetBackend()

void ChimeraTK::SubdeviceBackend::obtainTargetBackend ( )

protected

obtain the target backend if not yet done

Definition at line 172 of file SubdeviceBackend.cc.

◆ open()

void ChimeraTK::SubdeviceBackend::open ( )

overridevirtual

Open the device.

Implements ChimeraTK::DeviceBackend.

Definition at line 180 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 65 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 538 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 330 of file SubdeviceBackend.cc.

Friends And Related Symbol Documentation

◆ SubdeviceRegisterAccessor

friend class SubdeviceRegisterAccessor

friend

Definition at line 79 of file SubdeviceBackend.h.

Member Data Documentation

◆ _metadataCatalogue

MetadataCatalogue ChimeraTK::SubdeviceBackend::_metadataCatalogue

protected

Definition at line 119 of file SubdeviceBackend.h.

◆ _registerMap

NumericAddressedRegisterCatalogue ChimeraTK::SubdeviceBackend::_registerMap

protected

map from register names to addresses

Definition at line 118 of file SubdeviceBackend.h.

◆ addressToDataDelay

size_t ChimeraTK::SubdeviceBackend::addressToDataDelay {0}

protected

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

Definition at line 115 of file SubdeviceBackend.h.

◆ mutex

std::mutex ChimeraTK::SubdeviceBackend::mutex

protected

Mutex to deal with concurrent access to the device.

Definition at line 90 of file SubdeviceBackend.h.

◆ sleepTime

size_t ChimeraTK::SubdeviceBackend::sleepTime {100}

protected

for type == threeRegisters or twoRegisters: sleep time of polling loop resp. between operations, in usecs.

Definition at line 112 of file SubdeviceBackend.h.

◆ targetAddress

std::string ChimeraTK::SubdeviceBackend::targetAddress

protected

for type == threeRegisters or twoRegisters: the name of the target registers

Definition at line 109 of file SubdeviceBackend.h.

◆ targetAlias

std::string ChimeraTK::SubdeviceBackend::targetAlias

protected

the target device name

Definition at line 99 of file SubdeviceBackend.h.

◆ targetArea

std::string ChimeraTK::SubdeviceBackend::targetArea

protected

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

Definition at line 106 of file SubdeviceBackend.h.

◆ targetControl

std::string ChimeraTK::SubdeviceBackend::targetControl

protected

Definition at line 109 of file SubdeviceBackend.h.

◆ targetData

std::string ChimeraTK::SubdeviceBackend::targetData

protected

Definition at line 109 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 103 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 96 of file SubdeviceBackend.h.

◆ type

Type ChimeraTK::SubdeviceBackend::type

protected

type of the subdeivce

Definition at line 93 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

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Type

Constructor & Destructor Documentation

◆ SubdeviceBackend()

Member Function Documentation

◆ activateAsyncRead()

◆ close()

◆ createInstance()

◆ DEFINE_VIRTUAL_FUNCTION_TEMPLATE_VTABLE_FILLER()

◆ getInvolvedBackendIDs()

◆ getMetadataCatalogue()

◆ getRegisterAccessor_area() [1/2]

◆ getRegisterAccessor_area() [2/2]

◆ getRegisterAccessor_helper()

◆ getRegisterAccessor_impl()

◆ getRegisterAccessor_synchronized() [1/2]

◆ getRegisterAccessor_synchronized() [2/2]

◆ getRegisterCatalogue()

◆ needAreaParam()

◆ needStatusParam()

◆ obtainTargetBackend()

◆ open()

◆ readDeviceInfo()

◆ setExceptionImpl()

◆ verifyRegisterAccessorSize()

Friends And Related Symbol Documentation

◆ SubdeviceRegisterAccessor

Member Data Documentation

◆ _metadataCatalogue

◆ _registerMap

◆ addressToDataDelay

◆ mutex

◆ sleepTime

◆ targetAddress

◆ targetAlias

◆ targetArea

◆ targetControl

◆ targetData

◆ targetDevice

◆ timeout

◆ type