Master endpoint for memory transactions. More...

#include <Master.h>

Inheritance diagram for rogue::interfaces::memory::Master:

Public Member Functions
	Master ()
	Constructs a memory master instance.

virtual	~Master ()
	Destroys the memory master instance.

virtual void	stop ()
	Stops the interface and releases runtime resources.

void	setSlave (std::shared_ptr< rogue::interfaces::memory::Slave > slave)
	Sets the downstream slave or hub.

std::shared_ptr< rogue::interfaces::memory::Slave >	getSlave ()
	Returns the configured downstream slave or hub.

uint32_t	reqSlaveId ()
	Queries the downstream slave ID.

std::string	reqSlaveName ()
	Queries the downstream slave name.

uint32_t	reqMinAccess ()
	Queries minimum access size in bytes for this interface path.

uint32_t	reqMaxAccess ()
	Queries maximum access size in bytes for this interface path.

uint64_t	reqAddress ()
	Queries the address offset of the next downstream layer.

std::string	getError ()
	Returns the last transaction error string.

void	clearError ()
	Clears the stored transaction error string.

void	setTimeout (uint64_t timeout)
	Sets the timeout value for future transactions.

uint32_t	reqTransaction (uint64_t address, uint32_t size, void *data, uint32_t type)
	Starts a new transaction.

uint32_t	reqTransactionPy (uint64_t address, boost::python::object p, uint32_t size, uint32_t offset, uint32_t type)
	Python variant of `reqTransaction`.

void	rshiftPy (boost::python::object p)
	Supports `>>` operator usage from Python.

std::shared_ptr< rogue::interfaces::memory::Slave > &	operator>> (std::shared_ptr< rogue::interfaces::memory::Slave > &other)
	Connects this master to a slave via stream chaining operator.

void	waitTransaction (uint32_t id)
	Waits for transaction completion or timeout.

Static Public Member Functions
static std::shared_ptr< rogue::interfaces::memory::Master >	create ()
	Creates a memory master instance.

static void	setup_python ()
	Registers this type with Python bindings.

static void	copyBits (uint8_t dstData, uint32_t dstLsb, uint8_t srcData, uint32_t srcLsb, uint32_t size)
	Copies bits between two byte arrays.

static void	copyBitsPy (boost::python::object dst, uint32_t dstLsb, boost::python::object src, uint32_t srcLsb, uint32_t size)
	Python wrapper for `copyBits`.

static void	setBits (uint8_t *dstData, uint32_t lsb, uint32_t size)
	Sets a contiguous bit range in a byte array.

static void	setBitsPy (boost::python::object dst, uint32_t lsb, uint32_t size)
	Python wrapper for `setBits`.

static bool	anyBits (uint8_t *srcData, uint32_t lsb, uint32_t size)
	Tests whether any bit in a range is set.

static bool	anyBitsPy (boost::python::object src, uint32_t lsb, uint32_t size)
	Python wrapper for `anyBits`.

Protected Member Functions
uint32_t	intTransaction (std::shared_ptr< rogue::interfaces::memory::Transaction > tran)
	Starts an internal transaction from an existing transaction object.

Friends
class	Transaction

Detailed Description

Master endpoint for memory transactions.

Master initiates transactions on a memory bus tree. Each master connects to one downstream Slave or Hub, and hub levels may be chained. Hub offsets are applied to transaction addresses as requests propagate toward leaf slave devices.

Definition at line 50 of file Master.h.

Constructor & Destructor Documentation

◆ Master()

rogue::interfaces::memory::Master::Master ( )

Constructs a memory master instance.

Create object.

This constructor is a low-level C++ allocation path. Prefer create() when shared ownership or Python exposure is required.

Definition at line 76 of file Master.cpp.

◆ ~Master()

rogue::interfaces::memory::Master::~Master ( )

virtual

Destroys the memory master instance.

Destroy object.

Definition at line 86 of file Master.cpp.

Member Function Documentation

◆ anyBits()

bool rogue::interfaces::memory::Master::anyBits	(	uint8_t *	srcData,
		uint32_t	lsb,
		uint32_t	size
	)

static

Tests whether any bit in a range is set.

Return true if any bits are set in range.

Checks size bits in srcData starting at bit lsb and returns true if at least one bit is 1.

