doca-flow-perf

# DOCA Flow Perf (`doca_flow_perf`)

**Where to start:** This is a tool skill for invoking
`doca_flow_perf`, the host-side / DPU-CPU-side DOCA Flow
performance measurement tool. Open [`TASKS.md`](TASKS.md) and
start at [`## configure`](TASKS.md#configure) to commit to
the three-axis decision (target Flow pipeline shape × traffic
class × measurement axis) and pick the JSON policy file that
expresses the workload, then [`## run`](TASKS.md#run) for the
single-iteration smoke, then [`## test`](TASKS.md#test) for
the iterative eval loop that produces a defensible
Kops/sec-class number. Open [`CAPABILITIES.md`](CAPABILITIES.md)
when the question is *what `doca_flow_perf` measures and what
it deliberately does not measure*, *how its DPDK and DOCA
backends differ behind the same JSON contract*, *how to
interpret the per-iteration CPU-cycle output*, or *how it
differs from `doca-flow-tune` (measurement vs. optimization)
and `doca-flow-dpa-perf` (host / DPU-CPU vs. DPA-offloaded
path)*. If DOCA is not installed, route to
[`doca-setup`](../../doca-setup/SKILL.md) first; if the
target measurement is the DPA-offloaded path, route to
[`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md)
instead; if the goal is to optimize an already-deployed Flow
pipeline rather than measure a synthetic one, route to
[`doca-flow-tune`](../doca-flow-tune/SKILL.md) — `flow-perf`
is a synthetic-driver microbenchmark, not a tuner of a live
Flow application.

## Example questions this skill answers well

- *"I want a defensible host-side baseline number for how
  many `doca-flow` rules per second a single BlueField-3 can
  insert for a 5-tuple match-and-hairpin workload. Which
  policy JSON do I start from, how do I make the result
  reproducible, and what do I have to capture alongside the
  number for it to be defensible?"* — class-shaped flow-perf
  baseline question; the agent walks the `configs/` library,
  the JSON contract, and the four-tuple capture rule.
- *"What is the difference between `doca-flow-perf`,
  `doca-flow-dpa-perf`, and `doca-flow-tune`? They all
  mention `doca-flow` and `perf` in their names — when do I
  reach for each?"* — measurement-vs-optimization plus
  host-vs-DPA-path; the agent surfaces the boundaries.
- *"My policy JSON looks like the example, but the reported
  Kops/sec is dramatically lower than the published numbers I
  see in NVIDIA's release notes. What variables do I have to
  control before I can trust the comparison?"* — methodology
  question; the agent walks the controllable axes (number of
  workers, queue depth, burst size, fixed-vs-incremented match
  fields, DPDK vs DOCA backend, BlueField mode, driver /
  firmware).
- *"I have a workload that does not match any of the shipped
  policy JSONs in `configs/`. How do I author a new policy
  JSON, what is the JSON schema in broad strokes, and what
  changes when I switch a match field from `mode: fixed` to
  `mode: increase`?"* — JSON authoring question; the agent
  walks the shipped configs as exemplars and refuses to
  invent schema fields not present in the source tree.
- *"What does the tool actually NOT measure? I am trying to
  understand whether a flow-perf number tells me anything
  about end-to-end traffic latency or just about the
  rule-programming control-plane rate."* — methodology
  perimeter question; the agent draws a hard line: this tool
  measures rule install / delete (control-plane) rate plus
  optional query rate, NOT dataplane latency, NOT dataplane
  throughput, NOT end-to-end application performance.
- *"I see two backends — DPDK and DOCA — behind the same
  JSON. When do I pick which, and what does the choice mean
  for the result I report?"* — backend choice question; the
  agent walks the DPDK-backend vs. DOCA-backend trade-off and
  insists the operator REPORT which one they used.

## Audience

Experienced AI agents and platform / network engineers who
are comfortable with the `doca-flow` programming model and
the DPDK control-plane, who want a *defensible* number for
the host-side / DPU-CPU-side Flow rule-install / rule-delete
rate. Readers are expected to know that the published
numbers in NVIDIA release notes are run with very specific
preconditions (specific DOCA version, specific BlueField
firmware, specific traffic class) and that any number they
produce locally must explicitly state those preconditions.

This skill is NOT for:

- operators who want to optimize an already-deployed
  `doca-flow` application — that is
  [`doca-flow-tune`](../doca-flow-tune/SKILL.md);
- operators measuring the DPA-offloaded Flow path — that is
  [`doca-flow-dpa-perf`](../doca-flow-dpa-perf/SKILL.md);
- operators measuring end-to-end dataplane throughput or
  latency — that is the application's responsibility,
  layered on
  [`doca-flow`](../../libs/doca-flow/SKILL.md);
- contributors authoring or modifying the tool itself.

## Language scope

User interaction with `doca_flow_perf` is via:

1. The shipped binary's command-line flags (documented by
   `doca_flow_perf --help` and the public DOCA Flow Perf
   guide on `docs.nvidia.com`).
2. A JSON policy file describing the pipeline (ports, pipes,
   matchers, actions, forwarding). The shipped `configs/`
   directory contains canned policies for the most common
   traffic classes; new policies are authored by copying and
   editing one of those.
3. The tool's per-iteration output (CPU cycles per iteration,
   number-processed, number-failed; reported via the tool's
   stdout — the exact format is the public guide and the
   binary's runtime output, NOT this skill's invention).

The skill itself is Markdown. There is no programmatic API on
top of `doca_flow_perf`; consumers of its results read its
stdout / captured logs.

## When to load this skill

Load `doca-flow-perf` when ANY of the following is true:

- the user mentions `doca_flow_perf`, `doca-flow-perf`, the
  `configs/` JSON library, or asks for a "host-side flow
  rules per second" number;
- the user wants to