Memory interface Hub device. More...

#include <Hub.h>

Inheritance diagram for rogue::interfaces::memory::Hub:

Public Member Functions
	Hub (uint64_t offset, uint32_t min, uint32_t max)
	Constructs a Hub with optional virtual-root access constraints.

	~Hub ()
	Destroy a block.

uint64_t	getOffset ()
	Returns the local offset of this hub.

uint64_t	getAddress ()
	Returns the full address of this hub, including local offset.

uint32_t	doSlaveId ()
	Services `getSlaveId` request from an attached master.

std::string	doSlaveName ()
	Services `getSlaveName` request from an attached master.

uint32_t	doMinAccess ()
	Services `getMinAccess` request from an attached master.

uint32_t	doMaxAccess ()
	Services `getMaxAccess` request from an attached master.

uint64_t	doAddress ()
	Services `getAddress` request from an attached master.

virtual void	doTransaction (std::shared_ptr< rogue::interfaces::memory::Transaction > transaction)
	Services a transaction request from an attached master.

Public Member Functions inherited from rogue::interfaces::memory::Master
	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.

Public Member Functions inherited from rogue::interfaces::memory::Slave
	Slave (uint32_t min, uint32_t max)
	Constructs a memory slave.

virtual	~Slave ()
	Destroys the memory slave instance.

virtual void	stop ()
	Stops the memory slave interface.

void	addTransaction (std::shared_ptr< rogue::interfaces::memory::Transaction > transaction)
	Adds a transaction to the internal tracking map.

std::shared_ptr< rogue::interfaces::memory::Transaction >	getTransaction (uint32_t index)
	Gets a transaction from the internal tracking map.

uint32_t	min ()
	Returns configured minimum transaction size.

uint32_t	max ()
	Returns configured maximum transaction size.

uint32_t	id ()
	Returns unique slave ID.

void	setName (std::string name)
	Sets slave name.

std::string	name ()
	Returns slave name.

void	lshiftPy (boost::python::object p)
	Supports `<<` operator usage from Python.

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

Public Member Functions inherited from rogue::EnableSharedFromThis< rogue::interfaces::memory::Slave >
std::shared_ptr< rogue::interfaces::memory::Slave >	shared_from_this ()
	Returns a `shared_ptr<T>` for this instance.

Public Member Functions inherited from rogue::EnableSharedFromThisBase
virtual	~EnableSharedFromThisBase ()
	Virtual destructor for polymorphic base usage.

Static Public Member Functions
static std::shared_ptr< rogue::interfaces::memory::Hub >	create (uint64_t offset, uint32_t min, uint32_t max)
	Creates a memory Hub.

static void	setup_python ()

Static Public Member Functions inherited from rogue::interfaces::memory::Master
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`.

Static Public Member Functions inherited from rogue::interfaces::memory::Slave
static std::shared_ptr< rogue::interfaces::memory::Slave >	create (uint32_t min, uint32_t max)
	Creates a memory slave.

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

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

Detailed Description

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.

Definition at line 72 of file Hub.h.

Constructor & Destructor Documentation

◆ Hub()

rogue::interfaces::memory::Hub::Hub	(	uint64_t	offset,
		uint32_t	min,
		uint32_t	max
	)

Constructs a Hub with optional virtual-root access constraints.

Create an block.

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.

Definition at line 47 of file Hub.cpp.

◆ ~Hub()

rogue::interfaces::memory::Hub::~Hub ( )

Destroy a block.

Definition at line 54 of file Hub.cpp.

Member Function Documentation

◆ create()

rogue::interfaces::memory::HubPtr rogue::interfaces::memory::Hub::create	(	uint64_t	offset,
		uint32_t	min,
		uint32_t	max
	)

static

Creates a memory Hub.

Create a block, class creator.

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.

Company : SLAC National Accelerator Laboratory

Description: A memory interface hub. Accepts requests from multiple masters and forwards them to a downstream slave. Address is updated along the way. Includes support

for modification callbacks.

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 41 of file Hub.cpp.

◆ doAddress()

uint64_t rogue::interfaces::memory::Hub::doAddress ( )

virtual

Services getAddress request from an attached master.

Return address.

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

Reimplemented from rogue::interfaces::memory::Slave.

Definition at line 100 of file Hub.cpp.

◆ doMaxAccess()

uint32_t rogue::interfaces::memory::Hub::doMaxAccess ( )

virtual

Services getMaxAccess request from an attached master.

Return max access size to requesting 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

Reimplemented from rogue::interfaces::memory::Slave.

Definition at line 91 of file Hub.cpp.

◆ doMinAccess()

uint32_t rogue::interfaces::memory::Hub::doMinAccess ( )

virtual

Services getMinAccess request from an attached master.

Return min access size to requesting master.

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

Not exposed to Python

Returns: Min transaction access size

Reimplemented from rogue::interfaces::memory::Slave.

Definition at line 83 of file Hub.cpp.

◆ doSlaveId()

uint32_t rogue::interfaces::memory::Hub::doSlaveId ( )

virtual

Services getSlaveId request from an attached master.

Return id to requesting 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

Reimplemented from rogue::interfaces::memory::Slave.

Definition at line 67 of file Hub.cpp.

◆ doSlaveName()

std::string rogue::interfaces::memory::Hub::doSlaveName ( )

virtual

Services getSlaveName request from an attached master.

Return name to requesting 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

Reimplemented from rogue::interfaces::memory::Slave.

Definition at line 75 of file Hub.cpp.

◆ doTransaction()

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

virtual

Services a transaction request from an attached master.

Post a transaction. Master will call this method with the access attributes.

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.

Reimplemented from rogue::interfaces::memory::Slave.

Reimplemented in rogue::interfaces::memory::HubWrap.

Definition at line 108 of file Hub.cpp.

◆ getAddress()

uint64_t rogue::interfaces::memory::Hub::getAddress ( )

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

Get address.

Exposed as _getAddress() to Python.

Returns: 64-bit address

Definition at line 62 of file Hub.cpp.

◆ getOffset()

uint64_t rogue::interfaces::memory::Hub::getOffset ( )

Returns the local offset of this hub.

Get offset.

Exposed as _getOffset() to Python.

Returns: 64-bit address offset

Definition at line 57 of file Hub.cpp.

◆ setup_python()

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

static

Definition at line 155 of file Hub.cpp.

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

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

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ Hub()

◆ ~Hub()

Member Function Documentation

◆ create()

Company : SLAC National Accelerator Laboratory

for modification callbacks.

contained in the LICENSE.txt file.

◆ doAddress()

◆ doMaxAccess()

◆ doMinAccess()

◆ doSlaveId()

◆ doSlaveName()

◆ doTransaction()

◆ getAddress()

◆ getOffset()

◆ setup_python()