Scroll to navigation

rte_dmadev.h(3) Library Functions Manual rte_dmadev.h(3)

NAME

rte_dmadev.h

SYNOPSIS

#include <stdint.h>
#include <errno.h>
#include <rte_bitops.h>
#include <rte_common.h>
#include <rte_uuid.h>
#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_inter_domain_param
struct rte_dma_vchan_conf
struct rte_dma_stats
struct rte_dma_sge
struct rte_dma_op

Macros


#define RTE_DMADEV_DEFAULT_MAX 64
#define RTE_DMA_FOREACH_DEV(p)
#define RTE_DMA_CFG_FLAG_SILENT RTE_BIT64(0)
#define RTE_DMA_CFG_FLAG_ENQ_DEQ RTE_BIT64(1)
#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_PRI_POLICY_SP RTE_BIT64(8)
#define RTE_DMA_CAPA_INTER_PROCESS_DOMAIN RTE_BIT64(9)
#define RTE_DMA_CAPA_INTER_OS_DOMAIN RTE_BIT64(10)
#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)
#define RTE_DMA_CAPA_OPS_ENQ_DEQ RTE_BIT64(35)


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)


Typedefs


typedef void(* rte_dma_access_pair_group_event_cb_t) (int16_t dev_id, int16_t group_id, rte_uuid_t domain_id, enum rte_dma_access_pair_group_event_type event)

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_inter_domain_type { RTE_DMA_INTER_DOMAIN_NONE, RTE_DMA_INTER_PROCESS_DOMAIN, RTE_DMA_INTER_OS_DOMAIN }
enum rte_dma_vchan_status { RTE_DMA_VCHAN_IDLE, RTE_DMA_VCHAN_ACTIVE, RTE_DMA_VCHAN_HALTED_ERROR }
enum rte_dma_access_pair_group_event_type { RTE_DMA_GROUP_EVENT_MEMBER_LEFT, RTE_DMA_GROUP_EVENT_GROUP_DESTROYED }
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)
__rte_experimental int rte_dma_access_pair_group_create (int16_t dev_id, rte_uuid_t domain_id, rte_uuid_t token, int16_t *group_id, rte_dma_access_pair_group_event_cb_t cb)
__rte_experimental int rte_dma_access_pair_group_destroy (int16_t dev_id, int16_t group_id)
__rte_experimental int rte_dma_access_pair_group_join (int16_t dev_id, rte_uuid_t domain_id, rte_uuid_t token, int16_t group_id, rte_dma_access_pair_group_event_cb_t cb)
__rte_experimental int rte_dma_access_pair_group_leave (int16_t dev_id, int16_t group_id)
__rte_experimental int rte_dma_access_pair_group_handler_get (int16_t dev_id, int16_t group_id, rte_uuid_t domain_id, uint16_t *handler)
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)
static uint16_t rte_dma_enqueue_ops (int16_t dev_id, uint16_t vchan, struct rte_dma_op **ops, uint16_t nb_ops)
static uint16_t rte_dma_dequeue_ops (int16_t dev_id, uint16_t vchan, struct rte_dma_op **ops, uint16_t nb_ops)

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 159 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 218 of file rte_dmadev.h.






#define RTE_DMA_CAPA_MEM_TO_MEM RTE_BIT64(0)


Support memory-to-memory transfer


Definition at line 228 of file rte_dmadev.h.






#define RTE_DMA_CAPA_MEM_TO_DEV RTE_BIT64(1)


Support memory-to-device transfer.


Definition at line 230 of file rte_dmadev.h.






#define RTE_DMA_CAPA_DEV_TO_MEM RTE_BIT64(2)


Support device-to-memory transfer.


Definition at line 232 of file rte_dmadev.h.






#define RTE_DMA_CAPA_DEV_TO_DEV RTE_BIT64(3)


Support device-to-device transfer.


Definition at line 234 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 241 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 247 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 255 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 262 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 269 of file rte_dmadev.h.






#define RTE_DMA_CAPA_INTER_PROCESS_DOMAIN RTE_BIT64(9)


Support inter-process DMA transfers.




When this bit is set, the DMA device can perform memory transfers
    between different process memory spaces.


Definition at line 275 of file rte_dmadev.h.






#define RTE_DMA_CAPA_INTER_OS_DOMAIN RTE_BIT64(10)


Support inter-OS domain DMA transfers.




The DMA device can perform memory transfers across different
    operating system domains.


Definition at line 281 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 287 of file rte_dmadev.h.






#define RTE_DMA_CAPA_OPS_COPY_SG RTE_BIT64(33)


Support scatter-gather list copy operation.


Definition at line 289 of file rte_dmadev.h.






#define RTE_DMA_CAPA_OPS_FILL RTE_BIT64(34)


