Global Functions

This section documents the public API functions provided by the dma-utils

int mdb5_dmautils_sync_xfer(char *filename, enum mdb5_dma_chan_dir chan_dir,
                            void *buf, size_t xfer_len, size_t base);

Description:

Performs synchronous data transfers through device nodes.

Parameters:

  • filename — Device node path (e.g., /dev/mdb5_write00)

  • chan_dir — Transfer direction (MDB5_CHAN_DIR_TO_DEV or MDB5_CHAN_DIR_FROM_DEV)

  • buf — Data buffer pointer

  • xfer_len — Transfer size in bytes

  • base — Device memory offset

Returns:

Number of bytes transferred on success, negative error code on failure

int mdb5_dmautils_async_xfer(char *filename, enum mdb5_dma_chan_dir chan_dir,
                             void *buf, size_t xfer_len, size_t base);

Description:

Performs asynchronous data transfers through device nodes.

Parameters:

  • filename — Device node path (e.g., /dev/mdb5_write00)

  • chan_dir — Transfer direction (MDB5_CHAN_DIR_TO_DEV or MDB5_CHAN_DIR_FROM_DEV)

  • buf — Data buffer pointer

  • xfer_len — Transfer size in bytes

  • base — Device memory offset

Returns:

Number of bytes transferred on success, negative error code on failure

void prepare_node_name(char *s, char *fmt, uint32_t ch_num);

Description:

Prepares the name of an MDB5-DMA node. This function constructs the name of an MDB5-DMA node based on the format string and channel number.

Parameters:

  • s — Pointer to the buffer where the node name will be stored

  • fmt — Format string indicating the type of node (e.g., "write", "read", "ctrl")

  • ch_num — Channel number

Returns:

None

bool is_file_available(char *pathname);

Description:

Checks if a file or device node exists and is accessible.

Parameters:

  • pathname — Path to check

Returns:

true if accessible, false otherwise

int mdb5_dma_reg_read(void *arg);

Description:

Reads a register from BAR0 using memory-mapped I/O. This function reads a register offset of BAR0 using memory-mapped I/O. It logs an error message if the read operation fails and logs the register offset and data if the read operation is successful.

Parameters:

  • arg — Pointer to struct mdb5_dma_reg containing offset, data, and PCI BDF

Returns:

0 on success, negative error code on failure

int mdb5_dma_reg_write(void *arg);

Description:

Writes data to a register in BAR0 using memory-mapped I/O. This function writes data to register offset of BAR0 using memory-mapped I/O. It then reads back the data to verify the write operation.

Parameters:

  • arg — Pointer to struct mdb5_dma_reg containing offset, data, and PCI BDF

Returns:

0 on success, negative error code on failure

int reg_read_mmap(struct mdb5_dma_reg *reg);

Description:

Reads from a BAR0 register offset using memory-mapped I/O. Low-level function for direct register access.

Parameters:

  • reg — Pointer to struct mdb5_dma_reg containing register information

Returns:

0 on success, negative error code on failure

int reg_write_mmap(struct mdb5_dma_reg *reg);

Description:

Writes data to BAR0 register offset using memory-mapped I/O. Low-level function for direct register access.

Parameters:

  • reg — Pointer to struct mdb5_dma_reg containing register information

Returns:

0 on success, negative error code on failure

int mdb5_dma_stats_read(void *arg);

Description:

Reads MDB5-DMA read/write channel statistics. This function reads the statistics of MDB5-DMA read/write channel. It passes stat_addr physical address to kernel through ioctl operation to retrieve the statistics.

Parameters:

  • arg — Pointer to struct mdb5_dma_ioctl containing control information

Returns:

0 on success, negative error code on failure

int mdb5_dma_transfer_mode(void *arg);

Description:

Sets the transfer mode for an MDB5-DMA channel. This function configures the transfer mode for a MDB5-DMA read/write channel to Scatter-Gather (Linked-list) Mode or Simple (Non Linked-list) Mode.

Parameters:

  • arg — Pointer to struct mdb5_dma_ioctl containing mode configuration

Returns:

0 on success, negative error code on failure

int mdb5_dma_aperture_sz(void *arg);

Description:

