AutoGineer
Generated banner for Doca Dma
Generated logo for Doca Dma

Doca Dma

NVIDIAOfficialCreated by NVIDIA

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

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.
— the description by NVIDIA

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

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/nvidia/doca-dma/download

  2. Unzip 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_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.

  • "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-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 in

    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 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 the capabilities companion.

  3. 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.

Files

TASKS.md

DOCA DMA workflows

Where to start: The verbs run configure → build → modify → run → test → debug. Skip ahead only when the user is already past a verb. The ## test verb is an iterative loop (capability check → permission check → small-buffer smoke → bulk → loop back if a cap or permission boundary changed), not a one-shot pass — see the eval-loop overlay in ## test below.

Read this file when the loader sent you here from SKILL.md. For the DMA capability surface, the single-task type, the capability-query rule, the path-selection rule against RDMA / Comch / CPU memcpy, the error taxonomy, observability, and safety policy, see CAPABILITIES.md. For where to find docs, the installed DOCA layout, or release notes, route through doca-public-knowledge-map/SKILL.md.

Each verb below describes the shape of the workflow, not a copy-paste recipe. The agent's job is to walk the user through the steps in order, verifying preconditions before recommending the next call.

DOCA 3.5 field notes

Known behaviours on DOCA 3.5; check them before debugging further:

  • Size limit. Query doca_dma_cap_task_memcpy_get_max_buf_size() before submitting. The DMA Copy reference app caps files at 2 MiB (2097152 bytes) on a BlueField-3; the host only reports Failure was detected in dma copy, while the real reason is in the BlueField log.

  • Validate before submitting. On DOCA 3.5, doca_task_try_submit() rejected a too-large copy cleanly (buffer byte size=... must be <= maximum_byte size=2097152), whereas doca_task_submit() failed in hardware and stopped the DMA context.

  • Local copy runs on the host too. The local-copy sample refuses to run on the host (Local DMA copy can run only on the DPU), but the library supports host-local copies in your own program.

  • Run the BlueField side as root. Without it, DMA Copy fails with the misleading do not run on Host representor message.

configure

Goal: bring up a DOCA DMA context on a host or BlueField and confirm the device, the memcpy task type, and the source / destination mmap permissions are all in a state where a memcpy task is meaningful.

Steps the agent should walk the user through:

  1. Confirm the installed DOCA version. Use the procedure in doca-version TASKS.md ## configure (doca-version/TASKS.md#configure). Quote the version observed (pkg-config --modversion doca-dma, then doca_caps --version); do not assume "latest". The four-way match rule lives in doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility); if the observed sources disagree, route there before any DMA diagnosis.

  2. Discover the device capability surface for DMA. Run doca_caps --list-devs (per doca-caps/SKILL.md) to see which devices are present. If no DMA-capable device is visible, stop configuration and route to doca-setup/SKILL.md for device discovery; do not create a DMA context. Run the per-doca_devinfo doca_dma_cap_task_memcpy_* queries against every visible candidate device: _is_supported, _get_max_buf_size, _get_max_buf_list_len. When more than one device supports DMA, select and record the user-intended PCI BDF and its topology from the supported set; do not silently choose the first device. Quote the per-device queried values and selected BDF back to the user; do not assume from prior installs. The capability matrix to compare against lives in CAPABILITIES.md ## Capabilities and modes.

  3. Confirm DMA is the right library for this copy. Walk the path-selection rule in CAPABILITIES.md ## Capabilities and modes: if the data has to traverse the network, route to doca-rdma/SKILL.md; if it is producer / consumer messaging, route to doca-comch/SKILL.md; if it is tiny and one-shot, recommend a CPU memcpy. Picking DMA for the user when the path-selection rule rules it out is a wrong answer regardless of how cleanly the rest of the configure step goes.

  4. Configure the doca_dma instance. Mandatory before doca_ctx_start(): enable the memcpy task via doca_dma_task_memcpy_set_conf (passing the success and error completion callbacks plus the max-num-tasks budget). Set permissions on the source and destination doca_mmap regions (doca_mmap_set_permissions → doca_mmap_start) per the matrix in CAPABILITIES.md ## Safety policy. For cross-peer copies, export the source mmap via the matching doca_mmap_export_* and import it on the peer side.

  5. Sanity check before any task submission. Confirm with the user: which side owns the source mmap, which side owns the destination, what length they intend to memcpy, and whether that length is within doca_dma_cap_task_memcpy_get_max_buf_size. If any of those are unclear, stop and report the missing inputs explicitly (source mmap owner, destination mmap owner, intended memcpy length, or the queried maximum buffer size) so the caller can supply them before re-invocation — do not invent values.

