/doca-flow

name: doca-flow
license: Apache-2.0
description: >
  Build and debug DOCA Flow applications on supported NVIDIA NICs/DPUs:
  define match/action pipes, initialize ports and representors, choose
  forwarding targets, validate pipes before hardware programming, read
  counters, match the Flow version to the installed DOCA release, and
  diagnose Flow API errors. Trigger on DOCA packet steering, classifier,
  representor, rule-matching, hairpin, or 5-tuple-to-queue questions even
  when "DOCA Flow" is not named. Route 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:
  kind: library
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}.

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**. The program you produce **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 a **shipped DOCA Flow sample** under `/opt/mellanox/doca/samples/doca_flow/` and adapt it via [`TASKS.md ## configure`](TASKS.md#configure) / [`TASKS.md ## modify`](TASKS.md#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 [`CAPABILITIES.md ## API surface and name guards`](CAPABILITIES.md#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.

**Where to start:** Open [`TASKS.md`](TASKS.md) to *do* something (configure / build / modify / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can Flow express* on this version. **You MUST open [`TASKS.md ## configure`](TASKS.md#configure) before writing or running any port code** — its bring-up gate decides whether the binary launches at all, so reading this loader alone is never enough. If DOCA is not installed yet, route to [`doca-setup`](../../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:

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

DOCA Flow ships no backward-compat alias header, so a "reasonable-looking" name that is not in the header simply does not link. Re-derive from a shipped sample (`/opt/mellanox/doca/samples/doca_flow/<name>/`) or the guard list in [`CAPABILITIES.md ## API surface and name guards`](CAPABILITIES.md#api-surface-and-name-guards), never from prose.

Port bring-up: the gate lives in TASKS.md

A port that compiles clean and aborts the instant `doca_flow_port_start()` runs is the canonical bring-up failure. The bring-up gate (probe-before-count, `doca_flow_port_cfg_set_port_id()` plus the mode-appropriate device source — `doca_flow_port_cfg_set_dev()` in VNF mode or the installed switch sample's `doca_dev_rep` path — device taken from launch args not hard-coded, and the binary returning a non-zero exit from `main()` if the bridge cannot arm and forward) is enforced step-by-step in [`TASKS.md ## configure`](TASKS.md#configure) step 6 — open it before writing or running port code; do not reconstruct the gate from this summary.

When to refuse (push back before writing code)

Some requests cannot be satisfied as asked. **Refuse and explain — do not silently emit half-correct code — when:**

1. **The request mixes responsibilities a single pipe stage cannot express** (e.g. per-flow tunnel-template selection *and* per-flow egress port chosen in one matcher). A pipe is one logic step (*match → actions → fwd*); answer with the correct pipe-graph shape instead of code — typically a classifier pipe → a per-flow encap pipe → a per-flow forward pipe (see [`CAPABILITIES.md ## Pipe decomposition`](CAPABILITIES.md#pipe-decomposition-one-logic-step-per-pipe)). 2. **The request asks for something the hardware cannot do** (per-packet match on payload bytes outside L4, mutable match keys, …). Name the closest legal shape and stop. 3. **The request relies on an API name t