Sets the aperture size for an MDB5-DMA channel. This function configures the aperture size for a MDB5-DMA read/write channel. Assumes that transfer mode is set to Scatter-Gather (Linked-list) DMA before performing the operation.

Parameters:

  • arg — Pointer to struct mdb5_dma_ioctl containing aperture configuration

Returns:

0 on success, negative error code on failure

ssize_t read_to_buffer(char *fname, int fd, char *buffer,
                      size_t size, size_t base);

Description:

Reads data from a file into a buffer. This function reads a specified amount of data from a file, starting at a given base offset, into a provided buffer.

Parameters:

  • fname — File name for error reporting

  • fd — File descriptor

  • buffer — Destination buffer

  • size — Number of bytes to read

  • base — Base offset in the file to start reading from

Returns:

Number of bytes read on success, negative error code on failure

ssize_t write_from_buffer(char *fname, int fd, char *buffer,
                         size_t size, size_t base);

Description:

Writes data from a buffer to a file. This function writes a specified amount of data from a provided buffer to a file, starting at a given base offset.

Parameters:

  • fname — File name for error reporting

  • fd — File descriptor

  • buffer — Source buffer containing data to be written

  • size — Number of bytes to write

  • base — Base offset in the file to start writing to

Returns:

Number of bytes written on success, negative error code on failure

uint64_t getopt_integer(char *optarg);

Description:

Converts string arguments to 64-bit integers with hex/decimal support.

Parameters:

  • optarg — String to convert (supports 0x prefix for hex)

Returns:

Parsed integer value

void dump_throughput_result(uint64_t size, float result);

Description:

Displays bandwidth calculation results in appropriate units (GB/sec, MB/sec, KB/sec, or Bytes/sec).

Parameters:

  • size — Transfer size in bytes

  • result — Bandwidth result in bytes/second

Returns:
None

int arg_read_int(char *s, uint32_t *v);

Description:

Parse 32-bit integer values from strings with error checking.

Parameters:

  • s — String to parse

  • v — Pointer to output variable for parsed value

Returns:

0 on success, negative error code on failure

int arg_read_int_ull(char *s, uint64_t *v);

Description:

Parse 64-bit integer values from strings with error checking.

Parameters:

  • s — String to parse

  • v — Pointer to output variable for parsed value

Returns:

0 on success, negative error code on failure

char *strip_comments(char *word);

Description:

Removes comments (lines starting with #) from configuration parsing.

Parameters:

  • word — Input string

Returns:

Processed string or NULL if comment line

char *strip_blanks(char *word, unsigned long *blanks);

Description:

Removes leading whitespace from a string.

Parameters:

  • word — Input string

  • blanks — Pointer to store number of blanks removed

Returns:

Pointer to string with leading blanks removed

uint32_t copy_value(char *src, char *dst, uint32_t max_len);

Description:

Copies non-whitespace characters from source to destination.

Parameters:

  • src — Source string

  • dst — Destination buffer

  • max_len — Maximum length to copy

Returns:

Number of characters copied

char *get_chan_mode(enum mdb5_dma_chan_mode chan_mode);

Description:

Converts channel mode enumeration to string representation.

Parameters:

  • chan_mode — Channel mode enumeration value

Returns:

String representation or NULL for invalid values

char *get_transfer_mode(enum mdb5_dma_transfer_mode mode);

Description:

Converts transfer mode enumeration to string representation.

Parameters:

  • mode — Transfer mode enumeration value

Returns:

String representation or NULL for invalid values

char *get_chan_dir(enum mdb5_dma_chan_dir dir);

Description:

Converts channel direction enumeration to string representation.

Parameters:

  • dir — Channel direction enumeration value

Returns:

String representation or NULL for invalid values

char *get_io_type(enum mdb5_dma_io_type io_type);

Description:

Converts I/O type enum to string representation.

Parameters:

  • io_type — I/O type enumeration value

Returns:

String representation or NULL for invalid values

void timespec_sub(struct timespec *t1, struct timespec *t2);

Description:

Subtracts timespec t2 from t1. Both t1 and t2 must already be normalized (i.e., 0 <= nsec < 1000000000).

Parameters:

  • t1 — Pointer to minuend timespec (result stored here)

  • t2 — Pointer to subtrahend timespec

Returns:

None (result stored in t1)