/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:
  kind: library
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}.

DOCA DMA

**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 [`TASKS.md`](TASKS.md) if the user wants to *do* something (configure / build / modify / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can DMA express* on this version. If the user has not installed DOCA yet, route to [`doca-setup`](../../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.md ## Capabilities and modes`](CAPABILITIES.md#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 [`TASKS.md ## configure`](TASKS.md#configure) + [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the discovery step in

[`TASKS.md ## configure`](TASKS.md#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 [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the permission checklist in

[`TASKS.md ## test`](TASKS.md#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.md ## Capabilities and modes`](CAPABILITIES.md#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 [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which cross-links the canonical detection chain in [`doca-version`](../../doca-version/SKILL.md), plus the capability-query rule in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#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 [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)

• the layered ladder in

[`TASKS.md ## debug`](TASKS.md#debug) that escalates to [`doca-debug`](../../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 `TASKS.md` 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-taxonomy