doca-dma

# 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`](../../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`](#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`](../../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`](../../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`](../../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`](../../doca-setup/SKILL.md). ## What this skill deliberately does not ship This skill is **agent guidance**, not a samples or templates bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add: - **Pre-written DOCA DMA application source code, in any language.** The verified DMA source code is the shipped C samples at `/opt/mellanox/doca/samples/doca_dma/<name>/` and the DMA Copy reference application reachable via [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md). The agent's job is to route the user to those files and prescribe a minimum-diff modification on them via the universal modify-a-sample workflow in [`doca-programming-guide`](../../doca-programming-guide/SKILL.md), layered with the DMA-specific overrides in ## 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`](../../doca-version/SKILL.md) for the canonical version-handling rules, and [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) whenever the right answer is "look it up in the public docs or the installed package layout" rather than "DMA-specific guidance". ## Related skills - [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) — the routing table for every public DOCA documentation source and the on-disk layout of an installed DOCA package. The DMA URL is `https://docs.nvidia.com/doca/sdk/DOCA-DMA/index.html`; the canonical reference application is *DMA Copy*. - [`doca-setup`](../../doca-setup/SKILL.md) — env preparation, install verification, and the *I have no install yet* path with the public NGC DOCA container. This skill assumes its preconditions are satisfied. - [`doca-version`](../../doca-version/SKILL.md) — canonical DOCA version-handling rules. This skill's `## Version compatibility` cross-links the four-way match rule + detection chain and adds at most one DMA-specific overlay rule. - [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md) — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in the tasks companion honors this contract. - [`doca-programming-guide`](../../doca-programming-guide/SKILL.md) — general DOCA programming patterns shared by every library: the canonical `pkg-config` + meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the program-side debug order. This skill layers DMA specifics on top. - [`doca-rdma`](../doca-rdma/SKILL.md) — the right library when the copy has to traverse the network. This skill's path-selection rule routes to RDMA when DMA is *not* the answer. - [`doca-comch`](../doca-comch/SKILL.md) — the right library when the flow is producer / consumer messaging between a host and DPU process pair, rather than a raw mmap-to-mmap copy. - [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). DMA-specific debug (lifecycle violations, permission mismatches, oversize-buffer rejections) overlays on top of that ladder.