DPDK 22.11.6
Data Structures | Macros | Enumerations | Functions
rte_dmadev.h File Reference
#include <stdint.h>
#include <rte_bitops.h>
#include <rte_common.h>
#include <rte_compat.h>
#include "rte_dmadev_core.h"

Go to the source code of this file.

Data Structures

struct  rte_dma_info
 
struct  rte_dma_conf
 
struct  rte_dma_port_param
 
struct  rte_dma_vchan_conf
 
struct  rte_dma_stats
 
struct  rte_dma_sge
 

Macros

#define RTE_DMADEV_DEFAULT_MAX   64
 
#define RTE_DMA_FOREACH_DEV(p)
 
#define RTE_DMA_ALL_VCHAN   0xFFFFu
 
DMA capability
See also
struct rte_dma_info::dev_capa
#define RTE_DMA_CAPA_MEM_TO_MEM   RTE_BIT64(0)
 
#define RTE_DMA_CAPA_MEM_TO_DEV   RTE_BIT64(1)
 
#define RTE_DMA_CAPA_DEV_TO_MEM   RTE_BIT64(2)
 
#define RTE_DMA_CAPA_DEV_TO_DEV   RTE_BIT64(3)
 
#define RTE_DMA_CAPA_SVA   RTE_BIT64(4)
 
#define RTE_DMA_CAPA_SILENT   RTE_BIT64(5)
 
#define RTE_DMA_CAPA_HANDLES_ERRORS   RTE_BIT64(6)
 
#define RTE_DMA_CAPA_OPS_COPY   RTE_BIT64(32)
 
#define RTE_DMA_CAPA_OPS_COPY_SG   RTE_BIT64(33)
 
#define RTE_DMA_CAPA_OPS_FILL   RTE_BIT64(34)
 
DMA operation flag
#define RTE_DMA_OP_FLAG_FENCE   RTE_BIT64(0)
 
#define RTE_DMA_OP_FLAG_SUBMIT   RTE_BIT64(1)
 
#define RTE_DMA_OP_FLAG_LLC   RTE_BIT64(2)
 

Enumerations

enum  rte_dma_direction { RTE_DMA_DIR_MEM_TO_MEM , RTE_DMA_DIR_MEM_TO_DEV , RTE_DMA_DIR_DEV_TO_MEM , RTE_DMA_DIR_DEV_TO_DEV }
 
enum  rte_dma_port_type { }
 
enum  rte_dma_vchan_status { RTE_DMA_VCHAN_IDLE , RTE_DMA_VCHAN_ACTIVE , RTE_DMA_VCHAN_HALTED_ERROR }
 
enum  rte_dma_status_code {
  RTE_DMA_STATUS_SUCCESSFUL , RTE_DMA_STATUS_USER_ABORT , RTE_DMA_STATUS_NOT_ATTEMPTED , RTE_DMA_STATUS_INVALID_SRC_ADDR ,
  RTE_DMA_STATUS_INVALID_DST_ADDR , RTE_DMA_STATUS_INVALID_ADDR , RTE_DMA_STATUS_INVALID_LENGTH , RTE_DMA_STATUS_INVALID_OPCODE ,
  RTE_DMA_STATUS_BUS_READ_ERROR , RTE_DMA_STATUS_BUS_WRITE_ERROR , RTE_DMA_STATUS_BUS_ERROR , RTE_DMA_STATUS_DATA_POISION ,
  RTE_DMA_STATUS_DESCRIPTOR_READ_ERROR , RTE_DMA_STATUS_DEV_LINK_ERROR , RTE_DMA_STATUS_PAGE_FAULT , RTE_DMA_STATUS_ERROR_UNKNOWN = 0x100
}
 

Functions

__rte_experimental int rte_dma_dev_max (size_t dev_max)
 
__rte_experimental int rte_dma_get_dev_id_by_name (const char *name)
 
__rte_experimental bool rte_dma_is_valid (int16_t dev_id)
 
