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, and path-selection guidance
language-neutral, and to route the agent to the public C ABI as
the authoritative surface that any wrapper will eventually call.

## When to load this skill

Load this skill when the user is doing hands-on DOCA DMA work,
in any language. Concretely:

- Initializing a `doca_dma` context on a `doca_dev` and
  configuring the memcpy task type via
  `doca_dma_task_memcpy_set_conf` before `doca_ctx_start()`.
- Setting up the source and destination `doca_mmap` regions for
  a memcpy, including the per-side permission flags
  (`DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` on the source,
  `DOCA_ACCESS_FLAG_LOCAL_READ_WRITE` on the destination) and,
  for cross-peer copies, the `doca_mmap_export_*` step.
- Reading the device capability surface for DMA via the
  `doca_dma_cap_task_memcpy_*` query family
  (`_is_supported`, `_get_max_buf_size`,
  `_get_max_buf_list_len`) before sizing any buffer or assuming
  scatter-gather is available.
- Submitting `doca_dma_task_memcpy` tasks against a DOCA progress
  engine and reacting to per-task completion events.
- Choosing between DOCA DMA and an adjacent option (DOCA RDMA when
  the data has to cross the network, DOCA Comch fast-path for
  message-oriented producer/consumer flows, plain CPU memcpy when
  the copy is tiny and one-shot).
- Debugging a `DOCA_ERROR_*` returned from a DMA call (lifecycle
  vs. permission vs. capability vs. would-block) and the
  per-task completion status reported on the progress engine.
- Designing or extending non-C bindings (Rust, Go, Python, …)
  that wrap the DMA C ABI — for the lifecycle, permission, and
  capability rules the wrapper must honor.

Do **not** load this skill for general DOCA orientation, install
of DOCA itself, or non-DMA library questions. For those, use
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md).

## What this skill provides

This is a **thin loader**. The body keeps only the orientation
needed to pick the right next file. The substantive DMA-specific
material lives in two companion files:

- `CAPABILITIES.md` — what DMA can express on this version: the
  single `doca_dma_task_memcpy` task type and its scatter-gather
  buffer-list shape, the capability-query surface
  (`doca_dma_cap_task_memcpy_*`), the DMA error taxonomy (mapped
  onto the cross-library `DOCA_ERROR_*` set), the observability
  surface (per-task completion events on the progress engine),
  the source / destination mmap permission policy, and the
  path-selection rule against the adjacent libraries
  (RDMA / Comch / CPU memcpy).
- `TASKS.md` — step-by-step workflows for the six in-scope DMA
  verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`.
  Plus a `Deferred task verbs` block that points out-of-scope
  questions at the right next skill.

The skill assumes a host or BlueField where DOCA is already
installed at the standard location and the user has the
privileges their public install profile expects. It does not
cover installing DOCA — that path goes through
[`doca-setup`](../../doca-setup/SKILL.md).

## What this skill deliberately does not ship

This skill is **agent guidance**, not a samples or templates
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:

- **Pre-written DOCA DMA application source code, in any
  language.** The verified DMA source code is the shipped C
  samples at `/opt/mellanox/doca/samples/doca_dma/<name>/` and
  the DMA Copy reference application reachable via
  [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md).
  The agent's job is to route the user to those files and
  prescribe a minimum-diff modification on them via the universal
  modify-a-sample workflow in
  [`doca-programming-guide`](../../doca-programming-guide/SKILL.md),
  layered with the DMA-specific overrides in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **Standalone build manifests** (`meson.build`, `CMakeLists.txt`,
  `Cargo.toml`, …) parked inside the skill. The agent constructs
  the build manifest *in the user's project directory* against
  the user's installed DOCA, where `pkg-config --modversion
  doca-dma` is the source of truth.
- **A `samples/`, `bindings/`, or `reference/` subtree** of any
  kind. A mock or incomplete artifact in this skill's tree, even
  one labeled "reference", is misleading: users will read it as
  buildable.

## Loading order

1. Read this `SKILL.md` first to confirm the user's question is
   in scope.
2. **For the DMA capability surface, the memcpy task type, the
   capability-query rule, the source / destination permission
   matrix, the error taxonomy, observability, and the
   path-selection rule against RDMA / Comch / CPU memcpy, see
   [CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify, run,
   test, debug — see [TASKS.md](TASKS.md).**

Both companion files cross-link to each other,
[`doca-version`](../../doca-version/SKILL.md) for the canonical
version-handling rules, and
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)
whenever the right answer is "look it up in the public docs or
the installed package layout" rather than "DMA-specific
guidance".

## Related skills

- [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) —
  the routing table for every public DOCA documentation source
  and the on-disk layout of an installed DOCA package. The DMA
  URL is `https://docs.nvidia.com/doca/sdk/DOCA-DMA/index.html`;
  the canonical reference application is *DMA Copy*.
- [`doca-setup`](../../doca-setup/SKILL.md) — env preparation,
  install verification, and the *I have no install yet* path
  with the public NGC DOCA container. This skill assumes its
  preconditions are satisfied.
- [`doca-version`](../../doca-version/SKILL.md) — canonical DOCA
  version-handling rules. This skill's `## Version
  compatibility` cross-links the four-way match rule + detection
  chain and adds at most one DMA-specific overlay rule.
- [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md) —
  the bundle's structured-tools precedence rule (detect / prefer
  / fall back / report). The Command appendix in
  [TASKS.md](TASKS.md) honors this contract.
- [`doca-programming-guide`](../../doca-programming-guide/SKILL.md) —
  general DOCA programming patterns shared by every library: the
  canonical `pkg-config` + meson build pattern, the universal
  modify-a-shipped-sample first-app workflow, the universal
  lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the
  program-side debug order. This skill layers DMA specifics on
  top.
- [`doca-rdma`](../doca-rdma/SKILL.md) — the right library when
  the copy has to traverse the network. This skill's
  path-selection rule routes to RDMA when DMA is *not* the
  answer.
- [`doca-comch`](../doca-comch/SKILL.md) — the right library
  when the flow is producer / consumer messaging between a host
  and DPU process pair, rather than a raw mmap-to-mmap copy.
- [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting
  debug ladder (install / version / build / link / runtime /
  program / driver). DMA-specific debug (lifecycle violations,
  permission mismatches, oversize-buffer rejections) overlays on
  top of that ladder.