Bit numbering is least-significant-bit-first within each byte (bit 0 is the LSB of byte 0). This helper is commonly used for overlap and mask checks. Exposed as _anyBits() in Python.

Parameters

srcData	Source byte array to check.
lsb	Least-significant bit index to check.
size	Number of bits to check.

Returns: true if any bit in the range is set; otherwise false.

Definition at line 401 of file Master.cpp.

◆ anyBitsPy()

bool rogue::interfaces::memory::Master::anyBitsPy	(	boost::python::object	src,
		uint32_t	lsb,
		uint32_t	size
	)

static

Python wrapper for anyBits.

Return true if any bits are set in range.

Accepts a Python buffer-protocol object and checks whether any bit is set in the requested range.

Exposed as _anyBits() in Python.

Parameters

src	Source Python buffer to check.
lsb	Least-significant bit index to check.
size	Number of bits to check.

Returns: true if any bit in the range is set; otherwise false.

Definition at line 437 of file Master.cpp.

◆ clearError()

void rogue::interfaces::memory::Master::clearError ( )

Clears the stored transaction error string.

Rst error.

Exposed as _clearError() in Python.

Definition at line 134 of file Master.cpp.

◆ copyBits()

void rogue::interfaces::memory::Master::copyBits	(	uint8_t *	dstData,
		uint32_t	dstLsb,
		uint8_t *	srcData,
		uint32_t	srcLsb,
		uint32_t	size
	)

static

Copies bits between two byte arrays.

Copy bits from src to dst with lsbs and size.

Copies size bits from srcData starting at bit srcLsb into dstData starting at bit dstLsb.

Bit numbering is least-significant-bit-first within each byte (bit 0 is the LSB of byte 0). The routine preserves destination bits outside the copied range and supports arbitrary unaligned source/destination bit offsets. When both offsets are byte-aligned, it uses a byte-copy fast path.

This helper underpins variable packing/unpacking logic in the memory layer. Exposed as _copyBits() in Python.

Parameters

dstData	Destination byte array.
dstLsb	Least-significant destination bit index.
srcData	Source byte array.
srcLsb	Least-significant source bit index.
size	Number of bits to copy.

Definition at line 259 of file Master.cpp.

◆ copyBitsPy()

void rogue::interfaces::memory::Master::copyBitsPy	(	boost::python::object	dst,
		uint32_t	dstLsb,
		boost::python::object	src,
		uint32_t	srcLsb,
		uint32_t	size
	)

static

Python wrapper for copyBits.

Copy bits from src to dst with lsbs and size.

Accepts Python buffer-protocol objects, validates bounds, and copies size bits from src bit index srcLsb to dst bit index dstLsb. Bit numbering is least-significant-bit-first within each byte.

Exposed as _copyBits() in Python.

Parameters

dst	Destination writable contiguous Python buffer.
dstLsb	Least-significant destination bit index.
src	Source Python buffer.
srcLsb	Least-significant source bit index.
size	Number of bits to copy.

Definition at line 299 of file Master.cpp.

◆ create()

rogue::interfaces::memory::MasterPtr rogue::interfaces::memory::Master::create ( )

static

Creates a memory master instance.

Create a master container.

Exposed as rogue.interfaces.memory.Master() in Python. This static factory is the preferred construction path when the object is shared across Rogue graph connections or exposed to Python. It returns std::shared_ptr ownership compatible with Rogue pointer typedefs.

Returns: Shared pointer to the created master.

Company : SLAC National Accelerator Laboratory

Description:

Memory master interface.

This file is part of the rogue software platform. It is subject to the license terms in the LICENSE.txt file found in the top-level directory of this distribution and at: https://confluence.slac.stanford.edu/display/ppareg/LICENSE.html. No part of the rogue software platform, including this file, may be copied, modified, propagated, or distributed except according to the terms

contained in the LICENSE.txt file.

Definition at line 44 of file Master.cpp.

◆ getError()

std::string rogue::interfaces::memory::Master::getError ( )

Returns the last transaction error string.

Get error.

Exposed as _getError() in Python.

Returns: Error string for the last transaction sequence.

Definition at line 129 of file Master.cpp.

◆ getSlave()

rogue::interfaces::memory::SlavePtr rogue::interfaces::memory::Master::getSlave ( )

Returns the configured downstream slave or hub.

Get slave.

