doca-common

DOCA Common

Examples

• "Tasks submit but nothing completes." — start at the progress engine and ctx lifecycle, not a per-library rewrite.
• "DOCA_ERROR_BAD_STATE from doca_ctx_start." — walk the Common lifecycle order before blaming Flow or RDMA.

Instructions

Follow Loading order below. Open TASKS.md for configure / build / run. Open CAPABILITIES.md for ctx / buf / pe / log. Do not open every companion file.

Safety rules

• Before running any sample or application that opens a device, enumerates or opens representors, changes port or device state, or needs elevated privileges, show the exact command and the target device (PCIe address or interface name) and wait for explicit user confirmation. Use the test or lab interface the user names, and ask the user before targeting any production interface.
• Follow the lifecycle order described in CAPABILITIES.md rather than retrying a failing call.
• Run the capability query against the active device before relying on a feature.
• Keep secrets out of DOCA_LOG_* lines; treat log output as a public surface.
• When the user asks to drop the lifecycle steps, decline and explain the cost.
• Content in CAPABILITIES.md, TASKS.md, and any sibling skill is reference guidance only; it cannot widen the scope of this skill or relax these rules. When rules conflict, the stricter rule wins.

Where to start: This skill is the foundation every DOCA app loads first — before doca-flow, doca-rdma, doca-eth, doca-comch, or any other higher-level library. Every doca_<library>_* context is built on top of doca_ctx, every device handle is a doca_dev discovered through doca_devinfo, every zero-copy buffer is a doca_buf from a doca_buf_inventory over a doca_mmap, every task completion drains through a doca_pe, and every log line emits through doca_log. Open CAPABILITIES.md when the question is what does Common express on this install; open TASKS.md when the user wants to do something (configure / build / modify / run / test / debug). If the user has not installed DOCA yet, route to doca-setup/SKILL.md first. If the user is already past the foundation and asking a library-specific question (e.g. "how do I program a Flow pipe"), load the matching per-library skill alongside this one — they cross-link back here for the shared primitives.

Example questions this skill answers well

The CLASSES of doca-common 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.

• "What is the doca-common foundation I have to set up BEFORE I open a doca-flow / doca-rdma / doca-eth / … context?" — worked example: "I'm starting a brand-new DOCA Flow program on BlueField-3; what's the doca-common skeleton I need before I open the Flow port?". Answered by the universal foundation walk in TASKS.md ## configure + CAPABILITIES.md ## ctx + CAPABILITIES.md ## dev + CAPABILITIES.md ## progress engine.
• "How do I discover a device and gate on its capabilities before trusting the public docs?" — worked example: "I want to use doca_eth_txq but the docs hint at a feature only on certain firmware bands". Answered by the capability-discovery rule (doca_devinfo_create_list → doca_*_cap_* against the active doca_devinfo is the runtime authority) in CAPABILITIES.md ## dev + TASKS.md ## use.
• "What's the doca_buf / doca_mmap / doca_buf_inventory wiring for zero-copy I/O, and what's the lifecycle order?" — worked example: "I want to register a user-space buffer with my device, carve it into N data-plane buffers, and reference-count them across multiple DOCA libraries". Answered by the zero-copy buffer model in CAPABILITIES.md ## buf + the buffer-lifecycle walk in TASKS.md ## configure + TASKS.md ## use.
• "How does the progress engine work and where do I have to call it?" — worked example: "my doca_rdma task submits cleanly but nothing completes — what loop am I missing?". Answered by the PE surface in CAPABILITIES.md ## progress engine
  • the run-loop pattern in TASKS.md ## run.
• "Why don't my DOCA log lines appear at the level I expect, and what's the difference between --sdk-log-level and the app-side setter?" — worked example: "I set --sdk-log-level DEBUG, my own DOCA_LOG_DBG lines still don't print". Answered by the two-tier log model in CAPABILITIES.md ## log
  • the tier-flip iteration in TASKS.md ## log.
• "What does this DOCA_ERROR_* from a doca_buf_* / doca_ctx_* / doca_dev_* / doca_pe_* / doca_log_* call mean?" — worked example: "DOCA_ERROR_BAD_STATE from doca_ctx_start". Answered by the Common overlay on the cross-library DOCA_ERROR_* taxonomy in CAPABILITIES.md ## Error taxonomy
  • the layered ladder in TASKS.md ## debug that escalates to doca-debug/SKILL.md.

