AxiStreamDma

Examples of using the AxiStreamDma class are included in Using The AxiStreamDma Class.

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

typedef std::shared_ptr<rogue::hardware::axi::AxiStreamDma> rogue::hardware::axi::AxiStreamDmaPtr

Alias for shared pointer to AxiStreamDma.

The class description is shown below:

class AxiStreamDma : public rogue::interfaces::stream::Master, public rogue::interfaces::stream::Slave

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.

Public Functions

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

Constructs an AXI stream DMA bridge.

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.

~AxiStreamDma()

Destroys the interface and stops background activity.

virtual void stop()

Stops RX thread and closes DMA file descriptors.

void setTimeout(uint32_t timeout)

Sets TX/alloc wait timeout.

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.

void setDriverDebug(uint32_t level)

Sets DMA 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.

void dmaAck()

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

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

virtual std::shared_ptr<rogue::interfaces::stream::Frame> acceptReq(uint32_t size, bool zeroCopyEn)

Allocates a frame for upstream writers.

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.

virtual void acceptFrame(std::shared_ptr<rogue::interfaces::stream::Frame> frame)

Accepts a frame for DMA transmit.

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.

virtual void retBuffer(uint8_t *data, uint32_t meta, uint32_t rawSize)

Returns DMA-backed buffer memory after frame release.

Parameters:

  • data – Buffer data pointer.

  • meta – Driver-specific metadata/index.

  • rawSize – Original allocated buffer size in bytes.

std::string getGitVersion()

Gets DMA driver Git version string.

Returns:

Git version string, empty on failure.

uint32_t getApiVersion()

Gets DMA driver API version.

Returns:

Driver API version number.

uint32_t getBuffSize()

Gets DMA buffer size.

Returns:

RX/TX DMA buffer size in bytes.

uint32_t getRxBuffCount()

Gets RX DMA buffer count.

Returns:

Number of RX buffers.

uint32_t getRxBuffinUserCount()

Gets RX buffers currently held by user space.

Returns:

RX in-user count.

uint32_t getRxBuffinHwCount()

Gets RX buffers currently held by hardware.

Returns:

RX in-hardware count.

uint32_t getRxBuffinPreHwQCount()

Gets RX buffers queued before hardware.

Returns:

RX pre-hardware queue count.

uint32_t getRxBuffinSwQCount()

Gets RX buffers queued in software.

Returns:

RX software queue count.

uint32_t getRxBuffMissCount()

Gets RX buffer missing count.

Returns:

RX missing buffer count.

uint32_t getTxBuffCount()

Gets TX DMA buffer count.

Returns:

Number of TX buffers.

uint32_t getTxBuffinUserCount()

Gets TX buffers currently held by user space.

Returns:

TX in-user count.

uint32_t getTxBuffinHwCount()

Gets TX buffers currently held by hardware.

Returns:

TX in-hardware count.

uint32_t getTxBuffinPreHwQCount()

Gets TX buffers queued before hardware.

Returns:

TX pre-hardware queue count.

uint32_t getTxBuffinSwQCount()

Gets TX buffers queued in software.

Returns:

TX software queue count.

uint32_t getTxBuffMissCount()

Gets TX buffer missing count.

Returns:

TX missing buffer count.

Public Static 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.

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.

static void zeroCopyDisable(std::string path)

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.

static void setup_python()

Registers Python bindings for this class.