---

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 — NOT a workload-shape skill on its own. Open TASKS.md and start at ## 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 for how a custom extension is compiled and laid out, then ## run for how doca-bench discovers and invokes the extension, then ## test for the smoke-before-bulk loop the agent applies to every new extension. Open 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. If the question is "which built-in doca-bench mode do I pick?", that is also doca-bench — 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'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 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;
• 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) 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 (the parent tool — ALWAYS co-loaded; extensions only have value as plug-ins into doca-bench);
• doca-version (the DOCA_EXPERIMENTAL surface is versioned with DOCA; the extension's soversion is the DOCA soversion; the four-way version match applies);
• doca-gpunetio 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 and doca-setup 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 — this file. Audience, scope, loading order, related skills. Routes everything else.
• 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 — 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. 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