/doca-rdma

license: Apache-2.0
name: doca-rdma
description: >
  Use this skill when the user is doing hands-on DOCA RDMA programming
  on a BlueField DPU, ConnectX NIC, or DOCA host — bringing up an RDMA
  context on a doca_dev, picking a connection method (RDMA CM,
  bridge/OOB, or gRPC exchange of doca_rdma_export()), enabling one of
  the eleven task types (Send/Receive/Send-Imm, Read/Write/Write-Imm,
  Atomic CmpSwap/FetchAdd, Get/Set/Add Remote Sync Event), setting
  matching mmap + RDMA permissions, sizing queues and connections,
  querying doca_rdma_cap_*, or debugging DOCA_ERROR_* from an RDMA
  call. Trigger even when the user does not mention "DOCA RDMA" —
  typical implicit phrasings include "one-sided read returns permission
  denied", "completions never arrive after submit", "connection
  callback never fires", "how do I do atomic compare-and-swap over
  RoCE", or "send queue hits DOCA_ERROR_FULL under burst". Refuse and
  route elsewhere for general RDMA / ibverbs theory (queue pairs, MRs,
  RoCE vs IB), installing DOCA itself, or non-RDMA DOCA libraries.
metadata:
  kind: library
compatibility: >
  Requires DOCA SDK on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with a
  BlueField DPU or ConnectX NIC. Resolves the local install and module via
  `pkg-config --list-all | grep -i doca` and
  `pkg-config --variable=prefix MODULE`, replacing `MODULE` with the exact
  name returned by the preceding query. The normal module is the umbrella
  `doca`, while split installs may expose a per-library module.

DOCA RDMA

Non-negotiable: the deliverable uses DOCA RDMA, not raw verbs

When this skill is in scope, the user is asking for **DOCA RDMA**. The program you produce **must link `libdoca_rdma` and call the `doca_rdma_*` API** (directly in C/C++, or through a thin FFI/cgo shim from another language). Do **NOT** implement the request with raw `libibverbs` / `librdmacm` / RDMA-CM and call it done. Those move bytes but completely bypass DOCA — which defeats the entire purpose of using this library, loses the DOCA programming model (progress engine, task/ event lifecycle, capability discovery, portability across BlueField/ ConnectX generations), and is the single most common failure mode.

"Raw verbs is fewer lines" / "it avoids building a DOCA binding layer" is **not** an acceptable reason to bypass DOCA. The correct low-friction path for a non-C language (Go, Rust, Python, …) is **not** to re-bind the whole API — it is to start from a **shipped DOCA RDMA sample** under `$(pkg-config --variable=prefix doca)/samples/doca_rdma/` (substitute the module resolved on the target) and wrap its entry functions in a **thin** cgo/FFI shim built with `#cgo pkg-config: doca` (Go) or the equivalent. That shim is a single small file, not "a large custom binding layer". See [`TASKS.md ## build`](TASKS.md#build) Step 0 and [`TASKS.md ## modify`](TASKS.md#modify).

If `pkg-config doca` or the DOCA build fails, **fix the build** (module name, `PKG_CONFIG_PATH`, sample path) — do not silently fall back to verbs. A binary whose `ldd` shows no `libdoca_rdma` is a failed DOCA-RDMA task, regardless of whether bytes moved.

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on RDMA 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 RDMA express* on this version. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first.

Example questions this skill answers well

The CLASSES of RDMA 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 an RDMA context and connect two sides?"** —

worked example: *"set up sender + receiver with RDMA CM on a single host for first-run testing"*. Answered by the lifecycle + connection workflow in [`TASKS.md ## configure`](TASKS.md#configure) + [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) connection-method selection.

• **"Which RDMA task type fits this data-movement pattern?"** —

worked example: *"one-sided write + completion via Send-with-Immediate for a small control message"*. Answered by the task taxonomy in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the task-config workflow in

[`TASKS.md ## modify`](TASKS.md#modify).

• **"What mmap permissions does this task need? Do I have to export

the mmap?"** — worked example: *"my Read task fails with insufficient permissions"*. Answered by the permission matrix in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the mmap-export checklist in

[`TASKS.md ## test`](TASKS.md#test).

• **"Is this RDMA capability supported on my device + transport?"** —

worked example: *"does this device support Atomic Compare-and-Swap over RoCE"*. Answered by the capability-query rule (`doca_rdma_cap_task_*_is_supported` against a `doca_devinfo`) in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the discovery step in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"Is this RDMA API available on my installed DOCA version?"** —

worked example: *"is RDMA CM in DOCA 2.6.0"*. Answered by the version-compatibility section in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)

• the version-discovery rule (`pkg-config --modversion doca`)

pinned in [`TASKS.md ## configure`](TASKS.md#configure).

• **"What does this `DOCA_ERROR_*` from an RDMA call mean and which

layer caused it?"** — worked example: *"`DOCA_ERROR_BAD_STATE` from `doca_rdma_connection_disconnect`"*. Answered by the RDMA overlay on the cross-library taxonomy i