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).
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
"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
"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
This skill serves every external developer building applications
that consume any DOCA library — i.e., users whose code calls anydoca_* 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
Read this SKILL.md first to confirm the user's question is in
scope.
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.
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, 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.