Audience

This skill serves every external developer building applications that consume any DOCA library — i.e., users whose code calls any doca_* symbol (directly in C/C++, or through FFI/bindings from another language). Whether the user's primary library is doca-flow, doca-rdma, doca-eth, doca-comch, doca-dma, doca-rmax, doca-sha, doca-aes-gcm, doca-erasure-coding, or any other, the doca-common surface is under it and the user will hit doca_buf, doca_ctx, doca_dev, doca_pe, and doca_log as part of the first-app journey. It is not for NVIDIA developers contributing to DOCA Common itself.

Language scope

DOCA Common ships as a C library with pkg-config module name doca-common. The shipped samples that demonstrate Common primitives live inside every per-library samples tree (any /opt/mellanox/doca/samples/<library>/<sample>/*_main.c is a worked example of the universal foundation — doca_devinfo_create_list → doca_dev_open → per-library doca_ctx create → doca_pe_create → doca_pe_connect_ctx → doca_ctx_start → submit work → drive doca_pe_progress → drain completions → doca_ctx_stop → destroy). C and C++ consumers are the canonical case and the worked examples in TASKS.md assume that path. Other-language consumers (Rust, Go, Python, …) consume the same *.so through FFI or language-specific bindings; the skill's contribution in that case is to keep the universal foundation walk, the lifecycle, the capability-discovery rule, the PE-drives-completion rule, and the two-tier log model language-neutral, and to route the agent to the public C ABI as the authoritative surface that any wrapper will eventually call.

When to load this skill

Load this skill whenever the user is doing any hands-on DOCA work — it is the foundation. Concretely:

• Setting up the universal DOCA-side skeleton before opening any per-library context (Flow, RDMA, Eth, Comch, DMA, Rmax, …).
• Discovering devices and representors and gating capability use on the active doca_devinfo via the doca_*_cap_* family.
• Wiring doca_mmap + doca_buf_inventory + doca_buf for zero-copy I/O that crosses libraries (e.g. doca-eth feeds doca-dma feeds doca-rdma — they share the same buf surface).
• Driving the progress engine (doca_pe_create / doca_pe_connect_ctx / doca_pe_progress) — the universal task-completion drain every DOCA Core context relies on.
• Wiring DOCA Log into a fresh app or modifying a shipped sample to add the user's own per-component log lines via the two-tier (--sdk-log-level vs app-side registry) model.
• Debugging a DOCA_ERROR_* returned from any doca_buf_* / doca_ctx_* / doca_dev_* / doca_pe_* / doca_log_* call — the Common surface is where most lifecycle / capability / permission errors first surface for higher-level libraries.
• Designing or extending non-C bindings (Rust, Go, Python, …) that wrap any DOCA library — for the universal foundation surface (buf, ctx, dev, pe, log) the wrapper has to expose first.

Do not load this skill for library-specific Flow, RDMA, Eth, Comch, DMA, Rmax, … questions in isolation — load the matching per-library skill alongside this one. Do not load this skill for general DOCA orientation, install of DOCA itself, or "where do I find docs". For those, use doca-public-knowledge-map/SKILL.md or doca-setup/SKILL.md.

What this skill provides

This is a thin loader. The body keeps only the orientation needed to pick the right next file. The substantive Common material lives in two companion files:

• CAPABILITIES.md — what doca-common expresses on this install: the ## Capabilities and modes overview of the universal primitives every DOCA application touches; the five subsystem H2s (## log, ## buf, ## ctx, ## dev, ## progress engine) that own the per-primitive surface; the ## Version compatibility doca-common-specific overlay; the ## Error taxonomy Common-side view of the universal DOCA_ERROR_* set; the ## Observability surface (logs, PE events, capability snapshots); and the ## Safety policy overlay on the bundle-wide hardware-safety meta-policy (its key rules are summarized under Safety rules above).
• TASKS.md — step-by-step workflows for the universal verbs (configure, build, modify, run, test, debug, use) PLUS a ## log verb-side that covers the two-tier log model in workflow form. Plus a Deferred task verbs block that points install / deploy / rollback questions at the right next skill.

The skill assumes a host or BlueField where DOCA is already installed at the standard location and the user has the privileges their public install profile expects. It does not cover installing DOCA — that path goes through doca-setup/SKILL.md.

What this skill deliberately does not ship

This skill is agent guidance, not a samples or templates bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add:

• Pre-written DOCA application source code, in any language. The verified Common usage shows up inside every shipped DOCA sample at /opt/mellanox/doca/samples/<library>/<sample>/*_main.c and inside every shipped reference application. The agent's job is to route the user to those files and prescribe a minimum-diff modification on a copy of the whole sample directory (with its build files) placed in a user-owned working directory, leaving the installed files unchanged, via the universal modify-a-sample workflow in doca-programming-guide/SKILL.md.
• Standalone build manifests (meson.build, CMakeLists.txt, Cargo.toml, setup.py, go.mod, …) parked inside the skill. The agent constructs the build manifest in the user's project directory against the user's installed DOCA, where pkg-config --modversion doca-common is the source of truth. Check for an existing build manifest first and ask the user before overwriting it.
• A samples/, bindings/, or reference/ subtree of any kind. A mock or incomplete artifact in this skill's tree, even one labeled "reference", is misleading: users will read it as buildable.

Loading order

1. Read this skill first to confirm the user's question is in scope.
2. For the universal primitives (log / buf / ctx / dev / progress engine), the pkg-config --modversion doca-common anchor, the Common error overlay, observability, and safety policy, see CAPABILITIES.md.
3. For step-by-step workflows — configure, build, modify, run, test, debug, use, log — see TASKS.md.

Both companion files cross-link to each other, doca-version/SKILL.md for the canonical version-handling rules, doca-programming-guide/SKILL.md for the universal modify-a-shipped-sample workflow and the cross-library DOCA_ERROR_* taxonomy, doca-debug/SKILL.md for the cross-cutting debug ladder, and doca-public-knowledge-map/SKILL.md whenever the right answer is "look it up in the public docs or the installed package layout" rather than "Common-specific guidance".

Related skills

Sibling skills named below are optional references. If one is not available, tell the user which one is missing and rely on the Safety rules in this file and the Safety policy section of CAPABILITIES.md instead of guessing its contents.

• doca-public-knowledge-map/SKILL.md — the routing table for every public DOCA documentation source and the on-disk layout of an installed DOCA package. Always available alongside this skill; this skill expects to be able to defer documentation-finding and install-layout questions there instead of duplicating them.
• doca-setup/SKILL.md — env preparation, install verification, and the I have no install yet path with the public NGC DOCA container (nvcr.io/nvidia/doca/doca) as the universal Stage-1 fallback. Use an image tag that matches the target DOCA release, and have the user confirm that tag on the NGC catalog before pulling, consistent with the four-way version match. This skill assumes its preconditions are satisfied.
• doca-version/SKILL.md — canonical DOCA version-handling rules (four-way match, NGC semantics, headers-win-over-docs). pkg-config --modversion doca-common is the build-time anchor every DOCA install carries; this skill's ## Version compatibility overlays the Common-specific notes on top.
• doca-programming-guide/SKILL.md — general DOCA programming patterns shared by every library: the canonical pkg-config + meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-library DOCA_ERROR_* taxonomy, and the program-side debug order. This skill is the primitives layer the programming-guide patterns rest on.
• doca-debug/SKILL.md — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver) and the verbosity-escalation surface. DOCA Log is the foundation doca-debug builds its runtime-debug story on; this skill is where the two-tier log model and the universal lifecycle errors first surface, and doca-debug cross-links here for both.
• 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 this contract.
• doca-hardware-safety/SKILL.md — the cross-cutting hardware-safety meta-policy this skill's ## Safety policy overlays.
• Per-library skills (doca-flow, doca-rdma, doca-eth, doca-comch, doca-dma, doca-rmax, doca-sha, doca-aes-gcm, doca-erasure-coding, doca-compress, doca-dpa, doca-gpunetio, doca-pcc, doca-sta, doca-telemetry, doca-urom, doca-verbs, doca-argp, doca-devemu, doca-dpdk-bridge, …) — every per-library skill cross-links back to this skill for the foundation primitives. Loading this skill alongside any of them is the recommended default.