Class to handle register access over the ESS Readout Master Module. More...

#include <RMMRegisterAccess.h>

Collaboration diagram for RMMRegisterAccess:

Public Types
enum class	RegisterTag { CTRL , ENG , TIME , RING_MST , CMAC , ALL }
	Enum class representing different register tags. More...

Public Member Functions
	RMMRegisterAccess (const std::string &serverIP, int serverPort)
	Constructor of the RMMRegisterAccess instance.

	~RMMRegisterAccess ()
	Destructor of the RMMRegisterAccess.

std::unordered_map< RegisterTag, std::unordered_map< std::string, uint32_t > >	fillAllAddressMaps ()
	Fill all address maps.

std::list< std::string >	getAllRegMaps ()
	returns a list of shared pointers to current address maps.

void	addRegMapMutexes (FENRegMap map)
	Calls regMutex addMap.

unsigned int	addRegsMutexes (std::list< std::string > regs, bool critic=true)
	Calls regMutex addRegs.

bool	addRegMutex (std::string reg, std::string tag="NoTag", bool critic=true)
	Calls regMutex addReg.

RegLockGuard	regLockGuard (std::string reg, std::string tag="NoTag")
	returns a lock guard object for that register mutex.

std::string	addrLookUp (const std::string &name, RegisterTag tag=RegisterTag::ALL)
	Retrieves the address of a register from the address map.

RMMResult	feaFwRegRead (const std::string &reg_name, int ring_id, int node_id, const std::string &tag="")
	Read a front-end register, calculating the ring/node offset.

RMMResult	feaFwRegWrite (const std::string &reg_name, int ring_id, int node_id, uint32_t data, const std::string &tag="")
	Write in a front-end register, calculating the ring/node offset.

RMMResult	regRead (const std::string &regName, RegisterTag tag=RegisterTag::ALL)
	Reads a register value by its name from the register map.

void	regAssert (const std::string &reg_name, uint32_t exp_data, RegisterTag tag=RegisterTag::ALL)
	Check a register matches an expected value, or throw a ValueError exception.

RMMResult	regWrite (const std::string &regName, uint32_t data, RegisterTag tag=RegisterTag::ALL)
	Writes a value to a named register.

rmmStatus	regPoll (const std::string &regName, uint32_t expData, double pollDelay=1.0, uint32_t timeout=0, RegisterTag regTag=RegisterTag::ALL, std::function< bool(uint32_t)> stopCondition=nullptr, std::function< bool()> checkStop=nullptr)
	Polls a named register until it matches the expected value, or stops based on a custom stop condition or timeout.

RMMResult	fieldRead (const std::string &reg, RegisterTag tag, int bitBegin, int bitWidth)
	Reads a field from a register in the RMM space using a register name.

RMMResult	fieldRead (uint32_t reg, int bitBegin, int bitWidth)
	Reads a field from a register in the RMM space using a register address.

RMMResult	fieldWrite (const std::string &reg, RegisterTag tag, int bitBegin, int bitWidth, uint32_t data)
	Writes a field to a register in the RMM space using a register name.

RMMResult	fieldWrite (uint32_t reg, int bitBegin, int bitWidth, uint32_t data)
	Writes a field to a register in the RMM space using a register address.

rmmStatus	i2cWriteByte (int i2c_addr, uint32_t data)
	Writes a single byte to an I2C address.

rmmStatus	i2cWrite8bReg (int i2c_addr, int reg_addr, uint32_t data)
	Writes to an 8bit register at an I2C address.

rmmStatus	i2cWrite16bReg (int i2c_addr, int reg_addr, uint32_t data)
	Writes to a 16bit register at an I2C address.

uint32_t	i2cRead8bRegSi570 (int i2c_addr, int reg_addr)
	Reads from an 8bit register at an I2C address (Si570 only).

RMMResult	regMaskWrite (const std::string &regName, uint32_t data, uint32_t mask, RegisterTag tag=RegisterTag::ALL)
	Writes a value to a register using a bitmask.

rmmStatus	i2cDelay (uint32_t delay)
	Use the I2C controller to time a delay.

