Master

The memory interface Master class is the interface for initiating a memory transaction. Each Master class object will be coupled with one or more Slave objects. For conceptual usage, see:

Python binding

This C++ class is also exported into Python as rogue.interfaces.memory.Master.

Python API page: - Master

objects in C++ are referenced by the following shared pointer typedef:

typedef std::shared_ptr<rogue::interfaces::memory::Master> rogue::interfaces::memory::MasterPtr [header]: Shared pointer alias for Master.

The class description is shown below:

class Master [header]

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.

Subclassed by rogue::interfaces::memory::Block, rogue::interfaces::memory::Hub, rogue::interfaces::memory::TcpServer

Public Functions

Master() [header] [impl]

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.

virtual ~Master() [header] [impl]

Destroys the memory master instance.

Destroy object.

virtual void stop() [header] [impl]

Stops the interface and releases runtime resources.

Stop the interface.

void setSlave(std::shared_ptr<rogue::interfaces::memory::Slave> slave) [header] [impl]

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.

std::shared_ptr<rogue::interfaces::memory::Slave> getSlave() [header] [impl]

Returns the configured downstream slave or hub.

Get slave.

Exposed as _getSlave() in Python.

Returns:: Downstream slave or hub pointer.

uint32_t reqSlaveId() [header] [impl]

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.

std::string reqSlaveName() [header] [impl]

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.

uint32_t reqMinAccess() [header] [impl]

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.

uint32_t reqMaxAccess() [header] [impl]

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.

uint64_t reqAddress() [header] [impl]

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.

std::string getError() [header] [impl]

Returns the last transaction error string.

Get error.

Exposed as _getError() in Python.

Returns:: Error string for the last transaction sequence.

void clearError() [header] [impl]

Clears the stored transaction error string.

Rst error.

Exposed as _clearError() in Python.

void setTimeout(uint64_t timeout) [header] [impl]

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.

uint32_t reqTransaction(uint64_t address, uint32_t size, void *data, uint32_t type) [header] [impl]

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.

uint32_t reqTransactionPy(uint64_t address, boost::python::object p, uint32_t size, uint32_t offset, uint32_t type) [header] [impl]

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.

void rshiftPy(boost::python::object p) [header] [impl]: Supports >> operator usage from Python.

std::shared_ptr<rogue::interfaces::memory::Slave> &operator>>(std::shared_ptr<rogue::interfaces::memory::Slave> &other) [header] [impl]

Connects this master to a slave via stream chaining operator.

Support >> operator in C++.

void waitTransaction(uint32_t id) [header] [impl]

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.

Public Static Functions

static std::shared_ptr<rogue::interfaces::memory::Master> create() [header] [impl]

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.

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.

Returns:: Shared pointer to the created master.

static void setup_python() [header] [impl]: Registers this type with Python bindings.

static void copyBits(uint8_t *dstData, uint32_t dstLsb, uint8_t *srcData, uint32_t srcLsb, uint32_t size) [header] [impl]

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.

static void copyBitsPy(boost::python::object dst, uint32_t dstLsb, boost::python::object src, uint32_t srcLsb, uint32_t size) [header] [impl]

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.

static void setBits(uint8_t *dstData, uint32_t lsb, uint32_t size) [header] [impl]

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.

static void setBitsPy(boost::python::object dst, uint32_t lsb, uint32_t size) [header] [impl]

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.

static bool anyBits(uint8_t *srcData, uint32_t lsb, uint32_t size) [header] [impl]

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.

static bool anyBitsPy(boost::python::object src, uint32_t lsb, uint32_t size) [header] [impl]

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.