DPDK 22.11.5
|
#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 | |
| |
#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) |
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) |
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 (
The second part is to obtain the result of requests:
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.
Definition in file rte_dmadev.h.
#define RTE_DMADEV_DEFAULT_MAX 64 |
Maximum number of devices if rte_dma_dev_max() is not called.
Definition at line 158 of file rte_dmadev.h.
#define RTE_DMA_FOREACH_DEV | ( | p | ) |
Utility macro to iterate over all available dmadevs
Definition at line 234 of file rte_dmadev.h.
#define RTE_DMA_CAPA_MEM_TO_MEM RTE_BIT64(0) |
Support memory-to-memory transfer
Definition at line 244 of file rte_dmadev.h.
#define RTE_DMA_CAPA_MEM_TO_DEV RTE_BIT64(1) |
Support memory-to-device transfer.
Definition at line 246 of file rte_dmadev.h.
#define RTE_DMA_CAPA_DEV_TO_MEM RTE_BIT64(2) |
Support device-to-memory transfer.
Definition at line 248 of file rte_dmadev.h.
#define RTE_DMA_CAPA_DEV_TO_DEV RTE_BIT64(3) |
Support device-to-device transfer.
Definition at line 250 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 257 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.
Definition at line 263 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 271 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 276 of file rte_dmadev.h.
#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.
#define RTE_DMA_CAPA_OPS_FILL RTE_BIT64(34) |
Support fill operation.
Definition at line 280 of file rte_dmadev.h.
#define RTE_DMA_ALL_VCHAN 0xFFFFu |
Special ID, which is used to represent all virtual DMA channels.
Definition at line 631 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 811 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 816 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 821 of file rte_dmadev.h.
enum rte_dma_direction |
DMA transfer direction defines.
Enumerator | |
---|---|
RTE_DMA_DIR_MEM_TO_MEM | DMA transfer direction - from memory to memory.
|
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).
|
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).
|
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).
|
Definition at line 430 of file rte_dmadev.h.
enum rte_dma_port_type |
DMA access port type defines.
Enumerator | |
---|---|
RTE_DMA_PORT_PCIE | The DMA access port is PCIe. |
Definition at line 470 of file rte_dmadev.h.
enum rte_dma_vchan_status |
device vchannel status
Enum with the options for the channel status, either idle, active or halted due to error
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.
enum rte_dma_status_code |
DMA transfer result status code defines.
Definition at line 729 of file rte_dmadev.h.
__rte_experimental int rte_dma_dev_max | ( | size_t | dev_max | ) |
Configure the maximum number of dmadevs.
dev_max | maximum number of dmadevs. |
__rte_experimental int rte_dma_get_dev_id_by_name | ( | const char * | name | ) |
Get the device identifier for the named DMA device.
name | DMA device name. |
__rte_experimental bool rte_dma_is_valid | ( | int16_t | dev_id | ) |
Check whether the dev_id is valid.
dev_id | DMA device index. |
__rte_experimental uint16_t rte_dma_count_avail | ( | void | ) |
Get the total number of DMA devices that have been successfully initialised.
__rte_experimental int16_t rte_dma_next_dev | ( | int16_t | start_dev_id | ) |
Iterates over valid dmadev instances.
start_dev_id | The id of the next possible dmadev. |
__rte_experimental int rte_dma_info_get | ( | int16_t | dev_id, |
struct rte_dma_info * | dev_info | ||
) |
Retrieve information of a DMA device.
dev_id | The identifier of the device. | |
[out] | dev_info | A pointer to a structure of type rte_dma_info to be filled with the information of the device. |
__rte_experimental int rte_dma_configure | ( | int16_t | dev_id, |
const struct rte_dma_conf * | dev_conf | ||
) |
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.
dev_id | The identifier of the device to configure. |
dev_conf | The DMA device configuration structure encapsulated into rte_dma_conf object. |
__rte_experimental int rte_dma_start | ( | int16_t | dev_id | ) |
Start a DMA device.
The device start step is the last one and consists of setting the DMA to start accepting jobs.
dev_id | The identifier of the device. |
__rte_experimental int rte_dma_stop | ( | int16_t | dev_id | ) |
Stop a DMA device.
The device can be restarted with a call to rte_dma_start().
dev_id | The identifier of the device. |
__rte_experimental int rte_dma_close | ( | int16_t | dev_id | ) |
Close a DMA device.
The device cannot be restarted after this call.
dev_id | The identifier of the device. |
__rte_experimental int rte_dma_vchan_setup | ( | int16_t | dev_id, |
uint16_t | vchan, | ||
const struct rte_dma_vchan_conf * | conf | ||
) |
Allocate and set up a virtual DMA channel.
dev_id | The identifier of the device. |
vchan | The identifier of virtual DMA channel. The value must be in the range [0, nb_vchans - 1] previously supplied to rte_dma_configure(). |
conf | The virtual DMA channel configuration structure encapsulated into rte_dma_vchan_conf object. |
__rte_experimental int rte_dma_stats_get | ( | int16_t | dev_id, |
uint16_t | vchan, | ||
struct rte_dma_stats * | stats | ||
) |
Retrieve basic statistics of a or all virtual DMA channel(s).
dev_id | The identifier of the device. | |
vchan | The identifier of virtual DMA channel. If equal RTE_DMA_ALL_VCHAN means all channels. | |
[out] | stats | The basic statistics structure encapsulated into rte_dma_stats object. |
__rte_experimental int rte_dma_stats_reset | ( | int16_t | dev_id, |
uint16_t | vchan | ||
) |
Reset basic statistics of a or all virtual DMA channel(s).
dev_id | The identifier of the device. |
vchan | The identifier of virtual DMA channel. If equal RTE_DMA_ALL_VCHAN means all channels. |
__rte_experimental int rte_dma_vchan_status | ( | int16_t | dev_id, |
uint16_t | vchan, | ||
enum rte_dma_vchan_status * | status | ||
) |
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.
dev_id | The identifier of the device. | |
vchan | The identifier of virtual DMA channel. | |
[out] | status | The vchan status |
__rte_experimental int rte_dma_dump | ( | int16_t | dev_id, |
FILE * | f | ||
) |
Dump DMA device info.
dev_id | The identifier of the device. |
f | The file to write the output to. |
|
inlinestatic |
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.
dev_id | The identifier of the device. |
vchan | The identifier of virtual DMA channel. |
src | The address of the source buffer. |
dst | The address of the destination buffer. |
length | The length of the data to be copied. |
flags | An flags for this operation. |
Definition at line 855 of file rte_dmadev.h.
|
inlinestatic |
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.
dev_id | The identifier of the device. |
vchan | The identifier of virtual DMA channel. |
src | The pointer of source scatter-gather entry array. |
dst | The pointer of destination scatter-gather entry array. |
nb_src | The number of source scatter-gather entry. |
nb_dst | The number of destination scatter-gather entry. |
flags | An flags for this operation. |
Definition at line 905 of file rte_dmadev.h.
|
inlinestatic |
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.
dev_id | The identifier of the device. |
vchan | The identifier of virtual DMA channel. |
pattern | The pattern to populate the destination buffer with. |
dst | The address of the destination buffer. |
length | The length of the destination buffer. |
flags | An flags for this operation. |
Definition at line 954 of file rte_dmadev.h.
|
inlinestatic |
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().
dev_id | The identifier of the device. |
vchan | The identifier of virtual DMA channel. |
Definition at line 989 of file rte_dmadev.h.
|
inlinestatic |
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.
dev_id | The identifier of the device. | |
vchan | The identifier of virtual DMA channel. | |
nb_cpls | The maximum number of completed operations that can be processed. | |
[out] | last_idx | The last completed operation's ring_idx. If not required, NULL can be passed in. |
[out] | has_error | Indicates if there are transfer error. If not required, NULL can be passed in. |
Definition at line 1030 of file rte_dmadev.h.
|
inlinestatic |
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.
dev_id | The identifier of the device. | |
vchan | The identifier of virtual DMA channel. | |
nb_cpls | Indicates the size of status array. | |
[out] | last_idx | The last completed operation's ring_idx. If not required, NULL can be passed in. |
[out] | status | This is a pointer to an array of length 'nb_cpls' that holds the completion status code of each operation. |
Definition at line 1093 of file rte_dmadev.h.
|
inlinestatic |
Check remaining capacity in descriptor ring for the current burst.
dev_id | The identifier of the device. |
vchan | The identifier of virtual DMA channel. |
Definition at line 1131 of file rte_dmadev.h.