The dummy device opens a mapping file instead of a device, and implements all registers defined in the mapping file in memory. More...

#include <DummyBackend.h>

Inheritance diagram for ChimeraTK::DummyBackend:

Collaboration diagram for ChimeraTK::DummyBackend:

Classes
struct	AddressRange

Public Member Functions
	DummyBackend (const std::string &mapFileName, const std::string &dataConsistencyKeyDescriptor="")

	~DummyBackend () override=default

void	open () override
	Open the device.

void	closeImpl () override
	This closes the device, clears all internal registers, read-only settings and callback functions.

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

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

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.

DummyRegisterRawAccessor	getRawAccessor (const std::string &module, const std::string &register_name)
	Get a raw accessor to the underlying memory with the convenience of using register names.

VersionNumber	triggerInterrupt (uint32_t interruptNumber) override
	Simulate the arrival of an interrupt.

void	read (uint8_t bar, uint32_t address, int32_t *data, size_t sizeInBytes) final
	You cannot override the read version with 32 bit address any more.

void	write (uint8_t bar, uint32_t address, int32_t const *data, size_t sizeInBytes) final
	You cannot override the write version with 32 bit address any more.

Public Member Functions inherited from ChimeraTK::DummyBackendBase
	DummyBackendBase (std::string const &mapFileName, const std::string &dataConsistencyKeyDescriptor="")

	~DummyBackendBase () override=default

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

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

void	read (uint8_t bar, uint32_t address, int32_t *data, size_t sizeInBytes) final
	You cannot override the read version with 32 bit address any more.

void	write (uint8_t bar, uint32_t address, int32_t const *data, size_t sizeInBytes) final
	You cannot override the write version with 32 bit address any more.

bool	barIndexValid (uint64_t bar) override
	All bars are valid in dummies.

std::map< uint64_t, size_t >	getBarSizesInBytesFromRegisterMapping () const
	Determines the size of each bar because the DummyBackends allocate memory per bar.

template<typename UserType >
boost::shared_ptr< NDRegisterAccessor< UserType > >	getRegisterAccessor_impl (const RegisterPath &registerPathName, size_t numberOfWords, size_t wordOffsetInRegister, AccessModeFlags flags)
	Specific override which allows to create "DUMMY_INTEERRUPT_X" accessors.

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

	~NumericAddressedBackend () override=default

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

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

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)

Static Public Member Functions inherited from ChimeraTK::DummyBackendBase
static void	checkSizeIsMultipleOfWordSize (size_t sizeInBytes)

template<typename T , typename... Args>
static boost::shared_ptr< DeviceBackend >	returnInstance (const std::string &instanceId, Args &&... arguments)
	Backward compatibility: Leftover from the time when the dummy managed it's own map to return the same instance multiple times, and still allow to use the same map file with different instances.

Protected Member Functions
void	resizeBarContents ()

void	runWriteCallbackFunctionsForAddressRange (AddressRange addressRange)

std::list< boost::function< void(void)> >	findCallbackFunctionsForAddressRange (AddressRange addressRange)

void	setReadOnly (uint64_t bar, uint64_t address, size_t sizeInWords)

void	setReadOnly (AddressRange addressRange)

bool	isReadOnly (uint64_t bar, uint64_t address) const

void	setWriteCallbackFunction (AddressRange addressRange, boost::function< void(void)> const &writeCallbackFunction)

bool	isWriteRangeOverlap (AddressRange firstRange, AddressRange secondRange)
	returns true if the ranges overlap and at least one of the overlapping registers can be written

void	writeRegisterWithoutCallback (uint64_t bar, uint64_t address, int32_t data)
	Not write-protected function for internal use only.

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

Static Protected Member Functions
static std::string	convertPathRelativeToDmapToAbs (std::string const &mapfileName)

Protected Attributes
std::string	_mapFile
	name of the map file

std::map< uint64_t, std::vector< int32_t > >	_barContents

std::set< std::pair< uint64_t, uint64_t > >	_readOnlyAddresses

std::multimap< AddressRange, boost::function< void(void)> >	_writeCallbackFunctions

std::mutex	mutex

Protected Attributes inherited from ChimeraTK::NumericAddressedBackend
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<typename T >
class	DummyRegisterAccessor
	register accessors must be friends to access the map and the registers

template<typename T >
class	DummyMultiplexedRegisterAccessor

class	DummyRegisterRawAccessor

class	SharedDummyBackend

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

Public Attributes inherited from ChimeraTK::DummyBackendBase
std::atomic< bool >	throwExceptionOpen {false}

std::atomic< bool >	throwExceptionRead {false}

std::atomic< bool >	throwExceptionWrite {false}

std::atomic< size_t >	throwExceptionCounter {0}

Detailed Description

The dummy device opens a mapping file instead of a device, and implements all registers defined in the mapping file in memory.

