--- name: "rte_dma_vchan_status" section: "3" platform: "linux" package: "dpdk-doc" version: "24.11.4-0+deb13u1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/rte_dmadev.h" --- # rte\_dma\_vchan\_status(3) Part of [rte\_dmadev.h(3)](/rte_dmadev.h/3.md). ## NAME rte\_dmadev.h ## SYNOPSIS `#include `\ `#include `\ `#include `\ `#include `\ `#include 'rte_dmadev_core.h'`\ `#include 'rte_dmadev_trace_fp.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)](/RTE_BIT64/3.md)\ \#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\_PRI\_POLICY\_SP** **RTE\_BIT64**(8)\ \#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)](/RTE_BIT64/3.md)\ ### 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 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 **158** of file **rte\_dmadev.h**. ### #define RTE\_DMA\_FOREACH\_DEV(p) **Value:**.PP ``` 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 **217** of file **rte\_dmadev.h**. ### #define RTE\_DMA\_CAPA\_MEM\_TO\_MEM RTE\_BIT64(0) Support memory-to-memory transfer Definition at line **227** of file **rte\_dmadev.h**. ### #define RTE\_DMA\_CAPA\_MEM\_TO\_DEV RTE\_BIT64(1) Support memory-to-device transfer. Definition at line **229** of file **rte\_dmadev.h**. ### #define RTE\_DMA\_CAPA\_DEV\_TO\_MEM RTE\_BIT64(2) Support device-to-memory transfer. Definition at line **231** of file **rte\_dmadev.h**. ### #define RTE\_DMA\_CAPA\_DEV\_TO\_DEV RTE\_BIT64(3) Support device-to-device transfer. Definition at line **233** 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 **240** 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 **246** 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 **254** 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 **261** of file **rte\_dmadev.h**. ### #define RTE\_DMA\_CAPA\_PRI\_POLICY\_SP RTE\_BIT64(8) Support strict priority scheduling. Application could assign fixed priority to the DMA device using 'priority' field in struct **rte\_dma\_conf**. Number of supported priority levels will be known from 'nb\_priorities' field in struct **rte\_dma\_info**. Definition at line **268** 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 **274** of file **rte\_dmadev.h**. ### #define RTE\_DMA\_CAPA\_OPS\_COPY\_SG RTE\_BIT64(33) Support scatter-gather list copy operation. Definition at line **276** of file **rte\_dmadev.h**. ### #define RTE\_DMA\_CAPA\_OPS\_FILL RTE\_BIT64(34) Support fill operation. Definition at line **278** 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 **644** 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 **817** 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 **822** 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 **827** 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 **834** of file **rte\_dmadev.h**. ## Enumeration Type Documentation ### enum 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* **420** *of file* **rte\_dmadev.h***.* ### enum 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* **460** *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* **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* **684** *of file* **rte\_dmadev.h***.* ### enum 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* **726** *of file* **rte\_dmadev.h***.* ## Function Documentation ### int rte\_dma\_dev\_max (size\_t dev\_max) *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\_max maximum number of dmadevs.* **Returns** *0 on success. Otherwise negative value is returned.* ### int rte\_dma\_get\_dev\_id\_by\_name (const char \* name) *Get the device identifier for the named DMA device.* **Parameters** *name DMA device name.* **Returns** *Returns DMA device identifier on success.* - • *\<0: Failure to find named DMA device.* ### bool rte\_dma\_is\_valid (int16\_t dev\_id) *Check whether the dev\_id is valid.* **Parameters** *dev\_id DMA device index.* **Returns** - • *If the device index is valid (true) or not (false).* ### uint16\_t rte\_dma\_count\_avail (void) *Get the total number of DMA devices that have been successfully initialised.* **Returns** *The total number of usable DMA devices.* ### int16\_t rte\_dma\_next\_dev (int16\_t start\_dev\_id) *Iterates over valid dmadev instances.* **Parameters** *start\_dev\_id The id of the next possible dmadev.* **Returns** *Next valid dmadev, UINT16\_MAX if there is none.* ### int rte\_dma\_info\_get (int16\_t dev\_id, struct rte\_dma\_info \* dev\_info) *Retrieve information of a DMA device.* **Parameters** *dev\_id The identifier of the device.* \ *dev\_info A 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.** ### 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.** **Parameters** *dev\_id* **The identifier of the device to configure.** \ *dev\_conf* **The DMA device configuration structure encapsulated into rte\_dma\_conf object.** **Returns** **0 on success. Otherwise negative value is returned.** ### 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.** **Parameters** *dev\_id* **The identifier of the device.** **Returns** **0 on success. Otherwise negative value is returned.** ### int rte\_dma\_stop (int16\_t dev\_id) **Stop a DMA device.** **The device can be restarted with a call to rte\_dma\_start().** **Parameters** *dev\_id* **The identifier of the device.** **Returns** **0 on success. Otherwise negative value is returned.** ### int rte\_dma\_close (int16\_t dev\_id) **Close a DMA device.** **The device cannot be restarted after this call.** **Parameters** *dev\_id* **The identifier of the device.** **Returns** **0 on success. Otherwise negative value is returned.** ### 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.** **Parameters** *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.** **Returns** **0 on success. Otherwise negative value is returned.** ### 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).** **Parameters** *dev\_id* **The identifier of the device.** \ *vchan* **The identifier of virtual DMA channel. If equal RTE\_DMA\_ALL\_VCHAN means all channels.** \ *stats* **The basic statistics structure encapsulated into rte\_dma\_stats object.** **Returns** **0 on success. Otherwise negative value is returned.** ### int rte\_dma\_stats\_reset (int16\_t dev\_id, uint16\_t vchan) **Reset basic statistics of a or all virtual DMA channel(s).** **Parameters** *dev\_id* **The identifier of the device.** \ *vchan* **The identifier of virtual DMA channel. If equal RTE\_DMA\_ALL\_VCHAN means all channels.** **Returns** **0 on success. Otherwise negative value is returned.** ### 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.** **Parameters** *dev\_id* **The identifier of the device.** \ *vchan* **The identifier of virtual DMA channel.** \ *status* **The vchan status** **Returns** **0 - call completed successfully \< 0 - error code indicating there was a problem calling the API** ### int rte\_dma\_dump (int16\_t dev\_id, FILE \* f) **Dump DMA device info.** **Parameters** *dev\_id* **The identifier of the device.** \ *f* **The file to write the output to.** **Returns** **0 on success. Otherwise negative value is returned.** ### 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)` [inline]`, ` [static]` **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\_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.** **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 864 of file rte\_dmadev.h.** ### 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)` [inline]`, ` [static]` **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\_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.** **See also** **struct rte\_dma\_info::max\_sges** **Parameters** *nb\_dst* **The number of destination scatter-gather entry.** **See also** **struct rte\_dma\_info::max\_sges** **Parameters** *flags* **An 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 914 of file rte\_dmadev.h.** ### 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)` [inline]`, ` [static]` **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\_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.** **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 964 of file rte\_dmadev.h.** ### static int rte\_dma\_submit (int16\_t dev\_id, uint16\_t vchan)` [inline]`, ` [static]` **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\_id* **The identifier of the device.** \ *vchan* **The identifier of virtual DMA channel.** **Returns** **0 on success. Otherwise negative value is returned.** **Definition at line 999 of file rte\_dmadev.h.** ### 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)` [inline]`, ` [static]` **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\_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.** \ *last\_idx* **The last completed operation's ring\_idx. If not required, NULL can be passed in.** \ *has\_error* **Indicates 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.** **Definition at line 1040 of file rte\_dmadev.h.** ### 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)` [inline]`, ` [static]` **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\_id* **The identifier of the device.** \ *vchan* **The identifier of virtual DMA channel.** \ *nb\_cpls* **Indicates the size of status array.** \ *last\_idx* **The last completed operation's ring\_idx. If not required, NULL can be passed in.** \ *status* **This 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 1103 of file rte\_dmadev.h.** ### static uint16\_t rte\_dma\_burst\_capacity (int16\_t dev\_id, uint16\_t vchan)` [inline]`, ` [static]` **Check remaining capacity in descriptor ring for the current burst.** **Parameters** *dev\_id* **The identifier of the device.** \ *vchan* **The identifier of virtual DMA channel.** **Returns** - • **Remaining space in the descriptor ring for the current burst.** - • **0 on error** **Definition at line 1141 of file rte\_dmadev.h.** ## Author **Generated automatically by Doxygen for DPDK from the source code.**