doca-rdmi

# 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 compiled with
`doca-dpacc-compiler` and runs on the BlueField DPA datapath; a
GPU-side caller that drives the DPU's RDMA queues is the
sister case routed to [`doca-gpi`](../doca-gpi/SKILL.md). This
skill is *not* for NVIDIA developers contributing to DOCA RDMI
itself, and it is not the right surface for general host-CPU
two-sided RDMA — that belongs to
[`doca-rdma`](../doca-rdma/SKILL.md).

## Language scope

DOCA RDMI ships as a C library with the `pkg-config` module name
`doca-rdmi`. The library's *host-side* surface
(`doca_rdmi_connection_*`, `doca_rdmi_poster_*`) is C; the *DPA-side*
surface that the accelerator kernel uses is also C, compiled against
the DOCA DPA toolchain documented in
[`doca-dpa`](../doca-dpa/SKILL.md). Other-language consumers (Rust,
Go, Python, …) consume the host-side `*.so` through FFI; the skill's
contribution in that case is to keep the connection / poster
lifecycle, the EXPERIMENTAL-tag policy, the DPA-side handoff rules,
and the safety overlay language-neutral, and to route the agent to
the public C ABI as the authoritative surface that any wrapper will
eventually call. The DPA-side surface is *not* wrappable in another
language — it is compiled and linked into the DPA binary itself.

## When to load this skill

Load this skill when the user is doing **hands-on DOCA RDMI work**
on a host or BlueField with DOCA installed. Concretely:

- Deciding between `doca-rdmi` and `doca-rdma` for a new
  one-sided RDMA workload that runs from the DPA datapath.
- Creating a `doca_rdmi_connect