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 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) — the three modes the public guide
documents; confirm the list with
--help. The modes are not interchangeable.
- Probing the install's granular-build state so the agent can
honestly report "this library is not exposed on this install"
instead of inventing a workload.
- Capturing a documented baseline (command line + version + device
- as-deployed environment + numbers) for later regression hunts.
- Requiring the workload owner to predeclare acceptable variance
and obtaining two consecutive runs within that tolerance before
reporting a stable result; otherwise escalating the variance.
- Diagnosing why a bench run reported zero / unstable / unexpected
results (the error-taxonomy walk in
the tasks companion).
Do not load this skill for general DOCA orientation, library
API work, or installation. For those, use
doca-public-knowledge-map/SKILL.md,
the matching libs/<library> skill, or
doca-setup/SKILL.md. Do not load it for
application-level end-to-end benchmarking either — doca_bench
measures the DOCA library surface, not the user's application
above it.
What this skill provides
This is a thin loader. Substantive material lives in two
companion files:
- the capabilities companion — what
doca_bench can measure (the
cross-library scope, the three-axis configuration model, the
documented operating modes, the warm-up / pipeline / multi-core
concepts that constrain measurement soundness), the version
overlay (doca-bench-specific facts on top of the canonical
doca-version rules), the layered error taxonomy
(config-syntax / device-binding / library-precondition /
workload-precondition / measurement-soundness / version /
cross-cutting), the observability surface (screen + CSV
output, real-time stats, query system), and the safety
posture (the public guide's "not for production" warning,
the host vs BlueField execution rule, the companion-app
attack surface).
- the tasks companion — step-by-step workflows for the in-scope task
verbs:
configure (the three-axis decision + the
probe-before-bench step), build (route to install — the
binary is shipped, the companion app is shipped), modify
(refuse — do not patch the bench binary; modify the bench
invocation instead), run (the smoke-before-bulk flow),
test (the eval loop — warm-up, steady-state, outliers,
cross-version), debug (walk the error taxonomy layer by
layer), plus a Deferred task verbs block routing
out-of-scope questions and a Command appendix of
doca_bench-specific invocation classes.
The skill assumes a host where DOCA ≥ 2.7.0 is already installed
(or the public NGC DOCA container is running at an equivalent
version) and the operator has whatever permissions the public
guide requires for doca_bench to bind devices and allocate
resources on their platform.
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:
- Specific flag strings or scenario / metric / attribute names
beyond what the public DOCA Bench guide documents. The flag
surface evolves and is install-specific; the documented
invocations +
--help on the installed version are the
authoritative answer. Inventing a flag is the most common
hallucination failure for this skill.
- Pre-baked example output or expected throughput numbers.
Bench output is device-, version-, firmware-, NUMA-, and
tuning-specific. A captured number pinned to one platform and
one DOCA version misleads operators on a different
platform / version.
- Wrappers, parsers, or scripts in any language that consume
doca_bench CSV or stdout. The output formats are documented;
if a user wants to script against them, 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 and in --help.
Loading order
- Read this skill first to confirm the user's question is
in scope (the user actually wants to invoke
doca_bench for
measurement, not learn about a DOCA library in general).
- For what
doca_bench measures, the three-axis model, the
version overlay, the error taxonomy, observability surface,
and safety posture, see the capabilities companion.
- For the documented invocations and the smoke-before-bulk
workflow —
configure, build, modify, run, test,
debug — see the tasks companion.
Related skills
doca-public-knowledge-map/SKILL.md
— routing to the public DOCA Bench page on docs.nvidia.com
and the rest of the public DOCA documentation set.
doca-version/SKILL.md — the canonical
version-detection chain, four-way match rule, NGC container
semantics, and headers-win-over-docs rule. The
## Version compatibility section in this skill is a thin
overlay on top of doca-version; the body lives there.
doca-structured-tools-contract/SKILL.md
— the bundle-wide contract for structured-output helper tools.
When a site provides a helper that satisfies the
detect-prefer-fallback-report loop, the ## Command appendix
in the tasks companion uses it; otherwise it falls back to the
manual commands.
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/SKILL.md — the cross-cutting
debug ladder. Bench surfaces its own error taxonomy in
the capabilities companion;
when the cause turns out to be below DOCA (driver, firmware,
NUMA), the bench taxonomy hands off to doca-debug.
doca-caps/SKILL.md — the sibling DOCA tool
for the coarse per-device per-library capability snapshot.
Bench probes capability at finer grain via its own query
system; doca_caps is the cheaper first step to confirm the
device is even visible to DOCA.
- The matching
libs/<library> skill — e.g.
doca-comch/SKILL.md,
doca-compress/SKILL.md — for
the workload-side preconditions, capability-query rules, and
error-taxonomy overlays of the library under test. Bench
drives the library; the library skill explains what
"healthy" means for it.
1---2license: Apache-2.03name: doca-bench4description: >5 Run `doca_bench` (DOCA 2.7.0 or newer) to measure throughput, bulk6 latency, precision latency, or maximum bandwidth for RDMA, Compress,7 AES-GCM, SHA, DMA, EC, Ethernet, Comch, or GPUNetIO on a host or8 BlueField Arm. Use it to discover enabled benchmark libraries, capture9 a reproducible command/version/device/environment baseline, compare10 stable runs against a declared tolerance, or diagnose configuration,11 device-binding, workload-precondition, and measurement failures.12 Trigger for requests such as measuring BlueField compression speed,13 NIC RDMA throughput, crypto latency, or a pre-upgrade baseline. Do not14 use for application end-to-end timing, custom benchmark code, DOCA15 installation, or binary patches.16metadata:17 source: https://skillmd.com/skills/nvidia/doca-bench18 author: NVIDIA <doca-feedback@nvidia.com>19 kind: tool20 doca_version: "3.5"21 tags:22 - doca23 - bench24 - perf25compatibility: >26 Requires DOCA SDK ≥ 2.7.0 installed at /opt/mellanox/doca on Linux27 (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC28 attached and the `doca_bench` binary present at29 /opt/mellanox/doca/tools/doca_bench. Companion app must run on the far30 side for remote-memory / RDMA / Eth scenarios; host and BlueField-Arm31 execution both supported. The validation steps require a live DOCA32 install.33---3435# DOCA Bench (`doca_bench`)3637## Examples3839- **"What does this DOCA library actually deliver on this device?"** —40 this is in scope. Stay on `doca_bench`; do not write a custom41 microbenchmark.42- **"Which DOCA libraries can `doca_bench` drive on this install?"** —43 probe the built-in query first; empty enumeration is a missing44 library, not a bench failure.4546## Instructions4748Follow Loading order below. Open the tasks companion for configure /49run / debug. Open the capabilities companion for modes and50measurement soundness. Do not open every companion file.5152**Where to start:** This is a tool skill for invoking `doca_bench`,53the cross-library micro-benchmark harness. Open54the tasks companion and start at55`## configure` for the three-axis decision56(target library × workload shape × measurement axis), then57`## run` for the smoke-before-bulk flow. Open58the capabilities companion when the question is *what59`doca_bench` can measure*, *which DOCA libraries it can drive*, or60*how to interpret throughput / latency / op-rate output without61fooling yourself on warm-up or steady-state*. If DOCA is not62installed yet, route to63`doca-setup/SKILL.md` first; if the install64version is < 2.7.0, `doca_bench` is not shipped on this host.6566## Example questions this skill answers well6768The CLASSES of `doca_bench` questions this skill is built to answer,69each with one worked example. The class is the load-bearing piece;70the worked example is one instance.7172- **"What does this DOCA library actually deliver on this device?"** —73 worked example: *"throughput of DOCA Compress on my BlueField-3"*.74 Answered by the three-axis configuration in75 the capabilities companion76 + the smoke-before-bulk flow in77 the tasks companion. The *same* shape answers78 *"send-side throughput of DOCA RDMA"* — `doca_bench` is79 cross-library, not single-library.80- **"Which DOCA libraries can `doca_bench` actually drive on this81 install?"** — worked example: *"is doca_sha enumerable on a82 granular-build install"*. Answered by the built-in query system83 surfaced in84 the capabilities companion85 + the tasks companion step 286 (probe-before-bench). Empty enumeration = library not installed,87 not bench failure.88- **"Is this number reliable, or did I miss the warm-up?"** —89 worked example: *"why does my first-second number differ from my90 steady-state number"*. Answered by the measurement-soundness91 overlay in92 the capabilities companion93 layer 5 + the tasks companion (the eval-loop94 overlay treats warm-up / steady-state / outliers as95 re-iteration triggers, not one-shot facts).96- **"Bench reports zero throughput / hangs at start / disagrees97 with the public docs."** — worked example: *"`doca_bench` shows98 zero ops for AES-GCM but `doca_caps` says the device supports99 it"*. Answered by the layered error taxonomy in100 the capabilities companion101 (config-syntax → device-binding → library-precondition →102 workload-precondition → measurement-soundness → version →103 cross-cutting) + the tasks companion.104- **"How do I capture a baseline I can later regression-test105 against?"** — worked example: *"snapshot decompress throughput106 on this BlueField + DOCA version before a firmware update"*.107 Answered by the CSV output + version-overlay rule in108 the tasks companion (capture command line +109 version + device + as-deployed environment alongside the110 numbers; quoting numbers without the four-tuple is the111 cross-version regression-hunt failure mode).112- **"`doca_bench` returns nothing for library X — what does that113 mean?"** — worked example: *"empty output for DOCA SHA"*.114 Answered by the empty-output interpretation rules in115 the tasks companion +116 the capabilities companion.117 Re-route through118 `doca-caps/SKILL.md` for the coarse119 per-device per-library capability ground truth, then back120 into bench once the capability is confirmed present.121122## Audience123124This skill serves **external operators, developers, and AI agents125who need a reproducible, vendor-supported way to measure DOCA126library performance on the user's actual install and device**.127Concretely:128129- An external developer choosing between DOCA libraries (e.g.130 COMPRESS vs SHA vs DMA throughput) before committing an131 application design.132- A platform operator validating a tuning change (NUMA pinning,133 driver upgrade, firmware burn) by re-running a captured134 `doca_bench` baseline against the new state.135- An SRE / performance engineer producing a *"this is what the136 device delivers today"* artifact that downstream consumers137 (capacity planning, regression bisection) can cite.138- An AI agent answering *"what throughput / latency should I139 expect from DOCA library X on device Y?"* honestly — with a140 measured number, the command line that produced it, and the141 version + device + environment that scopes it — instead of142 guessing from datasheet headlines.143144It is **not** for users debugging the `doca_bench` source code,145and **not** a substitute for the live public DOCA Bench guide on146`docs.nvidia.com`.147148`doca_bench` is shipped as a **tool** (a single CLI binary plus a149companion app for the remote half of remote-memory / RDMA / Eth150scenarios), not a library you link against. The skill uses the151same `kind: tool` three-file shape as the rest of the bundle so152the agent's task-verb contract153(`configure / build / modify / run / test / debug`) is uniform154across libraries, services, and tools — even when individual155verbs collapse to a routing stub for a shipped binary.156157## When to load this skill158159Load this skill when the user is — or the agent needs to — invoke160`doca_bench` on a real host with DOCA ≥ 2.7.0 installed (or161inside the public NGC DOCA container with the equivalent version)162to measure performance of a DOCA library. Concretely:163164- Picking *which* DOCA library to benchmark for a candidate165 workload (RDMA vs COMPRESS vs DMA, etc.).166- Picking *which* measurement axis to ask for (throughput vs bulk167 latency vs precision latency) — the three modes the public guide168 documents; confirm the list with `--help`. The modes are not interchangeable.169- Probing the install's granular-build state so the agent can170 honestly report *"this library is not exposed on this install"*171 instead of inventing a workload.172- Capturing a documented baseline (command line + version + device173 + as-deployed environment + numbers) for later regression hunts.174- Requiring the workload owner to predeclare acceptable variance175 and obtaining two consecutive runs within that tolerance before176 reporting a stable result; otherwise escalating the variance.177- Diagnosing why a bench run reported zero / unstable / unexpected178 results (the error-taxonomy walk in179 the tasks companion).180181Do **not** load this skill for general DOCA orientation, library182API work, or installation. For those, use183`doca-public-knowledge-map/SKILL.md`,184the matching `libs/<library>` skill, or185`doca-setup/SKILL.md`. Do not load it for186*application-level* end-to-end benchmarking either — `doca_bench`187measures the DOCA library surface, not the user's application188above it.189190## What this skill provides191192This is a **thin loader**. Substantive material lives in two193companion files:194195- the capabilities companion — what `doca_bench` can measure (the196 cross-library scope, the three-axis configuration model, the197 documented operating modes, the warm-up / pipeline / multi-core198 concepts that constrain measurement soundness), the version199 overlay (`doca-bench`-specific facts on top of the canonical200 `doca-version` rules), the layered error taxonomy201 (config-syntax / device-binding / library-precondition /202 workload-precondition / measurement-soundness / version /203 cross-cutting), the observability surface (screen + CSV204 output, real-time stats, query system), and the safety205 posture (the public guide's *"not for production"* warning,206 the host vs BlueField execution rule, the companion-app207 attack surface).208- the tasks companion — step-by-step workflows for the in-scope task209 verbs: `configure` (the three-axis decision + the210 probe-before-bench step), `build` (route to install — the211 binary is shipped, the companion app is shipped), `modify`212 (refuse — do not patch the bench binary; modify the bench213 *invocation* instead), `run` (the smoke-before-bulk flow),214 `test` (the eval loop — warm-up, steady-state, outliers,215 cross-version), `debug` (walk the error taxonomy layer by216 layer), plus a `Deferred task verbs` block routing217 out-of-scope questions and a `Command appendix` of218 `doca_bench`-specific invocation classes.219220The skill assumes a host where DOCA ≥ 2.7.0 is already installed221(or the public NGC DOCA container is running at an equivalent222version) and the operator has whatever permissions the public223guide requires for `doca_bench` to bind devices and allocate224resources on their platform.225226## What this skill deliberately does not ship227228This skill is **agent guidance**, not a samples or scripts229bundle. To keep the boundary clean, it deliberately does not230contain — and pull requests should not add:231232- **Specific flag strings or scenario / metric / attribute names233 beyond what the public DOCA Bench guide documents.** The flag234 surface evolves and is install-specific; the documented235 invocations + `--help` on the installed version are the236 authoritative answer. Inventing a flag is the most common237 hallucination failure for this skill.238- **Pre-baked example output or expected throughput numbers.**239 Bench output is device-, version-, firmware-, NUMA-, and240 tuning-specific. A captured number pinned to one platform and241 one DOCA version misleads operators on a different242 platform / version.243- **Wrappers, parsers, or scripts** in any language that consume244 `doca_bench` CSV or stdout. The output formats are documented;245 if a user wants to script against them, the right answer is246 "read the live guide, write the parser against your installed247 version".248- **A `samples/` or `reference/` subtree.** This is a thin249 loader for a documented CLI; substantive material lives on250 the public page and in `--help`.251252## Loading order2532541. Read this skill first to confirm the user's question is255 in scope (the user actually wants to invoke `doca_bench` for256 measurement, not learn about a DOCA library in general).2572. **For what `doca_bench` measures, the three-axis model, the258 version overlay, the error taxonomy, observability surface,259 and safety posture, see the capabilities companion.**2603. **For the documented invocations and the smoke-before-bulk261 workflow — `configure`, `build`, `modify`, `run`, `test`,262 `debug` — see the tasks companion.**263264## Related skills265266- `doca-public-knowledge-map/SKILL.md`267 — routing to the public DOCA Bench page on `docs.nvidia.com`268 and the rest of the public DOCA documentation set.269- `doca-version/SKILL.md` — the canonical270 version-detection chain, four-way match rule, NGC container271 semantics, and headers-win-over-docs rule. The272 `## Version compatibility` section in this skill is a thin273 overlay on top of `doca-version`; the body lives there.274- `doca-structured-tools-contract/SKILL.md`275 — the bundle-wide contract for structured-output helper tools.276 When a site provides a helper that satisfies the277 detect-prefer-fallback-report loop, the `## Command appendix`278 in the tasks companion uses it; otherwise it falls back to the279 manual commands.280- `doca-setup/SKILL.md` — env preparation,281 install verification, hugepages, NUMA awareness, and the *I282 have no install yet* path with the public NGC DOCA container.283- `doca-debug/SKILL.md` — the cross-cutting284 debug ladder. Bench surfaces *its own* error taxonomy in285 the capabilities companion;286 when the cause turns out to be below DOCA (driver, firmware,287 NUMA), the bench taxonomy hands off to `doca-debug`.288- `doca-caps/SKILL.md` — the sibling DOCA tool289 for the coarse per-device per-library capability snapshot.290 Bench probes capability at finer grain via its own query291 system; `doca_caps` is the cheaper first step to confirm the292 device is even visible to DOCA.293- The matching `libs/<library>` skill — e.g.294 `doca-comch/SKILL.md`,295 `doca-compress/SKILL.md` — for296 the workload-side preconditions, capability-query rules, and297 error-taxonomy overlays of the library under test. Bench298 drives the library; the library skill explains *what299 "healthy" means for it*.