doca-programming-guide

DOCA programming guide

Examples

• "How do I write my first DOCA program?" — copy a shipped sample and follow the modify workflow, then the canonical pkg-config + meson build. Docker / NGC can compile and link; runtime needs a real BlueField or ConnectX.
• "What's the lifecycle every DOCA object follows?" — create → configure → start → connect → use → stop → destroy. Configuration finishes before start.

Instructions

Follow Loading order below. Open the tasks companion for how-to and the capabilities companion for coverage. Do not open every companion file.

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). Docker / NGC is the build half, not the runtime half. The NGC container can compile and link. Flow pipe creation, RDMA QP ops, and any call that needs a doca_dev on a port need a real BlueField or ConnectX. Do not promise the app will work entirely inside docker.

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 have docker; help me build my first DOCA Flow app." Answered by the modify-a-shipped-sample workflow in

  modify plus the canonical build

  pattern in ## build. Say that docker / NGC builds and links, but runtime needs a real NIC or DPU.
• "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

  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 Core order create → configure → start → connect → use → stop → destroy in ## Capabilities and modes (cfg-create / init implement configure and finish before start).
• "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

  Error taxonomy

  • the program-class debug order in

  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

  Safety policy

  and the layered program-class debug ladder in

  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

  build (FFI against the public C

  ABI) and the language-neutral lifecycle in

  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

  sample-and-app-categorization,

  which separates "the SDK is broken" from "the optional GPU / RMAX / MPI stack is not on this BlueField".