doca-bench-extension

DOCA Bench 扩展

示例

• “我的工作负载类别不是内置的 doca-bench 模式。” — 确认没有合适的内置模式后，这属于本技能范围。 如果只是要运行标准的 RDMA 吞吐量测试，不要从这里开始。
• “doca-bench 找不到或无法加载我的自定义 .so。” — 在重写 内核之前，先检查发现机制、soversion 和导出符号。

说明

请按照下方的加载顺序操作。打开任务配套文档，了解配置 / 构建 / 运行 / 调试。打开功能配套文档，了解扩展 API 的 形式。不要打开所有配套文件。

从何处开始： 这是一个关于扩展 / 插件框架的工具技能，用于扩展 doca-bench/SKILL.md — 本身并不是工作负载类型 技能。打开任务配套文档，从 ## configure 开始，确定三项决策（工作负载类别确实不属于 doca-bench 的 内置模式 × 扩展 API 表面适用 × 可以接受与父工具 共同加载），然后查看 ## build，了解自定义扩展的编译和布局方式， 接着查看 ## run，了解 doca-bench 如何发现并 调用扩展，最后查看 ## test，了解 Agent 对每个新 扩展采用的先冒烟、后批量测试流程。如果问题是扩展能做什么，而内置 doca-bench 模式做不到、扩展 API 表面大致是什么样子（已发布参考实现公开的 DOCA_EXPERIMENTAL C 入口点）、构建 / 注册 / 发现流程如何运作，或扩展的 生命周期如何受父级 doca-bench 调用的限制，请打开功能配套文档。如果问题涉及 doca-bench 本身，请转到 doca-bench/SKILL.md。如果问题是 “我该选哪个内置的 doca-bench 模式？”，也请查看 doca-bench/SKILL.md — 扩展是用于覆盖内置模式无法支持的工作负载的 备用途径。

本技能擅长回答的示例问题

• “我的工作负载类别是 <X> — doca-bench 能原生测量它吗， 还是我需要扩展？” — 这是扩展与内置模式之间的选择问题。Agent 会先引导 用户查看 doca-bench/SKILL.md 中的 内置模式清单，只有在没有适用的内置模式时才会转到 扩展框架。
• “我想对驱动 DOCA GPUNetIO RX 和 TX 队列的 CUDA / GPU 侧工作负载 进行基准测试。应该从哪里开始？ 是否有可供复制的参考扩展？” — Agent 会指出 /opt/mellanox/doca/tools/bench_extension/doca_bench_cuda/ 下已发布的 doca_bench_cuda 扩展，将其作为参考范例，并引导操作人员了解其 API 表面和构建形式。
• “doca-bench 在运行时究竟如何发现并加载我的 自定义扩展？它是带版本号的共享库吗？入口点需要是什么样子？” — 这是关于构建 / 注册 / 发现流程的问题。Agent 会说明 Meson 构建的共享库形式、 版本控制方式以及父工具的运行时发现路径 （Agent 不会凭记忆编造这些信息 — 已发布扩展的 meson.build 和 docs.nvidia.com 上的 DOCA Bench 公共文档才是准确信息来源）。
• “我拿到的 API 头文件标记为 DOCA_EXPERIMENTAL。 这对扩展在不同 DOCA 版本间的稳定性意味着什么？我是否每次发布 新版本时都必须重新构建？” — 这是关于实验性 API 表面和版本 兼容性的问题。
• “扩展构建完成后，在让实际工作负载使用它之前，我能运行的最简单 冒烟测试是什么？ 我如何确认 doca-bench 确实加载了它、调用了它， 并且调用返回了父 工具预期的数据？” — 这是关于先冒烟、后批量测试的问题。
• “我的自定义扩展可以构建，但 doca-bench 提示找不到 / 无法加载 / 无法调用它。我应该先从哪里排查？” — 这是一个分层调试问题，用于区分 构建失败、加载失败、注册不匹配和运行时调用失败。

受众

有经验的 AI Agent 和平台／性能工程师，已经使用 doca-bench/SKILL.md 了解内置工作负载模式，现在遇到了内置模式无法覆盖的工作负载类别。读者应熟悉原生构建系统（本代码库使用 Meson）、Linux 上的共享库打包，以及 DOCA_EXPERIMENTAL API 稳定性约定。如果用户询问如何通过随附的 doca_bench_cuda 参考扩展进行 GPU 侧基准测试，读者还应熟悉 DOCA GPUNetIO 和 CUDA 工具链基础知识——这些领域各有专门的技能，不在此处介绍。