If any step fails with a DOCA_ERROR_*, route through the error taxonomy in CAPABILITIES.md ## Error taxonomy before retrying.

build

Goal: produce a binary that links DOCA DMA against the user's installed DOCA, using the canonical cross-library build pattern.

The build pattern for any DOCA C/C++ consumer is identical across libraries — pkg-config for include + link flags, meson or CMake as the build system — and is fully documented in doca-programming-guide TASKS.md ## build (doca-programming-guide/TASKS.md#build). This skill carries only the DMA-specific overlay:

SlotValue for DMAWhy it matters
pkg-config module namedoca-dmaThe library's .pc file installed by the DOCA host packages. Wrong module name = pkg-config: Package 'doca-dma' was not found
Required runtime libslibdoca-common, libdoca-dma, plus whatever pkg-config --libs doca-dma resolves transitivelyDMA depends on Core; the resolver pulls in the right transitive set
Header checkthe artifact's public header resolvable under whichever include directory pkg-config --cflags reports (do not hardcode the include path — the install layout can move)If pkg-config --cflags doca-dma resolves but the include is missing, the install is partial — route to doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) layer 2
Minimum required DOCA versionQuery with pkg-config --modversion doca-dma; never hardcode in build filesCross-version build/runtime mixing breaks per CAPABILITIES.md ## Version compatibility

For non-C consumers (Rust, Go, Python), the link surface is the same *.so files; the FFI wrapper layer is the language-specific binding and is out of scope for this skill — but the four slots above are still the load-bearing inputs the wrapper needs.

modify

Goal: take a shipped DOCA DMA sample (or the DMA Copy reference application) as the verified starting point and apply a minimum-diff modification to express the user's intent.

The universal modify-a-shipped-sample workflow lives in doca-programming-guide TASKS.md ## modify (doca-programming-guide/TASKS.md#modify). Use it as-is. The DMA-specific overlay is the modify-from-sample schema fill — the slots the agent must elicit from the user before recommending any code-level edit:

