SrpV3

For conceptual usage, see:

SRP Protocol Version 3

Implementation

This Python API is provided by a Rogue C++ class exported into Python.

Native C++ class: - SrpV3

Generated API

class rogue.protocols.srp.SrpV3

C++: rogue::protocols::srp::SrpV3

Binding source: [SrpV3.cpp]

SRP v3 bridge between Rogue memory transactions and stream frames.

SrpV3 sits between the memory interface (memory::Slave) and stream transport (stream::Master/stream::Slave). It serializes memory read/write transactions into SRP v3 request frames and decodes incoming SRP responses to complete transactions. SRP frames are stream transactions carried over a physical/link transport (for example DMA, TCP, or other Rogue stream backends) before arriving at an FPGA or ASIC endpoint that implements the SRP protocol for register access. Implementation behavior:

doTransaction() serializes each memory request into one SRPv3 frame and transmits it immediately.
Non-posted transactions are registered in the base memory::Slave in-flight transaction map (addTransaction()), keyed by transaction ID.
Multiple requests may be transmitted before any responses arrive, so multiple transactions can be in flight concurrently.
acceptFrame() extracts the response ID and resolves it with getTransaction(id), so responses are matched by ID and may arrive out of order without violating correctness. Threading/locking model:
In-flight map access is protected by the memory::Slave mutex.
Per-transaction payload/state access is protected by TransactionLock.
doTransaction() and acceptFrame() can be called from different runtime contexts provided by the connected stream transport stack. Missing, late, or invalid responses:
Software wait timeout is enforced by the initiating memory::Master transaction timeout (Master::setTimeout() in microseconds).
If no valid response arrives before timeout, the waiting side completes with a timeout error.
If a late response arrives after timeout, it is treated as expired and ignored.
If a response has unknown ID, malformed header/size, or hardware error status in tail bits, the response is rejected. For matched transactions, protocol/tail/size errors are reported immediately; unknown-ID responses are dropped and do not complete any in-flight transaction. Compared with earlier protocol versions, v3 has a different header format and supports a configurable protocol timeout field through setHardwareTimeout(). This hardware timeout field is encoded into outgoing SRPv3 requests and is separate from Rogue software-side wait timeout behavior. Protocol reference: https://confluence.slac.stanford.edu/x/cRmVD

__init__()

C++: rogue::protocols::srp::SrpV3

Constructs an SRP v3 interface instance.

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

_addSlave(slave)

C++: rogue::interfaces::stream::Master::addSlave()

Attaches a downstream slave.

Multiple slaves are supported. The first attached slave is used for frame allocation and receives frames last during send. Exposed as _addSlave() in Python.

Parameters:: slave – Stream slave pointer.

_slaveCount()

C++: rogue::interfaces::stream::Master::slaveCount()

Returns the number of attached slaves.

Exposed as _slaveCount() in Python.

Returns:: Number of attached slaves.

_reqFrame(size, zeroCopyEn)

C++: rogue::interfaces::stream::Master::reqFrame()

Requests allocation of a new frame from the primary slave.

Creates an empty frame with at least the requested payload capacity. The Master will forward this request to the primary Slave object. The request for a new Frame includes a flag which indicates if a zeroCopy frame is allowed. In most cases this flag can be set to true. Non-zero-copy frames are requested if the Master may need to transmit the same frame multiple times. Exposed as _reqFrame() in Python.

Parameters:

size – Minimum requested payload size in bytes.
zeroCopyEn – Set to true when zero-copy frame allocation is allowed.

Returns:

Newly allocated frame pointer.

_sendFrame(frame)

C++: rogue::interfaces::stream::Master::sendFrame()

Sends a frame to all attached slaves.

This method sends the passed Frame to all of the attached Slave objects by calling their acceptFrame() method. First the secondary Slaves are called in order of attachment, followed last by the primary Slave. If the Frame is a zero copy frame it will most likely be empty when the sendFrame() method returns Exposed as _sendFrame() in Python.

Parameters:: frame – Frame to send.

_stop()

C++: rogue::interfaces::stream::Master::stop()

Stops frame generation and shuts down associated threads.

Exposed as stop() in Python. This is the primary subclass hook on Master. Override when the subclass owns background activity or transport resources that require deterministic shutdown.

__rshift__(other)

C++: rogue::interfaces::stream::Master::rshiftPy()

Supports >> operator usage from Python.

