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) inCapabilities and modes
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 inSafety 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
- "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 inVersion compatibility,
which cross-links the canonical detection chain in
doca-version/SKILL.md, plus the
capability-query rule inCapabilities 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 inError taxonomy
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-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/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:
- the capabilities companion — 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).
- the tasks companion — 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/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/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/SKILL.md,
layered with the DMA-specific overrides inmodify.
- 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
- Read this skill first to confirm the user's question is
in scope.
- 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
the capabilities companion.
- For step-by-step workflows — configure, build, modify, run,
test, debug — see the tasks companion.
Both companion files cross-link to each other,
doca-version/SKILL.md for the canonical
version-handling rules, and
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/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/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/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/SKILL.md —
the bundle's structured-tools precedence rule (detect / prefer
/ fall back / report). The Command appendix in
the tasks companion honors this contract.
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/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/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/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.
1---2license: Apache-2.03name: doca-dma4description: >5 Use this skill when the user is doing hands-on DOCA DMA programming —6 bringing up a doca_dma context, configuring the single7 doca_dma_task_memcpy task type, sizing buffers via the8 doca_dma_cap_task_memcpy_* queries, setting LOCAL_READ_ONLY /9 LOCAL_READ_WRITE permissions on source / destination doca_mmap regions10 (plus doca_mmap_export_* for cross-peer copies), driving the progress11 engine, or debugging DOCA_ERROR_* returns. Trigger even when the user12 does not explicitly mention "DOCA DMA" or "doca_mmap" — typical13 implicit phrasings include "memcpy host buffer to BlueField without14 using the CPU", "offload a bulk copy to the DPU", "copy returns15 NOT_PERMITTED on first submit", "buffer too big for one DMA task",16 "task submitted but no completion", or "scatter-gather copy between17 two memory regions". Refuse and route elsewhere for cross-network18 copies (DOCA RDMA), producer/consumer messaging (DOCA Comch), DOCA19 Core / progress-engine internals, or DOCA install — those belong to20 other skills.21metadata:22 source: https://skillmd.com/skills/nvidia/doca-dma23 author: NVIDIA <doca-feedback@nvidia.com>24 kind: library25 doca_version: "3.5"26 tags:27 - doca28 - dma29 - memcpy30compatibility: >31 Requires DOCA SDK installed at /opt/mellanox/doca on Linux32 (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or33 ConnectX NIC attached. Reads the user's local install via34 `pkg-config doca-dma` and inspects35 /opt/mellanox/doca/{lib,include,samples,applications}.36 The validation steps require a live DOCA install.37---3839# DOCA DMA4041## Examples4243- **"Memcpy a host buffer to BlueField without using the CPU."** —44 this is in scope. Use the shipped DMA sample and `doca_dma_task_memcpy`.45- **"Copy returns NOT_PERMITTED on first submit."** — check mmap46 permissions and `doca_dma_cap_*` before changing the task type.4748## Instructions4950Follow Loading order below. Open the tasks companion for configure /51build / run. Open the capabilities companion for the memcpy task52and path-selection vs RDMA. Do not open every companion file.5354**Where to start:** This skill assumes DOCA is already installed55and the user is doing **hands-on DMA work** on a BlueField /56ConnectX / host with DOCA. Open the tasks companion if the user57wants to *do* something (configure / build / modify / run / test /58debug); open the capabilities companion when the question59is *what can DMA express* on this version. If the user has not60installed DOCA yet, route to61`doca-setup/SKILL.md` first. If the user is62not sure DMA is even the right library — the data has to traverse63the network, or the flow is small messages between two processes —64read the path-selection rule in65## Capabilities and modes66before configuring anything.6768## Example questions this skill answers well6970The CLASSES of DMA questions this skill is built to answer, each71with one worked example. The agent should treat the *class* as72the load-bearing piece — the worked example is a single instance.7374- **"How do I bring up a DOCA DMA context and copy a buffer75 between host and DPU?"** — worked example: *"copy a 64 KiB76 buffer from host memory to DPU memory in one task, starting from77 the shipped DMA Copy reference application"*. Answered by the78 lifecycle + memcpy-task workflow in79 ## configure +80 ## Capabilities and modes81 task-type table.82- **"How big a buffer can I memcpy in one task on this device?"** —83 worked example: *"can I copy 16 MiB in a single84 `doca_dma_task_memcpy`"*. Answered by the capability-query rule85 (`doca_dma_cap_task_memcpy_get_max_buf_size`, plus86 `_get_max_buf_list_len` for scatter-gather) in87 ## Capabilities and modes88 + the discovery step in89 ## configure.90- **"What permissions do my source and destination mmaps need?"** —91 worked example: *"my memcpy task returns92 `DOCA_ERROR_NOT_PERMITTED` on the first submit"*. Answered by the93 source / destination permission matrix in94 ## Safety policy95 + the permission checklist in96 ## test.97- **"Should I use DOCA DMA or DOCA RDMA / Comch / a plain CPU98 memcpy for this copy?"** — worked example: *"I have a 1 MiB copy99 that has to go from a host process to a DPU process; do I want100 DMA or Comch fast-path"*. Answered by the *"when to use DMA"*101 vs *"when not to"* path-selection bullet in102 ## Capabilities and modes103 + the routing pointers in [`## Related skills`](#related-skills).104- **"Is DOCA DMA on my installed version, and is the memcpy task105 supported on my device?"** — worked example: *"is106 `doca_dma_task_memcpy` available on DOCA 2.6 against this107 ConnectX-6"*. Answered by the version-compatibility overlay in108 ## Version compatibility,109 which cross-links the canonical detection chain in110 `doca-version/SKILL.md`, plus the111 capability-query rule in112 ## Capabilities and modes.113- **"What does this `DOCA_ERROR_*` from a DMA call mean and which114 layer caused it?"** — worked example: *"`DOCA_ERROR_AGAIN` from115 `doca_task_submit` on a `doca_dma_task_memcpy`"*. Answered by116 the DMA overlay on the cross-library taxonomy in117 ## Error taxonomy118 + the layered ladder in119 ## debug that escalates to120 `doca-debug/SKILL.md`.121122## Audience123124This skill serves **external developers building applications125that consume the DOCA DMA library** — i.e., users whose code calls126`doca_dma_*` (directly in C/C++, or through FFI/bindings from127another language) to copy bytes between two `doca_mmap` regions128using the BlueField DMA engine instead of the host CPU. It is129*not* for NVIDIA developers contributing to DOCA DMA itself.130131**Language scope.** DOCA DMA ships as a C library with132`pkg-config` module name `doca-dma`. The shipped samples are133written in C. C and C++ consumers are the canonical case and the134worked examples in the tasks companion assume that path. Other-language135consumers (Rust, Go, Python, …) consume the same `*.so` through136FFI or language-specific bindings; the skill's contribution in137that case is to keep the lifecycle, capability-discovery,138permission, error-taxonomy, and path-selection guidance139language-neutral, and to route the agent to the public C ABI as140the authoritative surface that any wrapper will eventually call.141142## When to load this skill143144Load this skill when the user is doing hands-on DOCA DMA work,145in any language. Concretely:146147- Initializing a `doca_dma` context on a `doca_dev` and148 configuring the memcpy task type via149 `doca_dma_task_memcpy_set_conf` before `doca_ctx_start()`.150- Setting up the source and destination `doca_mmap` regions for151 a memcpy, including the per-side permission flags152 (`DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` on the source,153 `DOCA_ACCESS_FLAG_LOCAL_READ_WRITE` on the destination) and,154 for cross-peer copies, the `doca_mmap_export_*` step.155- Reading the device capability surface for DMA via the156 `doca_dma_cap_task_memcpy_*` query family157 (`_is_supported`, `_get_max_buf_size`,158 `_get_max_buf_list_len`) before sizing any buffer or assuming159 scatter-gather is available.160- Submitting `doca_dma_task_memcpy` tasks against a DOCA progress161 engine and reacting to per-task completion events.162- Choosing between DOCA DMA and an adjacent option (DOCA RDMA when163 the data has to cross the network, DOCA Comch fast-path for164 message-oriented producer/consumer flows, plain CPU memcpy when165 the copy is tiny and one-shot).166- Debugging a `DOCA_ERROR_*` returned from a DMA call (lifecycle167 vs. permission vs. capability vs. would-block) and the168 per-task completion status reported on the progress engine.169- Designing or extending non-C bindings (Rust, Go, Python, …)170 that wrap the DMA C ABI — for the lifecycle, permission, and171 capability rules the wrapper must honor.172173Do **not** load this skill for general DOCA orientation, install174of DOCA itself, or non-DMA library questions. For those, use175`doca-public-knowledge-map/SKILL.md`.176177## What this skill provides178179This is a **thin loader**. The body keeps only the orientation180needed to pick the right next file. The substantive DMA-specific181material lives in two companion files:182183- the capabilities companion — what DMA can express on this version: the184 single `doca_dma_task_memcpy` task type and its scatter-gather185 buffer-list shape, the capability-query surface186 (`doca_dma_cap_task_memcpy_*`), the DMA error taxonomy (mapped187 onto the cross-library `DOCA_ERROR_*` set), the observability188 surface (per-task completion events on the progress engine),189 the source / destination mmap permission policy, and the190 path-selection rule against the adjacent libraries191 (RDMA / Comch / CPU memcpy).192- the tasks companion — step-by-step workflows for the six in-scope DMA193 verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`.194 Plus a `Deferred task verbs` block that points out-of-scope195 questions at the right next skill.196197The skill assumes a host or BlueField where DOCA is already198installed at the standard location and the user has the199privileges their public install profile expects. It does not200cover installing DOCA — that path goes through201`doca-setup/SKILL.md`.202203## What this skill deliberately does not ship204205This skill is **agent guidance**, not a samples or templates206bundle. To keep the boundary clean, it deliberately does not207contain — and pull requests should not add:208209- **Pre-written DOCA DMA application source code, in any210 language.** The verified DMA source code is the shipped C211 samples at `/opt/mellanox/doca/samples/doca_dma/<name>/` and212 the DMA Copy reference application reachable via213 `doca-public-knowledge-map/SKILL.md`.214 The agent's job is to route the user to those files and215 prescribe a minimum-diff modification on them via the universal216 modify-a-sample workflow in217 `doca-programming-guide/SKILL.md`,218 layered with the DMA-specific overrides in219 ## modify.220- **Standalone build manifests** (`meson.build`, `CMakeLists.txt`,221 `Cargo.toml`, …) parked inside the skill. The agent constructs222 the build manifest *in the user's project directory* against223 the user's installed DOCA, where `pkg-config --modversion224 doca-dma` is the source of truth.225- **A `samples/`, `bindings/`, or `reference/` subtree** of any226 kind. A mock or incomplete artifact in this skill's tree, even227 one labeled "reference", is misleading: users will read it as228 buildable.229230## Loading order2312321. Read this skill first to confirm the user's question is233 in scope.2342. **For the DMA capability surface, the memcpy task type, the235 capability-query rule, the source / destination permission236 matrix, the error taxonomy, observability, and the237 path-selection rule against RDMA / Comch / CPU memcpy, see238 the capabilities companion.**2393. **For step-by-step workflows — configure, build, modify, run,240 test, debug — see the tasks companion.**241242Both companion files cross-link to each other,243`doca-version/SKILL.md` for the canonical244version-handling rules, and245`doca-public-knowledge-map/SKILL.md`246whenever the right answer is "look it up in the public docs or247the installed package layout" rather than "DMA-specific248guidance".249250## Related skills251252- `doca-public-knowledge-map/SKILL.md` —253 the routing table for every public DOCA documentation source254 and the on-disk layout of an installed DOCA package. The DMA255 URL is `https://docs.nvidia.com/doca/sdk/DOCA-DMA/index.html`;256 the canonical reference application is *DMA Copy*.257- `doca-setup/SKILL.md` — env preparation,258 install verification, and the *I have no install yet* path259 with the public NGC DOCA container. This skill assumes its260 preconditions are satisfied.261- `doca-version/SKILL.md` — canonical DOCA262 version-handling rules. This skill's `## Version263 compatibility` cross-links the four-way match rule + detection264 chain and adds at most one DMA-specific overlay rule.265- `doca-structured-tools-contract/SKILL.md` —266 the bundle's structured-tools precedence rule (detect / prefer267 / fall back / report). The Command appendix in268 the tasks companion honors this contract.269- `doca-programming-guide/SKILL.md` —270 general DOCA programming patterns shared by every library: the271 canonical `pkg-config` + meson build pattern, the universal272 modify-a-shipped-sample first-app workflow, the universal273 lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the274 program-side debug order. This skill layers DMA specifics on275 top.276- `doca-rdma/SKILL.md` — the right library when277 the copy has to traverse the network. This skill's278 path-selection rule routes to RDMA when DMA is *not* the279 answer.280- `doca-comch/SKILL.md` — the right library281 when the flow is producer / consumer messaging between a host282 and DPU process pair, rather than a raw mmap-to-mmap copy.283- `doca-debug/SKILL.md` — the cross-cutting284 debug ladder (install / version / build / link / runtime /285 program / driver). DMA-specific debug (lifecycle violations,286 permission mismatches, oversize-buffer rejections) overlays on287 top of that ladder.