/doca-bench-extension

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)