本技能不适用于：

• 能够使用 doca-bench 的内置模式之一来表达工作负载的操作人员——请参阅 doca-bench/SKILL.md；
• 希望通过其他 DOCA 原语（Flow、Comch、RMAX）各自的测量工具进行基准测试的操作人员——请转至对应的工具；
• 编写或修改树内扩展的贡献者（本技能面向使用该框架的外部操作人员，而非 DOCA 内部贡献者）。

语言范围

doca-bench 扩展包含：

1. Linux 上的带版本共享库（.so，其 soversion 与 DOCA 发行版匹配），通过随附的 /opt/mellanox/doca/tools/bench_extension/meson.build 中的 doca-bench-extension Meson 规则以及各扩展的子目录构建（参考示例为 doca_bench_cuda/）。
2. 一组小型的带有 DOCA_EXPERIMENTAL 标记的 C 入口点，由上层 doca-bench 调用——也就是扩展头文件中声明的 API 接口。随附的 doca_bench_cuda/doca_bench_cuda.h 展示了该接口在实践中的形态（*_init、*_device_query、*_device_synchronize，以及各工作负载的内核启动入口点，例如 *_start_nop_kernel、*_start_eth_recv_kernel、*_start_eth_send_kernel、*_start_eth_bidir_kernel）。
3. 一组针对各工作负载的设置结构体，由上层传入（例如，参考示例中的 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，包含区块数、每个区块的线程数、RX／TX 队列、缓冲区地址／mkey／大小、停止标志和统计信息指针）。

技能本身采用 Markdown 编写。用户的扩展源代码使用工作负载所需的语言（参考示例使用 C／C++／CUDA）。除了随附参考示例展示的内容外，Agent 不会规定使用何种语言。

何时加载此技能

符合以下任一条件时，加载 doca-bench-extension：

• 用户明确提及 doca-bench-extension、doca_bench_cuda 参考扩展、doca_bench_cuda_impl 共享库，或任何 DOCA_EXPERIMENTAL 扩展入口点；
• 用户已通过 doca-bench/SKILL.md 确认，doca-bench 的内置工作负载模式均无法测量其目标类别，需要借助扩展解决；
• 用户想要复制或扩展随附的 doca_bench_cuda 参考实现，以创建自定义的 GPU 侧工作负载扩展；
• 用户正在排查 doca-bench 无法找到、加载或调用其构建的自定义扩展的原因。

同时加载以下技能：

• doca-bench/SKILL.md（父级工具——始终同时加载；扩展只有作为 doca-bench 的插件才有价值）；
• doca-version/SKILL.md（DOCA_EXPERIMENTAL 接口随 DOCA 版本变化；扩展的 soversion 与 DOCA 的 soversion 相同；适用四方版本匹配规则）；
• 当扩展在 GPU 侧运行并使用与参考示例类似的 GPUNetIO RX / TX 队列时，加载 doca-gpunetio/SKILL.md（GPUNetIO 语义由该技能负责，而非此处）；
• 对于环境侧的调试流程（驱动程序、固件、CUDA 工具包、动态链接器），加载 doca-debug/SKILL.md 和 doca-setup/SKILL.md。

当用户的工作负载适用于 doca-bench 内置模式时，不要加载此技能——扩展会增加成本（构建工具链、版本变动、实验性接口契约）；应始终优先尝试内置模式。

此技能提供的内容

此目录中的三个配套文件分别负责不同的问题类型：

• 此技能——本文件。介绍目标受众、范围、加载顺序和相关技能，并将其他问题分流到相应位置。
• 能力配套文件——介绍扩展能够实现而内置模式无法实现的功能、API 接口的大致形式、构建、注册和发现流程的工作方式、扩展随哪些版本发布（包括在 doca-version 基础上叠加的 DOCA_EXPERIMENTAL 稳定性说明）、分层错误分类、可观测性和安全策略补充说明。
• 任务配套文件——介绍过程性动词（configure、build、run、test、debug 等），以及专用于 doca-bench-extension 的命令附录和 Agent 侧的 use 工作流（用于处理捕获的扩展运行数据）。

这些技能共同教会 AI Agent 处理 doca-bench 中编写并接入扩展这一类问题：确认是否确实需要扩展；找到随附的参考示例（/opt/mellanox/doca/tools/bench_extension/doca_bench_cuda/）；沿用其构建和 API 接口形式；构建与 DOCA 版本匹配的版本化共享库；进行冒烟测试，确认父级 doca-bench 确实加载了该库；并在加载失败时诊断分层故障。

