doca-dma

license	Apache-2.0
name	doca-dma
description	Use this skill when the user is doing hands-on DOCA DMA programming — bringing up a doca_dma context, configuring the single doca_dma_task_memcpy task type, sizing buffers via the doca_dma_cap_task_memcpy_* queries, setting LOCAL_READ_ONLY / LOCAL_READ_WRITE permissions on source / destination doca_mmap regions (plus doca_mmap_export_* for cross-peer copies), driving the progress engine, or debugging DOCA_ERROR_* returns. Trigger even when the user does not explicitly mention "DOCA DMA" or "doca_mmap" — typical implicit phrasings include "memcpy host buffer to BlueField without using the CPU", "offload a bulk copy to the DPU", "copy returns NOT_PERMITTED on first submit", "buffer too big for one DMA task", "task submitted but no completion", or "scatter-gather copy between two memory regions". Refuse and route elsewhere for cross-network copies (DOCA RDMA), producer/consumer messaging (DOCA Comch), DOCA Core / progress-engine internals, or DOCA install — those belong to other skills.
metadata	{"kind":"library"}
compatibility	Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC attached. Reads the user's local install via `pkg-config doca-dma` and inspects /opt/mellanox/doca/{lib,include,samples,applications}.

DOCA DMA

Where to start: This skill assumes DOCA is already installed and the user is doing hands-on DMA work on a BlueField / ConnectX / host with DOCA. Open TASKS.md if the user wants to do something (configure / build / modify / run / test / debug); open CAPABILITIES.md when the question is what can DMA express on this version. If the user has not installed DOCA yet, route to doca-setup first. If the user is not sure DMA is even the right library — the data has to traverse the network, or the flow is small messages between two processes — read the path-selection rule in CAPABILITIES.md ## Capabilities and modes before configuring anything.

Example questions this skill answers well

The CLASSES of DMA questions this skill is built to answer, each with one worked example. The agent should treat the class as the load-bearing piece — the worked example is a single instance.

• "How do I bring up a DOCA DMA context and copy a buffer between host and DPU?" — worked example: "copy a 64 KiB buffer from host memory to DPU memory in one task, starting from the shipped DMA Copy reference application". Answered by the lifecycle + memcpy-task workflow in TASKS.md ## configure + CAPABILITIES.md ## Capabilities and modes task-type table.
• "How big a buffer can I memcpy in one task on this device?" — worked example: "can I copy 16 MiB in a single doca_dma_task_memcpy". Answered by the capability-query rule (doca_dma_cap_task_memcpy_get_max_buf_size, plus _get_max_buf_list_len for scatter-gather) in CAPABILITIES.md ## Capabilities and modes
  • the discovery step in TASKS.md ## configure.
• "What permissions do my source and destination mmaps need?" — worked example: "my memcpy task returns DOCA_ERROR_NOT_PERMITTED on the first submit". Answered by the source / destination permission matrix in CAPABILITIES.md ## Safety policy
  • the permission checklist in TASKS.md ## test.
• "Should I use DOCA DMA or DOCA RDMA / Comch / a plain CPU memcpy for this copy?" — worked example: "I have a 1 MiB copy that has to go from a host process to a DPU process; do I want DMA or Comch fast-path". Answered by the "when to use DMA" vs "when not to" path-selection bullet in CAPABILITIES.md ## Capabilities and modes
  • 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 CAPABILITIES.md ## Version compatibility, which cross-links the canonical detection chain in doca-version, plus the capability-query rule in .

Audience

This skill serves external developers building applications that consume the DOCA DMA library — i.e., users whose code calls doca_dma_* (directly in C/C++, or through FFI/bindings from another language) to copy bytes between two doca_mmap regions using the BlueField DMA engine instead of the host CPU. It is not for NVIDIA developers contributing to DOCA DMA itself.

Language scope. DOCA DMA ships as a C library with pkg-config module name doca-dma. The shipped samples are written in C. C and C++ consumers are the canonical case and the worked examples in TASKS.md assume that path. Other-language consumers (Rust, Go, Python, …) consume the same *.so through FFI or language-specific bindings; the skill's contribution in that case is to keep the lifecycle, capability-discovery, permission, error-taxonomy, and path-selection guidance language-neutral, and to route the agent to the public C ABI as the authoritative surface that any wrapper will eventually call.

When to load this skill

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

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

Do not load this skill for general DOCA orientation, install of DOCA itself, or non-DMA library questions. For those, use doca-public-knowledge-map.

What this skill provides

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

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

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

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. 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, layered with the DMA-specific overrides in TASKS.md ## modify.
• Standalone build manifests (meson.build, CMakeLists.txt, Cargo.toml, …) parked inside the skill. The agent constructs the build manifest in the user's project directory against the user's installed DOCA, where pkg-config --modversion doca-dma is the source of truth.
• A samples/, bindings/, or reference/ subtree of any kind. A mock or incomplete artifact in this skill's tree, even one labeled "reference", is misleading: users will read it as buildable.

Loading order

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

Both companion files cross-link to each other, doca-version for the canonical version-handling rules, and doca-public-knowledge-map 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 — 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 — 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 — 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 — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in TASKS.md honors this contract.
• doca-programming-guide — 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 — 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 — 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 — 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.