doca-flow-dpa-perf

# DOCA Flow DPA Perf (`doca_flow_dpa_perf`)

**Where to start:** This is a tool skill for invoking
`doca_flow_dpa_perf`, the DPA-accelerated Flow performance tool.
Open [`TASKS.md`](TASKS.md) and start at
[`## configure`](TASKS.md#configure) to confirm DPA-capable
hardware + VNF Flow mode + the active / passive device split, then
[`## run`](TASKS.md#run) for the smoke-before-bulk flow with a
small operation count before any sweep, then
[`## test`](TASKS.md#test) for the eval-loop overlay that gates
defensible Kops/sec numbers. Open [`CAPABILITIES.md`](CAPABILITIES.md)
when the question is *what `doca_flow_dpa_perf` can measure*,
*what the DPA preconditions are*, *which devices it runs on*,
or *how to interpret update / disable / self-test output without
fooling yourself*. If DOCA is not installed yet, route to
[`doca-setup`](../../doca-setup/SKILL.md) first; if the device is
not DPA-capable (no ConnectX-7+ or BlueField-3+) then this tool is
the wrong surface and the right answer is
[`doca-flow-perf`](../doca-flow-perf/SKILL.md).

## Example questions this skill answers well

The CLASSES of `doca_flow_dpa_perf` questions this skill is built
to answer, each with one worked example. The class is the
load-bearing piece; the worked example is one instance.

- **"Should I measure the DPA-offloaded Flow path or the
  host / DPU-CPU Flow path for this question?"** — worked
  example: *"my workload programs path-selector entries via
  DOCA Flow; do I baseline with `doca_flow_dpa_perf` or with
  `doca_flow_perf`?"*. Answered by the *DPA-vs-host* boundary
  in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  and the device-preconditions table.
- **"What does the DPA-offload actually accelerate, and what
  doesn't it change?"** — worked example: *"if I move my Flow
  rule update path to the DPA, what changes in the data plane
  for the packets themselves?"*. Answered by the DPA-Provider
  scope in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).
- **"What hardware do I need to use this tool at all?"** —
  worked example: *"is my BlueField-2 DPA-capable?"*. Answered
  by the device-preconditions table in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  (BlueField-3 yes, BlueField-2 no; ConnectX-7 minimum
  supported, ConnectX-8 recommended, and later generations
  supported per the public guide and the
  shipped README on the user's install).
- **"How do I size my run — burst, queue, completion threshold,
  number of operations, iterations — to get a defensible
  Kops/sec number?"** — worked example: *"I want the median
  iteration time and standard deviation, not a single noisy
  first-iteration spike"*. Answered by the eval-loop overlay
  in
  [`TASKS.md ## test`](TASKS.md#test) and the iteration-stats
  rule in
  [`CAPABILITIES.md ## Observability`](CAPABILITIES.md#observability).
- **"My tool reports zero ops / hangs / fails the self-test —
  what does that mean?"** — worked example: *"the tool runs but
  the self-test step fails"*. Answered by the layered error
  taxonomy in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  + the debug ladder in
  [`TASKS.md ## debug`](TASKS.md#debug).
- **"How do I quote a DPA-perf number alongside a host-side
  Flow-perf number for the same workload, in a way the next
  engineer can actually compare?"** — worked example: *"two
  Kops/sec numbers for what is supposedly the same workload"*.
  Answered by the four-tuple capture rule in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the per-tool-name rule (the host tool and the DPA tool are
  different surfaces; their numbers are not interchangeable
  without naming which tool produced which).

## Audience

This skill serves **external operators, performance engineers,
DOCA Flow application developers, and AI agents who need a
defensible measurement of the DPA-offloaded Flow update path** on
DPA-capable hardware. Concretely:

- A platform operator deciding whether to move a path-selector
  workload onto the DPA versus keeping it on the host / DPU-CPU
  path, and wanting a number to compare.
- A performance engineer producing a *"DPA Kops/sec for update
  operation, queue-size X, burst-size Y, N workers"* baseline
  on a specific device + DOCA version so a downstream
  comparison is meaningful.
- A DOCA Flow application developer who has already used
  `doca-dpa` to land a DPA-offload of their Flow rule update
  path and wants to characterize what the device delivers.
- An AI agent answering *"what update rate should I expect from
  the DPA-offloaded Flow path on device Y?"* honestly — with a
  measured number, the command line that produced it, and the
  device + DOCA version + as-deployed environment that scopes
  it — instead of guessing from datasheet headlines.

It is **not** for users debugging the tool's source code,
**not** a substitute for the live public DOCA Flow DPA Perf guide
on `docs.nvidia.com`, **not** the place to learn the `doca-flow`
or `doca-dpa` APIs (that audience belongs in
[`doca-flow`](../../libs/doca-flow/SKILL.md) and
`doca-dpa`), and **not** the right
tool for the host / DPU-CPU Flow path (route to
[`doca-flow-perf`](../doca-flow-perf/SKILL.md)).

`doca_flow_dpa_perf` is shipped as a **single CLI binary** with
DPA-side device code linked in. The skill uses the same
`kind: tool` three-file shape as the rest of the bundle so
the agent's task-verb contract is uniform across the bundle.

## Language scope

This skill governs invocation, output interpretation, and
recommendation-of-routing for the `doca_flow_dpa_perf` CLI on
DPA-capable hardware. The tool itself has both a host-side
control (C-language ARGP + DOCA + DPDK code per the shipped
`flow_dpa_perf.c` / `flow_dpa_perf_core.c`) and a DPA-side device
component (DPA-side code on the shipped DPA device runtime).
External users do not link any of this; what they config