Bridge between Rogue stream interfaces and AXI Stream DMA drivers. More...

#include <AxiStreamDma.h>

Inheritance diagram for rogue::hardware::axi::AxiStreamDma:

Public Member Functions
	AxiStreamDma (std::string path, uint32_t dest, bool ssiEnable)
	Constructs an AXI stream DMA bridge.

	~AxiStreamDma ()
	Destroys the interface and stops background activity.

void	stop ()
	Stops RX thread and closes DMA file descriptors.

void	setTimeout (uint32_t timeout)
	Sets TX/alloc wait timeout.

void	setDriverDebug (uint32_t level)
	Sets DMA driver debug level.

void	dmaAck ()
	Sends an ACK strobe through driver-specific DMA control path.

std::shared_ptr< rogue::interfaces::stream::Frame >	acceptReq (uint32_t size, bool zeroCopyEn)
	Allocates a frame for upstream writers.

void	acceptFrame (std::shared_ptr< rogue::interfaces::stream::Frame > frame)
	Accepts a frame for DMA transmit.

void	retBuffer (uint8_t *data, uint32_t meta, uint32_t rawSize)
	Returns DMA-backed buffer memory after frame release.

std::string	getGitVersion ()
	Gets DMA driver Git version string.

uint32_t	getApiVersion ()
	Gets DMA driver API version.

uint32_t	getBuffSize ()
	Gets DMA buffer size.

uint32_t	getRxBuffCount ()
	Gets RX DMA buffer count.

uint32_t	getRxBuffinUserCount ()
	Gets RX buffers currently held by user space.

uint32_t	getRxBuffinHwCount ()
	Gets RX buffers currently held by hardware.

uint32_t	getRxBuffinPreHwQCount ()
	Gets RX buffers queued before hardware.

uint32_t	getRxBuffinSwQCount ()
	Gets RX buffers queued in software.

uint32_t	getRxBuffMissCount ()
	Gets RX buffer missing count.

uint32_t	getTxBuffCount ()
	Gets TX DMA buffer count.

uint32_t	getTxBuffinUserCount ()
	Gets TX buffers currently held by user space.

uint32_t	getTxBuffinHwCount ()
	Gets TX buffers currently held by hardware.

uint32_t	getTxBuffinPreHwQCount ()
	Gets TX buffers queued before hardware.

uint32_t	getTxBuffinSwQCount ()
	Gets TX buffers queued in software.

uint32_t	getTxBuffMissCount ()
	Gets TX buffer missing count.

Public Member Functions inherited from rogue::interfaces::stream::Master
	Master ()
	Constructs a stream master.

virtual	~Master ()
	Destroys the stream master.

uint32_t	slaveCount ()
	Returns the number of attached slaves.

void	addSlave (std::shared_ptr< rogue::interfaces::stream::Slave > slave)
	Attaches a downstream slave.

std::shared_ptr< rogue::interfaces::stream::Frame >	reqFrame (uint32_t size, bool zeroCopyEn)
	Requests allocation of a new frame from the primary slave.

void	sendFrame (std::shared_ptr< rogue::interfaces::stream::Frame > frame)
	Sends a frame to all attached slaves.

bool	ensureSingleBuffer (std::shared_ptr< rogue::interfaces::stream::Frame > &frame, bool reqEn)
	Ensures a frame is represented by a single buffer.

void	equalsPy (boost::python::object p)
	Supports `==` operator usage from Python.

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

void	operator== (std::shared_ptr< rogue::interfaces::stream::Slave > &other)
	Supports `==` operator usage in C++.

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

Public Member Functions inherited from rogue::EnableSharedFromThis< rogue::interfaces::stream::Master >
std::shared_ptr< rogue::interfaces::stream::Master >	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.

Public Member Functions inherited from rogue::interfaces::stream::Slave
	Slave ()
	Constructs a stream slave.

virtual	~Slave ()
	Destroys the stream slave.

void	setDebug (uint32_t debug, std::string name)
	Sets debug message verbosity and logger name.

uint64_t	getFrameCount ()
	Returns frame counter.

uint64_t	getByteCount ()
	Returns byte counter.

bool	ensureSingleBuffer (std::shared_ptr< rogue::interfaces::stream::Frame > &frame, bool reqEn)
	Ensures frame is backed by a single buffer.

std::shared_ptr< rogue::interfaces::stream::Frame >	reqLocalFrame (uint32_t size, bool zeroCopyEn)
	Services a local frame allocation request through this object's pool interface.

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

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

Public Member Functions inherited from rogue::interfaces::stream::Pool
	Pool ()
	Constructs a pool with default allocation behavior enabled.

