Skip to main content
skill CX Codex

doca-dma — Claude Code skill: setup and installation

Get help configuring and debugging memory copies with DOCA DMA. The skill covers memcpy tasks between host and DPU memory.

Apache-2.0 143 installs ★ 4,106 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add NVIDIA/skills --skill doca-dma -a claude-code
Open on GitHub

What doca-dma does

The skill guides DOCA DMA context setup and memcpy configuration. It covers checking device limits before choosing buffer sizes, assigning memory permissions, and driving the progress engine. It also helps investigate DOCA errors and scatter-gather support. Cross-peer copies involve a memory export step.

Use it on Linux with the DOCA SDK installed at /opt/mellanox/doca and a BlueField DPU or ConnectX NIC attached. Its examples use the C API; for other languages, it points to the public C ABI. This is hands-on DMA guidance, not an installer: DOCA setup belongs to doca-setup, while transfers across a network belong to DOCA RDMA.

What it helps with

  • configure a DOCA DMA context for memcpy
  • size a buffer against device capabilities
  • set source and destination memory permissions
  • trace an error returned during task submission
  • check whether scatter-gather copies are supported

Example prompts for the agent

  • Configure a DOCA DMA copy from host memory to a BlueField DPU.
  • Why does the first doca_dma_task_memcpy submission return DOCA_ERROR_NOT_PERMITTED?
  • Check the device's scatter-gather support and the maximum buffer size for one task.

How to install doca-dma

1Skills CLI (Vercel)

npx skills add NVIDIA/skills --skill doca-dma -a claude-code

2Manually: put the files in place

~/.claude/skills/doca-dma/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/doca-dma/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about doca-dma

How do I install doca-dma in Claude Code?

Run npx skills add NVIDIA/skills --skill doca-dma -a claude-code. The skill is installed at ~/.claude/skills/doca-dma/SKILL.md.

What does doca-dma do?

It helps configure and debug DOCA DMA memory copies, including context setup, permissions, device capability checks, and error diagnosis.

What do I need to use doca-dma?

You need the DOCA SDK installed at /opt/mellanox/doca on Linux, with a BlueField DPU or ConnectX NIC attached.

Source text

SKILL.md · Apache-2.0
---
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:
  author: NVIDIA <[email protected]>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - dma
    - memcpy
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}.
  The validation steps require a live DOCA install.
---

# 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`](#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.

© NVIDIA · Apache-2.0 · NVIDIA/skills

Similar skills

All skills for Backend and APIs →

From the same set312

The whole set →
doca-caps doca-caps is a Claude Code skill that runs the read-only CLI to show which DOCA devices and libraries a host can see. It can also check device capabilities and capture a snapshot for debugging. CX Codex +1 147installs doca-devemu The doca-devemu skill guides DOCA Device Emulation work on a BlueField DPU, from choosing the emulation library to diagnosing device and capability errors. CX Codex +1 146installs doca-container-deployment The doca-container-deployment skill deploys DOCA services as containers on BlueField using kubelet standalone. Use it when running Argus, DMS, Firefly, or UROM from pod specs and troubleshooting startup or service readiness issues. CX Codex +1 145installs doca-gpunetio This skill covers hands-on DOCA GPUNetIO work: connecting CUDA kernels to network queues and checking whether a GPU can run the path. CX Codex +1 144installs doca-comch doca-comch is a Claude Code skill for setting up DOCA Comch messaging between a host and BlueField. It handles role selection, transfer modes, capability checks, and API errors. CX Codex +1 142installs nemo-relay-plugin-observability nemo-relay-plugin-observability — a Claude Code skill for selecting and configuring observability exporters and subscribers in NeMo Relay 0.6 and 0.7. CX Codex +1 140installs doca-compress doca-compress is a Claude Code skill for moving DEFLATE compression and DEFLATE or LZ4 decompression to DOCA Compress. It activates for task setup, buffer checks, and accelerator errors. CX Codex +1 140installs doca-dms doca-dms is a Claude Code skill for managing NVIDIA DOCA Management Service on BlueField, hosts, and Kubernetes, with local dms-cli and remote gNMI/gNOI operations. CX Codex +1 138installs

Project sponsors

Companies that keep this analytics open