/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`](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