DMA Driver API

Complete C API reference for the DMA driver, extracted from include/DmaDriver.h via Doxygen and rendered by Breathe.

Includes all public structs (DmaWriteData, DmaReadData, DmaRegisterData), ioctl command code macros, and the full set of userspace inline helper functions such as dmaWrite, dmaRead, dmaMapDma, and dmaUnMapDma.

Note

All helper functions are static inline and are compiled directly into the calling application. They are not shared library symbols.

Defines

DMA_VERSION
DMA_ERR_FIFO
DMA_ERR_LEN
DMA_ERR_MAX
DMA_ERR_BUS
DMA_Get_Buff_Count

ioctl command code: get the total number of DMA buffers in the pool.

DMA_Get_Buff_Size

ioctl command code: get the size in bytes of each DMA buffer.

DMA_Set_Debug

ioctl command code: set the kernel debug verbosity level (0 = off).

DMA_Set_Mask

ioctl command code: set the 32-bit destination channel mask (convenience wrapper for single-mask use).

DMA_Ret_Index

ioctl command code: return one or more buffer indices to the DMA free pool.

The upper 16 bits of the command encode the count: cmd = DMA_Ret_Index | ((count << 16) & 0xFFFF0000).

DMA_Get_Index

ioctl command code: get the index of the next available write buffer.

DMA_Read_Ready

ioctl command code: check whether a receive frame is pending (returns 1 if data ready).

DMA_Set_MaskBytes

ioctl command code: set the destination channel mask using a 512-byte bitmap (DMA_MASK_SIZE bytes).

DMA_Get_Version

ioctl command code: get the driver API version integer; compare to DMA_VERSION for compatibility.

DMA_Write_Register

ioctl command code: write a 32-bit value to a device BAR register; argument is struct DmaRegisterData*.

DMA_Read_Register

ioctl command code: read a 32-bit value from a device BAR register; argument is struct DmaRegisterData*.

DMA_Get_RxBuff_Count

ioctl command code: get the total number of receive DMA buffers in the pool.

DMA_Get_TxBuff_Count

ioctl command code: get the total number of transmit DMA buffers in the pool.

DMA_Get_TxBuffinUser_Count

ioctl command code: get the count of TX buffers currently held in user space.

DMA_Get_TxBuffinHW_Count

ioctl command code: get the count of TX buffers currently submitted to hardware.

DMA_Get_TxBuffinPreHWQ_Count

ioctl command code: get the count of TX buffers in the pre-hardware queue.

DMA_Get_TxBuffinSWQ_Count

ioctl command code: get the count of TX buffers in the software queue.

DMA_Get_TxBuffMiss_Count

ioctl command code: get the TX buffer allocation miss count (buffers requested but unavailable).

DMA_Get_RxBuffinUser_Count

ioctl command code: get the count of RX buffers currently held in user space.

DMA_Get_RxBuffinHW_Count

ioctl command code: get the count of RX buffers currently submitted to hardware.

DMA_Get_RxBuffinPreHWQ_Count

ioctl command code: get the count of RX buffers in the pre-hardware queue.

DMA_Get_RxBuffinSWQ_Count

ioctl command code: get the count of RX buffers in the software queue.

DMA_Get_RxBuffMiss_Count

ioctl command code: get the RX buffer allocation miss count (buffers requested but unavailable).

DMA_Get_GITV

ioctl command code: get the driver git version string into a caller-supplied char[32] buffer.

DMA_MASK_SIZE

Functions

static inline ssize_t dmaWrite(int32_t fd, const void *buf, size_t size, uint32_t flags, uint32_t dest)

Writes data to a DMA channel.

This function writes a single frame of data to a DMA channel, specified by the file descriptor fd. The data to be written is pointed to by buf, with a specified size of size. Additional parameters include flags (flags) and a destination address (dest).

Parameters:

  • fd – File descriptor for the DMA device.

  • buf – Pointer to the data buffer.

  • size – Size of the data to write.

  • flags – Flags for the write operation.

  • dest – Destination address for the write.

