AutoGineer
Generated banner for Doca Verbs
Generated logo for Doca Verbs

Doca Verbs

NVIDIAOfficialCreated by NVIDIA

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

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.
— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The doca-verbs skill serves as an escape hatch for developers who need direct control over RDMA and Ethernet queue objects that are not exposed by higher-level DOCA libraries like doca-rdma, doca-eth, or doca-rmax. It enables the use of specific verbs, opcodes, WR flags, and esoteric QP attributes while maintaining integration with the DOCA Core context and progress engine. This skill is intended for advanced users porting existing libibverbs code or requiring fine-grained hardware object manipulation, and it enforces strict boundaries to prevent unnecessary use of raw verbs when higher-level abstractions suffice.

What it does

  • Provides direct access to QP, CQ, PD, SRQ, and address-handle objects via doca_verbs_context.
  • Facilitates porting of libibverbs code into the DOCA Core model.
  • Exposes raw WR flags, opcodes, and QP attributes not available in high-level DOCA APIs.
  • Supports congestion-control group attachment and custom CQ handling.
  • Integrates raw verbs objects with the DOCA progress engine for completion management.
  • Provides diagnostic guidance for IO_FAILED errors based on completion-queue entry inspection.

When to use it

  • When a specific verb, opcode, WR flag, or QP attribute is required but not exposed by higher-level DOCA libraries.
  • When porting legacy libibverbs applications to the DOCA Core framework.
  • When custom completion-queue handling or explicit SRQ control is necessary.
  • When attaching to congestion-control groups or performing advanced address-handle tuning.
  • When diagnosing errors in raw-verbs operations that require inspecting completion-queue entries.

Advantages

  • Enables fine-grained hardware control while remaining within the DOCA Core ecosystem.
  • Allows for the migration of complex libibverbs logic into modern DOCA-based applications.
  • Provides a structured path for advanced tuning of RDMA and Ethernet queueing.
  • Maintains consistency with DOCA's progress engine and lifecycle management.
  • Offers a clear decision framework to prevent the misuse of low-level APIs.

Usage examples

“I need to set a specific path MTU on my QP, but doca-rdma doesn't expose it. Can I use doca-verbs?”
The agent confirms if the attribute is available in the doca_verbs_qp_modify surface and guides the user through the integration with doca_verbs_context.
“How do I port my existing libibverbs code to DOCA?”
The agent provides the porting path, emphasizing replacing ibv_* handles with doca_verbs_* handles and integrating with the DOCA progress engine.
“I am getting DOCA_ERROR_IO_FAILED on a work request submit. How do I debug this?”
The agent instructs the user to inspect the completion-queue entry's error field rather than the submit return value to identify the root cause.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/nvidia/doca-verbs/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip doca-verbs.zip -d .agents/skills

Documentation by NVIDIA

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. 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 for what the verbs surface exposes and the libibverbs boundary; open 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.

  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 authoritative symbol surface. C / C++ is the canonical case TASKS.md assumes; other languages reach the same *.so through FFI, and the skill keeps its rules language-neutral while routing to the public C ABI as the authoritative surface.

When to load this skill

Load this skill ONLY after the user has confirmed the matching higher-level DOCA library does not expose the needed semantic. Concretely:

  • The user asks "do I need to drop to doca-verbs for this?" — load to answer, but expect "no, stay in the higher-level library" unless the user can name the verb / opcode / option the higher-level library does not surface.

  • The user wants a specific raw WR flag, QP option, SRQ feature, custom CQ-handling pattern, or congestion-control group attachment the higher-level library does not expose.

  • The user is porting libibverbs code into the DOCA Core model and needs the integration path (lifecycle, progress engine, no-mixing).

  • A DOCA_ERROR_* from a doca_verbs_* call needs diagnosis — including IO_FAILED, where the answer lives on the completion-queue entry, not the submit return.

  • Designing non-C bindings wrapping the verbs C ABI that must honor the boundary, lifecycle, and cap-query rules.

