doca-verbs

Files (14)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• command-appendix.md · references/
• deferred-topics.md · references/
• deferred-verbs.md · references/
• install.md · references/
• pattern-overview.md · references/
• use.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# DOCA Verbs

## Examples

- **"Should I use doca-verbs or doca-rdma?"** — ordinary RDMA data
  movement with no raw QP / CQ / WR / SRQ / Address-Handle attribute
  named is out of scope — route to
  `doca-rdma/SKILL.md`.
- **"I need a raw QP attribute the task API does not expose."** — stay
  here. Use only the public `doca_verbs.h` surface; do not quote
  restricted headers.

## Instructions

Follow [`## Loading order`](#loading-order). Open only the companion
that matches the question.

## STOP — most RDMA tasks do NOT belong here

If the task is general RDMA **data movement** (send / receive / read /
write / atomic between endpoints) and the user did **not** name a raw
QP / CQ / work-request / SRQ / Address-Handle attribute the
higher-level API cannot express, this skill is **out of scope** —
route to `doca-rdma/SKILL.md` and stop after
explaining the boundary. Unless `doca-rdma` guidance is loaded, do not
infer its implementation APIs; conceptual terms (QP, CQ, connection,
send, receive) are not implementation API names.

Loading this skill is **never** a license to hand-roll `libibverbs` /
`librdmacm`. A general-RDMA deliverable whose `ldd` shows no
`libdoca_rdma` is a **failed task** — the same rule
`doca-rdma/SKILL.md` enforces. Raw `doca_verbs_*` is in
scope only for the narrow attribute-level needs below; everything else
climbs back up.

**Where to start:** This skill is the **raw-verbs escape hatch beneath
the higher-level DOCA libraries** (`doca-rdma/SKILL.md`,
`doca-eth/SKILL.md`, `doca-rmax/SKILL.md`).
The agent's first job is to confirm the user actually needs to drop
down — most users do not; the right answer is almost always *"stay in
the higher-level library"*. Open [`CAPABILITIES.md`](CAPABILITIES.md)
for *what the verbs surface exposes and the libibverbs boundary*; open
[`TASKS.md`](TASKS.md) once raw verbs is confirmed. If DOCA is not
installed, route to `doca-setup/SKILL.md` first.

## Non-negotiable answer checklist

For every in-scope porting, lifecycle, or debugging answer, do not declare
it complete until it explicitly states all applicable items below:

1. `doca_verbs_context` is the DOCA Core context owning the verbs
   surface; it wraps the `doca_dev`, integrates with the progress
   engine, and owns the per-object PD / MR / CQ / QP lifecycle in
   [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).
2. A submit-time success followed by `DOCA_ERROR_IO_FAILED` is
   diagnosed from the completion-queue entry's error field — not the
   submit return — before recommending retries or code changes.
3. The answer selects exactly one completion path: progress engine,
   manual CQ polling, or completion-channel delivery.
4. Both version axes are stated before any symbol is promised:
   `pkg-config --modversion doca-verbs` must agree with
   `doca_caps --version` and `pkg-config --modversion doca-common`;
   and the `doca_verbs_*` ABI ships in the EXPERIMENTAL tier — symbols
   may rename or graduate between releases and the installed headers
   outrank documentation (`doca-version/SKILL.md`).
   Device support for a verb is answered by the `doca_devinfo`
   capability query, not by either version.
5. Existing `ibv_*` handles are replaced, never mixed with
   `doca_verbs_*` handles on the same hardware objects.

## The decision this skill exists to gate

The decision every conversation loading this skill must make FIRST,
before any code-level discussion:

1. **Has the user confirmed that the matching higher-level DOCA
   library does not expose the semantic they need?** If no — route
   back: `doca-rdma/SKILL.md` for general RDMA,
   `doca-eth/SKILL.md` for Ethernet TX / RX,
   `doca-rmax/SKILL.md` for timing-precise media.
   The most common failure is recommending raw verbs *unnecessarily*
   because the user said "verbs" or "QP" without confirming the
   higher-level surface already covers the case.
2. **Is the needed semantic a specific verb / opcode / WR flag / QP
   attribute / SRQ option the higher-level library does not expose?**
   Examples: a raw WR flag `doca_rdma_task_*` does not surface; custom
   CQ handling beyond the progress engine; an esoteric QP attribute
   (path MTU, PSN, ECE); explicit SRQ control; congestion-control
   group (`doca_verbs_cc_group_*`) attachment; Address-Handle tuning
   (DGID / DLID / SL / SGID index / hop limit / traffic class / UDP
   source port). If yes — in scope.
3. **Is the user porting existing libibverbs code into the DOCA Core
   model?** In scope, AND the agent must teach the porting path
   (replace `ibv_*` handles with `doca_verbs_*` handles, integrate via
   `doca_verbs_context_create`, drive completions via the DOCA
   progress engine instead of polling the CQ) — not a mechanical 1:1
   replacement.

If none of (1)-(3) apply, the answer to *"should I use `doca-verbs`?"*
is **no** — route back to the matching higher-level library. A raw-verbs
skill that talks the user *out* of raw verbs is doing its job.

## Audience

This skill serves **external developers building applications that
consume the DOCA Verbs library** — code calling `doca_verbs_*`
(directly in C/C++, or via FFI/bindings) for raw QP / CQ / PD / MR /
SRQ / Address-Handle / Ethernet-SQ / Ethernet-RQ control inside a
DOCA Core context. It is *not* for NVIDIA developers contributing to
DOCA Verbs, and *not* the entry point for general DOCA RDMA / Eth /
RMAX work — that belongs in the matching higher-level library skill.

## Language scope

DOCA Verbs ships as a C library (`pkg-config` module `doca-verbs`);
public headers live under the installed DOCA tree
(`$(pkg-config --variable=includedir doca-common)/doca_verbs.h` plus
the `doca_verbs_*.h` family) and, per the headers-win-over-docs rule
in `doca-version/SKILL.md`, are the

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills