doca-flow-dpa-perf · git:20260727.a5736e4 · 2026-07-27 · sha256 80702bdcd18aaf46
doca-flow-dpa-perf git:20260727.a5736e4A
Immutable. This exact content is served forever at /api/v1/blob/80702bdcd18aaf46.
--- license: Apache-2.0 name: doca-flow-dpa-perf description: > Use this skill when the user is invoking doca_flow_dpa_perf on DPA-capable hardware (ConnectX-7 minimum supported, ConnectX-8 recommended, or BlueField-3) to measure rule update / disable rates on the DPA-offloaded DOCA Flow path — picking the active / passive device split, choosing workload-shape axes (burst, queue, completion threshold, workers, hash pipe algo, PSL tables), or reading Kops/sec iteration stats and the optional self-test. Trigger even when the user does not explicitly mention "doca_flow_dpa_perf" or "DPA Provider" — typical implicit phrasings include "how fast can the DPA program path-selector entries", "baseline rule-update rate on ConnectX-8", "tool reports zero ops on my BlueField", "self-test sentinel never shows on tcpdump", or "is my BlueField-2 DPA-capable". Refuse and route elsewhere for the host / DPU-CPU Flow path (doca-flow-perf), Flow pipeline tuning (doca-flow-tune), writing doca-flow / doca-dpa applications, or DOCA install — those belong to other skills. metadata: kind: tool compatibility: > Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) with a DPA-capable device attached — ConnectX-7 as the minimum supported ConnectX generation, ConnectX-8 recommended, or BlueField-3 (BlueField-2 and earlier ConnectX are unsupported). VNF Flow mode required; PF or VF only (SFs are not supported on the DPA path). Reads `pkg-config doca-flow` and the shipped `doca_flow_dpa_perf` binary plus its README on the user's install. --- # 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 configure is the JSON-config-or-CLI invocation surface. For the `doca-dpa` programming model behind the DPA-side execution engine, see `doca-dpa`; for the `doca-flow` API behind the pipeline the DPA path executes, see [`doca-flow`](../../libs/doca-flow/SKILL.md). ## When to load this skill Load this skill when the user is — or the agent needs to — invoke `doca_flow_dpa_perf` on a real host with DOCA installed and a DPA-capable device attached (or the public NGC DOCA container with the equivalent device passthrough) to measure update / disable rates on the DPA-offloaded Flow path. Concretely: - Confirming DPA preconditions (DPA-capable device class, VNF Flow mode, recommended PF use, no SFs) before invoking the tool. - Picking the active / passive device split appropriate to the user's hardware (two-port BlueField-3 active + passive; one- port ConnectX-9 active only). - Picking the workload-shape axes (burst size, queue size, completion threshold, hash pipe algorithm, work policy, number of PSL tables, table size, number of workers). - Picking the operation axis (update or disable-enable) per the shipped README's documented operations. - Producing a defensible Kops/sec number with iteration stats (median, max, standard deviation) captured. - Diagnosing zero-ops / hung / failed-self-test runs through the layered error taxonomy. Do **not** load this skill for general DOCA orientation, Flow program API work, or installation. For those, use [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md), the matching `libs/<library>` skill, or [`doca-setup`](../../doca-setup/SKILL.md). Do not load it for the host / DPU-CPU Flow path — that audience belongs in [`doca-flow-perf`](../doca-flow-perf/SKILL.md). ## What this skill provides This is a **thin loader**. Substantive material lives in two companion files: - `CAPABILITIES.md` — what `doca_flow_dpa_perf` measures (the DPA-Provider-on-DPA-device update / disable path specifically), the DPA-vs-host-path boundary, the device-preconditions table (ConnectX-7+ / BlueField-3+), the documented VNF-only Flow-mode rule, the PF-vs-VF-vs-SF rule (SFs not supported on DPA), the workload-shape axes (burst, queue, completion threshold, hash pipe algorithm, work policy, PSL tables, table size, workers), the operation axis (update vs disable-enable), the version overlay (this tool rides the `doca-flow` and `doca-dpa` versions it links against; the canonical rules live in [`doca-version`](../../doca-version/SKILL.md)), the layered error taxonomy (config-syntax / device-binding / dpa-precondition / workload-precondition / measurement-soundness / self-test / version / cross-cutting), the observability surface (iteration statistics, self-test path-selector verification, tcpdump-side traffic verification), and the safety posture (smoke-before-bulk, four-tuple capture, name the tool that produced the number). - `TASKS.md` — step-by-step workflows for the in-scope task verbs: `install` (route to setup; the binary is shipped), `configure` (DPA-preconditions + active / passive device + workload-shape decision), `build` (route to install — the binary is shipped), `modify` (refuse — modify the invocation, not the binary), `run` (smoke before bulk), `test` (eval loop), `debug` (layered diagnosis), `use` (consume the captured number), plus a `Deferred task verbs` block routing out-of-scope questions and a `Command appendix`. The skill assumes a host where DOCA is already installed (or the NGC DOCA container is running) on a DPA-capable device and the operator has the permissions to bind the device and allocate the DPA execution resources the tool needs. ## What this skill deliberately does not ship This skill is **agent guidance**, not a samples or scripts bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add: - **Verbatim default values for flag inventories beyond what the shipped README or installed `--help` documents.** Read defaults from the README first, then fall back to the installed binary's `--help`. If neither defines a needed default, stop and request the operator's explicit value instead of guessing. The flag surface is install-specific within the documented surface; the documented invocations + `--help` on the installed version are the authoritative answer. Inventing a flag is the most common hallucination failure. - **Pre-baked example Kops/sec numbers or expected throughput numbers.** Output is device-, firmware-, DOCA-version-, workload-, and platform-specific; a pinned number for one platform misleads operators on a different platform / version. The shipped README's example numbers are *illustrative*, not a baseline the agent should quote as ground truth. - **Wrappers, parsers, or scripts** in any language that consume the tool's stdout / CSV. The output format is documented; if a user wants to script against it, the right answer is "read the live guide, write the parser against your installed version". - **A `samples/` or `reference/` subtree.** This is a thin loader for a documented CLI; substantive material lives on the public page, in `--help`, and in the shipped README on the user's install. ## Loading order 1. Read this `SKILL.md` first to confirm the user's question is in scope (the user actually wants to invoke `doca_flow_dpa_perf` on DPA-capable hardware, not measure the host / DPU-CPU Flow path). 2. **For what `doca_flow_dpa_perf` measures, the DPA-vs-host boundary, the device-preconditions table, the workload- shape axes, the version overlay, the error taxonomy, the observability surface, and the safety posture, see [CAPABILITIES.md](CAPABILITIES.md).** 3. **For the documented invocations and the smoke-before-bulk workflow — `install`, `configure`, `build`, `modify`, `run`, `test`, `debug`, `use` — see [TASKS.md](TASKS.md).** ## Related skills - [`doca-flow`](../../libs/doca-flow/SKILL.md) — the **base library** whose pipeline this tool measures on the DPA path. The pipe / entry / rule surface this tool drives is created by `doca-flow` program code; the library's pipe attributes and capability surface are the upstream context. - `doca-dpa` — the programming model behind the DPA execution engine the tool runs on. When the user's question goes from *"measure the DPA path"* to *"why is the DPA path doing this"*, that skill is the next stop. - [`doca-flow-perf`](../doca-flow-perf/SKILL.md) — the host / DPU-CPU Flow performance tool. The cross-tool comparison rule lives in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes): name which tool produced which number. - [`doca-flow-tune`](../doca-flow-tune/SKILL.md) — the Flow tuning tool. A DPA-perf number is the kind of baseline `doca-flow-tune` then optimizes on top of, via a Flow-program modify-a-sample loop. - [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) — routing to the public DOCA Flow DPA Perf page on `docs.nvidia.com` and the rest of the public DOCA documentation set. - [`doca-version`](../../doca-version/SKILL.md) — canonical DOCA version-handling rules. The [`## Version compatibility`](CAPABILITIES.md#version-compatibility) section in this skill is a thin overlay on top. - [`doca-setup`](../../doca-setup/SKILL.md) — env preparation, install verification, hugepages, NUMA awareness, and the *I have no install yet* path with the public NGC DOCA container. - [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting debug ladder. DPA-perf surfaces *its own* error taxonomy; when the cause turns out to be below DOCA, the taxonomy hands off to `doca-debug`. - [`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md) — the cross-cutting hardware-safety meta-policy this skill's `## Safety policy` overlays.