Returns:

Number of bytes written, or a negative error code on failure.

static inline ssize_t dmaWriteIndex(int32_t fd, uint32_t index, size_t size, uint32_t flags, uint32_t dest)

Writes data to a DMA channel using an index.

Similar to dmaWrite, but uses an index (index) to specify the data buffer instead of a direct pointer. This is useful for memory-mapped I/O operations where data buffers are identified by indexes.

Parameters:

  • fd – File descriptor for the DMA device.

  • index – Index of the data buffer.

  • size – Size of the data to write.

  • flags – Flags for the write operation.

  • dest – Destination address for the write.

Returns:

Number of bytes written, or a negative error code on failure.

static inline ssize_t dmaWriteVector(int32_t fd, struct iovec *iov, size_t iovlen, uint32_t begFlags, uint32_t midFlags, uint32_t endFlags, uint32_t dest)

Writes an array of data frames to a DMA channel.

This function writes multiple data frames to a DMA channel, where each frame is specified by an iovec structure in the array pointed to by iov. The number of frames to write is specified by iovlen. Flags for the beginning, middle, and end of the data stream are specified by begFlags, midFlags, and endFlags, respectively. The destination address for the write operation is specified by dest.

Parameters:

  • fd – File descriptor for the DMA device.

  • iov – Pointer to the array of iovec structures.

  • iovlen – Number of elements in the iov array.

  • begFlags – Flags for the beginning of the data stream.

  • midFlags – Flags for the middle of the data stream.

  • endFlags – Flags for the end of the data stream.

  • dest – Destination address for the write.

Returns:

Total number of bytes written, or a negative error code on failure.

static inline ssize_t dmaWriteIndexVector(int32_t fd, struct iovec *iov, size_t iovlen, uint32_t begFlags, uint32_t midFlags, uint32_t endFlags, uint32_t dest)

Write Frame, memory mapped from iovector.

This function writes a frame to a device, using DMA, where the frame data is described by an array of iovec structures.

Parameters:

  • fd – File descriptor for DMA operation.

  • iov – Pointer to array of iovec structures.

  • iovlen – Length of the iov array.

  • begFlags – Flags to use for the beginning of the DMA transaction.

  • midFlags – Flags to use for the middle of the DMA transaction.

  • endFlags – Flags to use for the end of the DMA transaction.

  • dest – Destination address for the DMA write.

Returns:

Total number of bytes written, or negative on failure.

static inline ssize_t dmaRead(int32_t fd, void *buf, size_t maxSize, uint32_t *flags, uint32_t *error, uint32_t *dest)

Receive Frame.

This function reads a frame from a device using DMA.

Parameters:

  • fd – File descriptor for DMA operation.

  • buf – Buffer to store received data.

  • maxSize – Maximum size to read.

  • flags – Pointer to store flags after reading.

  • error – Pointer to store error code if any.

  • dest – Pointer to store destination address.

Returns:

Size of the data received, or negative on failure.

static inline ssize_t dmaReadIndex(int32_t fd, uint32_t *index, uint32_t *flags, uint32_t *error, uint32_t *dest)

Receive Frame, access memory mapped buffer.

This function reads a frame from a device using DMA, specifically accessing the memory-mapped buffer and retrieves the index of the received data.

Parameters:

  • fd – File descriptor for DMA operation.

  • index – Pointer to store the index of the received data.

  • flags – Pointer to store flags after reading.

  • error – Pointer to store error code if any.

  • dest – Pointer to store destination address.

Returns:

Size of the data received, or negative on failure.

static inline ssize_t dmaReadBulkIndex(int32_t fd, uint32_t count, int32_t *ret, uint32_t *index, uint32_t *flags, uint32_t *error, uint32_t *dest)

Receive frame and access memory-mapped buffer.

This function reads bulk data from a DMA channel and extracts the metadata associated with each read operation, including return values, indices, flags, error codes, and destination addresses.