SlotWhat the agent asks the userDMA-specific consideration
1. Starting sampleWhich sample under /opt/mellanox/doca/samples/doca_dma/, or the DMA Copy reference application?Pick the closest in direction (intra-host vs host ↔ DPU) and buffer shape (single buffer vs scatter-gather list) to the user's intent. A smaller diff is always safer than a re-architecture
2. Buffer length and shapeSingle buffer, or scatter-gather list? What total length?Re-validate against _get_max_buf_size and _get_max_buf_list_len (per ## configure step 2); a sample sized for one length will not just work at 8x the length
3. Permission changesAre source / destination mmap permissions the same as the sample, or do they need to flip (e.g. the user is now the importing peer rather than the exporting peer)?Refer to the matrix in CAPABILITIES.md ## Safety policy; a wrong flag is a silent first-submit failure
4. Cross-peer vs localIs the copy intra-host, or does it cross a host ↔ DPU boundary?Cross-peer requires the doca_mmap_export_* step on the source side; intra-host does not. Switching one to the other is a sample swap, not an in-place tweak
5. Build manifestKeep the sample's existing meson.build (which already wires pkg-config doca-dma)?Yes. Do not switch to a hand-rolled Makefile for "simplicity" — it removes the version-check rail

The agent emits an intent description + the filled slots; the authoritative path is a manual, line-by-line diff against the shipped sample source read from the installed tree. Keep the diff minimal, preserve sample logic outside the stated intent, and leave the sample's build manifest unchanged. Before accepting the modification, require a successful build, re-run the DMA capability queries against the selected device, and verify the mmap permissions and device topology still match the intended local or cross-peer path.

run

Goal: actually execute the built binary against the user's installed DOCA on a host or BlueField, with the source + destination mmaps materialized and the progress engine driven.

Steps the agent should walk the user through:

  1. Confirm the active doca_dev and the active doca_devinfo. A binary that links cleanly but never produces a memcpy completion is most often opening the wrong device. Re-quote the output of doca_caps --list-devs (doca-caps/SKILL.md) and confirm the binary opens the same recorded PCI BDF selected during ## configure, and that the cap-query ran against that exact device.

  2. For cross-peer copies, run the side that exports first. The exporting peer must have its doca_mmap_export_* complete before the importing peer can use the export blob as a source doca_buf. Order matters; mismatched startup is a silent DOCA_ERROR_NOT_PERMITTED on the first submit.

  3. Capture the structured log. Set DOCA_LOG_LEVEL=trace for the first run (see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability)). This is the cheapest way to make the lifecycle and per-task submission visible on first failure.

  4. Drive the progress engine. A run that produces no completion events but doesn't error is almost always a missed doca_pe_progress() call in the user's main loop. Confirm the PE is being driven on the side that submits tasks.

test

Goal: prove the configured DMA instance can actually move data correctly between the source and destination mmaps on the user's hardware, and that the permission and capability set was sized right for the user's intended workload.

This is a bounded iterative sweep: run it once, then make at most one evidence-based correction and re-run it. Each sweep narrows either the capability set, the permission set, the buffer size, or the buffer-list length. The process terminates when either (a) the user's intended copy length flows end-to-end with the expected per-task completions, or (b) the agent has narrowed the failure cause to a layer outside DMA itself (driver / firmware / mmap-export bookkeeping) and escalated to the matching skill.

Iteration shape:

  1. Capability re-check. Re-run doca_dma_cap_task_memcpy_is_supported, _get_max_buf_size, and (if scatter-gather is in use) _get_max_buf_list_len against the active doca_devinfo. If _is_supported is false → that's the answer; the user's device or DOCA version does not support the memcpy task. Update the user's intent or update the install.

  2. Permission cross-check. Compare the configured source / destination mmap permission flags against the matrix in CAPABILITIES.md ## Safety policy. For cross-peer copies, confirm the source side exported via doca_mmap_export_* and the destination side imported the blob. Mismatches surface as DOCA_ERROR_NOT_PERMITTED on the first task submission, not at configure time.

  3. Small-buffer smoke. Always start with a single small memcpy (a few KiB) before bulk. If the small smoke works, the permission set and lifecycle for that tested path are 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. Skipping this step is the most common reason "bulk DMA fails and we don't know why".

  4. Completion drain. Confirm a per-task completion event arrives on the PE for every submitted memcpy. Submitted but no completion is the most expensive class of bug to discover late; confirm it on the smoke pair before adding bulk submissions.

  5. Bulk run. Once the smoke is green, scale up to the user's intended length and submission rate. Watch for DOCA_ERROR_AGAIN (drain the PE before retrying) and for DOCA_ERROR_INVALID_VALUE (a length boundary was crossed — re-narrow to the cap-query axis).

Eval-loop overlay — why this is a loop, not a one-shot pass:

