rte_dmadev.h(3)

📦
version 25.11.3 · 5 versions
, in ubuntu resolute, ubuntu stonking

💖 rte_dmadev.h — Library Functions Manual 💖

okay bestie, sit down, hydrate, because this is the manual page for rte_dmadev.h from the DPDK crew — it's the DMA device header, aka where all the DMA API lives — and it is long. We're doing it section by section, no skipping, no vibes-based summarising. every single flag, every single struct, every single number stays in. ✨

🌸 NAME 🌸

rte_dmadev.h — that's the whole name, that's it, that's the girl 💅

🦋 SYNOPSIS 🦋

First, the invites — you gotta #include these or nothing works:

#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'
lowkey important: the last two are included with single quotes, not angle brackets, and not double quotes. That's how the original rolls. Do not "fix" it, iykyk. 🙈

🍓 Data Structures 🍓

these are the lil guys you'll be passing around:

  • 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

nine of them. count them. we love a coherent struct family 👑

🎀 Macros 🎀

the preprocessor girlies, in order:

  • #define RTE_DMADEV_DEFAULT_MAX 64 — the default max is literally 64
  • #define RTE_DMA_FOREACH_DEV(p) — a function-like macro that takes exactly one thing: p
  • #define RTE_DMA_CFG_FLAG_SILENT RTE_BIT64(0) — bit 0
  • #define RTE_DMA_CFG_FLAG_ENQ_DEQ RTE_BIT64(1) — bit 1
  • #define RTE_DMA_ALL_VCHAN 0xFFFFu — the value is 0xFFFFu, all the vchans, no cap

✨ DMA capability ✨

See also: struct rte_dma_info::dev_capa — go read that field, it's the matching lore.

  • #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)
notice bestie: the bits jump from 10 straight to 32. that's not a typo, that's the actual numbering. respect the gap 💅

🌈 DMA operation flag 🌈

See also these three function girlies, they're the ones who care about these flags:

  • rte_dma_copy()
  • rte_dma_copy_sg()
  • rte_dma_fill()

and the flags themselves:

  • #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 💜

one (1) typedef and she's a whole callback:

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)

she takes a dev_id, a group_id, a domain_id (a rte_uuid_t, fancy), and an event from that enum. returns void. she's a callback, she doesn't owe you a return value 🫶

⭐ Enumerations ⭐

the full roster, in order:

  • enum rte_dma_direction with members: 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 — and bestie. she is empty. { }. literally nothing inside. iconic in a haunted way 💀
  • enum rte_dma_inter_domain_type with members: RTE_DMA_INTER_DOMAIN_NONE, RTE_DMA_INTER_PROCESS_DOMAIN, RTE_DMA_INTER_OS_DOMAIN
  • enum rte_dma_vchan_status with members: RTE_DMA_VCHAN_IDLE, RTE_DMA_VCHAN_ACTIVE, RTE_DMA_VCHAN_HALTED_ERROR
  • enum rte_dma_access_pair_group_event_type with members: RTE_DMA_GROUP_EVENT_MEMBER_LEFT, RTE_DMA_GROUP_EVENT_GROUP_DESTROYED
  • enum rte_dma_status_code with members: 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
do not touch, do not auto-correct: RTE_DMA_STATUS_DATA_POISION is spelled exactly like that in the source. poision. leave her alone, she's thriving 😭

🔥 Functions 🔥

here comes the main event, bestie. every single one, exactly as written:

  • 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)
tiny detail worth clocking: the access_pair_group_* girls are all tagged __rte_experimental, and the copy / copy_sg / fill / submit / completed / completed_status / burst_capacity / enqueue_ops / dequeue_ops crew are all static. that's not decoration, that's the actual signature. keep it ✨

and there's SO much more to come, bestie — this is just the table of contents energy, the real lore drops next 🧚

🌸 Detailed Description 🌸

okay so bestie, the DMA (Direct Memory Access) device API is built on this whole 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), and each HW-DMA-channel should be represented by a dmadev. no cap.

The dmadev could create multiple virtual DMA channels, and each virtual DMA channel represents a different transfer context. The DMA operation request must be submitted to the virtual DMA channel. e.g. an 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. it's giving ✨context separation✨.

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. periodt.

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. lowkey important bestie, do not skip the stop.

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. iykyk.

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 ✨