__rte_experimental uint16_t rte_dma_count_avail (void)
 
__rte_experimental int16_t rte_dma_next_dev (int16_t start_dev_id)
 
__rte_experimental int rte_dma_info_get (int16_t dev_id, struct rte_dma_info *dev_info)
 
__rte_experimental int rte_dma_configure (int16_t dev_id, const struct rte_dma_conf *dev_conf)
 
__rte_experimental int rte_dma_start (int16_t dev_id)
 
__rte_experimental int rte_dma_stop (int16_t dev_id)
 
__rte_experimental int rte_dma_close (int16_t dev_id)
 
__rte_experimental int rte_dma_vchan_setup (int16_t dev_id, uint16_t vchan, const struct rte_dma_vchan_conf *conf)
 
__rte_experimental int rte_dma_stats_get (int16_t dev_id, uint16_t vchan, struct rte_dma_stats *stats)
 
__rte_experimental int rte_dma_stats_reset (int16_t dev_id, uint16_t vchan)
 
__rte_experimental int rte_dma_vchan_status (int16_t dev_id, uint16_t vchan, enum rte_dma_vchan_status *status)
 
__rte_experimental int rte_dma_dump (int16_t dev_id, FILE *f)
 
static __rte_experimental int rte_dma_copy (int16_t dev_id, uint16_t vchan, rte_iova_t src, rte_iova_t dst, uint32_t length, uint64_t flags)
 
static __rte_experimental int rte_dma_copy_sg (int16_t dev_id, uint16_t vchan, struct rte_dma_sge *src, struct rte_dma_sge *dst, uint16_t nb_src, uint16_t nb_dst, uint64_t flags)
 
static __rte_experimental int rte_dma_fill (int16_t dev_id, uint16_t vchan, uint64_t pattern, rte_iova_t dst, uint32_t length, uint64_t flags)
 
static __rte_experimental int rte_dma_submit (int16_t dev_id, uint16_t vchan)
 
static __rte_experimental uint16_t rte_dma_completed (int16_t dev_id, uint16_t vchan, const uint16_t nb_cpls, uint16_t *last_idx, bool *has_error)
 
static __rte_experimental uint16_t rte_dma_completed_status (int16_t dev_id, uint16_t vchan, const uint16_t nb_cpls, uint16_t *last_idx, enum rte_dma_status_code *status)
 
static __rte_experimental uint16_t rte_dma_burst_capacity (int16_t dev_id, uint16_t vchan)
 

Detailed Description

DMA (Direct Memory Access) device API.

The DMA framework is built on the following model:

---------------   ---------------       ---------------
| virtual DMA |   | virtual DMA |       | virtual DMA |
| channel     |   | channel     |       | channel     |
---------------   ---------------       ---------------
       |                |                      |
       ------------------                      |
                |                              |
          ------------                    ------------
          |  dmadev  |                    |  dmadev  |
          ------------                    ------------
                |                              |
       ------------------               ------------------
       | HW DMA channel |               | HW DMA channel |
       ------------------               ------------------
                |                              |
                --------------------------------
                                |
                      ---------------------
                      | HW DMA Controller |
                      ---------------------

The DMA controller could have multiple HW-DMA-channels (aka. HW-DMA-queues), each HW-DMA-channel should be represented by a dmadev.

The dmadev could create multiple virtual DMA channels, each virtual DMA channel represents a different transfer context. The DMA operation request must be submitted to the virtual DMA channel. e.g. Application could create virtual DMA channel 0 for memory-to-memory transfer scenario, and create virtual DMA channel 1 for memory-to-device transfer scenario.

This framework uses 'int16_t dev_id' as the device identifier of a dmadev, and 'uint16_t vchan' as the virtual DMA channel identifier in one dmadev.

The functions exported by the dmadev API to setup a device designated by its device identifier must be invoked in the following order:

Then, the application can invoke dataplane functions to process jobs.