Exposed as _getSlave() in Python.

Returns: Downstream slave or hub pointer.

Definition at line 99 of file Master.cpp.

◆ intTransaction()

uint32_t rogue::interfaces::memory::Master::intTransaction ( std::shared_ptr< rogue::interfaces::memory::Transaction > tran )

protected

Starts an internal transaction from an existing transaction object.

Definition at line 207 of file Master.cpp.

◆ operator>>()

rogue::interfaces::memory::SlavePtr & rogue::interfaces::memory::Master::operator>> ( std::shared_ptr< rogue::interfaces::memory::Slave > & other )

Connects this master to a slave via stream chaining operator.

Support >> operator in C++.

Definition at line 490 of file Master.cpp.

◆ reqAddress()

uint64_t rogue::interfaces::memory::Master::reqAddress ( )

Queries the address offset of the next downstream layer.

Query the offset.

Returns the relative offset of the connected slave/hub and does not include any local master offset. Exposed as _reqAddress() in Python.

Returns: Downstream relative address offset.

Definition at line 124 of file Master.cpp.

◆ reqMaxAccess()

uint32_t rogue::interfaces::memory::Master::reqMaxAccess ( )

Queries maximum access size in bytes for this interface path.

Query the maximum access size in bytes for interface.

Request is forwared to the lowest-level slave to determine the maximum transaction size. Exposed as _reqMaxAccess() in Python.

Returns: Maximum transaction size in bytes.

Definition at line 119 of file Master.cpp.

◆ reqMinAccess()

uint32_t rogue::interfaces::memory::Master::reqMinAccess ( )

Queries minimum access size in bytes for this interface path.

Query the minimum access size in bytes for interface.

Request is forwared to the lowest-level slave to determine the minimum transaction size. Exposed as _reqMinAccess() in Python.

Returns: Minimum transaction size in bytes.

Definition at line 114 of file Master.cpp.

◆ reqSlaveId()

uint32_t rogue::interfaces::memory::Master::reqSlaveId ( )

Queries the downstream slave ID.

Query the slave id.

Forwards the request to the lowest-level slave servicing this master path. This is used to determine which masters share an address space. Exposed as _reqSlaveId() in Python.

Returns: Unique 32-bit slave ID.

Definition at line 104 of file Master.cpp.

◆ reqSlaveName()

std::string rogue::interfaces::memory::Master::reqSlaveName ( )

Queries the downstream slave name.

Query the slave name.

Forwards the request to the lowest-level slave servicing this master path. This allows the system to determine which memory Masters share an address space. Exposed as _reqSlaveName() in Python.

Returns: Slave name string.

Definition at line 109 of file Master.cpp.

◆ reqTransaction()

uint32_t rogue::interfaces::memory::Master::reqTransaction	(	uint64_t	address,
		uint32_t	size,
		void *	data,
		uint32_t	type
	)

Starts a new transaction.

Post a transaction, called locally, forwarded to slave.

Creates a transaction object and forwards it to the lowest-level slave in the memory tree. The address is relative to the next layer offset and multiple transactions may be pending simultaneously. Not exposed to Python (see reqTransactionPy).

Parameters

address	Relative 64-bit transaction address.
size	Transaction size in bytes.
data	Pointer to transaction data storage.
type	Transaction type constant.

Returns: 32-bit transaction ID.

Definition at line 153 of file Master.cpp.

◆ reqTransactionPy()

uint32_t rogue::interfaces::memory::Master::reqTransactionPy	(	uint64_t	address,
		boost::python::object	p,
		uint32_t	size,
		uint32_t	offset,
		uint32_t	type
	)

Python variant of reqTransaction.

Post a transaction, called locally, forwarded to slave, python version.

Uses a Python buffer-protocol object instead of a raw C++ data pointer. Exposed to Python as _reqTransaction().

p may be any object exporting the buffer protocol (for example bytearray, bytes, memoryview, or a contiguous NumPy array). For Read/Verify transactions, p should be a writable contiguous buffer so returned data can be written into it.

Parameters

address	Relative 64-bit transaction address.
p	Python buffer-protocol object containing transaction bytes.
size	Transaction size in bytes.
offset	Byte offset within `p`.
type	Transaction type constant.

Returns: 32-bit transaction ID.

Definition at line 167 of file Master.cpp.

◆ rshiftPy()

