doca-flow

Files (8)

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

SKILL.md (first lines)

# DOCA Flow

## Examples

- **“How do I bring up a Flow port on a representor?”** — this is in
  scope. Use the installed header and a shipped sample; do not author
  a first-app `main.c`.
- **“Match 5-tuple and send to a queue.”** — express it as a Flow
  pipe. Do not fall back to kernel tc or iptables.

## Instructions

Follow Loading order below. Open the tasks companion for configure /
modify / debug. Open the capabilities companion for the pipe-spec
schema and safety policy.
For connection tracking, read the tasks companion's `flow-ct` section
before starting ports: CT initialization is process-global and must precede
port start. Adding CT to running ports requires an approved interruption
and reconstruction from a captured configuration, not a per-port
`doca_ctx_start` call or reuse of invalidated pipe handles.

## Non-negotiable: first app is NGC pull + a shipped sample, not authored C

When the user is new to DOCA, has docker, has no host DOCA, or asks
for a first Flow app, do this **before host `pkg-config` and before
any source listing**:

1. **Bundle first.** This answer follows the local doca-skills
   bundle: `doca-setup/SKILL.md` (Stage 1 vs
   Stage 2), `doca-programming-guide/SKILL.md`
   (modify a shipped sample), this `doca-flow` skill, and
   `doca-public-knowledge-map/SKILL.md`.
   Name those skills. Do not invent other skill names.
2. **Stage 1 vs Stage 2 before any command.** Stage 1 = NGC container
   on a laptop (compile / learn; no real packets). Stage 2 = a real
   BlueField or ConnectX for pipe runtime. Docker compiles only; do
   not say the app works entirely inside docker.
3. **Path 0 (Stage 1).** Copy a tag from
   https://catalog.ngc.nvidia.com/orgs/nvidia/teams/doca/containers/doca/tags
   using *How to pick an NGC tag without guessing* — never invent one or
   use `latest`. Then `docker pull nvcr.io/nvidia/doca/doca:<tag>` and
   `docker run -it --rm -v $HOME/dev/doca-work:/work nvcr.io/nvidia/doca/doca:<tag> bash`
   (an empty dir, never `$HOME`). No invented `Dockerfile`, no source build.
4. **Resume inside the container (MUST, after `docker run`):** quote this
   hand-off — do not skip it for a full tutorial: "Paste back the output
   of `pkg-config --modversion doca-flow` and
   `ls /opt/mellanox/doca/samples/doca_flow/`." Then: "I resume from
   doca-programming-guide ## modify step 1 with the real install in
   hand." Name a directory that listing shows; copy it. If `ls` is
   empty, stop — do not scaffold. Use `doca-flow` on that `pkg-config`
   line, not `doca-common`.
5. **Never** emit a new `main.c`, `Makefile`, `Dockerfile`, or
   hand-typed `-l` / `-L` flags. Paste `pkg-config --libs doca-flow`.

## Non-negotiable: the deliverable uses DOCA Flow, not kernel tc/iptables

When this skill is in scope, the user is asking for **DOCA Flow**. After
the shipped-sample copy above, the binary you build **must link
`libdoca_flow` and exercise the `doca_flow_*` lifecycle** on the user's
installed DOCA — init, port start, pipe programming, entry commit, and
counter readback under traffic. Copy the call sequence from that
**shipped DOCA Flow sample** under `/opt/mellanox/doca/samples/doca_flow/`
and adapt it via ## configure /
## modify. Verify every symbol against
the installed header ([Ground rule](#ground-rule-verify-every-api-name-against-the-installed-header)
below) and the add-entry table in
## API surface and name guards.
Do **NOT** satisfy a hardware packet-steering / 5-tuple filter request
with kernel **`tc`/`flower`**, **`iptables`/`nftables`**, **eBPF/XDP**,
**OVS**, or bare **DPDK `rte_flow`** (without DOCA) and call it done.
Those may push a rule toward the NIC, but they completely bypass DOCA
Flow — which defeats the purpose of this library and loses the DOCA
model (pipe/entry lifecycle, hardware counters, capability discovery,
portability across BlueField/ConnectX generations).

"`tc flower skip_sw` also offloads to hardware" / "the kernel command
is fewer lines" is **not** an acceptable reason to bypass DOCA Flow.
The correct low-friction path is to start from a **shipped DOCA Flow
sample** under `/opt/mellanox/doca/samples/doca_flow/` and adapt it.

If `pkg-config doca-flow` (or the umbrella `pkg-config doca`) or the
DOCA build fails, **fix the build** (module name, `PKG_CONFIG_PATH`,
sample path, hugepages/EAL init) — do not silently fall back to `tc`.
A tool whose `ldd` shows no `libdoca_flow` is a failed DOCA Flow task,
regardless of whether a rule landed in the NIC. Verify explicitly with
`ldd ./your_app | grep -i libdoca_flow` before declaring success.

**Never invent a link line.** For `undefined reference` / link
failures, run `pkg-config --libs doca-flow` plus companion **module
names** (`doca-common`, `doca-argp`, `doca-dpdk-bridge`, `libdpdk`)
and paste that output. Those names stay on the pkg-config command;
never turn them into hand-typed `-l` / `-L` flags or a guessed
install path. The shipped sample's `meson.build` `dependency()` list
is the module set; `pkg-config` is the only translator into linker
flags.

**Where to start:** Open the tasks companion to *do* something
(configure / build / modify / run / test / debug); open
the capabilities companion when the question is *what can
Flow express* on this version. **You MUST open
## configure before writing or running
any port code** — its bring-up gate decides whether the binary launches
at all. If DOCA is not
installed yet, route to `doca-setup/SKILL.md` first.

## Ground rule: verify every API name against the installed header

Before quoting any `doca_*` / `DOCA_*` identifier, confirm it exists in
the user's installed headers — the header on the machine is ground
truth above prose, the API reference, blog posts, or memory:

```bash
for header in "$(pkg-config --variable=includedir doca-common)"/doca_flow*.h; do
  grep -n '<candidate_name>' "$header"
  # For a multi-line function declaration, print through its closing `);`.
  awk '/<candidate_name>[[:space:]]*\(/,/[)][[:space:]]*;/' "$header"
done
```

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills