/doca-verbs

license: Apache-2.0
name: doca-verbs
description: >
  Raw verbs inside DOCA Core (doca-verbs): direct control of QP, CQ,
  PD, SRQ and address-handle objects through doca_verbs_context and
  doca_verbs_qp_create / doca_verbs_qp_modify / doca_verbs_cq_create,
  porting libibverbs code into DOCA Core, or a QP attribute, opcode
  or WR flag the doca-rdma task API does not expose. Trigger on "raw
  QP attribute the task API does not expose", "porting libibverbs
  code", "IO_FAILED on WR submit", "QP state transition rejected",
  or "attach a congestion-control group", even without naming
  doca-verbs. Refuse and route elsewhere for ordinary doca-rdma /
  doca-eth / doca-rmax workloads, DOCA install, Core internals, and
  general libibverbs theory.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - verbs
    - rdma
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.
  Reads the local install via `pkg-config doca-verbs` (experimental ABI
  tier — symbols may shift between releases) and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}. The verbs
  headers (doca_verbs.h + doca_verbs_*.h family) are the authoritative
  symbol surface per headers-win-over-docs.

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 installed `doca_verbs.h` surface.

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_