Iteration triggerWhat it looks likeWhat changes next iteration
DOCA_ERROR_NOT_SUPPORTED on a memcpy submitThe cap query at configure time was assumed; the device-level reality differsRe-run doca_dma_cap_task_memcpy_is_supported against the active doca_devinfo, not a sibling device. The wrong-device case is the most common cause
Small-buffer smoke passes; bulk submit returns INVALID_VALUEThe bulk length crossed _get_max_buf_size (single buffer) or _get_max_buf_list_len (scatter-gather)Fragment at the application layer; the cap is device-bound and not raisable from software
Submitted task produces no completiondoca_task_submit() returned DOCA_SUCCESS; the PE produces nothingThe PE is not being progressed, or the context is not in RUNNING. Wire the lifecycle trace per doca-debug ## debug (doca-debug/TASKS.md#debug)
Cross-peer submit returns NOT_PERMITTED after smoke worked locallyThe local smoke used a local source mmap; the cross-peer case requires the source to be exported via doca_mmap_export_*Re-walk the cross-peer rule in CAPABILITIES.md ## Safety policy
DOCA_ERROR_AGAIN on bulk submitFirst N submissions succeed, then AGAINThe task queue is full. Drain completions on the PE before re-submitting; or raise max-num-tasks at configure time

Loop termination: run one initial sweep. If it is not green, make at most one correction justified by the captured evidence and re-run the same sweep once. If that rerun is not green, stop changing the system and escalate to doca-debug ## debug (doca-debug/TASKS.md#debug) with the captured layer-1-through-5 evidence.

debug