RMMResult	rawRead (const std::string &addr)
	Performs a read operation from a register address.

RMMResult	rawWrite (const std::string &addr, uint32_t data)
	Performs a write operation to a register address.

void	requestStop ()
	Requests to stop ongoing operations.

void	resetStop ()
	Resets the stop request flag, allowing operations to continue.

bool	isStopRequested () const
	Checks if a stop request has been issued.

bool	isLegacyFW () const
	Checks if the FW version is legagy (Non UDP Core version).

Public Attributes
RMMLog	rmmLog
	Log handler for RMMRegisterAccess messages.

Friends
class	I2CMutex

Detailed Description

Class to handle register access over the ESS Readout Master Module.

This class provides methods for reading and writing hardware registers via a network socket.

Note: The class maintains an internal mapping of register addresses and provides high-level functions for interacting with hardware.

Member Enumeration Documentation

◆ RegisterTag

enum class RMMRegisterAccess::RegisterTag

strong

Enum class representing different register tags.

This enum class is used to identify specific address maps for registers. Each tag corresponds to a particular set of registers in the system.

Enumerator
CTRL	Control register.
ENG	Engineering register.
TIME	Time register.
RING_MST	Ring master register.
CMAC	CMAC register (Used only by nonUDP FW version)
ALL	All registers.

Constructor & Destructor Documentation

◆ RMMRegisterAccess()

RMMRegisterAccess::RMMRegisterAccess	(	const std::string &	serverIP,
		int	serverPort )

Constructor of the RMMRegisterAccess instance.

This constructor initializes the logging system, connects to the specified server via a network socket, and populates the address maps for register access.

Parameters

serverIP	The IP address of the Readout Master Module.
serverPort	UDP Port of the Readout Master Module Slow Control.

◆ ~RMMRegisterAccess()

RMMRegisterAccess::~RMMRegisterAccess ( )

Destructor of the RMMRegisterAccess.

This destructor ensures proper cleanup by logging the destruction event and closing the network socket.

Member Function Documentation

◆ addrLookUp()

std::string RMMRegisterAccess::addrLookUp	(	const std::string &	name,
		RegisterTag	tag = RegisterTag::ALL )

Retrieves the address of a register from the address map.

This function searches for the specified register name within the loaded address maps. If a specific RegisterTag is provided, the search is limited to the corresponding address map. If RegisterTag::ALL is specified, it iterates through all available maps and returns the first match found.

Parameters

[in]	name	The name of the register to look up.
[in]	tag	The tag specifying which address map to search in.

Returns: A hexadecimal string representation of the register's address if found. Returns an empty string if the register is not found.

◆ feaFwRegRead()

RMMResult RMMRegisterAccess::feaFwRegRead	(	const std::string &	reg_name,
		int	ring_id,
		int	node_id,
		const std::string &	tag = "" )

Read a front-end register, calculating the ring/node offset.

Parameters

reg_name	Name of register to read from.
ring_id	ring id used to specify the front end we are addressing.
node_id	node id used to specify the front end we are addressing.
tag	Optional tag to tell us which address map to look in.

Returns: RMMResult (uint32_t, status).

◆ feaFwRegWrite()

RMMResult RMMRegisterAccess::feaFwRegWrite	(	const std::string &	reg_name,
		int	ring_id,
		int	node_id,
		uint32_t	data,
		const std::string &	tag = "" )

Write in a front-end register, calculating the ring/node offset.

Parameters

reg_name	Name of register to read from.
ring_id	Ring id used to specify the front end we are addressing.
node_id	Node id used to specify the front end we are addressing.
data	Data to write
tag	Optional tag to tell us which address map to look in.

Returns: data (uint32_t) Read data.

◆ fieldRead() [1/2]

RMMResult RMMRegisterAccess::fieldRead	(	const std::string &	reg,
		RegisterTag	tag,
		int	bitBegin,
		int	bitWidth )

Reads a field from a register in the RMM space using a register name.

This method reads a field from the specified register, identified by its name (reg). The requested field is extracted based on the bit index (bitBegin) and the field width (bitWidth).