Parameters:

  • fd – File descriptor to read from.

  • count – Number of elements in the buffers.

  • ret – Pointer to store the return values.

  • index – Buffer to store the indices of the DMA read operations.

  • flags – Buffer to store flags of the DMA read operations.

  • error – Buffer to store error codes of the DMA read operations.

  • dest – Buffer to store destination addresses of the DMA read operations.

Returns:

The number of bytes read.

static inline ssize_t dmaRetIndex(int32_t fd, uint32_t index)

Post an index back to the DMA.

This function posts a single index back to the DMA, indicating that the buffer associated with this index can be reused.

Parameters:

  • fd – File descriptor to use.

  • index – Index to be returned.

Returns:

Result of the IOCTL operation.

static inline ssize_t dmaRetIndexes(int32_t fd, uint32_t count, uint32_t *indexes)

Post multiple indices back to the DMA.

This function posts multiple indices back to the DMA, indicating that the buffers associated with these indices can be reused.

Parameters:

  • fd – File descriptor to use.

  • count – Number of indices to be returned.

  • indexes – Array of indices to be returned.

Returns:

Result of the IOCTL operation.

static inline int32_t dmaGetIndex(int32_t fd)

Get the current write buffer index.

This function retrieves the current index for writing to the DMA buffer.

Parameters:

  • fd – File descriptor to use.

Returns:

The current write buffer index.

static inline ssize_t dmaReadReady(int32_t fd)

Check if read is ready.

This function checks if the DMA is ready for reading.

Parameters:

  • fd – File descriptor to use.

Returns:

Result of the IOCTL operation, indicating read readiness.

static inline ssize_t dmaGetRxBuffCount(int32_t fd)

Get the receive buffer count.

This function retrieves the count of receive buffers available.

Parameters:

  • fd – File descriptor to use.

Returns:

The count of receive buffers.

static inline ssize_t dmaGetRxBuffinUserCount(int32_t fd)

Get the receive buffer count in user.

This function retrieves the count of receive buffers in user.

Parameters:

  • fd – File descriptor to use.

Returns:

The count of receive buffers in user

static inline ssize_t dmaGetRxBuffinHwCount(int32_t fd)

Get the receive buffer count in hardware.

This function retrieves the count of receive buffers in hardware.

Parameters:

  • fd – File descriptor to use.

Returns:

The count of receive buffers in hardware

static inline ssize_t dmaGetRxBuffinPreHwQCount(int32_t fd)

Get the receive buffer count in pre-hardware queue.

This function retrieves the count of receive buffers in pre-hardware queue

Parameters:

  • fd – File descriptor to use.

Returns:

The count of receive buffers in pre-hardware queue

static inline ssize_t dmaGetRxBuffinSwQCount(int32_t fd)

Get the receive buffer count in software queue.

This function retrieves the count of receive buffers in software queue

Parameters:

  • fd – File descriptor to use.

Returns:

The count of receive buffers in software queue

static inline ssize_t dmaGetRxBuffMissCount(int32_t fd)

Get the receive buffer missing count.

This function retrieves the count of receive buffer missing

Parameters:

  • fd – File descriptor to use.

Returns:

The count of receive buffers missing

static inline ssize_t dmaGetTxBuffCount(int32_t fd)

Get the transmit buffer count.

This function retrieves the count of transmit buffers available.

Parameters:

  • fd – File descriptor to use.

Returns:

The count of transmit buffers.

static inline ssize_t dmaGetTxBuffinUserCount(int32_t fd)

Get the transmit buffer count in user.

This function retrieves the count of transmit buffers in user.

Parameters:

  • fd – File descriptor to use.

Returns:

The count of transmit buffers in user

static inline ssize_t dmaGetTxBuffinHwCount(int32_t fd)

Get the transmit buffer count in hardware.

This function retrieves the count of transmit buffers in hardware.

Parameters:

  • fd – File descriptor to use.

Returns:

The count of transmit buffers in hardware

static inline ssize_t dmaGetTxBuffinPreHwQCount(int32_t fd)

Get the transmit buffer count in pre-hardware queue.