virtual	~Pool ()
	Destroys the pool and releases any cached buffer storage.

uint32_t	getAllocBytes ()
	Returns total currently allocated bytes.

uint32_t	getAllocCount ()
	Returns total currently allocated buffer count.

void	setFixedSize (uint32_t size)
	Sets fixed-size mode.

uint32_t	getFixedSize ()
	Returns fixed-size allocation setting.

void	setPoolSize (uint32_t size)
	Sets buffer pool size.

uint32_t	getPoolSize ()
	Returns configured maximum number of cached pool entries.

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

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

Static Public Member Functions
static std::shared_ptr< rogue::hardware::axi::AxiStreamDma >	create (std::string path, uint32_t dest, bool ssiEnable)
	Creates an AXI Stream DMA bridge instance.

static void	zeroCopyDisable (std::string path)
	Disables zero-copy mode for a device path.

static void	setup_python ()
	Registers Python bindings for this class.

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

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

Static Public Member Functions inherited from rogue::interfaces::stream::Slave
static std::shared_ptr< rogue::interfaces::stream::Slave >	create ()
	Creates a new stream slave.

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

Static Public Member Functions inherited from rogue::interfaces::stream::Pool
static void	setup_python ()
	Registers this type with Python bindings.

Additional Inherited Members
Protected Member Functions inherited from rogue::interfaces::stream::Pool
std::shared_ptr< rogue::interfaces::stream::Buffer >	allocBuffer (uint32_t size, uint32_t *total)
	Allocate a buffer passed size.

std::shared_ptr< rogue::interfaces::stream::Buffer >	createBuffer (void *data, uint32_t meta, uint32_t size, uint32_t alloc)
	Creates a Buffer with a pre-allocated data block.

void	decCounter (uint32_t alloc)
	Decrements allocation counter.

Detailed Description

Bridge between Rogue stream interfaces and AXI Stream DMA drivers.

AxiStreamDma connects Rogue stream::Master/stream::Slave APIs to the aes-stream-driver kernel interface. It supports:

RX path: DMA buffers received from hardware and forwarded as Rogue frames.
TX path: Rogue frames written to hardware via DMA.
Optional zero-copy buffer mapping when supported by the driver/path.

Threading model:

A background RX thread is started in the constructor and runs until stop() or destruction.
TX operations execute synchronously in caller context of acceptFrame().

Zero-copy model:

Enabled by default per device path.
zeroCopyDisable(path) must be called before first instance on that path.
When disabled or unavailable, frame buffers are allocated from local pool and copied on TX/RX boundaries.

Definition at line 93 of file AxiStreamDma.h.

Constructor & Destructor Documentation

◆ AxiStreamDma()

rogue::hardware::axi::AxiStreamDma::AxiStreamDma	(	std::string	path,
		uint32_t	dest,
		bool	ssiEnable
	)

Constructs an AXI stream DMA bridge.

Open the device. Pass destination.

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

The destination field is an AXI Stream sideband routing value. Usage is driver/firmware specific, but a common mapping is:

low 8 bits: AXI tDest value carried with the stream frame
upper bits: DMA channel selection/indexing in lower-level hardware

ssiEnable controls insertion/interpretation of SLAC SSI user bits:

SOF marker in first-user field bit 1
EOFE marker in last-user field bit 0

Parameters

path	Device path, for example `/dev/datadev_0`.
dest	Destination index used for DMA transactions.
ssiEnable	Enable SSI user-field handling.

Definition at line 166 of file AxiStreamDma.cpp.

◆ ~AxiStreamDma()

rogue::hardware::axi::AxiStreamDma::~AxiStreamDma ( )

Destroys the interface and stops background activity.

Close the device.

Definition at line 225 of file AxiStreamDma.cpp.

Member Function Documentation

◆ acceptFrame()

void rogue::hardware::axi::AxiStreamDma::acceptFrame ( std::shared_ptr< rogue::interfaces::stream::Frame > frame )

virtual

Accepts a frame for DMA transmit.

Accept a frame from master.

The frame may contain DMA-backed buffers (zero-copy) and/or local buffers. In SSI mode, SOF/EOFE bits are inserted into user fields for first/last buffer segments as required by the protocol.

Parameters

frame Input frame to transmit.

Reimplemented from rogue::interfaces::stream::Slave.

Definition at line 325 of file AxiStreamDma.cpp.

◆ acceptReq()

rogue::interfaces::stream::FramePtr rogue::hardware::axi::AxiStreamDma::acceptReq	(	uint32_t	size,
		bool	zeroCopyEn
	)

