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 the tasks companion for configure / build / run. Open the capabilities companion for ctx / buf / pe / log. Do not open every companion file. **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 the capabilities companion when the question is *what does Common express* on this install; open the tasks companion 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 ## configure + ## ctx + ## dev + ## 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 ## dev + ## 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 ## buf + the buffer-lifecycle walk in ## configure + ## 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 ## progress engine + the run-loop pattern in ## 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 ## log + the tier-flip iteration in ## 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 ## Error taxonomy + the layered ladder in ## 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 the tasks companion 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: - the capabilities companion — 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. - the tasks companion — 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 them 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. - **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 the capabilities companion.** 3. **For step-by-step workflows — configure, build, modify, run, test, debug, use, log — see the tasks companion.** 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 - `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. 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 the tasks companion 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.