This function retrieves the count of transmit buffers in pre-hardware queue

Parameters:

  • fd – File descriptor to use.

Returns:

The count of transmit buffers in pre-hardware queue

static inline ssize_t dmaGetTxBuffinSwQCount(int32_t fd)

Get the transmit buffer count in software queue.

This function retrieves the count of transmit buffers in software queue

Parameters:

  • fd – File descriptor to use.

Returns:

The count of transmit buffers in software queue

static inline ssize_t dmaGetTxBuffMissCount(int32_t fd)

Get the transmit buffer missing count.

This function retrieves the count of transmit buffer missing

Parameters:

  • fd – File descriptor to use.

Returns:

The count of transmit buffers missing

static inline ssize_t dmaGetBuffSize(int32_t fd)

Get the buffer size.

This function retrieves the size of DMA buffers.

Parameters:

  • fd – File descriptor to use.

Returns:

The size of DMA buffers.

static inline ssize_t dmaGetBuffCount(int32_t fd)

Get the buffer count.

This function retrieves the count of DMA buffers.

Parameters:

  • fd – File descriptor to use.

Returns:

The count of DMA buffers.

static inline std::string dmaGetGitVersion (int32_t fd)

Get the DMA Driver’s Git Version.

This function retrieves the DMA Driver’s Git Version string

Parameters:

  • fd – File descriptor to use.

Returns:

The DMA Driver’s Git Version string

static inline void **dmaMapDma(int32_t fd, uint32_t *count, uint32_t *size)

Map user space to DMA buffers.

This function maps DMA buffers into user space, allowing direct access.

Parameters:

  • fd – File descriptor to use.

  • count – Pointer to store the count of buffers.

  • size – Pointer to store the size of each buffer.

Returns:

Pointer to an array of pointers to the mapped buffers, or NULL on failure.

static inline ssize_t dmaUnMapDma(int32_t fd, void **buffer)

Unmap user space from DMA buffers.

This function unmaps DMA buffers from user space, releasing the resources.

Parameters:

  • fd – File descriptor to use.

  • buffer – Array of pointers to the mapped buffers.

Returns:

0 on success.

static inline ssize_t dmaSetDebug(int32_t fd, uint32_t level)

Set debugging level for DMA operations.

This function sets the specified debugging level for DMA operations using an IOCTL command.

Parameters:

  • fd – File descriptor for the DMA device.

  • level – Debugging level to be set.

Returns:

Result from the IOCTL call.

static inline void dmaAssignHandler(int32_t fd, void (*handler)(int32_t))

Assign a signal handler for asynchronous DMA operations.

This function sets up a signal action structure to handle SIGIO signals with the specified handler function. It also sets the file descriptor to receive signals for asynchronous I/O.

Parameters:

  • fd – File descriptor for the DMA device.

  • handler – Function pointer to the signal handler.

static inline ssize_t dmaSetMask(int32_t fd, uint32_t mask)

Set DMA mask.

Sets a DMA mask using an IOCTL command.

Parameters:

  • fd – File descriptor for the DMA device.

  • mask – DMA mask to be set.

Returns:

Result from the IOCTL call.

static inline void dmaInitMaskBytes(uint8_t *mask)

Initialize DMA mask byte array.

Initializes the DMA mask byte array to zeros.

Parameters:

  • mask – Pointer to the DMA mask byte array.

static inline void dmaAddMaskBytes(uint8_t *mask, uint32_t dest)

Add a destination to the DMA mask byte array.

Adds a destination to the DMA mask byte array by setting the appropriate bit based on the destination index.

Parameters:

  • mask – Pointer to the DMA mask byte array.

  • dest – Destination index to set in the mask.

static inline ssize_t dmaSetMaskBytes(int32_t fd, uint8_t *mask)

Set mask byte array to the driver.

Sets the DMA mask byte array using an IOCTL command.

Parameters:

  • fd – File descriptor for the DMA device.

  • mask – Pointer to the DMA mask byte array.

Returns:

Result from the IOCTL call.