Like this it mimics the real PCIe device.

Deriving from this class, you can write dedicated implementations with special functionality. For this purpose one can register write callback function which are executed if a certain register (or range of registers) is written. For instance: Writing to a START_DAQ register can fill a data buffer with dummy values which can be read back. For each call of writeReg or writeArea the callback function is called once. If you require the callback function to be executed after each register change, use writeReg multiple times instead of writeArea.

Registers can be set to read-only mode. In this case a write operation will just be ignored and no callback function is executed.

Examples: CustomBackend.cc.

Definition at line 45 of file DummyBackend.h.

Constructor & Destructor Documentation

◆ DummyBackend()

ChimeraTK::DummyBackend::DummyBackend	(	const std::string &	mapFileName,
		const std::string &	dataConsistencyKeyDescriptor = `""`
	)

explicit

Examples: CustomBackend.cc.

Definition at line 17 of file DummyBackend.cc.

◆ ~DummyBackend()

ChimeraTK::DummyBackend::~DummyBackend ( )

overridedefault

Member Function Documentation

◆ closeImpl()

void ChimeraTK::DummyBackend::closeImpl ( )

overridevirtual

This closes the device, clears all internal registers, read-only settings and callback functions.

As the device could be opened with another mapping file later, these will most probably be invalid in this case. This is why the read-only settings and callback functions have to be set again when reopening the file.

Reimplemented from ChimeraTK::NumericAddressedBackend.

Reimplemented in ChimeraTK::ExceptionDummy.

Definition at line 39 of file DummyBackend.cc.

◆ convertPathRelativeToDmapToAbs()

std::string ChimeraTK::DummyBackend::convertPathRelativeToDmapToAbs ( std::string const & mapfileName )

staticprotected

Examples: CustomBackend.cc.

Definition at line 176 of file DummyBackend.cc.

◆ createInstance()

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

static

Definition at line 160 of file DummyBackend.cc.

◆ findCallbackFunctionsForAddressRange()

std::list< boost::function< void(void)> > ChimeraTK::DummyBackend::findCallbackFunctionsForAddressRange ( AddressRange addressRange )

protected

Definition at line 115 of file DummyBackend.cc.

◆ getRawAccessor()

DummyRegisterRawAccessor ChimeraTK::DummyBackend::getRawAccessor	(	const std::string &	module,
		const std::string &	register_name
	)

Get a raw accessor to the underlying memory with the convenience of using register names.

This accessor had nothing to do with regular, TransferElement based accessors and serves as second, independent implementation for debugging.

We have to use the old module/register interface because the dummy uses the old style mapping internally.

Definition at line 184 of file DummyBackend.cc.

◆ isReadOnly()

bool ChimeraTK::DummyBackend::isReadOnly	(	uint64_t	bar,
		uint64_t	address
	)		const

protected

Definition at line 97 of file DummyBackend.cc.

◆ isWriteRangeOverlap()

bool ChimeraTK::DummyBackend::isWriteRangeOverlap	(	AddressRange	firstRange,
		AddressRange	secondRange
	)

protected

returns true if the ranges overlap and at least one of the overlapping registers can be written

Definition at line 139 of file DummyBackend.cc.

◆ open()

void ChimeraTK::DummyBackend::open ( )

overridevirtual

Open the device.

Implements ChimeraTK::DeviceBackend.

Reimplemented in ChimeraTK::ExceptionDummy.

Definition at line 22 of file DummyBackend.cc.

◆ read() [1/2]

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

overridevirtual

Read function to be implemented by backends.

TODO: Add documentation!

Reimplemented from ChimeraTK::NumericAddressedBackend.

Reimplemented in ChimeraTK::ExceptionDummy, and DummyForDoubleBuffering.

Definition at line 50 of file DummyBackend.cc.

◆ read() [2/2]

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

inlinefinalvirtual

You cannot override the read version with 32 bit address any more.

Please change your implementation to the 64 bit signature.

Reimplemented from ChimeraTK::NumericAddressedBackend.

Definition at line 55 of file DummyBackendBase.h.

◆ readDeviceInfo()

std::string ChimeraTK::DummyBackend::readDeviceInfo ( )

overridevirtual

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.

Implements ChimeraTK::DeviceBackend.

Definition at line 81 of file DummyBackend.cc.

◆ resizeBarContents()

void ChimeraTK::DummyBackend::resizeBarContents ( )

protected

Definition at line 28 of file DummyBackend.cc.

◆ runWriteCallbackFunctionsForAddressRange()

void ChimeraTK::DummyBackend::runWriteCallbackFunctionsForAddressRange ( AddressRange addressRange )

protected

Definition at line 107 of file DummyBackend.cc.

◆ setReadOnly() [1/2]

void ChimeraTK::DummyBackend::setReadOnly ( AddressRange addressRange )

protected

Definition at line 93 of file DummyBackend.cc.

◆ setReadOnly() [2/2]

void ChimeraTK::DummyBackend::setReadOnly	(	uint64_t	bar,
		uint64_t	address,
		size_t	sizeInWords
	)

protected

Definition at line 87 of file DummyBackend.cc.

◆ setWriteCallbackFunction()

void ChimeraTK::DummyBackend::setWriteCallbackFunction	(	AddressRange	addressRange,
		boost::function< void(void)> const &	writeCallbackFunction
	)

protected

Definition at line 101 of file DummyBackend.cc.

◆ triggerInterrupt()

VersionNumber ChimeraTK::DummyBackend::triggerInterrupt ( uint32_t interruptNumber )

overridevirtual

Simulate the arrival of an interrupt.

For all push-type accessors which have been created for that particular interrupt number, the data will be read out through a synchronous accessor and pushed into the data transport queues of the asynchronous accessors, so they can be received by the application.

Returns: The version number that was send with all data in this interrupt.

Implements ChimeraTK::DummyBackendBase.

Definition at line 188 of file DummyBackend.cc.

◆ write() [1/2]

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

overridevirtual

Write function to be implemented by backends.

TODO: Add documentation!

Reimplemented from ChimeraTK::NumericAddressedBackend.

Reimplemented in DummyForAreaHandshakeBackend, ChimeraTK::ExceptionDummy, TestDummy, and WriteCountingBackend.

Definition at line 62 of file DummyBackend.cc.

◆ write() [2/2]

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

inlinefinalvirtual

You cannot override the write version with 32 bit address any more.

Please change your implementation to the 64 bit signature.

Reimplemented from ChimeraTK::NumericAddressedBackend.

Definition at line 63 of file DummyBackendBase.h.

◆ writeRegisterWithoutCallback()

void ChimeraTK::DummyBackend::writeRegisterWithoutCallback	(	uint64_t	bar,
		uint64_t	address,
		int32_t	data
	)

protected

Not write-protected function for internal use only.

It does not trigger the callback function so it can be used inside a callback function for re-synchronization.

Definition at line 45 of file DummyBackend.cc.

Friends And Related Symbol Documentation

◆ DummyMultiplexedRegisterAccessor

template<typename T >

friend class DummyMultiplexedRegisterAccessor

friend

Definition at line 131 of file DummyBackend.h.

◆ DummyRegisterAccessor

template<typename T >

friend class DummyRegisterAccessor

friend

register accessors must be friends to access the map and the registers

Definition at line 128 of file DummyBackend.h.

◆ DummyRegisterRawAccessor

friend class DummyRegisterRawAccessor

friend

Definition at line 133 of file DummyBackend.h.

◆ SharedDummyBackend

friend class SharedDummyBackend

friend

Definition at line 134 of file DummyBackend.h.

Member Data Documentation

◆ _barContents

std::map<uint64_t, std::vector<int32_t> > ChimeraTK::DummyBackend::_barContents

protected

Definition at line 103 of file DummyBackend.h.

◆ _mapFile

std::string ChimeraTK::DummyBackend::_mapFile

protected

name of the map file

Definition at line 101 of file DummyBackend.h.

◆ _readOnlyAddresses

std::set<std::pair<uint64_t, uint64_t> > ChimeraTK::DummyBackend::_readOnlyAddresses

protected

Definition at line 104 of file DummyBackend.h.

◆ _writeCallbackFunctions

std::multimap<AddressRange, boost::function<void(void)> > ChimeraTK::DummyBackend::_writeCallbackFunctions

protected

Definition at line 105 of file DummyBackend.h.

◆ mutex

std::mutex ChimeraTK::DummyBackend::mutex

protected

Definition at line 106 of file DummyBackend.h.

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

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

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ DummyBackend()

◆ ~DummyBackend()

Member Function Documentation

◆ closeImpl()

◆ convertPathRelativeToDmapToAbs()

◆ createInstance()

◆ findCallbackFunctionsForAddressRange()

◆ getRawAccessor()

◆ isReadOnly()

◆ isWriteRangeOverlap()

◆ open()

◆ read() [1/2]

◆ read() [2/2]

◆ readDeviceInfo()

◆ resizeBarContents()

◆ runWriteCallbackFunctionsForAddressRange()

◆ setReadOnly() [1/2]

◆ setReadOnly() [2/2]

◆ setWriteCallbackFunction()

◆ triggerInterrupt()

◆ write() [1/2]

◆ write() [2/2]

◆ writeRegisterWithoutCallback()

Friends And Related Symbol Documentation

◆ DummyMultiplexedRegisterAccessor

◆ DummyRegisterAccessor

◆ DummyRegisterRawAccessor

◆ SharedDummyBackend

Member Data Documentation

◆ _barContents

◆ _mapFile

◆ _readOnlyAddresses

◆ _writeCallbackFunctions

◆ mutex