/doca-rdmi

license: Apache-2.0
name: doca-rdmi
description: >
  Use this skill when the user is doing hands-on DOCA RDMI (RDMA
  Initiator) programming — picking doca-rdmi vs doca-rdma for an
  accelerator-initiated one-sided RDMA flow, standing up a
  doca_rdmi_connection or doca_rdmi_poster, attaching a
  doca_dpa_completion or doca_verbs_cq before doca_ctx_start(),
  retrieving the DPA-side handle for a DPA kernel, auditing whether
  a doca_rdmi_* symbol is EXPERIMENTAL on this DOCA, or debugging
  DOCA_ERROR_* returns from RDMI calls. Trigger even when the user
  does not say "DOCA RDMI" or "initiator" — implicit phrasings
  include "my DPA kernel needs to post RDMA writes to a remote
  responder", "DPA kernel sees no completions", "function not found
  on doca_rdmi_* at link time", "DOCA_ERROR_BAD_STATE from
  completion attach", or "the DPA posted but the work request never
  arrived". Refuse and route elsewhere for two-sided or host-CPU
  RDMA, the DPA programming model, GPU-side RDMA initiation, or
  general RDMA/IB/RoCE concepts — those belong to other skills.
metadata:
  kind: library
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, plus the DOCA DPA toolchain and a
  DPA-capable BlueField when the data path runs on the DPA. Reads
  the user's local install via `pkg-config doca-rdmi` (alongside
  doca-common, doca-verbs, doca-dpa) and inspects
  /opt/mellanox/doca/{lib,include,samples}.

DOCA RDMA Initiator

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on RDMI work** on a host or BlueField with the DOCA package set that ships the `doca-rdmi` library. Open [`TASKS.md`](TASKS.md) if the user wants to *do* something (install / configure / build / modify / run / test / debug / use); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can RDMI express on this version* — the object model, the DPA-side handle types, the relationship to `doca-rdma`, the EXPERIMENTAL-tag policy, and the safety overlay.

**End-to-end "walk me through doca-rdmi" questions are answerable entirely from this skill.** Go straight to [`TASKS.md ## end-to-end (quickref)`](TASKS.md#end-to-end-quickref), which carries the self-contained install-check → device/cap discovery → sample → `pkg-config` build → run → debug walkthrough with the exact commands. You do **not** need to open `doca-setup` or `doca-programming-guide` to answer an RDMI build/run/debug question. Route to [`doca-setup`](../../doca-setup/SKILL.md) when the required DOCA prerequisites are absent, partial, or version-mismatched.

Example questions this skill answers well

The CLASSES of RDMI 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.

• **"Should I use `doca-rdmi` or `doca-rdma` for this case?"** —

worked example: *"I have a DPA kernel that needs to fire 1 MB RDMA writes at a remote responder; which library?"*. Answered by the *initiator-side vs general-purpose* selection rule in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) surface-selection table + the routing back to [`doca-rdma`](../doca-rdma/SKILL.md) when the use case is two-sided or host-CPU initiated.

• **"How do I bring up an RDMI connection on the DPA datapath?"** —

worked example: *"create a `doca_rdmi_connection`, attach a DPA completion context, hand the DPA-side handle to my kernel"*. Answered by the connection-object lifecycle in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the configure walk in

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

• **"How do connection and poster relate — when do I need both?"**

— worked example: *"my application receives work requests AND posts RDMA writes; do I need a `doca_rdmi_connection` plus a `doca_rdmi_poster`, or one of them?"*. Answered by the two-object model in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the modify-from-sample slot table in

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

• **"How do I drive completions on the DPA side?"** — worked

example: *"hook the connection to a `doca_dpa_completion` so my kernel polls completions directly"*. Answered by the DPA-side completion-attach pattern in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the run-side wiring in

[`TASKS.md ## run`](TASKS.md#run), cross-linked into [`doca-dpa`](../doca-dpa/SKILL.md) for the DPA programming surface itself.

• **"Is the symbol I want available — and is it stable enough to

ship?"** — worked example: *"is `doca_rdmi_poster_post` GA on my installed DOCA, or still EXPERIMENTAL?"*. Answered by the EXPERIMENTAL-tag policy in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)

• the version-discovery rule

(`pkg-config --modversion doca-rdmi`) pinned in [`TASKS.md ## configure`](TASKS.md#configure).

• **"What does this `DOCA_ERROR_*` from a `doca_rdmi_*` call

mean?"** — worked example: *"`DOCA_ERROR_BAD_STATE` from `doca_rdmi_connection_dpa_completion_attach`"*. Answered by the RDMI 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 DPA-resident DOCA applications that need to *initiate* one-sided RDMA operations against a remote responder** — i.e., users whose accelerator-side code wants to post sends, writes, or reads directly from the accelerator without round-tripping through the host CPU. The canonical caller is a DPA kernel that has been comp