Goal: when a DOCA DMA call returns a DOCA_ERROR_* (or the program doesn't make forward progress), narrow the cause to a specific layer and act on it.

The cross-library debug ladder lives in doca-debug ## debug (doca-debug/TASKS.md#debug). Walk through it in order — install → version → build → link → runtime → program → driver — before recommending DMA-specific fixes. This skill's overlay names the DMA-specific manifestation at layers 5 (runtime) and 6 (program):

Layer 5 (runtime) — DMA overlay.

  • Walk the lifecycle: was the context started? Were the source and destination mmaps started before the first submit? Was a task submitted before the context reached RUNNING? The wrong order returns DOCA_ERROR_BAD_STATE, not a clear symptom.

  • Confirm the PE is being progressed on the submitting side. No completion events is almost always a missing doca_pe_progress() in the user's main loop.

  • Confirm _AGAIN is not being treated as a bug. The DMA queue fills; the contract is that the program drains completions before re-submitting, not that the queue is infinite.

Layer 6 (program) — DMA overlay.

  • Permission matrix: the most common DMA program-layer bug is a source / destination mmap permission flag missing or the cross-peer export step skipped, surfaced as DOCA_ERROR_NOT_PERMITTED. Walk the matrix in CAPABILITIES.md ## Safety policy against the user's configured permissions.

  • Buffer-size sizing: DOCA_ERROR_INVALID_VALUE on submit is a cap-vs-payload mismatch, not a hardware failure. Re-read _get_max_buf_size / _get_max_buf_list_len against the active doca_devinfo and fragment at the application layer.

  • Lifecycle order: configure → start → submit → progress → stop → destroy. Out-of-order returns DOCA_ERROR_BAD_STATE. The most common case is destroying a source or destination mmap before doca_ctx_destroy().

Once the layer is identified, route to the matching debug verb on the matching skill: install / build / link / driver to doca-setup ## debug (doca-setup/TASKS.md#debug); version to doca-version ## debug (doca-version/TASKS.md#debug); cross-cutting runtime to doca-debug ## debug (doca-debug/TASKS.md#debug); program-layer Core-context patterns to doca-programming-guide TASKS.md ## debug (doca-programming-guide/TASKS.md#debug).

Deferred task verbs

The following verbs are out of scope for this skill but are commonly asked in the same conversations. Route them as follows so the agent does not invent guidance:

  • install. Installing DOCA, choosing packages, post-install verification, pkg-config wiring — defer to doca-setup/SKILL.md and to the install-tree layout in doca-public-knowledge-map ## Layout of an installed DOCA package (doca-public-knowledge-map/SKILL.md#layout-of-an-installed-doca-package). This skill assumes DOCA is already installed.

  • deploy. Deploying DMA-using applications at scale across many hosts / DPUs, Kubernetes operator workflows for DMA-accelerated workloads, multi-tenant DMA isolation — out of scope for this skill.

  • rollback. Coordinated rollback across multiple hosts / DPUs — out of scope for this skill. For a single in-session DMA configuration rollback, the right answer in this skill is destroying the context (doca_ctx_stop → doca_ctx_destroy) and re-running ## configure with the corrected parameters; do not invent a "rollback" workflow.

  • kernel-level driver install / firmware burn. If the debug ladder lands on a driver-layer issue (DOCA_ERROR_DRIVER from a memcpy submit, repeated mlx5 errors in dmesg), the fix is via the env-side skill: doca-setup ## debug (doca-setup/TASKS.md#debug) layer 5, then upstream MLNX OFED / firmware documentation reachable through doca-public-knowledge-map/SKILL.md.

Command appendix

Every command below is cross-cutting on DOCA DMA — it answers a recurring class of question that comes up in the verbs above. The agent should treat the class as load-bearing; the worked example is a single instance. Run-as user is the unprivileged user unless noted. Sudo is called out per row.

Infra-aware preamble (every row below). Per the bundle's detect → prefer → fall back → report contract documented in doca-structured-tools-contract ## The agent behavior contract (doca-structured-tools-contract/SKILL.md#the-agent-behavior-contract), the agent should:

  1. Probe for the matching structured helper FIRST (doca-env --json for version + devices + libraries + drivers + hugepages in one shot; doca-capability-snapshot for per-device capability flags; version-matrix.json for "available since" lookups).

  2. If the probe succeeds, the structured tool's output is the authoritative answer and the agent SHOULD NOT also run the manual command in the row below. Report "using structured <tool>".

  3. If the probe fails, fall back to the manual command in the row. Report "falling back to manual chain".

  4. The schemas the structured tools emit are defined in doca-structured-tools-contract ## Schemas (doca-structured-tools-contract/SKILL.md#schemas); the version-handling semantics (four-way match, NGC, headers-win) are owned by doca-version/SKILL.md.

Command (worked example)Owning stepClass of question it answersWhat healthy output looks like
pkg-config --modversion doca-dma## configure step 1; ## build slot 4What is the build-time DOCA DMA version?A semver string matching doca_caps --version. Disagreement = partial install (route to doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) layer 2)
pkg-config --cflags --libs doca-dma## buildWhat include + link flags does the linker need?Trust whatever pkg-config --cflags --libs produces on this install. Do not hardcode either the -I include path or the -l<name> flag form — both can drift between DOCA install profiles and DOCA majors; the on-disk .so basenames use underscores, while the .pc package names use hyphens, and pkg-config is the only thing that resolves both correctly. Hand-crafted -l lines silently break when DOCA upgrades.
doca_caps --list-devs## configure step 2; ## run step 1Which devices on this host can be used as a doca_dev for DMA?One row per visible device with PCIe address and capability flags
doca_caps --version## configure step 1; ## test step 1What is the runtime DOCA version on this host?A semver string matching pkg-config --modversion doca-dma
ls /opt/mellanox/doca/samples/doca_dma/## modify slot 1Which DMA samples ship in this install, and which is the closest starting point?A list of sample directories named after the buffer / direction pattern they demonstrate
cat /opt/mellanox/doca/applications/VERSION## configure step 1; ## debug layer 1What does the install tree itself claim its version is?A semver string matching the other two version sources
`dmesgtail -n 40` (sudo)## debug layer 7What did the kernel / driver log around the last DMA call?
DOCA_LOG_LEVEL=trace ./<binary>## run step 3What did the structured DOCA logger emit for the first failing call?A trace-level line on every lifecycle transition and every task submission. Silence after submission = PE not progressed

For commands shared across libraries (pkg-config --modversion, doca_caps, cat /opt/mellanox/doca/applications/VERSION, DOCA_LOG_LEVEL) the cross-library overlay is in doca-debug TASKS.md ## Command appendix (doca-debug/TASKS.md#command-appendix); this table adds the DMA-specific rows on top.

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.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-dma.zip