If the application wants to change the configuration (i.e. invoke rte_dma_configure() or rte_dma_vchan_setup()), it must invoke rte_dma_stop() first to stop the device and then do the reconfiguration before invoking rte_dma_start() again. The dataplane functions should not be invoked when the device is stopped.

Finally, an application can close a dmadev by invoking the rte_dma_close() function.

The dataplane APIs include two parts: The first part is the submission of operation requests:

These APIs could work with different virtual DMA channels which have different contexts.

The first three APIs are used to submit the operation request to the virtual DMA channel, if the submission is successful, a positive ring_idx <= UINT16_MAX is returned, otherwise a negative number is returned.

The last API is used to issue doorbell to hardware, and also there are flags (

See also
RTE_DMA_OP_FLAG_SUBMIT) parameter of the first three APIs could do the same work.
Note
When enqueuing a set of jobs to the device, having a separate submit outside a loop makes for clearer code than having a check for the last iteration inside the loop to set a special submit flag. However, for cases where one item alone is to be submitted or there is a small set of jobs to be submitted sequentially, having a submit flag provides a lower-overhead way of doing the submission while still keeping the code clean.

The second part is to obtain the result of requests:

Note
If the dmadev works in silent mode (
See also
RTE_DMA_CAPA_SILENT), application does not invoke the above two completed APIs.

About the ring_idx which enqueue APIs (e.g. rte_dma_copy(), rte_dma_fill()) return, the rules are as follows:

One example:

The DMA operation address used in enqueue APIs (i.e. rte_dma_copy(), rte_dma_copy_sg(), rte_dma_fill()) is defined as rte_iova_t type.

The dmadev supports two types of address: memory address and device address.

About MT-safe, all the functions of the dmadev API implemented by a PMD are lock-free functions which assume to not be invoked in parallel on different logical cores to work on the same target dmadev object.

Note
Different virtual DMA channels on the same dmadev DO NOT support parallel invocation because these virtual DMA channels share the same HW-DMA-channel.

Definition in file rte_dmadev.h.

Macro Definition Documentation

◆ RTE_DMADEV_DEFAULT_MAX

#define RTE_DMADEV_DEFAULT_MAX   64

Maximum number of devices if rte_dma_dev_max() is not called.

Examples
examples/dma/dmafwd.c, and examples/vhost/main.c.

Definition at line 158 of file rte_dmadev.h.

◆ RTE_DMA_FOREACH_DEV

#define RTE_DMA_FOREACH_DEV (   p)
Value:
for (p = rte_dma_next_dev(0); \
p != -1; \
p = rte_dma_next_dev(p + 1))
__rte_experimental int16_t rte_dma_next_dev(int16_t start_dev_id)

Utility macro to iterate over all available dmadevs

Definition at line 234 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_MEM_TO_MEM

#define RTE_DMA_CAPA_MEM_TO_MEM   RTE_BIT64(0)

Support memory-to-memory transfer

Definition at line 244 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_MEM_TO_DEV

#define RTE_DMA_CAPA_MEM_TO_DEV   RTE_BIT64(1)

Support memory-to-device transfer.

Definition at line 246 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_DEV_TO_MEM

#define RTE_DMA_CAPA_DEV_TO_MEM   RTE_BIT64(2)

Support device-to-memory transfer.

Definition at line 248 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_DEV_TO_DEV

#define RTE_DMA_CAPA_DEV_TO_DEV   RTE_BIT64(3)

Support device-to-device transfer.

Definition at line 250 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_SVA

#define RTE_DMA_CAPA_SVA   RTE_BIT64(4)

Support SVA which could use VA as DMA address. If device support SVA then application could pass any VA address like memory from rte_malloc(), rte_memzone(), malloc, stack memory. If device don't support SVA, then application should pass IOVA address which from rte_malloc(), rte_memzone().

Definition at line 257 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_SILENT

#define RTE_DMA_CAPA_SILENT   RTE_BIT64(5)

Support work in silent mode. In this mode, application don't required to invoke rte_dma_completed*() API.

See also
struct rte_dma_conf::silent_mode