Do not load for: general RDMA (doca-rdma/SKILL.md); Ethernet queueing (doca-eth/SKILL.md); timing-precise media (doca-rmax/SKILL.md); cases another higher-level library covers (doca-flow/SKILL.md for steering, doca-sta/SKILL.md for NVMe-oF target acceleration); DOCA install (doca-setup/SKILL.md); or general orientation — all routed via doca-public-knowledge-map/SKILL.md.

What this skill provides

This is a thin loader. The substantive raw-verbs material lives in two companion files:

  • CAPABILITIES.md — what doca-verbs can express on this version: the higher-level-vs-verbs selection table, the libibverbs boundary, the verbs object model (doca_verbs_context + QP / CQ / PD / MR / SRQ / Address-Handle / Completion-Channel / Ethernet-SQ / Ethernet-RQ / CC-group), the capability-query surface (doca_verbs_query_device + doca_verbs_device_attr_get_*), the error taxonomy (mapped onto DOCA_ERROR_* with the IO_FAILED → completion-entry overlay), the observability surface (progress engine vs manual CQ polling vs comp-channel delivery), and the safety policy gating the no-mixing-with-libibverbs rule.

  • TASKS.md — workflows for the six in-scope verbs: configure, build, modify, run, test, debug, plus a Deferred task verbs block. Every workflow assumes the drop-down decision above was made; ## configure re-confirms it.

The skill assumes DOCA is installed and the user has the privileges their install profile expects (RDMA stack on host, same as doca-rdma/SKILL.md). It does not cover installing DOCA — route to doca-setup/SKILL.md.

What this skill deliberately does not ship

This skill is agent guidance, not a samples or templates bundle. It deliberately does not contain — and pull requests should not add:

  • Pre-written DOCA Verbs application source code, in any language. The verified verbs source is the shipped C samples on the install (via ls /opt/mellanox/doca/samples/); the agent routes there and prescribes a minimum-diff modification via the modify-a-sample workflow in doca-programming-guide/SKILL.md, layered with the verbs overrides in TASKS.md ## modify.

  • Standalone build manifests (meson.build, CMakeLists.txt, Cargo.toml, …) parked inside the skill. The agent constructs the manifest in the user's project against the installed DOCA, where pkg-config --modversion doca-verbs is the source of truth.

  • A samples/, bindings/, or reference/ subtree of any kind. A mock artifact labeled "reference" reads as buildable and misleads.

  • A migration script from libibverbs to doca-verbs. Porting is judgment, not mechanical replacement — see TASKS.md ## modify.

Loading order

  1. Confirm the question is in scope by walking the drop-down decision above.

  2. For the higher-level-vs-verbs split, the libibverbs boundary, the object model, capability discovery, error taxonomy, observability, and safety policy, see CAPABILITIES.md.

  3. For step-by-step workflows — configure, build, modify, run, test, debug — see TASKS.md.

Both companion files cross-link to each other, to the higher-level libraries (doca-rdma/SKILL.md, doca-eth/SKILL.md, doca-rmax/SKILL.md) as climb-back homes, to doca-common/SKILL.md for the doca_dev / doca_pe / doca_ctx foundation primitives, to doca-version/SKILL.md for canonical version rules, and to doca-public-knowledge-map/SKILL.md whenever the right answer is "look it up in the public docs or the install layout".

Related skills

