doca-common

license	Apache-2.0
name	doca-common
description	Use this skill whenever the user is doing hands-on DOCA programming on a BlueField DPU or ConnectX NIC and needs the foundation primitives every per-library context rests on — walking the doca_ctx lifecycle, discovering doca_dev / doca_devinfo and gating on doca_*_cap_* before trusting a feature, wiring doca_mmap / doca_buf_inventory / doca_buf for zero-copy I/O across libraries, driving doca_pe for completions, or DOCA Log's two-tier (--sdk-log-level vs app-side) model. Trigger even when the user does not say "DOCA Common" — typical implicit phrasings include "my tasks submit but nothing completes", "DOCA_ERROR_BAD_STATE from doca_ctx_start", "--sdk-log-level does nothing for my DOCA_LOG_DBG lines", "share a buf between doca_dma and doca_rdma", or "crashes far from the offending line". Refuse and route elsewhere for per-library questions in isolation (load doca-flow / doca-rdma / doca-eth alongside), installing DOCA (doca-setup), or doc lookup (doca-public-knowledge-map).
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. doca-common is present on every healthy DOCA install; reads the user's local install via `pkg-config --modversion doca-common` and inspects /opt/mellanox/doca/{lib,include,samples,applications}.

DOCA Common

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 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

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 or doca-setup.

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.
• 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.

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.
• 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.md 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 for the canonical version-handling rules, doca-programming-guide for the universal modify-a-shipped-sample workflow and the cross-library DOCA_ERROR_* taxonomy, doca-debug for the cross-cutting debug ladder, and doca-public-knowledge-map 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 — 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 — 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 — 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 — 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 — 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 — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in TASKS.md honors this contract.
• doca-hardware-safety — 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, , , , , , , , , , , , , , , , …) — 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.