virtual

Allocates a frame for upstream writers.

Generate a buffer. Called from master.

In zero-copy mode, this may allocate one or more DMA-backed buffers and append them into a single frame until size is satisfied. If zero-copy is disabled (globally for the path or per-request via zeroCopyEn), allocation falls back to local frame buffers.

Parameters

size	Minimum requested payload size in bytes.
zeroCopyEn	`true` to allow zero-copy allocation when possible.

Returns: Newly allocated frame.

Adjust allocation size

Reimplemented from rogue::interfaces::stream::Pool.

Definition at line 263 of file AxiStreamDma.cpp.

◆ create()

rogue::hardware::axi::AxiStreamDmaPtr rogue::hardware::axi::AxiStreamDma::create	(	std::string	path,
		uint32_t	dest,
		bool	ssiEnable
	)

static

Creates an AXI Stream DMA bridge instance.

Class creation.

Parameter semantics are identical to the constructor; see AxiStreamDma() for destination and SSI behavior details. Exposed to Python as rogue.hardware.axi.AxiStreamDma(...). 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.

Parameters

path	Path to device, for example `/dev/datadev_0`.
dest	Destination index for DMA transactions.
ssiEnable	Enable SSI user-field handling.

Returns: Shared pointer to the created interface.

Definition at line 145 of file AxiStreamDma.cpp.

◆ dmaAck()

void rogue::hardware::axi::AxiStreamDma::dmaAck ( )

Sends an ACK strobe through driver-specific DMA control path.

Strobe ack line.

Hardware behavior is implementation-specific to the target DMA core. Exposed to Python as dmaAck().

Definition at line 258 of file AxiStreamDma.cpp.

◆ getApiVersion()

uint32_t rogue::hardware::axi::AxiStreamDma::getApiVersion ( )

Gets DMA driver API version.

Get the DMA Driver's API Version.

Returns: Driver API version number.

Definition at line 576 of file AxiStreamDma.cpp.

◆ getBuffSize()

uint32_t rogue::hardware::axi::AxiStreamDma::getBuffSize ( )

Gets DMA buffer size.

Get the size of buffers (RX/TX)

Returns: RX/TX DMA buffer size in bytes.

Definition at line 581 of file AxiStreamDma.cpp.

◆ getGitVersion()

std::string rogue::hardware::axi::AxiStreamDma::getGitVersion ( )

Gets DMA driver Git version string.

Get the DMA Driver's Git Version.

Returns: Git version string, empty on failure.

Definition at line 571 of file AxiStreamDma.cpp.

◆ getRxBuffCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getRxBuffCount ( )

Gets RX DMA buffer count.

Get the number of RX buffers.

Returns: Number of RX buffers.

Definition at line 586 of file AxiStreamDma.cpp.

◆ getRxBuffinHwCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getRxBuffinHwCount ( )

Gets RX buffers currently held by hardware.

Get RX buffer in HW count.

Returns: RX in-hardware count.

Definition at line 596 of file AxiStreamDma.cpp.

◆ getRxBuffinPreHwQCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getRxBuffinPreHwQCount ( )

Gets RX buffers queued before hardware.

Get RX buffer in Pre-HW Queue count.

Returns: RX pre-hardware queue count.

Definition at line 601 of file AxiStreamDma.cpp.

◆ getRxBuffinSwQCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getRxBuffinSwQCount ( )

Gets RX buffers queued in software.

Get RX buffer in SW Queue count.

Returns: RX software queue count.

Definition at line 606 of file AxiStreamDma.cpp.

◆ getRxBuffinUserCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getRxBuffinUserCount ( )

Gets RX buffers currently held by user space.

Get RX buffer in User count.

Returns: RX in-user count.

Definition at line 591 of file AxiStreamDma.cpp.

◆ getRxBuffMissCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getRxBuffMissCount ( )

Gets RX buffer missing count.

Get RX buffer missing count.

Returns: RX missing buffer count.

Definition at line 611 of file AxiStreamDma.cpp.

◆ getTxBuffCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getTxBuffCount ( )

Gets TX DMA buffer count.

Get the number of TX buffers.

Returns: Number of TX buffers.

Definition at line 616 of file AxiStreamDma.cpp.

◆ getTxBuffinHwCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getTxBuffinHwCount ( )

Gets TX buffers currently held by hardware.

Get TX buffer in HW count.

Returns: TX in-hardware count.

Definition at line 626 of file AxiStreamDma.cpp.

◆ getTxBuffinPreHwQCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getTxBuffinPreHwQCount ( )

Gets TX buffers queued before hardware.