Support fill operation.


Definition at line 291 of file rte_dmadev.h.






#define RTE_DMA_CAPA_OPS_ENQ_DEQ RTE_BIT64(35)


Support enqueue and dequeue operations.


Definition at line 293 of file rte_dmadev.h.






#define RTE_DMA_CFG_FLAG_SILENT RTE_BIT64(0)


DMA device configuration flags.


See also


struct rte_dma_conf::flags Operate in silent mode



RTE_DMA_CAPA_SILENT




Definition at line 302 of file rte_dmadev.h.






#define RTE_DMA_CFG_FLAG_ENQ_DEQ RTE_BIT64(1)


Enable enqueue and dequeue operations


See also


RTE_DMA_CAPA_OPS_ENQ_DEQ


Definition at line 306 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 733 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 1131 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 1136 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 1141 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 1148 of file rte_dmadev.h.








Typedef Documentation




typedef void(* rte_dma_access_pair_group_event_cb_t) (int16_t dev_id, int16_t group_id, rte_uuid_t domain_id, enum rte_dma_access_pair_group_event_type event)


This callback is used to notify interested parties (either the
    group creator or group joiners) about significant events related to the
    lifecycle of a DMA access pair group.




Warning


EXPERIMENTAL: this API may change without prior
  notice.


It can be registered by:


    
  
  • Group creators or group joiners to be notified when a member leaves
      the group.
    • 
  
  • Group joiners to be notified when the group is destroyed.
    • 



Parameters


dev_id Identifier of the DMA device.


group_id Identifier of the access pair group where the event occurred.


domain_id UUID of the domain_id associated with the event. For member
  leave events, this is the domain_id of the member that left. For group
  destruction events, this may refer to the domain_id of the respective member.


event Type of event that occurred.


See also


rte_dma_access_pair_group_event_type


Definition at line 856 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
  





  

  
DMA transfer direction - from memory to memory. When the device supports
      inter-process or inter-OS domain transfers, the field type in struct
      rte_dma_vchan_conf::domain specifies the type of domain. For
      memory-to-memory transfers within the same domain or process, type
      should be set to RTE_DMA_INTER_DOMAIN_NONE.
    

  




See also


struct rte_dma_vchan_conf::direction



struct rte_dma_inter_domain_param::type





  

  
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



  

  
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



  

  
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 441 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
  





  

  
The DMA access port is PCIe.




Definition at line 487 of file rte_dmadev.h.






enum rte_dma_inter_domain_type


Inter-DMA transfer domain type.




Warning


EXPERIMENTAL: this API may change without prior
  notice.


This enum defines the types of transfer domains applicable to DMA
    operations. It helps categorize whether a DMA transfer is occurring within
    the same domain, across different processes, or between distinct operating
    system domains.




See also


struct rte_dma_inter_domain_param:type


Enumerator
  





  

  
No inter-domain transfer; standard DMA within same domain.

  

  
Transfer occurs between different user-space processes.

  

  
Transfer spans across different operating system domains.




Definition at line 607 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
  





  

  
not processing, awaiting ops

  

  
currently processing jobs

  

  
not processing due to error, cannot accept new ops




Definition at line 773 of file rte_dmadev.h.






enum rte_dma_access_pair_group_event_type


Event types for DMA access pair group notifications.




Warning


EXPERIMENTAL: this API may change without prior
  notice.


When the event type is RTE_DMA_GROUP_EVENT_MEMBER_LEFT, the
    handler associated with the departing member's domain is no longer valid.
    Inter-domain DMA operations targeting that domain should be avoided.




When the event type is RTE_DMA_GROUP_EVENT_GROUP_DESTROYED, all
    handlers associated with the group become invalid. No further inter-domain
    DMA operations should be initiated using those handlers.


Enumerator
  





  

  
A member left the group (notifies creator and joiners).

  

  
Group was destroyed (notifies joiners).




Definition at line 824 of file rte_dmadev.h.






enum rte_dma_status_code


DMA transfer result status code defines.




See also


rte_dma_completed_status


Enumerator
  





  

  
The operation completed successfully.

  

  
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.

  

  
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.

  

  
The operation failed to complete due invalid source address.

  

  
The operation failed to complete due invalid destination address.

  

  
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.

  

  
The operation failed to complete due invalid length.

  

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

  

  
The operation failed to complete due bus read error.

  

  
The operation failed to complete due bus write error.

  

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

  

  
The operation failed to complete due data poison.

  

  
The operation failed to complete due descriptor read 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.

  

  
The operation failed to complete due lookup page fault.

  

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




Definition at line 983 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.






__rte_experimental int rte_dma_access_pair_group_create (int16_t dev_id, rte_uuid_t domain_id, rte_uuid_t token, int16_t * group_id, rte_dma_access_pair_group_event_cb_t cb)


