doca-dma

# 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`](TASKS.md) if the user
wants to *do* something (configure / build / modify / run / test /
debug); open [`CAPABILITIES.md`](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`](../../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.md ## Capabilities and modes`](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`](TASKS.md#configure) +
  [`CAPABILITIES.md ## Capabilities and modes`](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`](CAPABILITIES.md#capabilities-and-modes)
  + the discovery step in
  [`TASKS.md ## configure`](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`](CAPABILITIES.md#safety-policy)
  + the permission checklist in
  [`TASKS.md ## test`](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`](CAPABILITIES.md#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
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility),
  which cross-links the canonical detection chain in
  [`doca-version`](../../doca-version/SKILL.md), plus the
  capability-query rule in
  [`CAPABILITIES.md ## Capabilities and modes`](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`](CAPABILITIES.md#error-taxonomy)
  + the layered ladder in
  [`TASKS.md ## debug`](TASKS.md#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 `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.