doca-programming-guide

Files (7)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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`](#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 &lt;language&gt; 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 some 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"*.

If the question is env-class (install / build env / hugepages /
devices), route to `doca-setup/SKILL.md`. 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/`](https://docs.nvidia.com/doca/sdk/),
the public catalog at
[`catalog.ngc.nvidia.com`](https://catalog.ngc.nvidia.com/), the
public GitHub repos under
[`github.com/NVIDIA`](https://github.com/NVIDIA) /
[`github.com/NVIDIA-DOCA`](https://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

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills