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 ## modify. Verify every symbol against the installed header (Ground rule below) and the add-entry table in 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 to do something (configure / build / modify / run / test / debug); open CAPABILITIES.md when the question is what can Flow express on this version. You MUST open 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 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, 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 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).
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 above; route to the shipped-sample + DOCA Flow build path instead.

Output shape when pushing back:

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.

Example questions this skill answers well

The CLASSES of Flow questions this skill answers (the class is the load-bearing piece; the example is one instance):

• "How do I bring up a Flow port on a representor?" → TASKS.md ## configure + CAPABILITIES.md ## Capabilities and modes.
• "How do I express <match X, do Y> as a pipe?" → CAPABILITIES.md ## Capabilities and modes
  • TASKS.md ## modify.
• "Will this pipe spec program the HW, or will commit fail?" → CAPABILITIES.md ## Safety policy
  • TASKS.md ## test.
• "How do I read Flow counters to investigate observed traffic?" → CAPABILITIES.md ## Observability
  • TASKS.md ## debug.
• "My Flow port won't start — Failed to get hws cap / dest action ROOT … err -121." → device-placement signature (not a pipe bug); the steering plane belongs to the DPU Arm on a SEPARATED_HOST / NIC-mode BlueField. See the device-placement bullet in CAPABILITIES.md ## Capabilities and modes
  • TASKS.md ## configure step 2 + Step 0 of TASKS.md ## debug.
• "How do I add hardware-accelerated stateful 5-tuple connection tracking (aging, NAT) on top of my existing doca-flow setup?" → CAPABILITIES.md ## flow-ct + TASKS.md ## flow-ct.