Parameters

[in]	reg	The name of the register to read from.
[in]	tag	The tag identifying which address map to use. Valid values for `tag` are defined in the RMMRegisterAccess::RegisterTag enum class.
[in]	bitBegin	The index of the lowest bit in the register that is part of the field.
[in]	bitWidth	The width of the field in bits.

Returns

RMMResult The result of the write operation, containing:

value: The final register value after modification.
status: The status of the operation (e.g., rmmSuccess or an error status).

Exceptions

std::invalid_argument

If any of the following conditions are met:

The field width (bitWidth) is greater than 32 bits.
The sum of bitBegin and bitWidth exceeds 32 bits.
The bitWidth is 0.

◆ fieldRead() [2/2]

RMMResult RMMRegisterAccess::fieldRead	(	uint32_t	reg,
		int	bitBegin,
		int	bitWidth )

Reads a field from a register in the RMM space using a register address.

This method reads a field from the specified register, identified by its numerical address (reg). The requested field is extracted based on the bit index (bitBegin) and the field width (bitWidth).

Parameters

[in]	reg	The numerical address of the register to read from.
[in]	bitBegin	The index of the lowest bit in the register that is part of the field.
[in]	bitWidth	The width of the field in bits.

Returns

RMMResult The result of the write operation, containing:

value: The final register value after modification.
status: The status of the operation (e.g., rmmSuccess or an error status).

Exceptions

std::invalid_argument

If any of the following conditions are met:

The field width (bitWidth) is greater than 32 bits.
The sum of bitBegin and bitWidth exceeds 32 bits.
The bitWidth is 0.

◆ fieldWrite() [1/2]

RMMResult RMMRegisterAccess::fieldWrite	(	const std::string &	reg,
		RegisterTag	tag,
		int	bitBegin,
		int	bitWidth,
		uint32_t	data )

Writes a field to a register in the RMM space using a register name.

Parameters

[in]	reg	The name of the register to write to.
[in]	tag	The tag identifying which address map to use. Valid values for `tag` are defined in the RMMRegisterAccess::RegisterTag enum class.
[in]	bitBegin	The index of the lowest bit in the register that is part of the field.
[in]	bitWidth	The width of the field in bits.
[in]	data	The data to write to the field.

Returns

RMMResult The result of the write operation, containing:

value: The final register value after modification.
status: The status of the operation (e.g., rmmSuccess or an error status).

Exceptions

std::invalid_argument

If any of the following conditions are met:

The field width (bitWidth) is greater than 32 bits.
The sum of bitBegin and bitWidth exceeds 32 bits.
The bitWidth is 0.

◆ fieldWrite() [2/2]

RMMResult RMMRegisterAccess::fieldWrite	(	uint32_t	reg,
		int	bitBegin,
		int	bitWidth,
		uint32_t	data )

Writes a field to a register in the RMM space using a register address.

Parameters

[in]	reg	The numerical address of the register to write to.
[in]	bitBegin	The index of the lowest bit in the register that is part of the field.
[in]	bitWidth	The width of the field in bits.
[in]	data	The data to write to the field.

Returns

RMMResult The result of the write operation, containing:

value: The final register value after modification.
status: The status of the operation (e.g., rmmSuccess or an error status).

Exceptions

std::invalid_argument

If any of the following conditions are met:

The field width (bitWidth) is greater than 32 bits.
The sum of bitBegin and bitWidth exceeds 32 bits.
The bitWidth is 0.

◆ i2cDelay()

rmmStatus RMMRegisterAccess::i2cDelay ( uint32_t delay )

Use the I2C controller to time a delay.

Parameters

delay Delay in microseconds

Returns: Status success/failed.

◆ i2cRead8bRegSi570()

uint32_t RMMRegisterAccess::i2cRead8bRegSi570	(	int	i2c_addr,
		int	reg_addr )

Reads from an 8bit register at an I2C address (Si570 only).

Parameters

i2c_addr	I2C address of target Si570.
reg_addr	target register address inside I2C device.

