DPDK

NAME¶

rte_dmadev.h

SYNOPSIS¶

#include <stdint.h>
#include <rte_bitops.h>
#include <rte_common.h>
#include 'rte_dmadev_core.h'

Data Structures¶

struct rte_dma_info
struct rte_dma_conf
struct rte_dma_port_param
struct rte_dma_auto_free_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_M2D_AUTO_FREE RTE_BIT64(7)
#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

See also:

rte_dma_copy()

rte_dma_copy_sg()

rte_dma_fill()

#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)
#define RTE_DMA_OP_FLAG_AUTO_FREE RTE_BIT64(3)

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 { , RTE_DMA_PORT_PCIE }
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¶

int rte_dma_dev_max (size_t dev_max)
int rte_dma_get_dev_id_by_name (const char *name)
bool rte_dma_is_valid (int16_t dev_id)
uint16_t rte_dma_count_avail (void)
int16_t rte_dma_next_dev (int16_t start_dev_id)
int rte_dma_info_get (int16_t dev_id, struct rte_dma_info *dev_info)
int rte_dma_configure (int16_t dev_id, const struct rte_dma_conf *dev_conf)
int rte_dma_start (int16_t dev_id)
int rte_dma_stop (int16_t dev_id)
int rte_dma_close (int16_t dev_id)
int rte_dma_vchan_setup (int16_t dev_id, uint16_t vchan, const struct rte_dma_vchan_conf *conf)
int rte_dma_stats_get (int16_t dev_id, uint16_t vchan, struct rte_dma_stats *stats)
int rte_dma_stats_reset (int16_t dev_id, uint16_t vchan)
int rte_dma_vchan_status (int16_t dev_id, uint16_t vchan, enum rte_dma_vchan_status *status)
int rte_dma_dump (int16_t dev_id, FILE *f)
static 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 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 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 int rte_dma_submit (int16_t dev_id, uint16_t vchan)
static 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 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 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:

rte_dma_configure()
rte_dma_vchan_setup()
rte_dma_start()

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:

rte_dma_copy()
rte_dma_copy_sg()
rte_dma_fill()
rte_dma_submit()

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:

•: rte_dma_completed()

•: return the number of operation requests completed successfully.

•: rte_dma_completed_status()

•: return the number of operation requests completed.

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:

ring_idx for each virtual DMA channel are independent.
For a virtual DMA channel, the ring_idx is monotonically incremented, when it reach UINT16_MAX, it wraps back to zero.
This ring_idx can be used by applications to track per-operation metadata in an application-defined circular ring.
The initial ring_idx of a virtual DMA channel is zero, after the device is stopped, the ring_idx needs to be reset to zero.

One example:

step-1: start one dmadev
step-2: enqueue a copy operation, the ring_idx return is 0
step-3: enqueue a copy operation again, the ring_idx return is 1
...
step-101: stop the dmadev
step-102: start the dmadev
step-103: enqueue a copy operation, the ring_idx return is 0
...
step-x+0: enqueue a fill operation, the ring_idx return is 65535
step-x+1: enqueue a copy operation, the ring_idx return is 0
...

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.

•: memory address: the source and destination address of the memory-to-memory transfer type, or the source address of the memory-to-device transfer type, or the destination address of the device-to-memory transfer type.

Note:

If the device support SVA (

See also:

RTE_DMA_CAPA_SVA), the memory address can be any VA address, otherwise it must be an IOVA address.

•: device address: the source and destination address of the device-to-device transfer type, or the source address of the device-to-memory transfer type, or the destination address of the memory-to-device transfer type.

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¶

#define RTE_DMADEV_DEFAULT_MAX 64¶

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

Definition at line 157 of file rte_dmadev.h.

#define RTE_DMA_FOREACH_DEV(p)¶

Value:

for (p = rte_dma_next_dev(0);          p != -1;          p = rte_dma_next_dev(p + 1))

Utility macro to iterate over all available dmadevs

Definition at line 216 of file rte_dmadev.h.

#define RTE_DMA_CAPA_MEM_TO_MEM RTE_BIT64(0)¶

Support memory-to-memory transfer

Definition at line 226 of file rte_dmadev.h.

#define RTE_DMA_CAPA_MEM_TO_DEV RTE_BIT64(1)¶

Support memory-to-device transfer.

Definition at line 228 of file rte_dmadev.h.

#define RTE_DMA_CAPA_DEV_TO_MEM RTE_BIT64(2)¶

Support device-to-memory transfer.

Definition at line 230 of file rte_dmadev.h.

#define RTE_DMA_CAPA_DEV_TO_DEV RTE_BIT64(3)¶

Support device-to-device transfer.

Definition at line 232 of file rte_dmadev.h.

#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 239 of file rte_dmadev.h.

#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 245 of file rte_dmadev.h.

#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 253 of file rte_dmadev.h.

#define RTE_DMA_CAPA_M2D_AUTO_FREE RTE_BIT64(7)¶

Support auto free for source buffer once mem to dev transfer is completed.

Note:

Even though the DMA driver has this capability, it may not support all mempool drivers. If the mempool is not supported by the DMA driver, rte_dma_vchan_setup() will fail.

Definition at line 260 of file rte_dmadev.h.

#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 266 of file rte_dmadev.h.

#define RTE_DMA_CAPA_OPS_COPY_SG RTE_BIT64(33)¶

Support scatter-gather list copy operation.

Definition at line 268 of file rte_dmadev.h.

#define RTE_DMA_CAPA_OPS_FILL RTE_BIT64(34)¶

Support fill operation.

Definition at line 270 of file rte_dmadev.h.

#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 624 of file rte_dmadev.h.

#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 788 of file rte_dmadev.h.

#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 793 of file rte_dmadev.h.

#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 798 of file rte_dmadev.h.

#define RTE_DMA_OP_FLAG_AUTO_FREE RTE_BIT64(3)¶

Auto free buffer flag. Operation with this flag must issue command to hardware to free the DMA buffer after DMA transfer is completed.

See also:

struct rte_dma_vchan_conf::auto_free

Definition at line 805 of file rte_dmadev.h.

Enumeration Type Documentation¶