About this skill
---
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`](CAPABILITIES.md) when
the question is *what does Common express* on this install; open
[`TASKS.md`](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`](../../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`](TASKS.md#configure) +
[`CAPABILITIES.md ## ctx`](CAPABILITIES.md#ctx) +
[`CAPABILITIES.md ## dev`](CAPABILITIES.md#dev) +
[`CAPABILITIES.md ## progress engine`](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`](CAPABILITIES.md#dev) +
[`TASKS.md ## use`](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`](CAPABILITIES.md#buf) +
the buffer-lifecycle walk in
[`TASKS.md ## configure`](TASKS.md#configure) +
[`TASKS.md ## use`](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`](CAPABILITIES.md#progress-engine)
+ the run-loop pattern in [`TASKS.md ## run`](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`](CAPABILITIES.md#log)
+ the tier-flip iteration in [`TASKS.md ## log`](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`](CAPABILITIES.md#error-taxonomy)
+ the layered ladder in
[`TASKS.md ## debug`](TASKS.md#debug) that escalates to
[`doca-debug`](../../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`](../../doca-public-knowledge-map/SKILL.md)
or [`doca-setup`](../../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.
- `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`](../../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`](../../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.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](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify, run,
test, debug, use, log — see [TASKS.md](TASKS.md).**
Both companion files cross-link to each other,
[`doca-version`](../../doca-version/SKILL.md) for the canonical
version-handling rules,
[`doca-programming-guide`](../../doca-programming-guide/SKILL.md)
for the universal modify-a-shipped-sample workflow and the
cross-library `DOCA_ERROR_*` taxonomy,
[`doca-debug`](../../doca-debug/SKILL.md) for the cross-cutting
debug ladder, and
[`doca-public-knowledge-map`](../../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`](../../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`](../../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`](../../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`](../../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`](../../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`](../../doca-structured-tools-contract/SKILL.md) —
the bundle's structured-tools precedence rule (detect / prefer /
fall back / report). The Command appendix in
[TASKS.md](TASKS.md) honors this contract.
- [`doca-hardware-safety`](../../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.