Parameters:: p – Python object expected to resolve to a stream Slave.
Returns:: Original Python object for chaining semantics.

setDebug(debug, name)

C++: rogue::interfaces::stream::Slave::setDebug()

Sets debug message verbosity and logger name.

This method enables debug messages when using the base Slave class attached as a primary or secondary Slave on a Master. Typically used when attaching a base Slave object for debug purposes. Exposed as setDebug() in Python.

Parameters:

debug – Maximum number of bytes to print in debug message.
name – Name included in debug messages.

_acceptFrame(frame)

C++: rogue::interfaces::stream::Slave::acceptFrame()

Accepts a frame from an upstream master.

Invokes the Python override when provided.

Parameters:: frame – Frame received from the stream path.

getFrameCount()

C++: rogue::interfaces::stream::Slave::getFrameCount()

Returns frame counter.

Returns the total frames received. Only valid if acceptFrame is not re-implemented as a sub-class. Typically used when attaching a base Slave object for debug purposes. Exposed as getFrameCount() in Python.

Returns:: Total number of Frame objects received.

getByteCount()

C++: rogue::interfaces::stream::Slave::getByteCount()

Returns byte counter.

Returns the total bytes received. Only valid if acceptFrame is not re-implemented as a sub-class. Typically used when attaching a base Slave object for debug purposes. Exposed as getByteCount() in Python.

Returns:: Total number of bytes received.

_stop()

C++: rogue::interfaces::stream::Slave::stop()

Shuts down threads associated with this object.

Called during shutdown to stop activity and allow clean process exit. Subclasses should override when they own worker threads or timers. Exposed as stop() in Python.

getAllocCount()

C++: rogue::interfaces::stream::Pool::getAllocCount()

Returns total currently allocated buffer count.

This value is incremented as buffers are allocated and decremented as buffers are freed. Exposed as getAllocCount() in Python.

Returns:: Total currently allocated buffers.

getAllocBytes()

C++: rogue::interfaces::stream::Pool::getAllocBytes()

Returns total currently allocated bytes.

This value is incremented as buffers are allocated and decremented as buffers are freed. Exposed as getAllocBytes() in Python.

Returns:: Total currently allocated bytes.

setFixedSize(size)

C++: rogue::interfaces::stream::Pool::setFixedSize()

Sets fixed-size mode.

This method puts the allocator into fixed size mode. Exposed as setFixedSize() in Python.

Parameters:: size – Fixed size value.

getFixedSize()

C++: rogue::interfaces::stream::Pool::getFixedSize()

Returns fixed-size allocation setting.

A return value of 0 means fixed-size mode is disabled. Exposed as getFixedSize() in Python.

Returns:: Fixed size value or 0 when fixed-size mode is disabled.

setPoolSize(size)

C++: rogue::interfaces::stream::Pool::setPoolSize()

Sets buffer pool size. Exposed as setPoolSize() in Python.

Parameters:: size – Number of entries to keep in the pool.

getPoolSize()

C++: rogue::interfaces::stream::Pool::getPoolSize()

Returns configured maximum number of cached pool entries. Exposed as getPoolSize() in Python.

Returns:: Pool size.

__lshift__(other)

C++: rogue::interfaces::stream::Slave::lshiftPy()

Supports << operator usage from Python.

Parameters:: p – Python object expected to resolve to a stream Master.
Returns:: Original Python object for chaining semantics.

setName(name)

C++: rogue::interfaces::memory::Slave::setName()

Sets slave name.

Exposed to Python as setName.

Parameters:: name – New slave name string.

_addTransaction(transaction)

C++: rogue::interfaces::memory::Slave::addTransaction()

Adds a transaction to the internal tracking map.

This method is called by the sub-class to add a transaction into the local tracking map for later retrieval. This is used when the transaction will be completed later as the result of protocol data being returned to the Slave. Exposed to Python as _addTransaction().

Parameters:: transaction – Pointer to transaction as TransactionPtr.

_getTransaction(index)

C++: rogue::interfaces::memory::Slave::getTransaction()

Gets a transaction from the internal tracking map.

This method is called by the sub-class to retrieve an existing transaction using the unique transaction ID. If the transaction exists in the list the pointer to that transaction will be returned. If not a NULL pointer will be returned. When getTransaction() is called the map will also be checked for stale transactions which will be removed from the map. Exposed to Python as _getTransaction().