Get TX buffer in Pre-HW Queue count.

Returns: TX pre-hardware queue count.

Definition at line 631 of file AxiStreamDma.cpp.

◆ getTxBuffinSwQCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getTxBuffinSwQCount ( )

Gets TX buffers queued in software.

Get TX buffer in SW Queue count.

Returns: TX software queue count.

Definition at line 636 of file AxiStreamDma.cpp.

◆ getTxBuffinUserCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getTxBuffinUserCount ( )

Gets TX buffers currently held by user space.

Get TX buffer in User count.

Returns: TX in-user count.

Definition at line 621 of file AxiStreamDma.cpp.

◆ getTxBuffMissCount()

uint32_t rogue::hardware::axi::AxiStreamDma::getTxBuffMissCount ( )

Gets TX buffer missing count.

Get TX buffer missing count.

Returns: TX missing buffer count.

Definition at line 641 of file AxiStreamDma.cpp.

◆ retBuffer()

void rogue::hardware::axi::AxiStreamDma::retBuffer	(	uint8_t *	data,
		uint32_t	meta,
		uint32_t	rawSize
	)

virtual

Returns DMA-backed buffer memory after frame release.

Return a buffer.

Parameters

data	Buffer data pointer.
meta	Driver-specific metadata/index.
rawSize	Original allocated buffer size in bytes.

Reimplemented from rogue::interfaces::stream::Pool.

Definition at line 426 of file AxiStreamDma.cpp.

◆ setDriverDebug()

void rogue::hardware::axi::AxiStreamDma::setDriverDebug ( uint32_t level )

Sets DMA driver debug level.

Set driver debug level.

Forwards level to lower-level driver debug control. Driver messages can be inspected through kernel logs (for example dmesg). Typical drivers treat any positive value as debug enabled.

Exposed to Python as setDriverDebug().

Parameters

level Driver debug level.

Definition at line 253 of file AxiStreamDma.cpp.

◆ setTimeout()

void rogue::hardware::axi::AxiStreamDma::setTimeout ( uint32_t timeout )

Sets TX/alloc wait timeout.

Set timeout for frame transmits in microseconds.

The timeout is used in blocking select loops for outbound DMA resources. On timeout, warnings are logged and retries continue until resources are available.

Exposed to Python as setTimeout().

Parameters

timeout Timeout value in microseconds.

Definition at line 244 of file AxiStreamDma.cpp.

◆ setup_python()

void rogue::hardware::axi::AxiStreamDma::setup_python ( )

static

Registers Python bindings for this class.

Definition at line 645 of file AxiStreamDma.cpp.

◆ stop()

void rogue::hardware::axi::AxiStreamDma::stop ( )

virtual

Stops RX thread and closes DMA file descriptors.

Reimplemented from rogue::interfaces::stream::Master.

Definition at line 229 of file AxiStreamDma.cpp.

◆ zeroCopyDisable()

void rogue::hardware::axi::AxiStreamDma::zeroCopyDisable ( std::string path )

static

Disables zero-copy mode for a device path.

Must be called before the first AxiStreamDma instance for path.

By default, the class attempts to map kernel DMA buffers directly into user space and use those buffers as Rogue frame storage (zero-copy path). This reduces copies and CPU overhead. When disabled, Rogue allocates local pooled buffers and copies data to/from driver buffers.

Exposed to Python as zeroCopyDisable().

Parameters

path	Device path, for example `/dev/datadev_0`.

Definition at line 150 of file AxiStreamDma.cpp.

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

/home/runner/work/rogue/rogue/include/rogue/hardware/axi/AxiStreamDma.h
/home/runner/work/rogue/rogue/src/rogue/hardware/axi/AxiStreamDma.cpp

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ AxiStreamDma()

◆ ~AxiStreamDma()

Member Function Documentation

◆ acceptFrame()

◆ acceptReq()

◆ create()

◆ dmaAck()

◆ getApiVersion()

◆ getBuffSize()

◆ getGitVersion()

◆ getRxBuffCount()

◆ getRxBuffinHwCount()

◆ getRxBuffinPreHwQCount()

◆ getRxBuffinSwQCount()

◆ getRxBuffinUserCount()

◆ getRxBuffMissCount()

◆ getTxBuffCount()

◆ getTxBuffinHwCount()

◆ getTxBuffinPreHwQCount()

◆ getTxBuffinSwQCount()

◆ getTxBuffinUserCount()

◆ getTxBuffMissCount()

◆ retBuffer()

◆ setDriverDebug()

◆ setTimeout()

◆ setup_python()

◆ stop()

◆ zeroCopyDisable()