void rogue::interfaces::memory::Master::rshiftPy ( boost::python::object p )

Supports >> operator usage from Python.

Definition at line 460 of file Master.cpp.

◆ setBits()

void rogue::interfaces::memory::Master::setBits	(	uint8_t *	dstData,
		uint32_t	lsb,
		uint32_t	size
	)

static

Sets a contiguous bit range in a byte array.

Set all bits in dest with lbs and size.

Sets size bits to 1 in dstData starting at bit lsb.

Bit numbering is least-significant-bit-first within each byte (bit 0 is the LSB of byte 0). Bits outside the requested range are left unchanged. For byte-aligned regions, it uses a byte-fill fast path.

This helper is used to build masks such as overlap and verify masks. Exposed as _setBits() in Python.

Parameters

dstData	Destination byte array.
lsb	Least-significant bit index to set.
size	Number of bits to set.

Definition at line 345 of file Master.cpp.

◆ setBitsPy()

void rogue::interfaces::memory::Master::setBitsPy	(	boost::python::object	dst,
		uint32_t	lsb,
		uint32_t	size
	)

static

Python wrapper for setBits.

Set all bits in dest with lbs and size.

Accepts a Python writable contiguous buffer and sets size bits to 1 starting at bit lsb. Bit numbering is least-significant-bit-first within each byte.

Exposed as _setBits() in Python.

Parameters

dst	Destination writable contiguous Python buffer.
lsb	Least-significant bit index to set.
size	Number of bits to set.

Definition at line 377 of file Master.cpp.

◆ setSlave()

void rogue::interfaces::memory::Master::setSlave ( std::shared_ptr< rogue::interfaces::memory::Slave > slave )

Sets the downstream slave or hub.

Set slave.

Transactions generated by this master are forwarded to this target. The target may be a leaf slave or a hub that forwards to lower levels. Exposed as _setSlave() in Python.

Parameters

slave Downstream slave or hub pointer.

Definition at line 92 of file Master.cpp.

◆ setTimeout()

void rogue::interfaces::memory::Master::setTimeout ( uint64_t timeout )

Sets the timeout value for future transactions.

Set timeout.

Timeout controls how long the master waits for transaction completion. Exposed as _setTimeout() in Python.

Parameters

timeout Timeout value in microseconds. A value of 0 leaves the current timeout unchanged.

Definition at line 141 of file Master.cpp.

◆ setup_python()

void rogue::interfaces::memory::Master::setup_python ( )

static

Registers this type with Python bindings.

Definition at line 49 of file Master.cpp.

◆ stop()

void rogue::interfaces::memory::Master::stop ( )

virtual

Stops the interface and releases runtime resources.

Stop the interface.

Reimplemented in rogue::interfaces::memory::TcpServer.

Definition at line 89 of file Master.cpp.

◆ waitTransaction()

void rogue::interfaces::memory::Master::waitTransaction ( uint32_t id )

Waits for transaction completion or timeout.

Passing 0 waits for all currently pending transactions. Exposed as _waitTransaction() in Python.

Parameters

id	Transaction ID to wait for, or `0` for all.

Definition at line 231 of file Master.cpp.

Friends And Related Symbol Documentation

◆ Transaction

friend class Transaction

friend

Definition at line 51 of file Master.h.

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

/home/runner/work/rogue/rogue/include/rogue/interfaces/memory/Master.h
/home/runner/work/rogue/rogue/src/rogue/interfaces/memory/Master.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

◆ Master()

◆ ~Master()

Member Function Documentation

◆ anyBits()

◆ anyBitsPy()

◆ clearError()

◆ copyBits()

◆ copyBitsPy()

◆ create()

Company : SLAC National Accelerator Laboratory

Memory master interface.

contained in the LICENSE.txt file.

◆ getError()

◆ getSlave()

◆ intTransaction()

◆ operator>>()

◆ reqAddress()

◆ reqMaxAccess()

◆ reqMinAccess()

◆ reqSlaveId()

◆ reqSlaveName()

◆ reqTransaction()

◆ reqTransactionPy()

◆ rshiftPy()

◆ setBits()

◆ setBitsPy()

◆ setSlave()

◆ setTimeout()

◆ setup_python()

◆ stop()

◆ waitTransaction()

Friends And Related Symbol Documentation

◆ Transaction