doca-gpunetio-ib-write-bw

DOCA GPUNetIO ib_write_bw

示例

• “GPUNetIO 在这对 GPU-NIC 上能持续提供多少 RDMA-WRITE 带宽？”——这属于本工具的范围。请使用 gpunetio_ib_write_bw；不要在此处重新调优正在运行的 GPI 应用。
• “瓶颈在哪里——GPU 占用率、NIC 发出速率，还是链路饱和？”——请先拆解吞吐量，再更改 CUDA 内核。

说明

请遵循下方的加载顺序。打开任务配套文件以了解配置／运行／调试。打开能力配套文件以了解 GPU-NIC 配对和可观测性。不要打开所有配套文件。

**从这里开始：**这是一个工具技能，适用于 GPUNetIO 版本的 ib_write_bw 基准测试工具，位于 doca/tools/gpunetio_ib_write_bw/ 下（客户端与服务端配对，使用 meson 基于已安装的 DOCA 从源码构建）。它测量从 CUDA 内核通过 doca-gpunetio 设备端接口提交 WR 时的持续 RDMA WRITE 带宽，GPU 位于数据路径上。请打开任务配套文件，从 ## configure 开始，了解 GPU-NIC 配对前提和构建模式；跳转到 ## run 了解先进行冒烟测试再进行大规模测试的流程。若问题涉及此工具实际测量的内容、结果如何拆解（GPU 占用率与 NIC 发出速率、链路饱和度），或如何将结果与 GPI 同类工具及上游由 CPU 发起的 perftest ib_write_bw 对照解读，请打开能力配套文件。如果尚未安装 DOCA，请先转到 doca-setup/SKILL.md；如果用户仍在权衡 GPI 和 GPUNetIO 编程接口，请先查看 doca-gpunetio/SKILL.md 和 doca-gpi/SKILL.md。

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

doca-gpunetio-ib-write-bw 问题的类别（CLASSES），本技能旨在回答这些问题，每类都附有一个示例。类别是关键所在；示例只是其中一个实例。

• “这对 GPU-NIC 上的 GPUNetIO 路径能提供多少持续 RDMA-WRITE 带宽？” — 示例：“测量两台主机之间的持续 WRITE 带宽，每端各有一块 H100 和一张 ConnectX-7”。答案来自能力配套文档中的 GPU-NIC 配对前提、任务配套文档中的启动流程，以及任务配套文档。相同的问题类型也适用于*“测量主机 GPU 与 BlueField DPU 之间由 GPUNetIO 驱动的 WRITE 带宽”*。
• “瓶颈在哪里——GPU 计算占用率、NIC 发包速率，还是链路饱和？” — 示例：“我在 200 Gbit/s 链路上只测到 120 Gbit/s；是 NIC 已饱和、客户端受 CPU 限制，还是 CUDA 内核没有让足够多的 WR 同时在途？”。答案来自能力配套文档中的吞吐量分解规则，以及任务配套文档中的评估循环补充说明。
• “结果与经典的 CPU 发起型 perftest ib_write_bw 有何不同？” — 示例：“我的团队在同一张 NIC 上测得了一个 CPU 发起型 WRITE 带宽数值；我是否应预期 GPUNetIO 的数值与之相同？”。答案来自能力配套文档中的规则：“GPU 发起型路径相较 CPU 发起型路径会增加（或减少）开销”。
• “对于我的持续吞吐量工作负载，doca-gpunetio 路径是否合适？” — 示例：“我的应用以线速将传感器数据从 GPU 内存流式传输到远程使用方”。答案来自能力配套文档中的规则：“何时应选择 GPUNetIO，而非 GPI 或 CPU 发起型路径”，以及任务配套文档中的使用侧决策。
• “我的带宽数值每次运行都不一样。引用之前应检查什么？” — 示例：“使用相同标志运行了三次，结果分别为 145、187 和 160 Gbit/s；是基准测试结果波动，还是我的平台不一致？”。答案来自能力配套文档第 5 层中的测量可靠性规则，以及任务配套文档中的稳态运行指南。
• “要构建并运行此二进制文件，需要哪个版本的 DOCA 和 CUDA Toolkit？” — 示例：“我的安装中 DOCA 和 CUDA 的语义化版本号不同；随 ToT 发布的 gpunetio_ib_write_bw 能否成功链接？”。答案来自能力配套文档中的版本补充说明，该说明交叉引用了 doca-version/SKILL.md 中的规范检测流程。

受众

本技能面向外部开发者和性能工程师，他们需要在用户实际安装环境和 GPU-NIC 配对上，获得可复现的持续 RDMA WRITE 带宽测量结果；其中 WR 由 CUDA 内核通过 doca-gpunetio 发出。具体包括：

