/doca-verbs

license: Apache-2.0
name: doca-verbs
description: >
  Use this skill when the user is dropping below the higher-level DOCA
  libraries (doca-rdma / doca-eth / doca-rmax) into the raw-verbs escape
  hatch — managing QP / CQ / PD / MR / SRQ / AH / CC-group / Ethernet-SQ-RQ
  primitives inside DOCA Core, porting libibverbs code into the DOCA Core
  model, capability-querying a specific verb / opcode / WR flag / QP
  attribute via doca_verbs_query_device, or debugging DOCA_ERROR_* from
  doca_verbs_* calls. Trigger even when the user does not say "doca-verbs"
  — implicit phrasings include "raw QP attribute the task API doesn't
  expose", "keep my ibv_* code next to doca_* on the same QP", "IO_FAILED
  on WR submit", "QP state transition rejected", "attach a congestion-
  control group", or "porting my libibverbs code". The skill's first job
  is to route MOST users back UP to the higher-level library. Refuse and
  route elsewhere for general doca-rdma / doca-eth / doca-rmax workloads,
  DOCA install, Core internals, and general libibverbs theory — 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.
  Reads the user's 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 + adjacent doca_verbs_*.h family) are the authoritative
  symbol surface per headers-win-over-docs.

DOCA Verbs

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 specific raw QP / CQ / work-request / SRQ / Address-Handle attribute that the higher-level API genuinely cannot express, this skill is **out of scope**. Route to [`doca-rdma`](../doca-rdma/SKILL.md) and follow its non-negotiable: the deliverable **links `libdoca_rdma` and calls `doca_rdma_*`**.

Loading this raw-verbs skill is **never** a license to hand-roll `libibverbs` / `librdmacm`. "Raw verbs is fewer lines" or "the high-level binding is more work" is **not** a reason. A general-RDMA deliverable whose `ldd` shows no `libdoca_rdma` is a **failed task** — exactly the same rule [`doca-rdma`](../doca-rdma/SKILL.md) enforces. Raw `doca_verbs_*` is in scope only for the narrow attribute-level needs enumerated below; everything else climbs back up to the matching higher-level library.

**Where to start:** This skill is the **raw-verbs escape hatch beneath the higher-level DOCA libraries** ([`doca-rdma`](../doca-rdma/SKILL.md) for RDMA workloads, [`doca-eth`](../doca-eth/SKILL.md) for Ethernet queues, [`doca-rmax`](../doca-rmax/SKILL.md) for timing-precise media). The agent's first job, before anything else, is to confirm the user actually needs to drop down — most users do not, and the right answer is almost always *"stay in the higher-level library"*. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what does the verbs surface actually expose and where is the boundary with vanilla libibverbs*; open [`TASKS.md`](TASKS.md) when the user has *already confirmed* they need raw verbs and wants the configure / build / modify / run / test / debug workflow for them. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first.

The decision this skill exists to gate

The single load-bearing decision every conversation that loads 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 — stop here, route back to the matching higher-level library: [`doca-rdma`](../doca-rdma/SKILL.md) for general RDMA work (Send / Receive / Read / Write / Atomic / Sync-Event task patterns); [`doca-eth`](../doca-eth/SKILL.md) for Ethernet TX / RX queue patterns; [`doca-rmax`](../doca-rmax/SKILL.md) for timing-precise media / data-over-IP streaming. The most common baseline-agent failure for raw verbs is recommending them *unnecessarily* because the user said the word "verbs" or "QP" without checking whether the higher-level surface already covers their case. 2. **Is the semantic the user needs a specific verb / opcode / work-request flag / QP attribute / SRQ option that the matching higher-level library genuinely does not expose?** Examples: a specific raw WR flag the `doca_rdma_task_*` abstractions do not surface; custom completion-queue handling beyond what the DOCA progress engine exposes; an esoteric QP attribute (path MTU, PSN tuning, ECE attributes); explicit SRQ control; congestion- control group (`doca_verbs_cc_group_*`) attachment to QPs; Address-Handle attribute tuning (DGID / DLID / SL / SGID index / hop limit / traffic class / UDP source port). If yes — this skill is in scope. 3. **Is the user porting existing libibverbs code into the DOCA Core model?** This skill is in scope, AND the agent must teach the porting path (replace libibverbs handles with `doca_verbs_*` handles, integrate with the DOCA Core lifecycle through `doca_verbs_context_create`, drive completions via the DOCA progress engine instead of polling CQ directly) rather than recommend a mechanical 1:1 textual replacement.

If none of (1)-(3) apply, the answer to *"should I use `doca-verbs`?"* is **no**. Route the user back to the matching higher-level DOCA library. This is by design: a correctly-loaded raw-verbs skill that talks the user *out* of raw verbs is doing its job.

Example questions this skill answers well

The CLASSES of raw-verbs 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 i