Definition at line 263 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_HANDLES_ERRORS

#define RTE_DMA_CAPA_HANDLES_ERRORS   RTE_BIT64(6)

Supports error handling

With this bit set, invalid input addresses will be reported as operation failures to the user but other operations can continue. Without this bit set, invalid data is not handled by either HW or driver, so user must ensure that all memory addresses are valid and accessible by HW.

Definition at line 271 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_OPS_COPY

#define RTE_DMA_CAPA_OPS_COPY   RTE_BIT64(32)

Support copy operation. This capability start with index of 32, so that it could leave gap between normal capability and ops capability.

Definition at line 276 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_OPS_COPY_SG

#define RTE_DMA_CAPA_OPS_COPY_SG   RTE_BIT64(33)

Support scatter-gather list copy operation.

Definition at line 278 of file rte_dmadev.h.

◆ RTE_DMA_CAPA_OPS_FILL

#define RTE_DMA_CAPA_OPS_FILL   RTE_BIT64(34)

Support fill operation.

Definition at line 280 of file rte_dmadev.h.

◆ RTE_DMA_ALL_VCHAN

#define RTE_DMA_ALL_VCHAN   0xFFFFu

Special ID, which is used to represent all virtual DMA channels.

See also
rte_dma_stats_get
rte_dma_stats_reset

Definition at line 631 of file rte_dmadev.h.

◆ RTE_DMA_OP_FLAG_FENCE

#define RTE_DMA_OP_FLAG_FENCE   RTE_BIT64(0)

Fence flag. It means the operation with this flag must be processed only after all previous operations are completed. If the specify DMA HW works in-order (it means it has default fence between operations), this flag could be NOP.

Definition at line 811 of file rte_dmadev.h.

◆ RTE_DMA_OP_FLAG_SUBMIT

#define RTE_DMA_OP_FLAG_SUBMIT   RTE_BIT64(1)

Submit flag. It means the operation with this flag must issue doorbell to hardware after enqueued jobs.

Definition at line 816 of file rte_dmadev.h.

◆ RTE_DMA_OP_FLAG_LLC

#define RTE_DMA_OP_FLAG_LLC   RTE_BIT64(2)

Write data to low level cache hint. Used for performance optimization, this is just a hint, and there is no capability bit for this, driver should not return error if this flag was set.

Definition at line 821 of file rte_dmadev.h.

Enumeration Type Documentation

◆ rte_dma_direction

DMA transfer direction defines.

See also
struct rte_dma_vchan_conf::direction
Enumerator
RTE_DMA_DIR_MEM_TO_MEM 

DMA transfer direction - from memory to memory.

See also
struct rte_dma_vchan_conf::direction
RTE_DMA_DIR_MEM_TO_DEV 

DMA transfer direction - from memory to device. In a typical scenario, the SoCs are installed on host servers as iNICs through the PCIe interface. In this case, the SoCs works in EP(endpoint) mode, it could initiate a DMA move request from memory (which is SoCs memory) to device (which is host memory).

See also
struct rte_dma_vchan_conf::direction
RTE_DMA_DIR_DEV_TO_MEM 

DMA transfer direction - from device to memory. In a typical scenario, the SoCs are installed on host servers as iNICs through the PCIe interface. In this case, the SoCs works in EP(endpoint) mode, it could initiate a DMA move request from device (which is host memory) to memory (which is SoCs memory).

See also
struct rte_dma_vchan_conf::direction
RTE_DMA_DIR_DEV_TO_DEV 

DMA transfer direction - from device to device. In a typical scenario, the SoCs are installed on host servers as iNICs through the PCIe interface. In this case, the SoCs works in EP(endpoint) mode, it could initiate a DMA move request from device (which is host memory) to the device (which is another host memory).

See also
struct rte_dma_vchan_conf::direction

Definition at line 430 of file rte_dmadev.h.

◆ rte_dma_port_type

DMA access port type defines.

See also
struct rte_dma_port_param::port_type
Enumerator
RTE_DMA_PORT_PCIE 

The DMA access port is PCIe.

Definition at line 470 of file rte_dmadev.h.

◆ rte_dma_vchan_status

device vchannel status

Enum with the options for the channel status, either idle, active or halted due to error

See also
rte_dma_vchan_status
Enumerator
RTE_DMA_VCHAN_IDLE 

not processing, awaiting ops

RTE_DMA_VCHAN_ACTIVE 

currently processing jobs

RTE_DMA_VCHAN_HALTED_ERROR 

not processing due to error, cannot accept new ops

Definition at line 679 of file rte_dmadev.h.

◆ rte_dma_status_code

DMA transfer result status code defines.

See also
rte_dma_completed_status
Enumerator
RTE_DMA_STATUS_SUCCESSFUL 

The operation completed successfully.

RTE_DMA_STATUS_USER_ABORT 

The operation failed to complete due abort by user. This is mainly used when processing dev_stop, user could modify the descriptors (e.g. change one bit to tell hardware abort this job), it allows outstanding requests to be complete as much as possible, so reduce the time to stop the device.

RTE_DMA_STATUS_NOT_ATTEMPTED 

The operation failed to complete due to following scenarios: The jobs in a particular batch are not attempted because they appeared after a fence where a previous job failed. In some HW implementation it's possible for jobs from later batches would be completed, though, so report the status from the not attempted jobs before reporting those newer completed jobs.

RTE_DMA_STATUS_INVALID_SRC_ADDR 

The operation failed to complete due invalid source address.

RTE_DMA_STATUS_INVALID_DST_ADDR 

The operation failed to complete due invalid destination address.

RTE_DMA_STATUS_INVALID_ADDR 

The operation failed to complete due invalid source or destination address, cover the case that only knows the address error, but not sure which address error.

RTE_DMA_STATUS_INVALID_LENGTH 

The operation failed to complete due invalid length.

RTE_DMA_STATUS_INVALID_OPCODE 

The operation failed to complete due invalid opcode. The DMA descriptor could have multiple format, which are distinguished by the opcode field.

RTE_DMA_STATUS_BUS_READ_ERROR 

The operation failed to complete due bus read error.

RTE_DMA_STATUS_BUS_WRITE_ERROR 

The operation failed to complete due bus write error.

RTE_DMA_STATUS_BUS_ERROR 

The operation failed to complete due bus error, cover the case that only knows the bus error, but not sure which direction error.

RTE_DMA_STATUS_DATA_POISION 

The operation failed to complete due data poison.

RTE_DMA_STATUS_DESCRIPTOR_READ_ERROR 

The operation failed to complete due descriptor read error.

RTE_DMA_STATUS_DEV_LINK_ERROR 

The operation failed to complete due device link error. Used to indicates that the link error in the memory-to-device/ device-to-memory/device-to-device transfer scenario.

RTE_DMA_STATUS_PAGE_FAULT 

The operation failed to complete due lookup page fault.

RTE_DMA_STATUS_ERROR_UNKNOWN 

The operation failed to complete due unknown reason. The initial value is 256, which reserves space for future errors.

Definition at line 729 of file rte_dmadev.h.

Function Documentation

◆ rte_dma_dev_max()

__rte_experimental int rte_dma_dev_max ( size_t  dev_max)
Warning
EXPERIMENTAL: this API may change without prior notice.

Configure the maximum number of dmadevs.

Note
This function can be invoked before the primary process rte_eal_init() to change the maximum number of dmadevs. If not invoked, the maximum number of dmadevs is
See also
RTE_DMADEV_DEFAULT_MAX
Parameters
dev_maxmaximum number of dmadevs.
Returns
0 on success. Otherwise negative value is returned.

◆ rte_dma_get_dev_id_by_name()

__rte_experimental int rte_dma_get_dev_id_by_name ( const char *  name)
Warning
EXPERIMENTAL: this API may change without prior notice.

Get the device identifier for the named DMA device.