When a step below routes to another skill that is not already loaded, read that skill first; if unavailable, stop and name it and the layer it covers — do not continue that layer from memory.

  • doca-rdma/SKILL.md — the canonical higher-level RDMA library and the home this skill routes most RDMA users back to. Any conversation loading doca-verbs for an RDMA question should also load doca-rdma so the climb-back answer is immediate.

  • doca-eth/SKILL.md — the higher-level Ethernet queue library. doca-verbs also exposes Ethernet SQ / RQ verbs (doca_verbs_eth_sq_*, doca_verbs_eth_rq_*); once the user confirms doca-eth lacks the needed option (TS-source-type tuning, plane-index pinning, multi-pkt-send-WQE), this skill takes over.

  • doca-rmax/SKILL.md — the higher-level Rivermax library for timing-precise media. Most Rivermax cases stay there; raw verbs is the escape hatch for the rare case needing a verb Rivermax does not expose.

  • doca-common/SKILL.md — the foundation every DOCA context (including doca_verbs_context) rests on: doca_dev / doca_pe / doca_ctx, the doca_devinfo cap-query rule, and the lifecycle. This skill layers verbs specifics on top.

  • doca-public-knowledge-map/SKILL.md — the routing table for public DOCA docs and the install layout; the DOCA Verbs public guide is listed there.

  • doca-setup/SKILL.md — env preparation, install verification, and the no install yet path via the NGC DOCA container. This skill assumes its preconditions hold.

  • doca-version/SKILL.md — canonical DOCA version-handling rules. ## Version compatibility cross-links the four-way match rule (with doca-verbs.pc joining the match set) and the cap-query-is-runtime-authority rule.

  • doca-structured-tools-contract/SKILL.md — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in TASKS.md honors it.

  • doca-programming-guide/SKILL.md — general DOCA programming patterns shared by every library: pkg-config + meson build, modify-a-shipped-sample first-app, the universal lifecycle, the DOCA_ERROR_* taxonomy, and the debug order. This skill layers raw-verbs specifics on top.

  • doca-debug/SKILL.md — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). Raw-verbs debug (completion-entry inspection, no-mixing-with-libibverbs, lifecycle in verbs terms) overlays on top.

  • doca-hardware-safety/SKILL.md — the cross-cutting hardware-safety meta-policy this skill's ## Safety policy overlays.

Files

references/use.md

use

Goal: walk the verbs object-use sequence — the exact sequence of doca_verbs_* calls that follows a healthy ## configure on the live raw-verbs context.

This verb is the use-the-verbs-context counterpart to ## configure: it names the sequence so the agent can quote it the same way every time, whether the user is on the RDMA-side, the Ethernet-queue side, or porting from libibverbs.