static inline ssize_t dmaCheckVersion(int32_t fd)

Check API version of the DMA driver.

Checks the API version of the DMA driver to ensure compatibility.

Parameters:

  • fd – File descriptor for the DMA device.

Returns:

0 if the version matches, -1 otherwise.

static inline ssize_t dmaGetApiVersion(int32_t fd)

Get API version of the DMA driver.

Get the API version of the DMA driver

Parameters:

  • fd – File descriptor for the DMA device.

Returns:

The API version of the DMA driver

static inline ssize_t dmaWriteRegister(int32_t fd, uint64_t address, uint32_t data)

Write to a DMA register.

Writes data to a specified register address using an IOCTL command.

Parameters:

  • fd – File descriptor for the DMA device.

  • address – Register address.

  • data – Data to write.

Returns:

Result from the IOCTL call.

static inline ssize_t dmaReadRegister(int32_t fd, uint64_t address, uint32_t *data)

Read a value from a DMA register.

This function reads a 32-bit value from a specified DMA register address. The read value is stored in the location pointed to by data if data is not NULL.

Parameters:

  • fd – File descriptor for the DMA device.

  • address – The address of the register to be read.

  • data – Pointer to store the read data.

Returns:

The result of the ioctl operation, indicating success or failure.

static inline void *dmaMapRegister(int32_t fd, off_t offset, uint32_t size)

Map a DMA register space to user space.

This function calculates an internal offset based on the buffer size and count obtained from the DMA device. It then attempts to map a region of memory into the user space corresponding to this calculated offset plus the specified offset.

Parameters:

  • fd – File descriptor for the DMA device.

  • offset – Offset from the start of the register space to be mapped.

  • size – Size of the memory region to map.

Returns:

A pointer to the mapped memory region in user space, or MAP_FAILED on failure.

static inline ssize_t dmaUnMapRegister(int32_t fd, void *ptr, uint32_t size)

Unmap a DMA register space from user space.

This function unmaps a previously mapped region of memory from the user space. The fd parameter is not used but is included for symmetry with the dmaMapRegister function.

Parameters:

  • fd – File descriptor for the DMA device. (Unused in this function, but kept for symmetry with map function)

  • ptr – Pointer to the start of the mapped memory region.

  • size – Size of the memory region to unmap.

Returns:

Always returns 0 indicating success.

struct DmaWriteData
#include <DmaDriver.h>

Structure representing a DMA write operation.

This structure is used to initiate a DMA write operation. It contains information about the data to be written, the destination, and various control flags.

Param data:

Physical address of the data to be written.

Param dest:

Destination address within the device.

Param flags:

Flags to control the write operation.

Param index:

Index of the buffer to be used for the write operation.

Param size:

Size of the data to be written.

Param is32:

Flag indicating whether the system uses 32-bit addressing.

Param pad:

Padding to align the structure to 64 bits.

Public Members

uint64_t data
uint32_t dest
uint32_t flags
uint32_t index
uint32_t size
uint32_t is32
uint32_t pad
struct DmaReadData
#include <DmaDriver.h>

Structure representing a DMA read operation.

This structure is used to initiate a DMA read operation. It contains information about where to store the read data, the source of the data, and various control flags.

Param data:

Physical address where the read data will be stored.

Param dest:

Source address within the device.

Param flags:

Flags to control the read operation.

Param index:

Index of the buffer to be used for the read operation.

Param error:

Error code returned by the read operation.

Param size:

Size of the data to be read.

Param is32:

Flag indicating whether the system uses 32-bit addressing.

Param ret:

The return value of the read operation, typically the size of the data read.

Public Members

uint64_t data
uint32_t dest
uint32_t flags
uint32_t index
uint32_t error
uint32_t size
uint32_t is32
int32_t ret
struct DmaRegisterData
#include <DmaDriver.h>

Register data structure.

This structure holds the data necessary to perform a register write operation within a DMA context.

Param address:

Memory address.

Param data:

Data to be written.

Public Members

uint64_t address
uint32_t data