Doca Programming Guide

DOCA programming guide

Where to start: Read ## Audience to confirm the user is consuming DOCA, not contributing to it. Then jump to the H2 that matches the verb (## modify for first-app derivation, ## build for the canonical build pattern, ## test for the test loop, ## debug for the program-class debug ladder).

Example questions this skill answers well

These are the CLASSES of program-class questions the skill is built to answer, each with one worked example. Library-specific overlays (Flow / DMS / Caps / …) live in the matching library skill; this skill answers the library-agnostic shape.

• "How do I write my first DOCA program for <any library>?" — worked example: "I want to write my first DOCA Flow application." Answered by the modify-a-shipped-sample workflow in TASKS.md ## modify plus the canonical build pattern in TASKS.md ## build.
• "What's the right build line for any DOCA library?" — worked example: "How do I compile a program that calls doca_rdma_*?" Answered by the pkg-config doca-<library> pattern in TASKS.md ## build (C/C++ Track 1) and the FFI/bindings pattern in Track 2.
• "What's the lifecycle every DOCA object follows?" — worked example: "What's the right order of doca_flow_pipe_* calls in my program?" Answered by the cfg-create / init / start / use / stop / destroy template in CAPABILITIES.md ## Capabilities and modes.
• "DOCA_ERROR_* came back — what does it mean and what do I do?" — worked example: "My code got DOCA_ERROR_BAD_STATE." Answered by the cross-library doca_error_get_descr() rule in CAPABILITIES.md ## Error taxonomy
  • the program-class debug order in TASKS.md ## debug.
• "My program built and started, but does nothing on the wire." — worked example: "My Flow program runs cleanly but no traffic is matched." Answered by the validate-before-commit rule in CAPABILITIES.md ## Safety policy and the layered program-class debug ladder in TASKS.md ## debug.
• "What does <language> consumer of DOCA look like (FFI / bindings)?" — worked example: "How do I call DOCA Comch from Rust without writing C?" Answered by Track 2 of TASKS.md ## build (FFI against the public C ABI) and the language-neutral lifecycle in CAPABILITIES.md ## Capabilities and modes.
• "How should I classify and build all the shipped DOCA samples and applications? What's the difference between a sample and an application?" — worked example: "I tried to build all DOCA apps and 20/159 failed — which ones are real regressions vs missing optional stacks?" Answered by the sample-vs-application model and the category / dependency / skip-vs-fail taxonomy in TASKS.md ## sample-and-app-categorization, which separates "the SDK is broken" from "the optional GPU / RMAX / MPI stack is not on this BlueField".

If the question is env-class (install / build env / hugepages / devices), route to doca-setup. If it is library-specific (Flow pipe topology, RDMA QP setup, DMS service deploy), layer the matching library skill on top.

Audience

This skill serves external developers building applications that consume DOCA libraries — i.e., users whose code calls one or more doca_<library>_* symbols (directly in C/C++, or through FFI / bindings from another language). It is programming with DOCA, not programming of DOCA: it is not for NVIDIA developers contributing to DOCA itself, and it does not assume access to the DOCA source tree, internal NVIDIA tooling, or any non-public information. The only inputs it ever points the agent at are the ones any external user has: the public docs at docs.nvidia.com/doca/sdk/, the public catalog at catalog.ngc.nvidia.com, the public GitHub repos under github.com/NVIDIA / github.com/NVIDIA-DOCA, the public developer forum, and the on-disk /opt/mellanox/doca tree that the public DOCA install (or the public NGC DOCA container, nvcr.io/nvidia/doca/doca) puts on the user's host. Where to find and how to install questions are routed elsewhere — see Related skills below.

Language scope. DOCA itself is a C library family; every shipped sample in /opt/mellanox/doca/samples/ and every shipped reference application in /opt/mellanox/doca/applications/ is C. C and C++ consumers are the canonical case for every prescriptive workflow in this skill. Other-language consumers (Rust, Go, Python, …) consume the same *.so libraries through FFI or language-specific bindings against the public C ABI; the skill keeps the lifecycle, capability, error, observability, and safety guidance language-neutral, and routes the language-specific build / FFI work back to the consumer's own toolchain without authoring wrappers.

When to load this skill

Load this skill when the user has DOCA installed and the env-class preconditions are already satisfied (i.e., doca-setup has produced a clean install where pkg-config doca-<library> resolves, hugepages are mounted, and devices are visible), and is now asking a question about how to actually program against DOCA in a library-agnostic way:

• Understanding what DOCA's pieces are (libraries, apps, services, tools) and which side of the wire they run on.
• The canonical pkg-config + meson build pattern any DOCA application follows, regardless of which library it consumes.
• The universal derive a custom first application from a shipped sample workflow that every library skill extends with library-specific overrides — moved here from doca-setup because it is a programming verb, not an env verb.
• The universal DOCA lifecycle (cfg-create → init → start → use → stop → destroy) and how it manifests across libraries.
• The general DOCA_ERROR_* pattern, doca_error_t, and doca_error_get_descr() — the cross-library shape, not Flow- or RDMA-specific overlays.
• The validate-before-commit rule and the program-side safety policy that every library skill inherits.
• Programming patterns that apply to consumers in any language (C/C++ directly, FFI / bindings for Rust / Go / Python / …) — the skill keeps the patterns language-neutral and points the agent at the public C ABI as the authoritative surface.

Do not load this skill for:

• "Is my install healthy? Why does pkg-config not find doca-flow? How do I mount hugepages? I don't have DOCA installed yet — can I use a container?" — env-class questions belong in doca-setup, which owns install verification, env preparation, env-class debugging, and the no-install → NGC container fallback path for any user on macOS, Windows, or Linux without DOCA.
• "What is DOCA? Where is the Flow programming guide? Which package do I install?" — routing / orientation questions belong in doca-public-knowledge-map.
• "How do I construct a Flow pipe / set up an RDMA queue / use Comch to send a message?" — library-internal API questions belong in the matching library skill (e.g. doca-flow).