doca-common

# 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, C