Parameters
nameDMA device name.
Returns
Returns DMA device identifier on success.
  • <0: Failure to find named DMA device.
Examples
examples/vhost/main.c.

◆ rte_dma_is_valid()

__rte_experimental bool rte_dma_is_valid ( int16_t  dev_id)
Warning
EXPERIMENTAL: this API may change without prior notice.

Check whether the dev_id is valid.

Parameters
dev_idDMA device index.
Returns
  • If the device index is valid (true) or not (false).

◆ rte_dma_count_avail()

__rte_experimental uint16_t rte_dma_count_avail ( void  )
Warning
EXPERIMENTAL: this API may change without prior notice.

Get the total number of DMA devices that have been successfully initialised.

Returns
The total number of usable DMA devices.

◆ rte_dma_next_dev()

__rte_experimental int16_t rte_dma_next_dev ( int16_t  start_dev_id)

Iterates over valid dmadev instances.

Parameters
start_dev_idThe id of the next possible dmadev.
Returns
Next valid dmadev, UINT16_MAX if there is none.
Examples
examples/dma/dmafwd.c.

◆ rte_dma_info_get()

__rte_experimental int rte_dma_info_get ( int16_t  dev_id,
struct rte_dma_info dev_info 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Retrieve information of a DMA device.

Parameters
dev_idThe identifier of the device.
[out]dev_infoA pointer to a structure of type rte_dma_info to be filled with the information of the device.
Returns
0 on success. Otherwise negative value is returned.
Examples
examples/dma/dmafwd.c, and examples/vhost/main.c.

◆ rte_dma_configure()

__rte_experimental int rte_dma_configure ( int16_t  dev_id,
const struct rte_dma_conf dev_conf 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Configure a DMA device.

This function must be invoked first before any other function in the API. This function can also be re-invoked when a device is in the stopped state.

Parameters
dev_idThe identifier of the device to configure.
dev_confThe DMA device configuration structure encapsulated into rte_dma_conf object.
Returns
0 on success. Otherwise negative value is returned.
Examples
examples/dma/dmafwd.c, and examples/vhost/main.c.

◆ rte_dma_start()

__rte_experimental int rte_dma_start ( int16_t  dev_id)
Warning
EXPERIMENTAL: this API may change without prior notice.

Start a DMA device.

The device start step is the last one and consists of setting the DMA to start accepting jobs.

Parameters
dev_idThe identifier of the device.
Returns
0 on success. Otherwise negative value is returned.
Examples
examples/dma/dmafwd.c, and examples/vhost/main.c.

◆ rte_dma_stop()

__rte_experimental int rte_dma_stop ( int16_t  dev_id)
Warning
EXPERIMENTAL: this API may change without prior notice.

Stop a DMA device.

The device can be restarted with a call to rte_dma_start().

Parameters
dev_idThe identifier of the device.
Returns
0 on success. Otherwise negative value is returned.
Examples
examples/dma/dmafwd.c.

◆ rte_dma_close()

__rte_experimental int rte_dma_close ( int16_t  dev_id)
Warning
EXPERIMENTAL: this API may change without prior notice.

Close a DMA device.

The device cannot be restarted after this call.

Parameters
dev_idThe identifier of the device.
Returns
0 on success. Otherwise negative value is returned.

◆ rte_dma_vchan_setup()

__rte_experimental int rte_dma_vchan_setup ( int16_t  dev_id,
uint16_t  vchan,
const struct rte_dma_vchan_conf conf 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Allocate and set up a virtual DMA channel.

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel. The value must be in the range [0, nb_vchans - 1] previously supplied to rte_dma_configure().
confThe virtual DMA channel configuration structure encapsulated into rte_dma_vchan_conf object.
Returns
0 on success. Otherwise negative value is returned.
Examples
examples/dma/dmafwd.c, and examples/vhost/main.c.

◆ rte_dma_stats_get()

__rte_experimental int rte_dma_stats_get ( int16_t  dev_id,
uint16_t  vchan,
struct rte_dma_stats stats 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Retrieve basic statistics of a or all virtual DMA channel(s).

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel. If equal RTE_DMA_ALL_VCHAN means all channels.
[out]statsThe basic statistics structure encapsulated into rte_dma_stats object.
Returns
0 on success. Otherwise negative value is returned.
Examples
examples/dma/dmafwd.c.

◆ rte_dma_stats_reset()

__rte_experimental int rte_dma_stats_reset ( int16_t  dev_id,
uint16_t  vchan 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Reset basic statistics of a or all virtual DMA channel(s).

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel. If equal RTE_DMA_ALL_VCHAN means all channels.
Returns
0 on success. Otherwise negative value is returned.

◆ rte_dma_vchan_status()

__rte_experimental int rte_dma_vchan_status ( int16_t  dev_id,
uint16_t  vchan,
enum rte_dma_vchan_status status 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Determine if all jobs have completed on a device channel. This function is primarily designed for testing use, as it allows a process to check if all jobs are completed, without actually gathering completions from those jobs.

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel.
[out]statusThe vchan status
Returns
0 - call completed successfully < 0 - error code indicating there was a problem calling the API

◆ rte_dma_dump()

__rte_experimental int rte_dma_dump ( int16_t  dev_id,
FILE *  f 
)
Warning
EXPERIMENTAL: this API may change without prior notice.

Dump DMA device info.

Parameters
dev_idThe identifier of the device.
fThe file to write the output to.
Returns
0 on success. Otherwise negative value is returned.
Examples
examples/dma/dmafwd.c.

◆ rte_dma_copy()

static __rte_experimental int rte_dma_copy ( int16_t  dev_id,
uint16_t  vchan,
rte_iova_t  src,
rte_iova_t  dst,
uint32_t  length,
uint64_t  flags 
)
inlinestatic
Warning
EXPERIMENTAL: this API may change without prior notice.

Enqueue a copy operation onto the virtual DMA channel.

This queues up a copy operation to be performed by hardware, if the 'flags' parameter contains RTE_DMA_OP_FLAG_SUBMIT then trigger doorbell to begin this operation, otherwise do not trigger doorbell.

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel.
srcThe address of the source buffer.
dstThe address of the destination buffer.
lengthThe length of the data to be copied.
flagsAn flags for this operation.
See also
RTE_DMA_OP_FLAG_*
Returns
  • 0..UINT16_MAX: index of enqueued job.
  • -ENOSPC: if no space left to enqueue.
  • other values < 0 on failure.
Examples
examples/dma/dmafwd.c.

Definition at line 855 of file rte_dmadev.h.

◆ rte_dma_copy_sg()

static __rte_experimental int rte_dma_copy_sg ( int16_t  dev_id,
uint16_t  vchan,
struct rte_dma_sge src,
struct rte_dma_sge dst,
uint16_t  nb_src,
uint16_t  nb_dst,
uint64_t  flags 
)
inlinestatic
Warning
EXPERIMENTAL: this API may change without prior notice.

Enqueue a scatter-gather list copy operation onto the virtual DMA channel.

This queues up a scatter-gather list copy operation to be performed by hardware, if the 'flags' parameter contains RTE_DMA_OP_FLAG_SUBMIT then trigger doorbell to begin this operation, otherwise do not trigger doorbell.

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel.
srcThe pointer of source scatter-gather entry array.
dstThe pointer of destination scatter-gather entry array.
nb_srcThe number of source scatter-gather entry.
See also
struct rte_dma_info::max_sges
Parameters
nb_dstThe number of destination scatter-gather entry.
See also
struct rte_dma_info::max_sges
Parameters
flagsAn flags for this operation.
See also
RTE_DMA_OP_FLAG_*
Returns
  • 0..UINT16_MAX: index of enqueued job.
  • -ENOSPC: if no space left to enqueue.
  • other values < 0 on failure.

Definition at line 905 of file rte_dmadev.h.

◆ rte_dma_fill()

static __rte_experimental int rte_dma_fill ( int16_t  dev_id,
uint16_t  vchan,
uint64_t  pattern,
rte_iova_t  dst,
uint32_t  length,
uint64_t  flags 
)
inlinestatic
Warning
EXPERIMENTAL: this API may change without prior notice.

Enqueue a fill operation onto the virtual DMA channel.

This queues up a fill operation to be performed by hardware, if the 'flags' parameter contains RTE_DMA_OP_FLAG_SUBMIT then trigger doorbell to begin this operation, otherwise do not trigger doorbell.

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel.
patternThe pattern to populate the destination buffer with.
dstThe address of the destination buffer.
lengthThe length of the destination buffer.
flagsAn flags for this operation.
See also
RTE_DMA_OP_FLAG_*
Returns
  • 0..UINT16_MAX: index of enqueued job.
  • -ENOSPC: if no space left to enqueue.
  • other values < 0 on failure.

Definition at line 954 of file rte_dmadev.h.

◆ rte_dma_submit()

static __rte_experimental int rte_dma_submit ( int16_t  dev_id,
uint16_t  vchan 
)
inlinestatic
Warning
EXPERIMENTAL: this API may change without prior notice.

Trigger hardware to begin performing enqueued operations.

Writes the "doorbell" to the hardware to trigger it to begin the operations previously enqueued by rte_dma_copy/fill().

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel.
Returns
0 on success. Otherwise negative value is returned.
Examples
examples/dma/dmafwd.c.

Definition at line 989 of file rte_dmadev.h.

◆ rte_dma_completed()

static __rte_experimental uint16_t rte_dma_completed ( int16_t  dev_id,
uint16_t  vchan,
const uint16_t  nb_cpls,
uint16_t *  last_idx,
bool *  has_error 
)
inlinestatic
Warning
EXPERIMENTAL: this API may change without prior notice.

Return the number of operations that have been successfully completed. Once an operation has been reported as completed, the results of that operation will be visible to all cores on the system.

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel.
nb_cplsThe maximum number of completed operations that can be processed.
[out]last_idxThe last completed operation's ring_idx. If not required, NULL can be passed in.
[out]has_errorIndicates if there are transfer error. If not required, NULL can be passed in.
Returns
The number of operations that successfully completed. This return value must be less than or equal to the value of nb_cpls.
Examples
examples/dma/dmafwd.c.

Definition at line 1030 of file rte_dmadev.h.

◆ rte_dma_completed_status()

static __rte_experimental uint16_t rte_dma_completed_status ( int16_t  dev_id,
uint16_t  vchan,
const uint16_t  nb_cpls,
uint16_t *  last_idx,
enum rte_dma_status_code status 
)
inlinestatic
Warning
EXPERIMENTAL: this API may change without prior notice.

Return the number of operations that have been completed, and the operations result may succeed or fail. Once an operation has been reported as completed successfully, the results of that operation will be visible to all cores on the system.

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel.
nb_cplsIndicates the size of status array.
[out]last_idxThe last completed operation's ring_idx. If not required, NULL can be passed in.
[out]statusThis is a pointer to an array of length 'nb_cpls' that holds the completion status code of each operation.
See also
enum rte_dma_status_code
Returns
The number of operations that completed. This return value must be less than or equal to the value of nb_cpls. If this number is greater than zero (assuming n), then n values in the status array are also set.

Definition at line 1093 of file rte_dmadev.h.

◆ rte_dma_burst_capacity()

static __rte_experimental uint16_t rte_dma_burst_capacity ( int16_t  dev_id,
uint16_t  vchan 
)
inlinestatic
Warning
EXPERIMENTAL: this API may change without prior notice.

Check remaining capacity in descriptor ring for the current burst.

Parameters
dev_idThe identifier of the device.
vchanThe identifier of virtual DMA channel.
Returns
  • Remaining space in the descriptor ring for the current burst.
  • 0 on error

Definition at line 1131 of file rte_dmadev.h.