Hub

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

typedef std::shared_ptr<rogue::interfaces::memory::Hub> rogue::interfaces::memory::HubPtr: Alias for using shared pointer as HubPtr

The class description is shown below:

class Hub : public rogue::interfaces::memory::Master, public rogue::interfaces::memory::Slave 

Memory interface Hub device.

The memory bus Hub serves as both a Slave and a Master for memory transactions. It will accept a Transaction from an attached Master and pass it down to the next level Slave or Hub device. It will apply its local offset address to the transaction as it is passed down to the next level.

A Hub can be sub-classed in either Python or C++ is order to further manipulate the transaction data on the way down or convert the initial Transaction into multiple transactions to the next level. This can be useful to hide complex windows memory spaces or transactions that require multiplied steps be performed in hardware.

If a non zero min and max transaction size are passed at creation this Hub will behave as if it is a new root Slave memory device in the tree. This is useful in cases where this Hub will master a paged address or other virtual address space.

Access-size behavior is selected by the min/max constructor parameters:

min == 0 and max == 0: pass-through mode. Access-size identity/name queries are forwarded to the downstream interface.
min != 0 and max != 0: virtual-root mode. This hub advertises its own Slave-like identity and access limits (min/max) to upstream masters.
Mixed values (min == 0, max != 0 or min != 0, max == 0): also pass-through mode (virtual-root mode is not enabled).

In other words, this hub behaves as a virtual root only when both min and max are non-zero.

A pyrogue.Device instance is the most typical Hub used in Rogue.

Subclassed by rogue::interfaces::memory::HubWrap

Public Functions

Hub(uint64_t offset, uint32_t min, uint32_t max)

Constructs a Hub with optional virtual-root access constraints.

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

Virtual-root mode is enabled only when both min and max are non-zero. When both are zero, the hub behaves as a pass-through for access-limit queries. Mixed values (only one non-zero) also behave as pass-through.

Parameters:

offset – The offset of this Hub device.
min – Minimum transaction size in virtual-root mode. Use 0 with max=0 to disable virtual-root mode.
max – Maximum transaction size in virtual-root mode. Use 0 with min=0 to disable virtual-root mode.

uint64_t getOffset()

Returns the local offset of this hub.

Exposed as _getOffset() to Python.

Returns:: 64-bit address offset

uint64_t getAddress()

Returns the full address of this hub, including local offset.

Exposed as _getAddress() to Python.

Returns:: 64-bit address

virtual uint32_t doSlaveId()

Services getSlaveId request from an attached master.

By default the Hub forwards this request to the next level. A hub may want to override this when mastering a virtual address space such as a paged address map. Otherwise incorrect overlap errors may be generated by the PyRogue Root.

Not exposed to Python

Returns:: 32-bit slave ID

virtual std::string doSlaveName()

Services getSlaveName request from an attached master.

By default the Hub forwards this request to the next level. A hub may want to override this when mastering a virtual address space such as a paged address map. Otherwise incorrect overlap errors may be generated by the PyRogue Root.

Not exposed to Python

Returns:: slave name

virtual uint32_t doMinAccess()

Services getMinAccess request from an attached master.

This hub forwards the request to the next-level device.

Not exposed to Python

Returns:: Min transaction access size

virtual uint32_t doMaxAccess()

Services getMaxAccess request from an attached master.

This hub forwards the request to the next-level device. A hub sub-class is allowed to override this method.

Not exposed to Python

Returns:: Max transaction access size

virtual uint64_t doAddress()

Services getAddress request from an attached master.

This hub forwards the request to the next-level device and applies the local address offset. A Hub sub-class is allowed to override this method.

Not exposed to Python

Returns:: 64-bit address including this hub offset

virtual void doTransaction(std::shared_ptr<rogue::interfaces::memory::Transaction> transaction)

Services a transaction request from an attached master.

This hub forwards the request to the next-level device and applies the local address offset.

It is possible for this method to be overridden in either a Python or C++ subclass. Examples of sub-classing a Hub are included elsewhere in this document.

Exposed to Python as _doTransaction().

Parameters:: transaction – Transaction pointer as TransactionPtr.

Public Static Functions

static std::shared_ptr<rogue::interfaces::memory::Hub> create(uint64_t offset, uint32_t min, uint32_t max)

Creates a memory Hub.

Exposed to Python as rogue.interfaces.memory.Hub(). 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. Parameter semantics are identical to the constructor; see Hub() for virtual-root behavior details.

Parameters:

offset – The offset of this Hub device.
min – Minimum transaction size in virtual-root mode. Use 0 with max=0 to disable virtual-root mode.
max – Maximum transaction size in virtual-root mode. Use 0 with min=0 to disable virtual-root mode.

Returns:

Shared pointer to the created hub.