Okay bestie, this is the macro section, and it's giving "reference table but make it fashion" 💅 Every single macro below is in rte_dmadev.h, and I'm keeping all the line numbers because we don't do missing receipts in this house. No cap.

#define RTE_DMADEV_DEFAULT_MAX 64

The maximum number of devices if rte_dma_dev_max() is not called. If that function never gets called, this is your limit, periodt.

📌 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. It's the "go through every single one, no skip" loop 💫

📌 Definition at line 218 of file rte_dmadev.h.

#define RTE_DMA_CAPA_MEM_TO_MEM RTE_BIT64(0)

Support memory-to-memory transfer. Mem to mem, the blueprint.

📌 Definition at line 228 of file rte_dmadev.h.

#define RTE_DMA_CAPA_MEM_TO_DEV RTE_BIT64(1)

Support memory-to-device transfer. Mem to dev, we love a directional slay.

📌 Definition at line 230 of file rte_dmadev.h.

#define RTE_DMA_CAPA_DEV_TO_MEM RTE_BIT64(2)

Support device-to-memory transfer. Dev to mem, the reverse iconique.

📌 Definition at line 232 of file rte_dmadev.h.

#define RTE_DMA_CAPA_DEV_TO_DEV RTE_BIT64(3)

Support device-to-device transfer. Dev to dev, no middleman.

📌 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(). So like, SVA = VA-friendly, no SVA = stick to IOVA from those allocators.

📌 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. Yes, the * is doing its thing — rte_dma_completed*().

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. So if this bit is missing, bestie, you better triple-check those addresses 😭

📌 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. Priority drama, but make it hardware.

📌 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. Crossing process boundaries like it's nothing.

📌 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. OS to OS, the ultimate long-distance relationship.

📌 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. The gap is intentional, don't come for it.

📌 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. SG copy, we stan a list that scatters and gathers.

📌 Definition at line 289 of file rte_dmadev.h.

#define RTE_DMA_CAPA_OPS_FILL RTE_BIT64(34)

Support fill operation. Fill it up, bestie.

📌 Definition at line 291 of file rte_dmadev.h.

#define RTE_DMA_CAPA_OPS_ENQ_DEQ RTE_BIT64(35)

Support enqueue and dequeue operations. Enqueue, dequeue, repeat.

📌 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. It's the "all of them" ID.

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. So like, respect the queue order or this flag is just chillin'.

📌 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. Ring that doorbell 🔔

📌 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. It's giving "just a suggestion, not a contract."

📌 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. Clean up after yourself, periodt.

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)

Wait, the typedef signature in the original wraps, so here it is exactly as it appears:

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. Basically: which way is the data going, bestie? 🦋

See also: struct rte_dma_vchan_conf::direction

Enumerator

  • RTE_DMA_DIR_MEM_TO_MEM — DMA transfer direction, memory ➡️ memory. When the device supports inter-process or inter-OS domain transfers, the type field in struct rte_dma_vchan_conf::domain tells you what kind of domain it is. 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

  • RTE_DMA_DIR_MEM_TO_DEV — DMA transfer direction, memory ➡️ device. Typical scenario iykyk: the SoCs are installed on host servers as iNICs through the PCIe interface. In this case the SoCs works in EP (endpoint) mode, and 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, device ➡️ memory. Same typical scenario: SoCs installed on host servers as iNICs through the PCIe interface, SoCs in EP (endpoint) mode, and 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, device ➡️ device. Again the classic setup: SoCs on host servers as iNICs through the PCIe interface, SoCs in EP (endpoint) mode, initiating a DMA move request from device (which is host memory) to the device (which is another host memory). no cap 🫶

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. Just letting you know what kind of port we're on 💅

See also: struct rte_dma_port_param::port_type

Enumerator

  • RTE_DMA_PORT_PCIE — The DMA access port is PCIe. periodt ✨

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. lowkey unstable bestie, don't get attached 😭

This enum defines the types of transfer domains applicable to DMA operations. It helps categorize whether a DMA transfer is happening within the same domain, across different processes, or between distinct operating system domains. vibe check for your transfers 🌈

See also: struct rte_dma_inter_domain_param:type

Enumerator

  • RTE_DMA_INTER_DOMAIN_NONE — No inter-domain transfer; standard DMA within same domain. 💖
  • RTE_DMA_INTER_PROCESS_DOMAIN — Transfer occurs between different user-space processes. 👑
  • RTE_DMA_INTER_OS_DOMAIN — 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. It's giving "how's your channel doing today" energy 💀

See also: rte_dma_vchan_status

Enumerator

  • RTE_DMA_VCHAN_IDLE — not processing, awaiting ops. just chilling 🧘
  • RTE_DMA_VCHAN_ACTIVE — currently processing jobs. booked and busy 🔥
  • RTE_DMA_VCHAN_HALTED_ERROR — not processing due to error, cannot accept new ops. it's over bestie 😭

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. fr fr, that handler is gone gone 👋

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. the whole squad left, do not call them back 💀

Enumerator

  • RTE_DMA_GROUP_EVENT_MEMBER_LEFT — A member left the group (notifies creator and joiners). 💔
  • RTE_DMA_GROUP_EVENT_GROUP_DESTROYED — 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. The receipts of your transfer, basically 💅

See also: rte_dma_completed_status

Enumerator

  • RTE_DMA_STATUS_SUCCESSFUL — The operation completed successfully. slay! 🎉
  • 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. graceful exit energy ✨
  • 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. mysterious ✨
  • 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. main character mystery 🤷‍♀️

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. name lookup bestie 🔍

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. the headcount 💁‍♀️

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. gossip time 🗣️

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. not optional bestie, do this first 💅

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. green light, let's go 🚦

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(). it's not a forever goodbye 🥺

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. this one is a forever goodbye 💀

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. building your lil channel home 🏡✨

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).

Okay so back to the stats-getter, bestie — here's what you gotta hand it:

  • dev_id — the identifier of the device.
  • vchan — the identifier of virtual DMA channel. If it's equal to RTE_DMA_ALL_VCHAN, that means all the channels 💫
  • stats — the basic statistics structure encapsulated into rte_dma_stats object.

It hands back 0 on success. Otherwise a negative value is returned. That's the whole vibe check. ✨

int rte_dma_stats_reset(int16_t dev_id, uint16_t vchan)

Reset the basic statistics of a virtual DMA channel — or of literally all of them, your call. 🧹

Parameters

  • dev_id — the identifier of the device.
  • vchan — the identifier of virtual DMA channel. If it's equal to RTE_DMA_ALL_VCHAN, that means all the channels.

Returns

0 on success. Otherwise negative value is returned. no cap.

int rte_dma_vchan_status(int16_t dev_id, uint16_t vchan, enum rte_dma_vchan_status *status)

Figure out if all the jobs on a device channel have completed. 🎀

Real talk: this function is primarily designed for testing use, because it lets a process check whether every job is done without actually gathering completions from those jobs. Sneaky but iconic. 💅

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 the 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 so you can do secure DMA transfers between devices across different processes or operating system domains. It's giving ✨trust but verify✨.

⚠️ WARNING: EXPERIMENTAL: this API may change without prior notice. (bestie, it could get a glow-up at literally any moment 💀)

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 — but only if all the participating devices have exited. The group leaves the chat only when everyone's gone. 👋

⚠️ WARNING: EXPERIMENTAL: this API may change without prior notice.

Important: this operation is only permitted by the device that originally created the group. Attempts by other devices will result in failure. So don't try it, it's not your group, main character. 🙈

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 so you can do secure DMA transfers between devices across different processes or OS domains. It's the group chat invite we've all been waiting for 🫶.

⚠️ 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: this removes the device's entry from the group table and disables inter-domain DMA transfers to and from this device. Basically soft-blocking yourself from the inter-domain server. 🚪

⚠️ WARNING: EXPERIMENTAL: this API may change without prior notice.

Heads up: this operation is not permitted for the device that originally created the group. You made it, you're stuck with it. 👑

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)

Grab the handler associated with a specific domain ID. The application uses it to query the source or destination handler and then kick off 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] — yes she's both, she contains multitudes 💅

Enqueue a copy operation onto the virtual DMA channel. 💖

Here's the tea: this queues up a copy operation to be performed by hardware. If the flags parameter contains RTE_DMA_OP_FLAG_SUBMIT then it triggers the doorbell to begin this operation — otherwise it does not trigger the doorbell. No doorbell, no party. 🔔

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. We're not doing one buffer, we're doing a whole ✨collection✨. 🦋

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 it triggers the doorbell to begin this operation, otherwise it does not trigger the 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
  • nb_dst — the number of destination scatter-gather entry.
    • See also: struct rte_dma_info::max_sges
  • 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 — paint the destination with your pattern, periodt. 🎨