Returns: Status success/failed.

◆ i2cWrite16bReg()

rmmStatus RMMRegisterAccess::i2cWrite16bReg	(	int	i2c_addr,
		int	reg_addr,
		uint32_t	data )

Writes to a 16bit register at an I2C address.

Parameters

i2c_addr	I2C address of target.
reg_addr	target register address inside I2C device.
data	data bytes to write

Returns: Status success/failed.

◆ i2cWrite8bReg()

rmmStatus RMMRegisterAccess::i2cWrite8bReg	(	int	i2c_addr,
		int	reg_addr,
		uint32_t	data )

Writes to an 8bit register at an I2C address.

Parameters

i2c_addr	I2C address of target.
reg_addr	target register address inside I2C device.
data	data bytes to write

Returns: Status success/failed.

◆ i2cWriteByte()

rmmStatus RMMRegisterAccess::i2cWriteByte	(	int	i2c_addr,
		uint32_t	data )

Writes a single byte to an I2C address.

Useful for setting I2C muxes.

Parameters

i2c_addr	I2C address of target.
data	data byte to write.

Returns: Status success/failed.

◆ isLegacyFW()

bool RMMRegisterAccess::isLegacyFW ( ) const

Checks if the FW version is legagy (Non UDP Core version).

Returns: True if version is <= 1.0, false otherwise.

◆ isStopRequested()

bool RMMRegisterAccess::isStopRequested ( ) const

Checks if a stop request has been issued.

Returns: True if a stop request has been issued, false otherwise.

◆ rawRead()

RMMResult RMMRegisterAccess::rawRead ( const std::string & addr )

Performs a read operation from a register address.

This method constructs a read packet and sends it via the slow control protocol, then parses the received data to extract the register value.

Parameters

[in] addr The hexadecimal string representing the register address.

Returns: RMMResult containing the register value and the status of the operation.

◆ rawWrite()

RMMResult RMMRegisterAccess::rawWrite	(	const std::string &	addr,
		uint32_t	data )

Performs a write operation to a register address.

This method constructs a write packet and sends it via the slow control protocol, then parses the received data to verify the success of the operation.

Parameters

[in]	addr	The hexadecimal string representing the register address.
[in]	data	The 32-bit value to be written to the register.

Returns: RMMResult containing tje register value and the status of the write operation.

◆ regAssert()

void RMMRegisterAccess::regAssert	(	const std::string &	reg_name,
		uint32_t	exp_data,
		RegisterTag	tag = RegisterTag::ALL )

Check a register matches an expected value, or throw a ValueError exception.

Parameters

[in]	reg_name	Name of register to read from.
[in]	exp_data	Expected data.
[in]	tag	(Optional) The tag identifying which address map to use. If not specified, `RegisterTag::ALL` is assumed, and all maps are searched. Valid values for `tag` are defined in the RegisterTag enum class.

◆ regLockGuard()

RegLockGuard RMMRegisterAccess::regLockGuard	(	std::string	reg,
		std::string	tag = "NoTag" )

returns a lock guard object for that register mutex.

Parameters

[in] reg string representing register address to look.

Returns: RegLockGuard object which will keep mutex locked until it's destroyed.

◆ regMaskWrite()

RMMResult RMMRegisterAccess::regMaskWrite	(	const std::string &	regName,
		uint32_t	data,
		uint32_t	mask,
		RegisterTag	tag = RegisterTag::ALL )

Writes a value to a register using a bitmask.

This method reads the current value of the specified register, applies a bitmask to retain or modify specific bits, and then writes the modified value back to the register.

Parameters

	regName	The name of the register to write to.
	data	The 32-bit value to be written.
	mask	The bitmask determining which bits should be retained from the original value. Bits set to `1` in the mask remain unchanged, while bits set to `0` are updated.
[in]	tag	(Optional) The tag identifying which address map to use. If not specified, `RegisterTag::ALL` is assumed, and all maps are searched. Valid values for `tag` are defined in the RegisterTag enum class.

◆ regPoll()

