Base class for address-based device backends (e.g. More...

#include <NumericAddressedBackend.h>

Inheritance diagram for ChimeraTK::NumericAddressedBackend:

Collaboration diagram for ChimeraTK::NumericAddressedBackend:

Public Member Functions
	NumericAddressedBackend (const std::string &mapFileName="", std::unique_ptr< NumericAddressedRegisterCatalogue > registerMapPointer=std::make_unique< NumericAddressedRegisterCatalogue >(), const std::string &dataConsistencyKeyDescriptor="")

	~NumericAddressedBackend () override=default

virtual void	read (uint64_t bar, uint64_t address, int32_t *data, size_t sizeInBytes)
	Read function to be implemented by backends.

virtual void	write (uint64_t bar, uint64_t address, int32_t const *data, size_t sizeInBytes)
	Write function to be implemented by backends.

virtual void	read (uint8_t bar, uint32_t address, int32_t *data, size_t sizeInBytes)
	Deprecated read function using 32bit address for backwards compatibility.

virtual void	write (uint8_t bar, uint32_t address, int32_t const *data, size_t sizeInBytes)
	Deprecated write function using 32bit address for backwards compatibility.

virtual bool	barIndexValid (uint64_t bar)
	Function to be implemented by the backends.

virtual bool	canMergeRequests () const
	Determines whether the backend supports merging of requests (read or write)

virtual size_t	minimumTransferAlignment (uint64_t bar) const
	Determines the supported minimum alignment for any read/write requests.

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

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

NumericAddressedRegisterInfo	getRegisterInfo (const RegisterPath &registerPathName)
	getRegisterInfo returns a NumericAddressedRegisterInfo object for the given register.

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

void	close () final
	Deactivates all asynchronous accessors and calls closeImpl().

virtual void	closeImpl ()
	All backends derrived from NumericAddressedBackend must implement closeImpl() instead of close.

virtual std::future< void >	activateSubscription (uint32_t interruptNumber, boost::shared_ptr< async::DomainImpl< std::nullptr_t > > asyncDomain)
	Activate/create the subscription for a given interrupt (for instance by starting the according interrupt handling thread).

void	setExceptionImpl () noexcept override
	Turn off the internal variable which remembers that async is active.

template<typename BackendSpecificUserType >
std::pair< BackendSpecificUserType, VersionNumber >	getAsyncDomainInitialValue (size_t asyncDomainId)
	Get the initial value for a certain async::Domain.

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

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

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

virtual void	open ()=0
	Open the device.

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

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

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

Protected Attributes
std::unique_ptr< NumericAddressedRegisterCatalogue >	_registerMapPointer

NumericAddressedRegisterCatalogue &	_registerMap

MetadataCatalogue	_metadataCatalogue
	metadata catalogue

std::mutex	_unalignedAccess
	mutex for protecting unaligned access

friend	NumericAddressedLowLevelTransferElement

friend	TriggeredPollDistributor

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
template<class UserType , class ConverterType >
class	NumericAddressedBackendMuxedRegisterAccessor

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

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

Detailed Description

Base class for address-based device backends (e.g.

PICe, Rebot, ...)

Definition at line 20 of file NumericAddressedBackend.h.

Constructor & Destructor Documentation

◆ NumericAddressedBackend()

ChimeraTK::NumericAddressedBackend::NumericAddressedBackend	(	const std::string &	mapFileName = `""`,
		std::unique_ptr< NumericAddressedRegisterCatalogue >	registerMapPointer = `std::make_unique<NumericAddressedRegisterCatalogue>()`,
		const std::string &	dataConsistencyKeyDescriptor = `""`
	)

explicit

Definition at line 23 of file NumericAddressedBackend.cc.

◆ ~NumericAddressedBackend()

ChimeraTK::NumericAddressedBackend::~NumericAddressedBackend ( )

overridedefault

Member Function Documentation

◆ activateAsyncRead()

void ChimeraTK::NumericAddressedBackend::activateAsyncRead ( )

overridevirtualnoexcept

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 208 of file NumericAddressedBackend.cc.

◆ activateSubscription()

std::future< void > ChimeraTK::NumericAddressedBackend::activateSubscription	(	uint32_t	interruptNumber,
		boost::shared_ptr< async::DomainImpl< std::nullptr_t > >	asyncDomain
	)

virtual

Activate/create the subscription for a given interrupt (for instance by starting the according interrupt handling thread).

A shared pointer to the async::Domain is handed as a parameter. The backend has to store it together with the subscription (usually as a weak pointer) and use it to distribute the interrupt.

A future is returned. It becomes ready when the subscription is actually active (e.g. from inside the an interrupt handling thread after the initialisation sequence with the hardware is done).

If the subscription already exists and is active, a ready future is returned.

The function has an empty default implementation which returns a ready future.

Reimplemented in ChimeraTK::UioBackend, and ChimeraTK::XdmaBackend.

Definition at line 229 of file NumericAddressedBackend.cc.

◆ barIndexValid()

bool ChimeraTK::NumericAddressedBackend::barIndexValid ( uint64_t bar )

virtual

Function to be implemented by the backends.

Returns whether the given bar number is valid.

Reimplemented in ChimeraTK::DummyBackendBase, and ChimeraTK::UioBackend.

Definition at line 113 of file NumericAddressedBackend.cc.

◆ canMergeRequests()

virtual bool ChimeraTK::NumericAddressedBackend::canMergeRequests ( ) const

inlinevirtual

Determines whether the backend supports merging of requests (read or write)

Should return true if the backend supports that several consecutive write or read operations are merged into one single read or write request. If a deriving backend cannot handle such requests, it can prevent this by returning false here.

Returns: true if supported, false otherwise

Definition at line 77 of file NumericAddressedBackend.h.

◆ close()

void ChimeraTK::NumericAddressedBackend::close ( )

finalvirtual

Deactivates all asynchronous accessors and calls closeImpl().

Implements ChimeraTK::DeviceBackend.

Definition at line 238 of file NumericAddressedBackend.cc.

◆ closeImpl()

virtual void ChimeraTK::NumericAddressedBackend::closeImpl ( )

inlinevirtual

All backends derrived from NumericAddressedBackend must implement closeImpl() instead of close.

Like this it is assured that the deactivation of the asynchronous accessors is always executed.

Reimplemented in ChimeraTK::DummyBackend, ChimeraTK::ExceptionDummy, ChimeraTK::PcieBackend, ChimeraTK::RebotBackend, ChimeraTK::SharedDummyBackend, ChimeraTK::UioBackend, and ChimeraTK::XdmaBackend.

Definition at line 118 of file NumericAddressedBackend.h.

◆ getAsyncDomainInitialValue()

template<typename BackendSpecificUserType >

std::pair< BackendSpecificUserType, VersionNumber > ChimeraTK::NumericAddressedBackend::getAsyncDomainInitialValue ( size_t asyncDomainId )

Get the initial value for a certain async::Domain.

The return value is the backend specific user type (which can vary for different async domains) and the according version number. For the NumericAddressedBackend the BackendSpecificUserType is nullptr_t, which does not contain any information about the version number. Hence this implementation always returns [nullptr, VersionNumber{nullptr}]. The code has to be template code because it is called with the template parameter from the DomainsContainer.

Definition at line 186 of file NumericAddressedBackend.h.

◆ getMetadataCatalogue()

MetadataCatalogue ChimeraTK::NumericAddressedBackend::getMetadataCatalogue ( ) const

overridevirtual

Return the device metadata catalogue.

Reimplemented from ChimeraTK::DeviceBackendImpl.

Definition at line 254 of file NumericAddressedBackend.cc.

◆ getRegisterCatalogue()

RegisterCatalogue ChimeraTK::NumericAddressedBackend::getRegisterCatalogue ( ) const

overridevirtual

Return the register catalogue with detailed information on all registers.

Implements ChimeraTK::DeviceBackend.

Definition at line 248 of file NumericAddressedBackend.cc.

◆ getRegisterInfo()

NumericAddressedRegisterInfo ChimeraTK::NumericAddressedBackend::getRegisterInfo ( const RegisterPath & registerPathName )

getRegisterInfo returns a NumericAddressedRegisterInfo object for the given register.

This is mainly used by accessor implementations

Parameters

registerPathName identifies which register to return the RegisterInfo for.

Returns: Shared pointer to the NumericAddressedRegisterInfo object in the catalogue.

FIXME move into catalogue implementation, then make return type a const reference!

Definition at line 49 of file NumericAddressedBackend.cc.

◆ minimumTransferAlignment()

virtual size_t ChimeraTK::NumericAddressedBackend::minimumTransferAlignment ( uint64_t bar ) const

inlinevirtual

Determines the supported minimum alignment for any read/write requests.

If the backend expects a particular alignment for read()/write() calls it should return a value bigger than 1. The address and sizeInBytes arguments of the read()/write() calls will be always an integer multiple of this number. Any unaligned transfers will be changed to meet these criteria (additional padding data will be thrown away).

The default implementation returns 1, which means no special alignment is required.

Returns: Minimum alignment in bytes

Reimplemented in ChimeraTK::DummyBackendBase, ChimeraTK::RebotBackend, and ChimeraTK::UioBackend.

Definition at line 91 of file NumericAddressedBackend.h.

◆ read() [1/2]

void ChimeraTK::NumericAddressedBackend::read	(	uint64_t	bar,
		uint64_t	address,
		int32_t *	data,
		size_t	sizeInBytes
	)

virtual

Read function to be implemented by backends.

TODO: Add documentation!

Reimplemented in ChimeraTK::DummyBackend, ChimeraTK::ExceptionDummy, ChimeraTK::SharedDummyBackend, ChimeraTK::UioBackend, ChimeraTK::XdmaBackend, and DummyForDoubleBuffering.

Definition at line 94 of file NumericAddressedBackend.cc.

◆ read() [2/2]

void ChimeraTK::NumericAddressedBackend::read	(	uint8_t	bar,
		uint32_t	address,
		int32_t *	data,
		size_t	sizeInBytes
	)

virtual

Deprecated read function using 32bit address for backwards compatibility.

Old backends which have not yet been updated to the new 64 bit address interface will implement this. Please implement the read() function with the 64 bit address signature instead!

Note: deprecated with warning since 2022-07-28 remove after end of 2023.

Reimplemented in ChimeraTK::DummyBackend, ChimeraTK::DummyBackendBase, ChimeraTK::SharedDummyBackend, ChimeraTK::PcieBackend, and ChimeraTK::RebotBackend.

Definition at line 79 of file NumericAddressedBackend.cc.

◆ setExceptionImpl()

void ChimeraTK::NumericAddressedBackend::setExceptionImpl ( )

overridevirtualnoexcept

Turn off the internal variable which remembers that async is active.

Reimplemented from ChimeraTK::DeviceBackendImpl.

Definition at line 260 of file NumericAddressedBackend.cc.

◆ write() [1/2]

void ChimeraTK::NumericAddressedBackend::write	(	uint64_t	bar,
		uint64_t	address,
		int32_t const *	data,
		size_t	sizeInBytes
	)

virtual

Write function to be implemented by backends.

TODO: Add documentation!

Reimplemented in ChimeraTK::XdmaBackend, DummyForAreaHandshakeBackend, ChimeraTK::DummyBackend, ChimeraTK::ExceptionDummy, ChimeraTK::SharedDummyBackend, ChimeraTK::UioBackend, TestDummy, and WriteCountingBackend.

Definition at line 103 of file NumericAddressedBackend.cc.

◆ write() [2/2]

void ChimeraTK::NumericAddressedBackend::write	(	uint8_t	bar,
		uint32_t	address,
		int32_t const *	data,
		size_t	sizeInBytes
	)

virtual

Deprecated write function using 32bit address for backwards compatibility.

Old backends which have not yet been updated to the new 64 bit address interface will implement this. Please implement the write() function with the 64 bit address signature instead!

Note: deprecated with warning since 2022-07-28, remove after end of 2023.

Reimplemented in ChimeraTK::DummyBackend, ChimeraTK::DummyBackendBase, ChimeraTK::SharedDummyBackend, ChimeraTK::PcieBackend, and ChimeraTK::RebotBackend.

Definition at line 86 of file NumericAddressedBackend.cc.

Friends And Related Symbol Documentation

◆ NumericAddressedBackendMuxedRegisterAccessor

template<class UserType , class ConverterType >

friend class NumericAddressedBackendMuxedRegisterAccessor

friend

Definition at line 166 of file NumericAddressedBackend.h.

Member Data Documentation

◆ _metadataCatalogue

MetadataCatalogue ChimeraTK::NumericAddressedBackend::_metadataCatalogue

protected

metadata catalogue

Definition at line 157 of file NumericAddressedBackend.h.

◆ _registerMap

NumericAddressedRegisterCatalogue& ChimeraTK::NumericAddressedBackend::_registerMap

protected

Definition at line 154 of file NumericAddressedBackend.h.

◆ _registerMapPointer

std::unique_ptr<NumericAddressedRegisterCatalogue> ChimeraTK::NumericAddressedBackend::_registerMapPointer

protected

Definition at line 153 of file NumericAddressedBackend.h.

◆ _unalignedAccess

std::mutex ChimeraTK::NumericAddressedBackend::_unalignedAccess

protected

mutex for protecting unaligned access

Definition at line 160 of file NumericAddressedBackend.h.

◆ NumericAddressedLowLevelTransferElement

friend ChimeraTK::NumericAddressedBackend::NumericAddressedLowLevelTransferElement

protected

Definition at line 162 of file NumericAddressedBackend.h.

◆ TriggeredPollDistributor

friend ChimeraTK::NumericAddressedBackend::TriggeredPollDistributor

protected

Definition at line 163 of file NumericAddressedBackend.h.

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

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

Public Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ NumericAddressedBackend()

◆ ~NumericAddressedBackend()

Member Function Documentation

◆ activateAsyncRead()

◆ activateSubscription()

◆ barIndexValid()

◆ canMergeRequests()

◆ close()

◆ closeImpl()

◆ getAsyncDomainInitialValue()

◆ getMetadataCatalogue()

◆ getRegisterCatalogue()

◆ getRegisterInfo()

◆ minimumTransferAlignment()

◆ read() [1/2]

◆ read() [2/2]

◆ setExceptionImpl()

◆ write() [1/2]

◆ write() [2/2]

Friends And Related Symbol Documentation

◆ NumericAddressedBackendMuxedRegisterAccessor

Member Data Documentation

◆ _metadataCatalogue

◆ _registerMap

◆ _registerMapPointer

◆ _unalignedAccess

◆ NumericAddressedLowLevelTransferElement

◆ TriggeredPollDistributor