Doca Dma
NVIDIAOfficialCreated by NVIDIA
- Skill
- Tool integration
- Software development
- Apache-2.0
- Medium risk
AutoGineer summary
Written by AutoGineer from the skill’s own files, not by the author
The doca-dma skill provides specialized support for developers building applications that utilize the DOCA DMA library. It focuses on offloading memory copy operations between host and DPU memory without CPU intervention. The skill covers the full lifecycle of DMA tasks, including context initialization, buffer sizing via capability queries, memory mapping permissions, and debugging common runtime errors. It is designed to integrate with existing DOCA installations and provides clear routing for scenarios better suited for other DOCA libraries like RDMA or Comch.
What it does
- Guides the configuration of doca_dma_task_memcpy tasks.
- Explains how to size buffers using doca_dma_cap_task_memcpy_* queries.
- Defines the required permission flags for source and destination doca_mmap regions.
- Assists in debugging DOCA_ERROR_* codes specific to DMA operations.
- Provides path-selection logic to distinguish between DMA, RDMA, and Comch use cases.
- Outlines the lifecycle management for DMA contexts and progress engine interaction.
When to use it
- When implementing bulk memory copies between host and DPU memory.
- When encountering permission errors like DOCA_ERROR_NOT_PERMITTED during DMA submission.
- When determining if a specific buffer size or scatter-gather operation is supported by the hardware.
- When troubleshooting task completion issues within the DOCA progress engine.
- When deciding whether to use DMA for a specific data transfer requirement.
Advantages
- Provides precise, library-specific guidance for DOCA DMA development.
- Includes clear decision-making criteria for choosing the correct DOCA library.
- Focuses on actionable workflows for configuration, testing, and debugging.
- Maintains a clean separation between DMA-specific logic and general DOCA knowledge.
- Ensures developers follow standard practices for capability discovery and error handling.
Usage examples
- “How do I copy a 64 KiB buffer from host memory to DPU memory using DOCA DMA?”
- The agent will guide you through initializing the DMA context, setting up the source and destination mmap regions with appropriate permissions, and configuring the memcpy task.
- “My DMA task is returning DOCA_ERROR_NOT_PERMITTED. What should I check?”
- The agent will direct you to verify the LOCAL_READ_ONLY and LOCAL_READ_WRITE flags on your source and destination mmap regions.
- “Can I perform a 16 MiB copy in a single DMA task?”
- The agent will explain how to use the doca_dma_cap_task_memcpy_get_max_buf_size query to check the hardware limits for your specific device.
- “Should I use DOCA DMA or RDMA for a 1 MiB transfer between host and DPU processes?”
- The agent will apply the path-selection rules to determine if DMA is appropriate or if the requirements necessitate using RDMA or Comch.
Install
Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/nvidia/doca-dma/downloadUnzip it into the cross-client skills folder of your project:
mkdir -p .agents/skills && unzip doca-dma.zip -d .agents/skills
Documentation by NVIDIA
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_lenfor scatter-gather) inCapabilities 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_PERMITTEDon 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
the routing pointers in
## Related skills.
"Is DOCA DMA on my installed version, and is the memcpy task supported on my device?" — worked example: "is
doca_dma_task_memcpyavailable 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_AGAINfromdoca_task_submiton adoca_dma_task_memcpy". Answered by the DMA overlay on the cross-library taxonomy inError 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-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_dmacontext on adoca_devand configuring the memcpy task type viadoca_dma_task_memcpy_set_confbeforedoca_ctx_start().Setting up the source and destination
doca_mmapregions for a memcpy, including the per-side permission flags (DOCA_ACCESS_FLAG_LOCAL_READ_ONLYon the source,DOCA_ACCESS_FLAG_LOCAL_READ_WRITEon the destination) and, for cross-peer copies, thedoca_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_memcpytasks 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_memcpytask 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-libraryDOCA_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 aDeferred task verbsblock 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 viadoca-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 indoca-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, wherepkg-config --modversion doca-dmais the source of truth.A
samples/,bindings/, orreference/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 ishttps://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 compatibilitycross-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 canonicalpkg-config+ meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-libraryDOCA_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.
Files
- ATTRIBUTION.mdAdded by AutoGineer882 B
- BENCHMARK.md9.7 KiB
- CAPABILITIES.md16.8 KiB
- LICENSELicence file added by AutoGineer11.2 KiB
- SKILL.md12.7 KiB
- SKILLCARD.yaml2.7 KiB
- TASKS.md23.1 KiB
- evals/evals.json2.9 KiB
- skill-card.md5.1 KiB
- skill.oms.sig5.1 KiB
CAPABILITIES.md
DOCA DMA capabilities, version overlay, errors, observability, safety
Where to start: Pick the H2 anchor that matches your question (task type / capability discovery / path selection / version / errors / observability / safety) and read that section end-to-end. The tables in each section are the load-bearing content; the prose around them is interpretation.
Read this file when the loader sent you here from
SKILL.md. For the how of executing each pattern (the
verbs configure / build / modify / run / test / debug), jump to
TASKS.md. For the canonical DOCA version-handling
rules that this skill layers a DMA overlay on top of, see
doca-version/SKILL.md.
Pattern overview
Every DMA question this skill teaches resolves into one of FIVE patterns. The patterns are CLASSES — they apply across every DMA release and every host / DPU / ConnectX combination, not just the worked examples shown.
| Pattern | When it applies (class shape) | Where the substance lives |
|---|---|---|
| 1. Decide DMA is the right library | The copy is between two doca_mmap regions on the same host or across a host ↔ DPU PCIe boundary; the data does NOT need to traverse the network and is NOT message-oriented producer/consumer | ## Capabilities and modes path-selection bullet |
| 2. Stand up the context | DOCA Core lifecycle: create → configure (memcpy task, properties) → start → submit memcpy tasks → progress → stop → destroy | TASKS.md ## configure |
| 3. Discover capabilities | doca_dma_cap_task_memcpy_is_supported, _get_max_buf_size, _get_max_buf_list_len against the active doca_devinfo BEFORE sizing buffers or assuming scatter-gather | ## Capabilities and modes capability-query rule + TASKS.md ## configure step 2 |
| 4. Honor permissions | Source mmap → DOCA_ACCESS_FLAG_LOCAL_READ_ONLY (and doca_mmap_export_* for cross-peer); destination mmap → DOCA_ACCESS_FLAG_LOCAL_READ_WRITE | ## Safety policy permission matrix + TASKS.md ## test |
| 5. Diagnose a DMA error | Map symptom (BAD_STATE, INVALID_VALUE, AGAIN, NOT_PERMITTED, NOT_SUPPORTED, DRIVER) to root cause without leaving the DMA layer prematurely | ## Error taxonomy + TASKS.md ## debug |
Two cross-cutting rules that apply to every pattern above:
Cap query before payload, every time. Do not size a buffer or assume scatter-gather is supported without first reading
doca_dma_cap_task_memcpy_get_max_buf_sizeand_get_max_buf_list_lenagainst the activedoca_devinfo. Quoting a number from memory is the most common hallucination failure mode for this library.Source / destination permission pair before submit, every time. The
DOCA_ACCESS_FLAG_LOCAL_READ_ONLY/DOCA_ACCESS_FLAG_LOCAL_READ_WRITEpair must be set on the matching mmap before the task is submitted. Skipping the permission set returnsDOCA_ERROR_NOT_PERMITTEDthat masquerades as a hardware bug.
Capabilities and modes
DOCA DMA is a DOCA Core Context. Every doca_dma instance
follows the universal cfg-create → cfg-set-* → init → start → use → stop → destroy lifecycle (see
doca-programming-guide CAPABILITIES.md ## Capabilities and modes (doca-programming-guide/CAPABILITIES.md#capabilities-and-modes)).
On top of that lifecycle, DMA layers a single task type and a
small capability-query family.
The single task type. DMA exposes ONE task type. The agent must not invent additional ones; the public surface is closed.
| Task type | Direction | Notes |
|---|---|---|
doca_dma_task_memcpy | one source doca_mmap region → one destination doca_mmap region, with a length in bytes | Asynchronous; completion arrives as an event on the DOCA progress engine. Both regions must be valid doca_mmaps with the matching permission flag set; for cross-peer copies the source region must be exported via the appropriate doca_mmap_export_* so the DMA engine on the other side can read from it. |
Capability discovery — the only rule. Before sizing any
buffer or assuming scatter-gather is supported, call the matching
doca_dma_cap_task_memcpy_* query against the active
doca_devinfo:
| Capability | Query | Why the agent must ask |
|---|---|---|
| Memcpy task supported on this device | doca_dma_cap_task_memcpy_is_supported(devinfo) | Some doca_dev entries do not advertise DMA at all; recommending the task without the probe is the silent-fail case |
| Maximum per-task buffer size | doca_dma_cap_task_memcpy_get_max_buf_size(devinfo) | Device-dependent; submitting a task whose source or destination buffer exceeds this returns DOCA_ERROR_INVALID_VALUE |
| Maximum scatter-gather buffer-list length | doca_dma_cap_task_memcpy_get_max_buf_list_len(devinfo) | Some devices cap the buffer-list at 1 (no scatter-gather); a multi-element list past the cap also returns DOCA_ERROR_INVALID_VALUE |
Path selection — DMA vs the adjacent libraries. DMA is for mmap-to-mmap copies through the BlueField DMA engine. It is not the answer for every copy; the agent must walk this rule before recommending DMA setup.
| Use DOCA DMA when … | Use a different library when … |
|---|---|
Bulk copy between two doca_mmap regions on the same host, between host and DPU memory, or between two DPU memory regions, where the goal is to free CPU cycles or hit lower latency than a CPU memcpy can provide | The data has to traverse the network — use doca-rdma/SKILL.md (its Read / Write task types are the cross-network analog of DMA's memcpy) |
The user already holds (or can register) the source and destination as doca_mmap regions and the copy length is large enough that DMA submit overhead is amortized | The data flow is producer / consumer message-oriented between a host process and a DPU process — use doca-comch/SKILL.md fast-path, whose producer / consumer surface is purpose-built for that pattern |
| The copy is part of a chain of accelerator offloads (DMA → SHA → AES-GCM → Compress) where keeping the bytes inside DOCA accelerator queues avoids extra CPU round-trips | The copy is tiny and one-shot (a few hundred bytes, executed once) — a CPU memcpy finishes faster than the DMA submit + completion-drain round-trip |
Configuration shape. Mandatory configurations before
doca_ctx_start(): enable the memcpy task via
doca_dma_task_memcpy_set_conf (with completion callbacks +
max-num-tasks); set permissions on the source and destination
doca_mmap regions to match the matrix in
## Safety policy. Optional configurations
(per-task user-data, completion-batch tuning) follow the standard
DOCA Core surface; defaults come from the library and the active
doca_devinfo.
Version compatibility
For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.
The DMA-specific overlay is:
Use the
doca_dma_cap_task_memcpy_*query family at runtime. Per the cross-cutting rule indoca-version CAPABILITIES.md ## Observability(doca-version/CAPABILITIES.md#observability), the cap-query is the runtime authority for "is the memcpy task supported on this device + this DOCA version, and how big a buffer can it move". The version-matrix is the promise; the cap query is the reality. Usepkg-config --modversion doca-dmaas the build-time anchor (perdoca-version TASKS.md ## configure(doca-version/TASKS.md#configure)) when the user asks which DMA features ship on this install.doca-dma.pcplusdoca-common.pcmust both matchdoca_caps --versionat the four-way-match check (perdoca-version CAPABILITIES.md ## Version compatibility(doca-version/CAPABILITIES.md#version-compatibility)). A common partial-install pattern after a DOCA upgrade is thatdoca-dma.pclingers from the previous release; route todoca-version TASKS.md ## debug(doca-version/TASKS.md#debug) ladder step 2 before any DMA-layer diagnosis.Headers in $(pkg-config --variable=includedir doca-common) win over public docs. Per the headers-win-over-docs rule in
doca-version/SKILL.md, if a public DMA doc page mentions adoca_dma_*symbol that is not in the installeddoca_dma.h, the headers describe what this install can call; the docs describe what some release shipped. The agent must quote the headers, not the docs URL, when the two disagree.
Error taxonomy
DMA-specific overlays on the cross-library DOCA_ERROR_*
taxonomy. The cross-library taxonomy itself lives in
doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy);
the rows below are the DMA surface meaning that the agent must
disambiguate before falling back to the cross-library response.
| Error | DMA context where it shows up | DMA-specific cause |
|---|---|---|
DOCA_ERROR_BAD_STATE | Any submit before doca_ctx_start() or after doca_ctx_stop(); destroying the source or destination doca_mmap before doca_ctx_destroy() | Lifecycle violation. Walk the call sequence against the lifecycle in doca-programming-guide CAPABILITIES.md ## Capabilities and modes (doca-programming-guide/CAPABILITIES.md#capabilities-and-modes); the most common case is releasing an mmap underneath a still-running context. |
DOCA_ERROR_INVALID_VALUE | doca_dma_task_memcpy_alloc_init with an oversized buffer or an oversized buffer-list | The length exceeds doca_dma_cap_task_memcpy_get_max_buf_size(devinfo), or the scatter-gather list exceeds _get_max_buf_list_len(devinfo). The fix is to fragment at the application layer; do not retry without re-reading the cap. |
DOCA_ERROR_AGAIN | doca_task_submit on the memcpy task | The DMA task queue is full. This is not a hardware error; the program must drain completions via doca_pe_progress() before re-submitting. Same as the cross-library "would-block, retry after progress" pattern. |
DOCA_ERROR_NOT_PERMITTED | First memcpy submit, or first cross-peer submit | The mmap permission flag is missing for the direction of access — source mmap missing DOCA_ACCESS_FLAG_LOCAL_READ_ONLY, destination missing DOCA_ACCESS_FLAG_LOCAL_READ_WRITE, or a cross-peer source not exported via doca_mmap_export_*. Re-walk the matrix in ## Safety policy. |
DOCA_ERROR_NOT_SUPPORTED | doca_dma_task_memcpy_set_conf or first submit | The active doca_devinfo does not advertise the memcpy task at all. Re-run doca_dma_cap_task_memcpy_is_supported(devinfo); if false, that is the answer — the user's device cannot offload this copy. |
DOCA_ERROR_DRIVER | Any submit / completion call | The layer below DOCA reported failure (driver / firmware). Before routing, capture the recent driver log (dmesg), trace-level DOCA output, and active-device listing (doca_caps --list-devs) using the commands in TASKS.md ## Command appendix, then route to env-class debug (doca-setup ## debug (doca-setup/TASKS.md#debug)) — the layer below DOCA is the suspect, not the DMA program. |
The agent's rule: never recommend a retry loop on
DOCA_ERROR_* without first identifying which of the rows above
is the cause. _AGAIN is the only one that wants a retry
(after doca_pe_progress()); the others want investigation, not
retry.
Observability
The DOCA Core progress engine (PE) is the single source of
observability for DMA: every memcpy task completion (success or
failure) arrives as an event on the PE. DMA does not maintain
external counters; completion events arrive on the PE, and the
program must repeatedly call doca_pe_progress() to pump them.
Three primary signals the agent should reach for:
Per-task completion events on the PE. Every submitted
doca_dma_task_memcpyproduces a completion event when it finishes (or errors). The completion carries thedoca_error_tif it failed; the agent must inspect the per-task completion, not thedoca_task_submit()return value alone.Capability snapshot at configure time. The output of every
doca_dma_cap_task_memcpy_*query is a snapshot of what the library said was possible before any task was submitted. Save it as the baseline; if a later submit returnsDOCA_ERROR_INVALID_VALUEor_NOT_SUPPORTEDthe diff against this snapshot is the bug.Lifecycle / state transitions. Trace-level DOCA logs (
DOCA_LOG_LEVEL=trace) show when the context moved fromINITtoSTARTINGtoRUNNING. A DMA submit that appears to silently disappear is almost always the context not being inRUNNINGat submit time.
For the cross-cutting observability primitives
(--sdk-log-level, the doca-<lib>-trace build flavor, the
DOCA_LOG_LEVEL env var) see
doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability).
For the install-tree observability (logger names, package
layout) defer to
doca-public-knowledge-map/SKILL.md.
Safety policy
Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in
doca-hardware-safetyCAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.
DMA's safety surface is mmap-permission-driven. The library moves bytes between two memory regions exposed to the BlueField DMA engine; an incorrect permission either silently fails the task or, worse, allows the engine to access memory the user did not intend to share with the engine.
The source / destination permission matrix the agent must walk for any new DMA setup:
| Region | Required permission flag | Cross-peer rule | Verifies via |
|---|---|---|---|
Source doca_mmap (local memcpy) | DOCA_ACCESS_FLAG_LOCAL_READ_ONLY (at minimum) | n/a | Set via doca_mmap_set_permissions before doca_mmap_start |
Source doca_mmap (cross-peer copy) | Same as above on the local side; additionally the source must be exported via doca_mmap_export_* so the DMA engine on the other peer can read it | The peer side imports the export and uses it as the source doca_buf for the memcpy task | Confirmed end-to-end by a successful first memcpy on a small buffer |
Destination doca_mmap | DOCA_ACCESS_FLAG_LOCAL_READ_WRITE (at minimum) | The destination is always local to the side submitting the task; no export required | Set via doca_mmap_set_permissions before doca_mmap_start |
The mmap must stay valid until the DMA context is destroyed. Destroying the source or destination mmap before
doca_ctx_destroy()is a use-after-free on the library's bookkeeping; symptoms includeDOCA_ERROR_BAD_STATEfrom subsequent calls and undefined behavior on outstanding tasks.Validate permissions BEFORE the bulk run. A small-buffer smoke memcpy (a few KiB) is the cheapest way to confirm the source / destination permission pair for the tested path is correct. For a cross-peer copy, the smoke must exercise the exported and imported mmap path before its permissions are considered valid. Any subsequent oversize-buffer failure then narrows cleanly to the cap-query / size axis instead of the permission axis.
Deferred topic boundaries
This skill scopes itself to the DOCA DMA library. Adjacent topics the agent will get asked but should route elsewhere:
General BlueField DMA-engine internals (queue arbitration, per-channel scheduling, hardware-side error counters) — outside this skill. Route to the public DOCA DMA guide reachable through
doca-public-knowledge-map/SKILL.md.DOCA Core context, progress engine, and
doca_mmapinternals — owned bydoca-programming-guide/SKILL.md. This skill uses the Core context lifecycle and thedoca_mmappermission flags; it does not redefine them.Cross-network copies — owned by
doca-rdma/SKILL.md. When the user's data flow has to traverse IB / RoCE, DMA is not the answer.Producer / consumer message flows between host and DPU — owned by
doca-comch/SKILL.md. When the user is moving messages, not raw mmap regions, Comch fast-path is the answer.Cross-cutting
DOCA_ERROR_*taxonomy — owned bydoca-programming-guide CAPABILITIES.md ## Error taxonomy(doca-programming-guide/CAPABILITIES.md#error-taxonomy). This skill adds the DMA overlay, not the taxonomy itself.Cross-cutting debug ladder (install / version / build / link / runtime / program / driver) — owned by
doca-debug ## debug(doca-debug/TASKS.md#debug). This skill's## debugoverlays the runtime + program layers.
Requirements and compatibility
Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta
“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.
The author says: 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.
Security
What our scanner noticed· Medium risk
- Large base64-encoded blobs
A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.
Attribution and licence
- Created by
- NVIDIA
- Publisher
- NVIDIA (Official)
- Source
- NVIDIA/skills · skills/doca-dma · commit fce3cca
- Licence
- Apache License 2.0 (redistribution allowed)
- LICENSE (added by AutoGineer from LICENSE-APACHE)
- ATTRIBUTION.md (written by AutoGineer)
- Synced
AutoGineer is not affiliated with or endorsed by NVIDIA.
Related skills
Implement Spec
Matt Pocock· Community
A workflow for implementing technical specifications and tickets using concurrent subagents.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository317.5k
MCP Builder
AnthropicOfficial
A comprehensive guide for building high-quality Model Context Protocol (MCP) servers to integrate external services with LLMs.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreApache-2.0Low riskHas scriptsGitHub stars of the source repository188.6k
Schema
Corey Haines· Community
Expert guidance for implementing and optimizing JSON-LD schema markup to improve search engine content understanding.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository59k
Postgresql Table Design
Seth Hobson· Community
A comprehensive guide for designing, reviewing, and optimizing PostgreSQL database schemas.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository42.3k
SQL Optimization Patterns
Seth Hobson· Community
A comprehensive guide to optimizing SQL database performance through indexing, query plan analysis, and efficient coding patterns.
Software developmentClaude CodeClaude appsOpenAI Codex+14 moreMITGitHub stars of the source repository42.3k
API Scaffolding Fastapi Pro
Seth Hobson· Community
An expert FastAPI developer focused on high-performance, async-first API architecture and production-ready microservices.
Software developmentClaude CodeMITGitHub stars of the source repository42.3k
Download ZIP
The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-dma.zip