/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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - common
    - core
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}.
  The validation steps require a live DOCA install.

DOCA Common

Examples

• **"Tasks submit but nothing completes."** — start at the progress

engine and ctx lifecycle, not a per-library rewrite.

• **"DOCA_ERROR_BAD_STATE from doca_ctx_start."** — walk the Common

lifecycle order before blaming Flow or RDMA.

Instructions

Follow Loading order below. Open the tasks companion for configure / build / run. Open the capabilities companion for ctx / buf / pe / log. Do not open every companion file.

**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 the capabilities companion when the question is *what does Common express* on this install; open the tasks companion 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/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

configure +

ctx +

dev +

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

dev +

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

buf +

the buffer-lifecycle walk in

configure +

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

progress engine

• the run-loop pattern in ## 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 60` (DEBUG), my own `DOCA_LOG_DBG` lines still don't print"*. Answered by the two-tier log model in ## log

• the tier-flip iteration in ## 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

Error taxonomy

• the layered ladder in

debug that escalates to

`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`, `doc