Doca Common Agent Skill

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

+ the run-loop pattern in 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

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

+ the layered ladder in

TASKS.md ## debug that escalates to

doca-debug.

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

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.