rmmStatus RMMRegisterAccess::regPoll	(	const std::string &	regName,
		uint32_t	expData,
		double	pollDelay = 1.0,
		uint32_t	timeout = 0,
		RegisterTag	regTag = RegisterTag::ALL,
		std::function< bool(uint32_t)>	stopCondition = nullptr,
		std::function< bool()>	checkStop = nullptr )

Polls a named register until it matches the expected value, or stops based on a custom stop condition or timeout.

This function repeatedly reads the value from the specified register and compares it to the expected value. It allows for custom stop conditions and external interrupt requests, such as when polling needs to be terminated early.

Parameters

[in]	regName	Name of the register to read from.
[in]	expData	Expected data that the register should match.
[in]	pollDelay	Optional delay (in seconds) between polling attempts. Default is 1.0 second if not provided.
[in]	timeout	Optional maximum number of polling attempts before giving up. If set to 0, no timeout will be enforced. Default is 0 (no timeout).
[in]	regTag	(Optional) The tag identifying which address map to use. If not specified, `RegisterTag::ALL` is assumed, and all maps are searched. Valid values for `tag` are defined in the RegisterTag enum class.
[in]	stopCondition	Optional custom stop condition, which should return `true` to stop polling. This function is called with the current register value (`tmp_read`), and if it returns `true`, the polling process will stop.
[in]	checkStop	Optional function to check for an external stop request. If this function returns `true`, the polling will be aborted and an exception will be thrown. This can be used to interrupt polling based on an external condition.

Returns: rmmSuccess if the register value matches the expected value (expData) before a stop condition or timeout. rmmError if the timeout is reached before the value matches the expected value. Throws RMMAbortException if the polling is interrupted by an external stop request.

◆ regRead()

RMMResult RMMRegisterAccess::regRead	(	const std::string &	regName,
		RegisterTag	tag = RegisterTag::ALL )

Reads a register value by its name from the register map.

This method retrieves the address of the specified register using the register map and performs a raw read operation.

Parameters

[in]	regName	The name of the register to read from the register map.
[in]	tag	(Optional) The tag identifying which address map to use. If not specified, `RegisterTag::ALL` is assumed, and all maps are searched. Valid values for `tag` are defined in the RMMRegisterAccess::RegisterTag enum class.

Returns: A RMMResult object containing the register value and the status of the operation. If the register is not found, the value is set to 0, and the status indicates an error.

◆ regWrite()

RMMResult RMMRegisterAccess::regWrite	(	const std::string &	regName,
		uint32_t	data,
		RegisterTag	tag = RegisterTag::ALL )

Writes a value to a named register.

This method retrieves the address of the specified register using the register map and performs a write operation.

Parameters

[in]	regName	The name of the register to write to.
[in]	data	The 32-bit value to be written.
[in]	tag	(Optional) The tag identifying which address map to use. If not specified, `RegisterTag::ALL` is assumed, and all maps are searched. Valid values for `tag` are defined in the RMMRegisterAccess::RegisterTag enum class.

Returns: RMMResult containing the register value and the status of the write operation.

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

include/RMMRegisterAccess.h
src/RMMRegisterAccess.cpp

Public Types

Public Member Functions

Public Attributes

Friends

Detailed Description

Member Enumeration Documentation

◆ RegisterTag

Constructor & Destructor Documentation

◆ RMMRegisterAccess()

◆ ~RMMRegisterAccess()

Member Function Documentation

◆ addrLookUp()

◆ feaFwRegRead()

◆ feaFwRegWrite()

◆ fieldRead() [1/2]

◆ fieldRead() [2/2]

◆ fieldWrite() [1/2]

◆ fieldWrite() [2/2]

◆ i2cDelay()

◆ i2cRead8bRegSi570()

◆ i2cWrite16bReg()

◆ i2cWrite8bReg()

◆ i2cWriteByte()

◆ isLegacyFW()

◆ isStopRequested()

◆ rawRead()

◆ rawWrite()

◆ regAssert()

◆ regLockGuard()

◆ regMaskWrite()

◆ regPoll()

◆ regRead()

◆ regWrite()