Doca Dma Agent Skill

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

CAPABILITIES.md ## 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

CAPABILITIES.md ## Error taxonomy

+ the layered ladder in

TASKS.md ## debug that escalates to

doca-debug.

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

• Read this SKILL.md 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

CAPABILITIES.md.**

• **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.