About this skill
---
license: Apache-2.0
name: doca-bench-extension
description: >
Use this skill when the operator is authoring, building, loading,
or debugging a custom doca-bench plug-in — a versioned shared
library with DOCA_EXPERIMENTAL-marked C entry points that
doca-bench loads to measure a workload class its built-in modes
do not cover, with doca_bench_cuda as the shipped reference
exemplar. Trigger even when the user does not say
"doca-bench-extension" or "doca_bench_cuda" — typical implicit
phrasings include "no built-in doca-bench mode fits my workload",
"how do I benchmark a CUDA GPUNetIO RX/TX kernel", "doca-bench
cannot find or load my custom .so", "extension exported symbols
do not match what the parent expects", "soversion mismatch after
a DOCA upgrade", or "my GPU kernel hangs because stop_flag was
never set". Refuse and route elsewhere for questions about which
built-in doca-bench mode to pick, DOCA GPUNetIO programming
semantics, CUDA toolkit installation, or contributor work on
in-tree extensions — 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 BlueField DPU or
ConnectX NIC. Source tree: `/opt/mellanox/doca/tools/bench_extension/`
(underscored, NOT kebab-case); the built shared library
`libdoca_bench_cuda_impl.so` lands in the platform libdir on a
binary install. Also needs `pkg-config doca-common` and, for
the GPU-side reference exemplar (DOCA GPUNetIO RX/TX kernels),
an NVIDIA GPU + matching CUDA toolkit.
---
# DOCA Bench Extension
**Where to start:** This is a tool skill for the **extension /
plug-in framework** that augments
[`doca-bench`](../doca-bench/SKILL.md) — NOT a workload-shape
skill on its own. Open [`TASKS.md`](TASKS.md) and start at
[`## configure`](TASKS.md#configure) to commit to the three-axis
decision (workload class is genuinely outside doca-bench's
built-in modes × extension API surface fits × parent-tool
co-load is acceptable), then [`## build`](TASKS.md#build) for
how a custom extension is compiled and laid out, then
[`## run`](TASKS.md#run) for how `doca-bench` discovers and
invokes the extension, then [`## test`](TASKS.md#test) for the
smoke-before-bulk loop the agent applies to every new
extension. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the
question is *what an extension can do that built-in
`doca-bench` modes cannot*, *what the extension API surface
looks like in broad strokes (the `DOCA_EXPERIMENTAL` C entry
points the shipped reference exposes)*, *how the
build / registration / discovery flow works*, or *how the
extension's lifetime is bounded by the parent `doca-bench`
invocation*. If `doca-bench` itself is the question, route to
[`doca-bench`](../doca-bench/SKILL.md). If the question is
"which built-in `doca-bench` mode do I pick?", that is also
[`doca-bench`](../doca-bench/SKILL.md) — extensions are the
*exit ramp* for workloads built-in modes do not cover.
## Example questions this skill answers well
- *"My workload class is `<X>` — does `doca-bench` measure it
natively, or do I need an extension?"* — the
extension-vs-built-in decision question. The agent walks
the user back to [`doca-bench`](../doca-bench/SKILL.md)'s
built-in mode inventory FIRST and only routes to the
extension framework when no built-in mode applies.
- *"I want to benchmark a CUDA / GPU-side workload that
drives DOCA GPUNetIO RX and TX queues. Where do I start?
Is there a reference extension I can copy?"* — the agent
surfaces the shipped `doca_bench_cuda` extension under
`/opt/mellanox/doca/tools/bench_extension/doca_bench_cuda/` as the
reference exemplar and walks the operator through its
API surface and build shape.
- *"How does `doca-bench` actually discover and load my
custom extension at runtime? Is it a versioned shared
library? What does my entry-point need to look like?"* —
the build / registration / discovery flow question. The
agent walks the Meson-built shared library shape, the
versioning, and the parent-tool's runtime discovery path
(which the agent does NOT invent from memory — the
shipped extension's `meson.build` and the public DOCA Bench
documentation on `docs.nvidia.com` are the source of
truth).
- *"The API headers I have are marked `DOCA_EXPERIMENTAL`.
What does that mean for my extension's stability across
DOCA releases? Am I going to have to rebuild it every
release?"* — the experimental-surface and version
compatibility question.
- *"Once I build my extension, what is the cheapest possible
smoke I can run before pointing my real workload at it?
How do I know `doca-bench` actually loaded it, called
into it, and that the call returned the data the parent
tool expected?"* — the smoke-before-bulk question.
- *"My custom extension builds, but `doca-bench` says it
cannot find / load / call it. Where do I look first?"* —
the layered-debug question that distinguishes
build-failures, load-failures, registration-mismatches,
and runtime-call-failures.
## Audience
Experienced AI agents and platform / performance engineers
who already use [`doca-bench`](../doca-bench/SKILL.md) for
the built-in workload modes and now have a workload class
that the built-in modes do not cover. Readers are expected
to be comfortable with native build systems (Meson, in this
codebase), shared-library packaging on Linux, and the
`DOCA_EXPERIMENTAL` API stability contract. If the user
asks about GPU-side benchmarking via the shipped
`doca_bench_cuda` reference extension, the reader is also
expected to be familiar with DOCA GPUNetIO and CUDA toolchain
basics — those domains live in their own skills, not here.
This skill is NOT for:
- operators who can express their workload with one of
`doca-bench`'s built-in modes — that is
[`doca-bench`](../doca-bench/SKILL.md);
- operators who want to benchmark a different DOCA primitive
(Flow, Comch, RMAX) via that primitive's own
measurement tool — route to that tool;
- contributors authoring or modifying the in-tree extensions
themselves (this skill is for external operators consuming
the framework, not for internal DOCA contributors).
## Language scope
A `doca-bench` extension surfaces as:
1. A **versioned shared library** on Linux (`.so` with
`soversion` matching the DOCA release), built via the
`doca-bench-extension` Meson rules in the shipped
`/opt/mellanox/doca/tools/bench_extension/meson.build` and the
per-extension subdirectory (the reference exemplar is
`doca_bench_cuda/`).
2. A small set of **`DOCA_EXPERIMENTAL`-marked C entry
points** that the parent `doca-bench` invokes — i.e. the
API surface declared in the extension's header file.
The shipped `doca_bench_cuda/doca_bench_cuda.h` is the
reference for what that surface shape looks like in
practice (`*_init`, `*_device_query`,
`*_device_synchronize`, and per-workload kernel-start
entry points such as `*_start_nop_kernel`,
`*_start_eth_recv_kernel`, `*_start_eth_send_kernel`,
`*_start_eth_bidir_kernel`).
3. A set of **per-workload settings structs** that the
parent passes through (e.g. the reference exemplar's
`doca_bench_cuda_kernel_settings`,
`doca_bench_cuda_eth_rx_kernel_settings`,
`doca_bench_cuda_eth_tx_kernel_settings`,
`doca_bench_cuda_eth_bidir_kernel_settings` carry block
counts, threads-per-block, RX / TX queues, buffer
address / mkey / size, a stop flag, and a stats
pointer).
The skill itself is Markdown. The user's extension source
is whatever language the workload requires (C / C++ / CUDA
in the reference case). The agent does NOT prescribe a
language beyond what the shipped reference demonstrates.
## When to load this skill
Load `doca-bench-extension` when ANY of the following is
true:
- the user explicitly mentions `doca-bench-extension`, the
`doca_bench_cuda` reference extension, the
`doca_bench_cuda_impl` shared library, or any of the
`DOCA_EXPERIMENTAL` extension entry points;
- the user has confirmed (via
[`doca-bench TASKS.md ## configure`](../doca-bench/TASKS.md#configure))
that none of `doca-bench`'s built-in workload modes
measures the class they want, and an extension is the
exit ramp;
- the user wants to copy / extend the shipped
`doca_bench_cuda` reference into a custom GPU-side
workload extension;
- the user is debugging why `doca-bench` cannot find / load
/ call a custom extension they built.
Co-load this skill with:
- [`doca-bench`](../doca-bench/SKILL.md) (the parent tool —
ALWAYS co-loaded; extensions only have value as
plug-ins into `doca-bench`);
- [`doca-version`](../../doca-version/SKILL.md) (the
`DOCA_EXPERIMENTAL` surface is versioned with DOCA; the
extension's `soversion` is the DOCA `soversion`; the
four-way version match applies);
- [`doca-gpunetio`](../../libs/doca-gpunetio/SKILL.md) when
the extension is GPU-side and uses GPUNetIO RX / TX
queues like the reference exemplar (route the GPUNetIO
semantics there, not here);
- [`doca-debug`](../../doca-debug/SKILL.md) and
[`doca-setup`](../../doca-setup/SKILL.md) for the
env-side debug ladder (driver, firmware, CUDA toolkit,
dynamic linker).
Do NOT load this skill when the user's workload fits a
`doca-bench` built-in mode — extensions add cost (build
toolchain, version churn, the experimental-surface
contract); the built-in modes are always the first answer to
try.
## What this skill provides
Three companion files in this directory, each owning a
different question shape:
- [`SKILL.md`](SKILL.md) — this file. Audience, scope,
loading order, related skills. Routes everything else.
- [`CAPABILITIES.md`](CAPABILITIES.md) — *what an extension
can do that the built-in modes cannot*, *what the API
surface looks like in broad strokes*, *how the
build / registration / discovery flow works*, *what
versions it ships in (including the
`DOCA_EXPERIMENTAL`-stability overlay on top of
`doca-version`)*, *the layered error taxonomy*,
observability, and the safety policy overlay.
- [`TASKS.md`](TASKS.md) — the procedural verbs
(`configure`, `build`, `run`, `test`, `debug`, etc.) plus
a `doca-bench-extension`-specific command appendix and
the agent-side `use` workflow that consumes the captured
extension run.
The combined skill teaches an AI agent to drive the
*extension-author-and-wire-in class* of `doca-bench`
questions: confirm an extension is needed at all; locate
the shipped reference exemplar
(`/opt/mellanox/doca/tools/bench_extension/doca_bench_cuda/`); copy
its build + API surface shape; build a versioned shared
library that matches the DOCA release; smoke that the
parent `doca-bench` actually loads it; diagnose layered
failures when it does not.
## What this skill deliberately does not ship
- **Inventory of `doca-bench`'s built-in workload modes.**
That belongs to [`doca-bench`](../doca-bench/SKILL.md).
This skill is the exit ramp for what the built-in modes
do not cover; it does not duplicate the parent's mode
inventory.
- **Invented `DOCA_EXPERIMENTAL` entry-point names beyond
what the shipped reference declares.** The shipped
`doca_bench_cuda/doca_bench_cuda.h` on the user's
install is the reference for what the surface shape
looks like; the agent does not assert other extensions
exist with specific signatures.
- **A canonical "right" extension layout.** The shipped
`doca_bench_cuda` reference IS the canonical layout;
rewriting it here would drift from the source of truth.
The agent points the operator at the shipped tree and
walks the operator through *adapting* it.
- **A documented runtime discovery mechanism the agent
invents.** The exact mechanism `doca-bench` uses to
locate and load extensions (search path, naming
convention, registration call) lives in the public DOCA
Bench documentation on `docs.nvidia.com` and the
installed `doca-bench` binary. The agent points the
operator there rather than asserting a mechanism from
memory.
- **DOCA GPUNetIO programming details.** When the
extension is GPU-side (as the reference exemplar is),
the GPUNetIO RX / TX queue semantics live in
[`doca-gpunetio`](../../libs/doca-gpunetio/SKILL.md);
this skill cross-links rather than duplicates.
- **CUDA toolchain installation guidance.** Route to the
public NVIDIA CUDA Toolkit documentation on
`docs.nvidia.com`; this skill does not duplicate it.
- **Library-internal `doca-bench` invocation details
unrelated to extensions.** The parent's CLI flags,
pipeline shapes, and built-in workload classes belong
to [`doca-bench`](../doca-bench/SKILL.md).
## Loading order
When a `doca-bench-extension` question arrives:
1. Confirm DOCA is installed AND `doca-bench` is reachable
on the user's install — if not, route to
[`doca-setup`](../../doca-setup/SKILL.md);
2. **Confirm none of `doca-bench`'s built-in modes covers
the workload class** — if any of them does, route back
to [`doca-bench TASKS.md ## configure`](../doca-bench/TASKS.md#configure)
and stop. Extensions are the exit ramp, not the first
answer;
3. Read [`CAPABILITIES.md`](CAPABILITIES.md) to commit to
the three-axis decision and walk the reference
exemplar's API surface shape;
4. Read [`TASKS.md`](TASKS.md) and walk
`## configure → ## build → ## run → ## test → ## debug`
in that order; do NOT start with `## run` without the
build precondition step.
## Related skills
Cross-link conventions follow the bundle's relative path
contract from `tools/<X>/`:
- [`doca-bench`](../doca-bench/SKILL.md) — the parent tool.
**ALWAYS co-loaded.** Extensions are plug-ins into
`doca-bench`; they do not replace it, they do not have a
standalone CLI, they do not measure anything without the
parent invoking them. Every question on this skill
presupposes the parent.
- [`doca-version`](../../doca-version/SKILL.md) — the
`DOCA_EXPERIMENTAL` surface is versioned with DOCA; the
extension's `soversion` matches the DOCA release per
the shipped `meson.build`. The four-way version match
applies; rebuilding the extension across DOCA upgrades
is the rule, not the exception.
- [`doca-gpunetio`](../../libs/doca-gpunetio/SKILL.md) —
when the extension is GPU-side and uses GPUNetIO RX /
TX queues like the reference `doca_bench_cuda`. Route
the GPUNetIO semantics there.
- [`doca-setup`](../../doca-setup/SKILL.md) — DOCA install
posture (does `doca-bench` exist? does the
`doca_bench_cuda_impl` reference library exist? is the
CUDA toolchain installed when needed?).
- [`doca-debug`](../../doca-debug/SKILL.md) — the
cross-cutting debug ladder for env-side issues (dynamic
linker, library search path, CUDA driver / toolkit,
firmware).
- [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)
— routing to the public DOCA Bench / DOCA GPUNetIO pages
on `docs.nvidia.com` and the release notes for the
documented extension lifecycle / discovery mechanism.
- [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md)
— the agent's detect → prefer → fall back → report
contract for the structured helpers
(`doca-env --json`, `doca-capability-snapshot`,
`version-matrix.json`) the build / load preconditions
rely on.
- [`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md)
— the canonical hardware-safety meta-policy that
[`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
overlays. Extensions are external code loaded into
`doca-bench`; the safety implications of loading
experimental code into a benchmark that touches the
dataplane / device are real.
This skill assumes the user has built shared libraries on
Linux before and knows what a Meson build is. Background
material on those topics belongs in the toolchain docs, not
in this skill.