doca-bench

# DOCA Bench (`doca_bench`)

**Where to start:** This is a tool skill for invoking `doca_bench`,
the cross-library micro-benchmark harness. Open
[`TASKS.md`](TASKS.md) and start at
[`## configure`](TASKS.md#configure) for the three-axis decision
(target library × workload shape × measurement axis), then
[`## run`](TASKS.md#run) for the smoke-before-bulk flow. Open
[`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what
`doca_bench` can measure*, *which DOCA libraries it can drive*, or
*how to interpret throughput / latency / op-rate output without
fooling yourself on warm-up or steady-state*. If DOCA is not
installed yet, route to
[`doca-setup`](../../doca-setup/SKILL.md) first; if the install
version is < 2.7.0, `doca_bench` is not shipped on this host.

## Example questions this skill answers well

The CLASSES of `doca_bench` 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.

- **"What does this DOCA library actually deliver on this device?"** —
  worked example: *"throughput of DOCA Compress on my BlueField-3"*.
  Answered by the three-axis configuration in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the smoke-before-bulk flow in
  [`TASKS.md ## run`](TASKS.md#run). The *same* shape answers
  *"send-side throughput of DOCA RDMA"* — `doca_bench` is
  cross-library, not single-library.
- **"Which DOCA libraries can `doca_bench` actually drive on this
  install?"** — worked example: *"is doca_sha enumerable on a
  granular-build install"*. Answered by the built-in query system
  surfaced in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + [`TASKS.md ## configure`](TASKS.md#configure) step 2
  (probe-before-bench). Empty enumeration = library not installed,
  not bench failure.
- **"Is this number reliable, or did I miss the warm-up?"** —
  worked example: *"why does my first-second number differ from my
  steady-state number"*. Answered by the measurement-soundness
  overlay in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  layer 5 + [`TASKS.md ## test`](TASKS.md#test) (the eval-loop
  overlay treats warm-up / steady-state / outliers as
  re-iteration triggers, not one-shot facts).
- **"Bench reports zero throughput / hangs at start / disagrees
  with the public docs."** — worked example: *"`doca_bench` shows
  zero ops for AES-GCM but `doca_caps` says the device supports
  it"*. Answered by the layered error taxonomy in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  (config-syntax → device-binding → library-precondition →
  workload-precondition → measurement-soundness → version →
  cross-cutting) + [`TASKS.md ## debug`](TASKS.md#debug).
- **"How do I capture a baseline I can later regression-test
  against?"** — worked example: *"snapshot decompress throughput
  on this BlueField + DOCA version before a firmware update"*.
  Answered by the CSV output + version-overlay rule in
  [`TASKS.md ## test`](TASKS.md#test) (capture command line +
  version + device + as-deployed environment alongside the
  numbers; quoting numbers without the four-tuple is the
  cross-version regression-hunt failure mode).
- **"`doca_bench` returns nothing for library X — what does that
  mean?"** — worked example: *"empty output for DOCA SHA"*.
  Answered by the empty-output interpretation rules in
  [`TASKS.md ## debug`](TASKS.md#debug) +
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).
  Re-route through
  [`doca-caps`](../doca-caps/SKILL.md) for the coarse
  per-device per-library capability ground truth, then back
  into bench once the capability is confirmed present.

## Audience

This skill serves **external operators, developers, and AI agents
who need a reproducible, vendor-supported way to measure DOCA
library performance on the user's actual install and device**.
Concretely:

- An external developer choosing between DOCA libraries (e.g.
  COMPRESS vs SHA vs DMA throughput) before committing an
  application design.
- A platform operator validating a tuning change (NUMA pinning,
  driver upgrade, firmware burn) by re-running a captured
  `doca_bench` baseline against the new state.
- An SRE / performance engineer producing a *"this is what the
  device delivers today"* artifact that downstream consumers
  (capacity planning, regression bisection) can cite.
- An AI agent answering *"what throughput / latency should I
  expect from DOCA library X on device Y?"* honestly — with a
  measured number, the command line that produced it, and the
  version + device + environment that scopes it — instead of
  guessing from datasheet headlines.

It is **not** for users debugging the `doca_bench` source code,
and **not** a substitute for the live public DOCA Bench guide on
`docs.nvidia.com`.

`doca_bench` is shipped as a **tool** (a single CLI binary plus a
companion app for the remote half of remote-memory / RDMA / Eth
scenarios), not a library you link against. The skill uses the
same `kind: tool` three-file shape as the rest of the bundle so
the agent's task-verb contract
(`configure / build / modify / run / test / debug`) is uniform
across libraries, services, and tools — even when individual
verbs collapse to a routing stub for a shipped binary.

## When to load this skill

Load this skill when the user is — or the agent needs to — invoke
`doca_bench` on a real host with DOCA ≥ 2.7.0 installed (or
inside the public NGC DOCA container with the equivalent version)
to measure performance of a DOCA library. Concretely:

- Picking *which* DOCA library to benchmark for a candidate
  workload (RDMA vs COMPRESS vs DMA, etc.).
- Picking *which* measurement axis to ask for (throughput vs bulk
  latency vs precision latency vs max-bandwidth) — the four modes
  defined in `tools/bench/doca_bench/configuration.hpp` are not
  interchangeable.
- Probing the