此技能明确不包含的内容

• doca-bench 内置工作负载模式清单。 这部分属于 doca-bench/SKILL.md。 此技能用于处理内置模式未涵盖的情况； 不会重复父技能的模式清单。
• 超出已发布参考内容所声明范围的、臆造的 DOCA_EXPERIMENTAL 入口点名称。 用户安装中的已发布 doca_bench_cuda/doca_bench_cuda.h 是了解其接口形态的参考；Agent 不会声称存在具有特定签名的其他扩展。
• 所谓规范的“正确”扩展布局。 已发布的 doca_bench_cuda 参考实现就是规范布局； 在此重写会偏离事实来源。 Agent 会引导操作者查看已安装的代码树，并指导其在此基础上进行改编。
• Agent 臆造的运行时发现机制。 doca-bench 用于 查找和加载扩展的确切机制（搜索路径、命名 约定、注册调用）以 docs.nvidia.com 上的公开 DOCA Bench 文档和已安装的 doca-bench 二进制文件为准。Agent 会引导操作者查阅这些资料，而不会凭记忆断言某种机制。
• DOCA GPUNetIO 编程细节。 如果扩展在 GPU 端运行（如参考示例），GPUNetIO RX / TX 队列语义请查阅 doca-gpunetio/SKILL.md； 此技能提供交叉链接，而不会重复相关内容。
• CUDA 工具链安装指南。 请参阅 docs.nvidia.com 上公开的 NVIDIA CUDA Toolkit 文档；此技能不重复相关内容。
• 与扩展无关的 doca-bench 库内部调用细节。 父技能中的 CLI 标志、流水线形态和内置工作负载类别属于 doca-bench/SKILL.md。

加载顺序

收到 doca-bench-extension 问题时：

1. 确认已安装 DOCA，且用户的安装中可以调用 doca-bench；如果不能，请转至 doca-setup/SKILL.md；
2. 确认 doca-bench 的内置模式均未涵盖 此工作负载类别——如果有任何一种模式适用，请转回 doca-bench/SKILL.md 并停止。扩展是补充方案，而不是首选答案；
3. 阅读能力配套文档，以确定 三轴决策，并了解参考示例的 API 接口形态；
4. 阅读任务配套文档，并按顺序执行 ## configure → ## build → ## run → ## test → ## debug； 不要跳过构建前置步骤，直接从 ## run 开始。

相关技能

交叉链接约定遵循 tools/<X>/ 下的 bundle 相对路径约定：

• doca-bench/SKILL.md — 父工具。 始终一同加载。 扩展是 doca-bench 的插件，不会取代它，也没有独立 CLI；没有父工具调用时，它们不会进行任何测量。关于此技能的所有问题都以父工具为前提。
• doca-version/SKILL.md — DOCA_EXPERIMENTAL 接口与 DOCA 一同进行版本管理；根据随附的 meson.build，扩展的 soversion 与 DOCA 发行版相匹配。四方版本匹配规则同样适用；DOCA 升级后重新构建扩展是常态，而非例外。
• doca-gpunetio/SKILL.md — 当扩展运行在 GPU 端，并使用与参考实现 doca_bench_cuda 类似的 GPUNetIO RX / TX 队列时，应在此处处理 GPUNetIO 的语义。
• doca-setup/SKILL.md — DOCA 安装情况（是否存在 doca-bench？是否存在参考库 doca_bench_cuda_impl？需要时是否已安装 CUDA 工具链？）。
• doca-debug/SKILL.md — 针对环境问题的跨领域调试流程（动态链接器、库搜索路径、CUDA 驱动程序 / 工具包、固件）。
• doca-public-knowledge-map/SKILL.md — 导航至 docs.nvidia.com 上的公开 DOCA Bench / DOCA GPUNetIO 页面，以及介绍扩展生命周期 / 发现机制的发行说明。
• doca-structured-tools-contract/SKILL.md — Agent 针对结构化辅助工具（doca-env --json、doca-capability-snapshot、version-matrix.json）的 detect → prefer → fall back → report 约定；构建 / 加载的前置条件依赖这些工具。
• doca-hardware-safety/SKILL.md — 能力配套技能遵循的硬件安全规范。扩展是加载到 doca-bench 中的外部代码；将实验性代码加载到会触及数据平面 / 设备的基准测试工具，其安全影响不容忽视。

本技能假设用户以前在 Linux 上构建过共享库，并了解 Meson 构建。相关背景材料应放在工具链文档中，而非本技能中。