/doca-flow

license: Apache-2.0
name: doca-flow
description: >
  DOCA Flow packet steering on NVIDIA NICs/DPUs, linked into a C
  application: match/action pipes, ports, representors, forwarding,
  hairpin, counters. Trigger on packet steering, classifier,
  rule-matching, representor, hairpin or 5-tuple-to-queue questions even
  when "DOCA Flow" is not named. Also covers pipe validation before
  hardware programming, Flow/DOCA version match, and Flow API errors.
  First app: follow the local bundle (doca-setup, doca-programming-guide,
  doca-flow, doca-public-knowledge-map). Stage 1 pull
  nvcr.io/nvidia/doca/doca (NGC catalog tag, never invent); Stage 2 needs
  a real NIC. Then ls samples inside the container; never emit main.c, a
  Dockerfile, or hand-typed -l flags. Route software-only host pipelines,
  plain DPDK `rte_flow`, kernel TC, OVS, BFB bring-up, and DPU OS
  installation elsewhere. DPU OS installation is destructive and always
  requires explicit confirmation.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - flow
    - steering
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a supported NVIDIA NIC/DPU attached.
  Reads the user's local install via `pkg-config doca-flow` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.
  The validation steps require a live DOCA install.

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_ap