/doca-dma

license: Apache-2.0
name: doca-dma
description: >
  Use this skill when the user is doing hands-on DOCA DMA programming —
  bringing up a doca_dma context, configuring the single
  doca_dma_task_memcpy task type, sizing buffers via the
  doca_dma_cap_task_memcpy_* queries, setting LOCAL_READ_ONLY /
  LOCAL_READ_WRITE permissions on source / destination doca_mmap regions
  (plus doca_mmap_export_* for cross-peer copies), driving the progress
  engine, or debugging DOCA_ERROR_* returns. Trigger even when the user
  does not explicitly mention "DOCA DMA" or "doca_mmap" — typical
  implicit phrasings include "memcpy host buffer to BlueField without
  using the CPU", "offload a bulk copy to the DPU", "copy returns
  NOT_PERMITTED on first submit", "buffer too big for one DMA task",
  "task submitted but no completion", or "scatter-gather copy between
  two memory regions". Refuse and route elsewhere for cross-network
  copies (DOCA RDMA), producer/consumer messaging (DOCA Comch), DOCA
  Core / progress-engine internals, or DOCA install — those belong to
  other skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - dma
    - memcpy
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux
  (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or
  ConnectX NIC attached. Reads the user's local install via
  `pkg-config doca-dma` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.
  The validation steps require a live DOCA install.

DOCA DMA

Examples

• **"Memcpy a host buffer to BlueField without using the CPU."** —

this is in scope. Use the shipped DMA sample and `doca_dma_task_memcpy`.

• **"Copy returns NOT_PERMITTED on first submit."** — check mmap

permissions and `doca_dma_cap_*` before changing the task type.

Instructions

Follow Loading order below. Open the tasks companion for configure / build / run. Open the capabilities companion for the memcpy task and path-selection vs RDMA. Do not open every companion file.

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on DMA work** on a BlueField / ConnectX / host with DOCA. Open the tasks companion if the user wants to *do* something (configure / build / modify / run / test / debug); open the capabilities companion when the question is *what can DMA express* on this version. If the user has not installed DOCA yet, route to `doca-setup/SKILL.md` first. If the user is not sure DMA is even the right library — the data has to traverse the network, or the flow is small messages between two processes — read the path-selection rule in

Capabilities and modes

before configuring anything.

Example questions this skill answers well

The CLASSES of DMA questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance.

• **"How do I bring up a DOCA DMA context and copy a buffer

between host and DPU?"** — worked example: *"copy a 64 KiB buffer from host memory to DPU memory in one task, starting from the shipped DMA Copy reference application"*. Answered by the lifecycle + memcpy-task workflow in

configure +

Capabilities and modes

task-type table.

• **"How big a buffer can I memcpy in one task on this device?"** —

worked example: *"can I copy 16 MiB in a single `doca_dma_task_memcpy`"*. Answered by the capability-query rule (`doca_dma_cap_task_memcpy_get_max_buf_size`, plus `_get_max_buf_list_len` for scatter-gather) in

Capabilities and modes

• the discovery step in

configure.

• **"What permissions do my source and destination mmaps need?"** —

worked example: *"my memcpy task returns `DOCA_ERROR_NOT_PERMITTED` on the first submit"*. Answered by the source / destination permission matrix in

Safety policy

• the permission checklist in

test.

• **"Should I use DOCA DMA or DOCA RDMA / Comch / a plain CPU

memcpy for this copy?"** — worked example: *"I have a 1 MiB copy that has to go from a host process to a DPU process; do I want DMA or Comch fast-path"*. Answered by the *"when to use DMA"* vs *"when not to"* path-selection bullet in

Capabilities and modes

• the routing pointers in [`## Related skills`](#related-skills).
• **"Is DOCA DMA on my installed version, and is the memcpy task

supported on my device?"** — worked example: *"is `doca_dma_task_memcpy` available on DOCA 2.6 against this ConnectX-6"*. Answered by the version-compatibility overlay in

Version compatibility,

which cross-links the canonical detection chain in `doca-version/SKILL.md`, plus the capability-query rule in

Capabilities and modes.

• **"What does this `DOCA_ERROR_*` from a DMA call mean and which

layer caused it?"** — worked example: *"`DOCA_ERROR_AGAIN` from `doca_task_submit` on a `doca_dma_task_memcpy`"*. Answered by the DMA overlay on the cross-library taxonomy in

Error taxonomy

• the layered ladder in

debug that escalates to

`doca-debug/SKILL.md`.

Audience

This skill serves **external developers building applications that consume the DOCA DMA library** — i.e., users whose code calls `doca_dma_*` (directly in C/C++, or through FFI/bindings from another language) to copy bytes between two `doca_mmap` regions using the BlueField DMA engine instead of the host CPU. It is *not* for NVIDIA developers contributing to DOCA DMA itself.

**Language scope.** DOCA DMA ships as a C library with `pkg-config` module name `doca-dma`. The shipped samples are written in C. C and C++ consumers are the canonical case and the worked examples in the tasks companion assume that path. Other-language consumers (Rust, Go, Python, …) consume the same `*.so` through FFI or language-specific bindings; the skill's contribution in that case is to keep the lifecycle, capability-discovery, permission, error-