doca-flow

# 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:

```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
```

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 that is not in the installed
   headers.** Grep the header for the closest real symbol, name it in
   the refusal, and stop without generating code. A later, explicit
   request using the verified symbol may begin a new build workflow;
   do not silently substitute it in the current request.
4. **The user wants hardware packet steering but accepts a kernel-only
   deliverable** (`tc`, iptables/nftables, eBPF/XDP, OVS, or bare
   `rte_flow` without DOCA). Refuse per
   [Non-negotiable](#non-negotiable-the-deliverable-uses-doca-flow-not-kernel-tciptables)
   above; route to the shipped-sample + DOCA Flow build path instead.

Output shape when pushing back:

```text
REFUSED: <one-sentence summary>
Reason: <2-4 bullets, each tied to a hardware or API constraint>
Suggested alternative: <pipe-graph sketch, or "this is not expressible in DOCA Flow">
```

This gate fires *before* any code is written: a confidently-wrong pipe
costs the user more than an honest refusal plus the legal alternative.

## Exampl