• 在将应用设计定型之前，需要比较 GPUNetIO 路径、GPI 路径或主机发起型 perftest 风格路径的开发者。
• 通过重新运行此基准测试，验证调优变更的平台运维人员（例如 NUMA 绑定、GPU PCIe 位置、IB 设备选择、GID 索引或 NIC 固件烧录）。
• 需要生成下游使用者可引用的产物的 SRE／性能工程师，例如“当前这对 GPU-NIC 上由 GPUNetIO 驱动的 WRITE 带宽”。
• 需要如实回答“对于我的持续吞吐量工作负载，doca-gpunetio 路径是否有优势”的 AI Agent：提供实测数值、生成该数值的构建方式与调用命令，以及限定该数值适用范围的 GPU、NIC 和 DOCA 版本，而不是根据数据表上的宣传数字进行猜测。

本技能不适用于调试 doca-gpunetio 库本身的用户（请转到 ../../libs/doca-gpunetio/SKILL.md（doca-gpunetio/SKILL.md）），也不能替代上游 perftest 的 ib_write_bw（它测量的是 CPU 发起型 WRITE 带宽）。

语言范围

doca-gpunetio-ib-write-bw 工具以 C 加 一个 CUDA .cu 转译单元的形式提供，位于 doca/tools/gpunetio_ib_write_bw/，分为 client/ 子目录和 server/ 子目录。经验证的功能范围（依据 client/{main.c,common.h,common.c,kernel.cu,perftest.c} 和 server/{main.c,common.h,common.c,perftest.c}）：主机端 通过 meson，使用已安装的 DOCA pkg-config 模块（doca-gpunetio、doca-rdma、doca-common）进行构建；设备端 通过 nvcc，使用 DOCA GPU NetIO 设备端头文件集进行构建；带外（OOB）描述符通过客户端与服务器之间的 TCP 套接字交换。没有 Python / Rust / Go 绑定——该工具由一对命令行二进制文件组成。 此技能旨在让操作员侧工作流与语言无关；设备端 CUDA 功能无法用其他语言封装。

何时加载此技能

当用户需要，或 Agent 需要在安装了 DOCA 的真实主机上构建并运行 gpunetio_ib_write_bw 客户端和服务器时，请加载此技能。主机还必须安装与 DOCA 相匹配的 CUDA Toolkit，并且其 PCIe 拓扑中需要有 GPU 和 IB 设备。具体情况包括：

• 使用 GPUNetIO 功能测量两台主机（或一台主机与一台 BlueField DPU）之间由内核发起的持续 RDMA WRITE 带宽。
• 判断对于某类工作负载，GPUNetIO 路径是否比 GPI 编程 功能（doca-gpi/SKILL.md 库——doca/tools/ 不提供 GPI 基准测试二进制文件）或经典的 CPU 发起 perftest 路径更适合作为运行时功能。
• 记录有文档说明的基线（构建方式 + 调用方式 + DOCA 版本 + GPU + NIC + 实际部署环境 + 性能数据），以便之后排查性能回归。
• 诊断在此工具提供的脚手架中，GPUNetIO + RDMA 初始化流程所暴露的构建、链接或运行故障。

一般性 DOCA 入门、库 API 工作或安装问题不要加载此技能。此类问题请使用 doca-public-knowledge-map/SKILL.md、 ../../libs/doca-gpunetio/SKILL.md（doca-gpunetio/SKILL.md） 或 doca-setup/SKILL.md。应用级端到端吞吐量问题也不要加载此技能—— 此基准测试测量的是通过 GPUNetIO 提交 WR 的路径，而不是用户的完整流水线。

此技能提供的内容

这是一个轻量加载器。实质性内容位于两个配套文件中：

• capabilities 配套文件——工具测量的内容（由客户端侧 CUDA 内核通过 doca-gpunetio 驱动的持续 WRITE-BW 基元）、运行时表面选择规则（GPUNetIO、GPI 或 CPU 发起）、GPU-NIC 配对前提条件、吞吐量分解指南（GPU 计算占用率与 NIC 发起速率及链路饱和度）、版本叠加层（DOCA .pc 加 CUDA Toolkit）、分层错误分类（配置语法／构建时／GPU-NIC 配对／GPUNetIO 生命周期／RDMA 连接／测量可靠性／版本／跨领域）、可观测性表面（标准输出报告、DOCA 日志级别、OOB 套接字交换），以及安全叠加层（doca-gpunetio 中的*"GPU 侧句柄就是凭证"*规则；跨领域硬件安全元策略）。
• tasks 配套文件——涵盖适用任务动词的分步工作流：install（前提条件——DOCA 安装、CUDA Toolkit、GPU + NIC 配对、OOB 连通性）、configure（位于 doca/tools/gpunetio_ib_write_bw/ 下的构建树，以及封装随附 DOCA 的 meson 构建）、build（公开 DOCA 构建文档中的 meson setup + meson compile 模式）、modify（不要修补随附工具源代码；应修改调用方式和周边环境）、run（先冒烟测试再批量运行；客户端与服务端启动顺序；解读每轮报告）、test（评估循环——稳定状态、NUMA 放置、NIC 饱和度交叉检查）、debug（逐层检查错误分类）、use（如何根据 BW 结果决定工作负载类别），以及用于引导处理范围外问题的 Deferred task verbs 区块。

此技能假定主机上已安装 DOCA，存在与该安装匹配的 CUDA Toolkit，且操作人员拥有公共安装配置文件要求的权限，能够绑定 doca_dev、doca_gpu 和 OOB TCP 套接字。

此技能有意不包含的内容

此技能是Agent 指引，不是示例或脚本包。为保持边界清晰，它有意不包含以下内容，拉取请求也不应添加：

• 具体标志字符串或预期吞吐量数值，除非这些内容已由工具随附的 --help 和 main.c ARGP 注册信息确定。标志范围很小（设备名称、GPU PCIe 地址、GID 索引、客户端侧的服务器 IP）；Agent 在引用标志字符串前，会针对已安装的版本重新读取二进制文件的 --help。吞吐量数值取决于设备、固件、版本和拓扑。
• 预先编写的 DOCA GPUNetIO 或 CUDA 内核源代码，以免与随附工具树竞争。随附的 client/{main.c,kernel.cu,perftest.c,common.{c,h}} 和 server/{main.c,perftest.c,common.{c,h}} 文件是经过验证的完整示例；Agent 的职责是引导用户使用这些文件，并按照 doca-programming-guide/SKILL.md 中通用的示例修改工作流，制定最小差异修改方案。
• 任何语言编写的包装器、解析器或脚本，用于处理工具的标准输出。输出格式简单，并已在 capabilities 配套文件中说明；如果用户想要针对它编写脚本，正确的答复是*"阅读当前源代码，针对你已安装的二进制文件编写解析器"*。
• samples/、bindings/ 或 reference/ 子树。这是针对随附工具树的轻量加载器；实质性内容位于源代码树和 GPUNetIO 库文档中。

加载顺序

1. 请先阅读此技能，以确认用户的问题属于其适用范围（用户确实想通过 GPUNetIO 测量由内核发起的持续 WRITE 带宽，而不是了解 GPUNetIO 这个库或进行由 CPU 发起的测量）。
2. 关于此工具的测量内容、与 GPI 同类工具及由 CPU 发起的 perftest 之间的选择规则、吞吐量分解指南、版本叠加说明、错误分类、可观测性界面和安全叠加说明，请参阅功能配套文档。
3. 有关分步工作流——install、configure、build、modify、run、test、debug、use——请参阅任务配套文档。

相关技能

• ../../libs/doca-gpunetio/SKILL.md（doca-gpunetio/SKILL.md）——此工具封装的库。每个 GPU 的 doca_gpu 上下文、GPU 可见的 doca_gpu_eth_* 和 RDMA 侧句柄、CUDA 侧持久内核模式、双重能力发现规则（DOCA 能力查询和 cudaGetDeviceProperties），以及环境前提条件（已加载 nvidia_peermem，并已通过 DOCA 注册 CUDA 缓冲区）均在此处说明。
• ../../libs/doca-rdma/SKILL.md（doca-rdma/SKILL.md）——底层 RDMA 库。此工具绑定的 RDMA 队列通过 doca-rdma 创建并连接；队列生命周期、传输类型（RC、UC 或 UD）、权限矩阵和连接方法均由此库负责。
• ../../libs/doca-verbs/SKILL.md（doca-verbs/SKILL.md）——位于 doca-rdma / doca-gpunetio 之下的原始 verbs 备用方案。此工具使用更高层的接口；只有当用户需要 GPUNetIO + RDMA 接口未提供的特定 WR 标志 / QP 属性时，才应使用 doca-verbs。
• ../doca-gpunetio-ib-write-lat/SKILL.md（doca-gpunetio-ib-write-lat/SKILL.md）——此工具的延迟对应项。两者执行相同的物理操作，使用相同的运行时框架，但指标类别不同（带宽与延迟）。两者结合后，可全面了解 GPUNetIO 侧的吞吐量 / 延迟。
• doca-gpi/SKILL.md——GPI 编程接口（由 CUDA 内核发起的 RDMA），也是执行相同物理操作的另一种运行时框架。doca/tools/ 中没有随附 GPI 的 ib_write_lat / ib_write_bw 基准测试二进制文件，因此 GPI 对比针对的是库接口，而非同类工具。功能配套文档中的选择规则可帮助做出判断。
• doca-version/SKILL.md——规范的版本检测流程、四方匹配规则、NGC 容器语义，以及头文件优先于文档的规则。此技能中的 ## Version compatibility 部分仅提供简要叠加说明；完整内容请见该技能。
• doca-setup/SKILL.md——环境准备、安装验证、GPU + CUDA Toolkit 配套、加载 nvidia_peermem、大页、NUMA，以及使用公开 NGC DOCA 容器的 尚未安装 路径。
• doca-public-knowledge-map/SKILL.md——如何查阅公开 DOCA 文档集（docs.nvidia.com 上的 DOCA GPU NetIO 和 DOCA RDMA 页面），以及 CUDA Toolkit 的 docs.nvidia.com/cuda/ 指引。
• doca-debug/SKILL.md——贯穿各处的调试流程。此工具提供自身的错误分类；若问题根源在 DOCA 以下层级，错误分类会引导至此处。
• doca-hardware-safety/SKILL.md——适用于整个工具包的硬件安全元策略。## Safety policy 叠加说明中提供了指向该技能的交叉链接。