/doca-bench

license: Apache-2.0
name: doca-bench
description: >
  Run `doca_bench` (DOCA 2.7.0 or newer) to measure throughput, bulk
  latency, precision latency, or maximum bandwidth for RDMA, Compress,
  AES-GCM, SHA, DMA, EC, Ethernet, Comch, or GPUNetIO on a host or
  BlueField Arm. Use it to discover enabled benchmark libraries, capture
  a reproducible command/version/device/environment baseline, compare
  stable runs against a declared tolerance, or diagnose configuration,
  device-binding, workload-precondition, and measurement failures.
  Trigger for requests such as measuring BlueField compression speed,
  NIC RDMA throughput, crypto latency, or a pre-upgrade baseline. Do not
  use for application end-to-end timing, custom benchmark code, DOCA
  installation, or binary patches.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - bench
    - perf
compatibility: >
  Requires DOCA SDK ≥ 2.7.0 installed at /opt/mellanox/doca on Linux
  (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC
  attached and the `doca_bench` binary present at
  /opt/mellanox/doca/tools/doca_bench. Companion app must run on the far
  side for remote-memory / RDMA / Eth scenarios; host and BlueField-Arm
  execution both supported. The validation steps require a live DOCA
  install.

DOCA Bench (`doca_bench`)

Examples

• **"What does this DOCA library actually deliver on this device?"** —

this is in scope. Stay on `doca_bench`; do not write a custom microbenchmark.

• **"Which DOCA libraries can `doca_bench` drive on this install?"** —

probe the built-in query first; empty enumeration is a missing library, not a bench failure.

Instructions

Follow Loading order below. Open the tasks companion for configure / run / debug. Open the capabilities companion for modes and measurement soundness. Do not open every companion file.

**Where to start:** This is a tool skill for invoking `doca_bench`, the cross-library micro-benchmark harness. Open the tasks companion and start at `## configure` for the three-axis decision (target library × workload shape × measurement axis), then `## run` for the smoke-before-bulk flow. Open the capabilities companion 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/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 the capabilities companion

• the smoke-before-bulk flow in

the tasks companion. 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 the capabilities companion

• the tasks companion 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 the capabilities companion layer 5 + the tasks companion (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 the capabilities companion (config-syntax → device-binding → library-precondition → workload-precondition → measurement-soundness → version → cross-cutting) + the tasks companion.

• **"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 the tasks companion (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 the tasks companion + the capabilities companion. Re-route through `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