This queues up a fill operation to be performed by hardware. If the flags parameter contains RTE_DMA_OP_FLAG_SUBMIT then it triggers the doorbell to begin this operation, otherwise it does not trigger the 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 the hardware to begin performing enqueued operations. 🔔✨

It writes the "doorbell" to the hardware to trigger it to begin the operations you previously enqueued with rte_dma_copy/fill(). Ring ring, bestie, work time.

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 completed successfully, starting from the current ring position. 🏁

This function reports a contiguous run of successfully completed operations. It stops at the very first operation that either failed or hasn't completed yet. And once an operation is reported as successfully completed, the results of that operation are visible to all cores on the system. Iconic cross-core transparency, we love to see it. 👑

Parameters

  • dev_id — the identifier of the device.
  • vchan — the identifier of the virtual DMA channel.
  • nb_cpls — the maximum number of completed operations to report.
  • last_idx — the ring_idx of the last successfully completed operation reported by this call. The function stops at the first failed or incomplete operation, and reports at most nb_cpls operations, so this may not be the last successful operation the device has actually completed. If you don't need it, NULL can be passed in.
  • has_error — when set to true, a failed operation was encountered among the completed operations on the device (within the nb_cpls limit), which caused the function to stop early. The returned count covers only the successful completions preceding that first failure. When false, all operations reported by this call succeeded; the function stopped either because nb_cpls operations have been reported, or because no more completed operations are available on the device. If you don't need it, NULL can be passed in.

Returns

The number of operations that successfully completed. This return value is less than or equal to the value of nb_cpls.

Definition at line 1367 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 completed (successfully or with error), starting from the current ring position. 💀✅

Okay so this one reports ALL the completed ops up to nb_cpls, no cap, and it does not care whether each individual operation ate or flopped — completed is completed. And once an op has been reported as completed successfully, bestie, its results are visible to every core on the system. That's the whole point of the handoff. 💅

Parameters

  • dev_id — the identifier of the device. 🎀
  • vchan — the identifier of the virtual DMA channel.
  • nb_cpls — the size of the status array, i.e. the max number of completed operations you wanna get reported back.
  • last_idx — the ring_idx of the last completed operation reported by this call, whether it slayed or flopped. The function reports up to nb_cpls completed operations without stopping on errors, so heads up: this may not be the last operation the device has actually completed. Not needed? Pass in NULL and move on. 💖
  • status — pointer to an array of length nb_cpls that receives the completion status code of each reported operation.

See also

enum rte_dma_status_code ✨

Returns

The number of operations that completed. This return value is less than or equal to the value of nb_cpls. If this number is n (n > 0), the first n entries in the status array are valid. So like… only read the first n, okay? The rest is giving nothing. 🙈

Definition at line 1436 of file rte_dmadev.h.

uint16_t rte_dma_burst_capacity (int16_t dev_id, uint16_t vchan) [inline], [static]

Vibe check on the descriptor ring 💅 — how much room is left 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 1473 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 the DMA device — but NGL, this one only works if the underlying device supports RTE_DMA_CAPA_OPS_ENQ_DEQ and rte_dma_conf::enable_enq_deq is enabled in rte_dma_configure(). Both. No skipping steps. 🫶

The ops you enqueue get immediately submitted to the DMA device. And this is the important part: the enqueue has to be coupled with dequeue to retrieve the completed ops, so calls to rte_dma_submit(), rte_dma_completed() and rte_dma_completed_status() are not valid here. Different lane, different rules, periodt. 💀

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 1511 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 the completed rte_dma_ops that were submitted to the DMA device. Same deal as enqueue: this can only be used when the underlying device 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. Not more, bestie, never more. 😌

Definition at line 1546 of file rte_dmadev.h.

👑 Author 👑

Generated automatically by Doxygen for DPDK from the source code. Yes, the robot wrote it. It's still iconic. ✨

And that's a wrap on rte_dmadev.h(3) fr fr 🎀 this whole page came straight out of the DPDK source, Version 25.11.3, and the footer didn't hand over a date stamp this time — keeping it mysterious I guess 💜 Doxygen said what it said, and honestly? It ate. Go enqueue something. 🫶

📦 where this page comes from