Create an access pair group to enable secure DMA transfers between
    devices across different processes or operating system domains.




Warning


EXPERIMENTAL: this API may change without prior
  notice.


Parameters


dev_id Identifier of the DMA device initiating the
  group.


domain_id Unique identifier representing the current process or OS
  domain.


token Authentication token used to establish the access group.


group_id Pointer to store the ID of the newly created access group.


cb Callback function to be invoked when a member leaves the group.


Returns


0 on success, negative error code on failure.






__rte_experimental int rte_dma_access_pair_group_destroy (int16_t dev_id, int16_t group_id)


Destroy an access pair group if all participating devices have
    exited.




Warning


EXPERIMENTAL: this API may change without prior
  notice.


This operation is only permitted by the device that originally
    created the group; attempts by other devices will result in failure.




Parameters


dev_id Identifier of the device requesting group
  destruction.


group_id ID of the access group to be destroyed.


Returns


0 on success, negative value on failure indicating the
  error code.






__rte_experimental int rte_dma_access_pair_group_join (int16_t dev_id, rte_uuid_t domain_id, rte_uuid_t token, int16_t group_id, rte_dma_access_pair_group_event_cb_t cb)


Join an existing access group to enable secure DMA transfers
    between devices across different processes or OS domains.




Warning


EXPERIMENTAL: this API may change without prior
  notice.


Parameters


dev_id Identifier of the DMA device attempting to
  join the group.


domain_id Unique identifier representing the current process or OS
  domain.


token Authentication token used to validate group membership.


group_id ID of the access group to join.


cb Callback function to be invoked when the device leaves the group or
  when the group is destroyed due to some exception or failure.


Returns


0 on success, negative value on failure indicating the
  error code.






__rte_experimental int rte_dma_access_pair_group_leave (int16_t dev_id, int16_t group_id)


Leave an access group, removing the device's entry from the group
    table and disabling inter-domain DMA transfers to and from this device.




Warning


EXPERIMENTAL: this API may change without prior
  notice.


This operation is not permitted for the device that originally
    created the group.




Parameters


dev_id Identifier of the device requesting to
  leave the group.


group_id ID of the access group to leave.


Returns


0 on success, negative value on failure indicating the
  error code.






__rte_experimental int rte_dma_access_pair_group_handler_get (int16_t dev_id, int16_t group_id, rte_uuid_t domain_id, uint16_t * handler)


Retrieve the handler associated with a specific domain ID, which
    is used by the application to query source or destinationin handler to
    initiate inter-process or inter-OS DMA transfers.




Warning


EXPERIMENTAL: this API may change without prior
  notice.


Parameters


dev_id Identifier of the DMA device requesting the
  handler.


group_id ID of the access group to query.


domain_id Unique identifier of the target process or OS domain.


handler Pointer to store the retrieved handler value.


Returns


0 on success, negative value on failure indicating the
  error code.






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






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






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






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






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






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






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






uint16_t rte_dma_enqueue_ops (int16_t dev_id, uint16_t vchan, struct rte_dma_op ** ops, uint16_t nb_ops) [inline], [static]


Enqueue rte_dma_ops to DMA device, can only be used underlying
    supports RTE_DMA_CAPA_OPS_ENQ_DEQ and rte_dma_conf::enable_enq_deq is
    enabled in rte_dma_configure(). The ops enqueued will be immediately
    submitted to the DMA device. The enqueue should be coupled with dequeue to
    retrieve completed ops, calls to rte_dma_submit(),
    rte_dma_completed() and rte_dma_completed_status() are not
    valid.




Parameters


dev_id The identifier of the device.


vchan The identifier of virtual DMA channel.


ops Pointer to rte_dma_op array.


nb_ops Number of rte_dma_op in the ops array


Returns


uint16_t Number of successfully submitted ops.


Definition at line 1489 of file rte_dmadev.h.






uint16_t rte_dma_dequeue_ops (int16_t dev_id, uint16_t vchan, struct rte_dma_op ** ops, uint16_t nb_ops) [inline], [static]


Dequeue completed rte_dma_ops submitted to the DMA device, can
    only be used underlying supports RTE_DMA_CAPA_OPS_ENQ_DEQ and
    rte_dma_conf::enable_enq_deq is enabled in rte_dma_configure().




Parameters


dev_id The identifier of the device.


vchan The identifier of virtual DMA channel.


ops Pointer to rte_dma_op array.


nb_ops Size of rte_dma_op array.


Returns


Number of successfully completed ops. Should be less or
  equal to nb_ops.


Definition at line 1524 of file rte_dmadev.h.








Author


Generated automatically by Doxygen for DPDK from the source
  code.







  

    Version 25.11.0
    DPDK