The use sequence, in order, on top of the doca-common foundation walked in doca-common TASKS.md ## use (doca-common/TASKS.md#use):

  1. doca_verbs_context_create(dev, &ctx) — wrap the doca_dev opened in doca-common TASKS.md ## use (doca-common/TASKS.md#use) step 4 in a verbs context. The ctx handle is the root of the per-library object set.

  2. doca_verbs_pd_create(ctx, &pd) — create the protection domain. Every QP / MR / AH attached to this verbs context lives inside this PD.

  3. (Optional) Create the completion channel. If the user picked the comp-channel completion path (per CAPABILITIES.md ## Observability), call doca_verbs_comp_channel_create(ctx, &chan). The channel must exist before the CQ that will use it.

  4. Create the CQ(s). Build a doca_verbs_cq_attr via the doca_verbs_cq_attr_create + _set_* family (size, overrun, collapsed, entry size). For the comp-channel path, attach the already-created channel with doca_verbs_cq_attr_set_comp_channel BEFORE doca_verbs_cq_create(ctx, cq_attr, &cq). One CQ per send / receive direction is the common case; shared send-and-receive CQs are valid when the user has named that as the shape.

  5. (Optional) Create the SRQ(s). Build a doca_verbs_srq_init_attr via the doca_verbs_srq_init_attr_create

    • _set_* family, then doca_verbs_srq_create(ctx, init_attr, &srq). Use when multiple QPs share a receive queue.

  6. (Optional) Create the CC group. If the user is attaching a congestion-control group, build a doca_verbs_cc_group_attr via doca_verbs_cc_group_attr_create

    • _set_hint, then doca_verbs_cc_group_create(ctx, group_attr, &cc_group). Attach to the QP via doca_verbs_qp_attr_set_cc_group during the QP modify.

  7. Build the QP. doca_verbs_qp_init_attr_create(&init_attr) → call the doca_verbs_qp_init_attr_set_* setters to wire set_pd(pd), set_send_cq(send_cq), set_receive_cq(receive_cq), set_sq_wr(...), set_rq_wr(...), set_send_max_sges(...), set_receive_max_sges(...), set_max_inline_data(...), set_qp_type(...), plus any feature-specific setter the cap-query allowed (set_send_dbr_mode, set_ordering_semantic, set_cqe_inline, set_dpa, …) → doca_verbs_qp_create(ctx, init_attr, &qp). Destroy the init_attr after with doca_verbs_qp_init_attr_destroy (it holds only the init-time spec; the QP object owns its own state).

  8. Drive the QP state machine. Build a doca_verbs_qp_attr via doca_verbs_qp_attr_create + _set_current_state / _set_next_state plus the per-state required setters (path MTU / PKey index / port num / SQ-PSN / RQ-PSN / dest QP num / AH attributes / atomic mode / retry / RNR / timeout for an RC QP; the subset varies by QP type). Apply each transition via doca_verbs_qp_modify(qp, qp_attr) until the QP is in the in-use state (RTS for RC). Destroy the qp_attr after with doca_verbs_qp_attr_destroy.

  9. Connect the PE. doca_pe_connect_ctx(pe, ctx_as_doca_ctx) so completions on this context surface through doca_pe_progress. This step must happen BEFORE doca_ctx_start; the verbs context's doca_ctx * is accessible through the standard DOCA Core bridge accessors.

  10. doca_ctx_start(ctx_as_doca_ctx) — transition the verbs context to RUNNING. From this point WR submission is allowed.

  11. Post WRs. The submit family is the doca_verbs_bridge_* surface: doca_verbs_bridge_post_send(qp, wr, ...) for send WRs, doca_verbs_bridge_post_recv(qp, wr, ...) for receive WRs, doca_verbs_bridge_post_srq_recv(srq, wr, ...) for SRQ receives. The submit return is DOCA_SUCCESS / DOCA_ERROR_*; on success the WR is in flight and completion is reported on the chosen completion path.

  12. Drain completions. PE path: doca_pe_progress(pe) in the main loop. Manual path: doca_verbs_bridge_poll_cq(cq, ...) in the main loop. Comp-channel path: doca_verbs_req_notify_cq to arm → epoll/poll on the doca_verbs_comp_channel_get_handle fd → on event, doca_verbs_get_cq_event(chan, ...) to drain → doca_verbs_ack_cq_events(cq, n) to ACK → re-arm with doca_verbs_req_notify_cq.

  13. (Optional) Wire async events. doca_verbs_get_async_event_handle(ctx) returns an OS handle; epoll it and call doca_verbs_get_async_event / doca_verbs_ack_async_event on fire to surface device-level events (QP fatal, port state change) that do not appear on the data-plane CQ.

  14. Shutdown. Drain inflight WRs (loop the chosen completion path until quiet); transition the QP through the destroy- appropriate state (typically ERR via doca_verbs_qp_modify(qp, qp_attr_to_err)); doca_ctx_stop; destroy in reverse order — QP → SRQ → CQ → CC group → comp channel → PD → doca_verbs_context_destroy(ctx). Per CAPABILITIES.md ## Safety policy, destroying a parent (PD, context) before its children (QP, CQ) is DOCA_ERROR_BAD_STATE.

The agent's rule: the order of the selected objects is the contract. Optional steps 3, 5, and 6 impose ordering only when their objects are used: a completion channel precedes its CQ, and an SRQ or CC group precedes the QP configuration that references it. Violating a selected object's API preconditions can return DOCA_ERROR_BAD_STATE; misordering step 14 destroy-targets can do the same. The cost of getting the order right once is much lower than the cost of debugging a misordered destroy in production.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: 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.

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/doca-verbs · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-verbs.zip