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 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.