全文 - DOCA GPUNetIO Open Source 仓库 README

Eloudy2026-09-18 12:08

DOCA GPUNetIO 开源版（Open Source）

原文：DOCA GPUNetIO Open Source 仓库 README（github.com/NVIDIA-DOCA/gpunetio）

本仓库提供 DOCA GPUNetIO 和 DOCA Verbs 库的开源版本。其中包含的功能仅限于：在开源环境中，使用类 DOCA 风格的 API，基于 RDMA 协议（InfiniBand 和 RoCE）启用 GPUDirect Async Kernel-Initiated（GDAKI） 网络通信技术。

开源版 vs 完整版（Open vs Full）

下表列出了本 DOCA GPUNetIO 开源项目与完整版 DOCA GPUNetIO SDK 之间的主要区别：

项目 DOCA 完整版 SDK DOCA 开源版
Verbs CPU 控制路径 闭源共享库 开源 C++ 文件
GPUNetIO CPU 控制路径 闭源共享库 开源 C++ 文件
RDMA Verbs 单边（one-sided）的 GPUNetIO GPU 数据路径 支持 支持
RDMA Verbs 双边（two-sided）的 GPUNetIO GPU 数据路径 支持 不支持
以太网（Ethernet）的 GPUNetIO GPU 数据路径 支持 不支持
DMA 的 GPUNetIO GPU 数据路径 支持 不支持

完整版 SDK 更为全面，包含本次开源发布中未包含的更多功能。

但需要注意的是，GPUNetIO Verbs 数据路径的 CUDA 头文件在开源版和完整版之间是完全相同的。

目标

DOCA GPUNetIO（包括开源版和完整版）的总体目标是：将多种 GDAKI 实现整合为一个统一的驱动程序和库，提供一致的主机侧（host-side）和设备侧（device-side）接口。这一共同基础可以在当前和未来的 GDAKI 技术使用者之间共享，例如 NVSHMEM、NCCL 或 UCX。

这种方式在促进知识共享的同时，也降低了长期维护所需的工程量。

核心特性

CPU 控制路径：

  • 在 CPU/GPU 内存中创建和管理完成队列（CQ）与队列对（QP）的接口。
  • 支持通过可靠连接（Reliable Connection，RC）传输方式连接 QP。
  • 在 CPU 与 GPU 内存之间迁移 CQ/QP 资源。
  • 与标准 verbs 资源（MR、PD、上下文、设备属性等）兼容。
  • 可通过基于 dlopen 的内部动态链接使用 DOCA SDK 的受限功能。

GPU 数据路径：

  • 用于提交直接工作请求（WR）和轮询完成响应（CQE）的设备侧 API。
  • 从 GPU 直接敲响网卡门铃（更新寄存器）。

要深入了解各项特性，请参阅官方的 DOCA GPUNetIO 文档和 DOCA Verbs 文档。

使用方法

要通过 DOCA API 启用 GDAKI 技术，应用必须划分为两个阶段：

  • CPU 控制路径阶段：初始化设备、分配内存并执行其他设置任务。
  • GPU 数据路径阶段：启动一个 CUDA kernel，并在其中使用 GPUNetIO CUDA 函数。

控制路径工作流程

  1. 打开 RDMA 设备上下文：ibv_open_device。
  2. 分配 PD：ibv_alloc_pd。
  3. 注册内存区域：ibv_reg_mr。
  4. 创建 GPUNetIO 句柄：doca_gpu_create。
  5. 使用 doca_verbs_* 函数创建 CQ 和 QP。
  6. 使用 doca_verbs_qp_modify 与远程对端连接 QP。
  7. 使用 doca_gpu_verbs_export_cq 和 doca_gpu_verbs_export_qp 将 QP 和 CQ 导出到 GPU 内存。

数据路径工作流程

  1. 启动一个 GPU kernel。
  2. 使用以下方式提交工作请求：
    • 高层 API ：位于 CUDA 头文件 doca_gpunetio_dev_verbs_onesided.cuh 和 doca_gpunetio_dev_verbs_counter.cuh 中，以 doca_gpu_dev_verbs_* 开头。
    • 低层 API（高级用户） ：位于 doca_gpunetio_dev_verbs_qp.cuh 和 doca_gpunetio_dev_verbs_cq.cuh 等 CUDA 头文件中，如 doca_gpu_dev_verbs_wqe_prepare_*、doca_gpu_dev_verbs_submit。
  3. 使用 doca_gpu_dev_verbs_poll_cq_* 轮询完成事件。

不建议混用高层和低层 API。

CPU 辅助的 GDAKI（CPU-assisted GDAKI）

某些系统不支持从 GPU SM 直接敲响网卡门铃。在这种情况下，CUDA kernel 可以在 GPU 内存中提交 WQE 并轮询 CQE，但无法更新网卡寄存器。

在这类场景下，仍可通过启用 CPU 辅助模式来使用 DOCA GPUNetIO GDAKI：GPU 通知一个 CPU 线程，由该线程代为敲响网卡门铃。该模式提供了一种可靠的回退方案（性能较低），需要一个 CPU 线程周期性地调用 doca_gpu_verbs_cpu_proxy_progress()。

构建

构建主机侧库 libdoca_gpunetio.so：

bash 复制代码 
cd doca-gpunetio
make -j

输出为包含该共享库的 lib 目录。

也可以在构建时指定 CUDA 架构，并将库和示例安装到指定目录。以下示例针对 Hopper GPU（sm_90）构建并将库和示例安装到指定前缀路径：

bash 复制代码 
make install install_examples PREFIX=/path/to/directory/install CUDA_ARCH=90

启用日志

日志由 DOCA_LOG 宏管理，基于 syslog，分为不同的日志级别：

  1. EMERG
  2. ALERT
  3. CRIT
  4. ERR
  5. WARNING
  6. NOTICE
  7. INFO
  8. DEBUG

默认设置为 EMERG 级别（0）。要打印更高级别的 DOCA_LOG，请将 DOCA_GPUNETIO_LOG 环境变量设置为相应的级别数字。

启用 SDK 模式

为从 GPUNetIO 开源版访问 DOCA SDK 的受限功能，CPU 函数现在使用基于 dlopen 的内部动态链接。

如果将环境变量 DOCA_SDK_LIB_PATH 设置为有效的 DOCA SDK 库安装目录（x86 系统上通常为 /opt/mellanox/doca/libs/x86_64-linux-gnu），GPUNetIO 开源版会动态加载 DOCA SDK 函数，并用它们替代独立的开源实现。

启用 SDK 模式的示例命令行：

复制代码 
$ DOCA_GPUNETIO_LOG=6 DOCA_SDK_LIB_PATH=/opt/mellanox/doca/lib/x86_64-linux-gnu ./gpunetio_verbs_write_lat -d mlx5_0 -g 8a:00.0
Wed Apr  1 10:42:00 2026 [INFO] [examples/verbs_common.cpp]: 255: create_verbs_resources(): Setting GPU device 0 at 8a:00.0
Wed Apr  1 10:42:00 2026 [WARNING] [src/doca_gpunetio_sdk_wrapper.cpp]: 202: doca_gpu_sdk_wrapper_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64-linux-gnu. DOCA SDK is in use
Wed Apr  1 10:42:00 2026 [INFO] [src/doca_gpunetio.cpp]: 120: doca_gpu_create(): Use DOCA GPUNetIO SDK
Wed Apr  1 10:42:00 2026 [WARNING] [src/doca_verbs_dev_sdk_wrapper.cpp]: 164: doca_verbs_sdk_wrapper_dev_open_from_pd(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64-linux-gnu. DOCA SDK is in use
Wed Apr  1 10:42:00 2026 [INFO] [src/doca_verbs_dev.cpp]: 83: doca_verbs_dev_open(): Use DOCA Verbs Dev SDK
Wed Apr  1 10:42:00 2026 [WARNING] [src/doca_verbs_qp_sdk_wrapper.cpp]: 1430: doca_verbs_sdk_wrapper_ah_attr_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64-linux-gnu. DOCA SDK is in use
Wed Apr  1 10:42:00 2026 [INFO] [src/doca_verbs_qp.cpp]: 2902: doca_verbs_ah_attr_create(): Use DOCA Verbs AH Attr SDK
Wed Apr  1 10:42:00 2026 [WARNING] [src/doca_verbs_cq_sdk_wrapper.cpp]: 246: doca_verbs_sdk_wrapper_cq_attr_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64-linux-gnu. DOCA SDK is in use
Wed Apr  1 10:42:00 2026 [INFO] [src/doca_verbs_cq.cpp]: 327: doca_verbs_cq_attr_create(): Use DOCA Verbs CQ Attr SDK
Wed Apr  1 10:42:00 2026 [WARNING] [src/doca_verbs_umem_sdk_wrapper.cpp]: 204: doca_verbs_sdk_wrapper_umem_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64-linux-gnu. DOCA SDK is in use
Wed Apr  1 10:42:00 2026 [INFO] [src/doca_verbs_umem.cpp]: 150: doca_verbs_umem_create(): Use DOCA Verbs UMEM SDK
Wed Apr  1 10:42:00 2026 [WARNING] [src/doca_verbs_cq_sdk_wrapper.cpp]: 449: doca_verbs_sdk_wrapper_cq_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64-linux-gnu. DOCA SDK is in use
Wed Apr  1 10:42:00 2026 [INFO] [src/doca_verbs_cq.cpp]: 589: doca_verbs_cq_create(): Use DOCA Verbs CQ SDK
Wed Apr  1 10:42:00 2026 [WARNING] [src/doca_verbs_uar_sdk_wrapper.cpp]: 160: doca_verbs_sdk_wrapper_uar_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64-linux-gnu. DOCA SDK is in use
Wed Apr  1 10:42:00 2026 [INFO] [src/doca_verbs_uar.cpp]: 164: doca_verbs_uar_create(): Use DOCA Verbs UAR SDK
Wed Apr  1 10:42:00 2026 [WARNING] [src/doca_verbs_qp_sdk_wrapper.cpp]: 574: doca_verbs_sdk_wrapper_qp_init_attr_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64-linux-gnu. DOCA SDK is in use
....

出现 Use DOCA GPUNetIO SDK、Use DOCA Verbs Dev SDK 等打印信息，表明 DOCA_SDK_LIB_PATH 中指定的路径正确指向了 DOCA SDK 库安装目录。

反之，如果 DOCA_SDK_LIB_PATH 中指定的路径有问题，输出会发生变化：

复制代码 
$ DOCA_GPUNETIO_LOG=6 DOCA_SDK_LIB_PATH=/opt/mellanox/doca/lib/x86_64 ./gpunetio_verbs_write_lat -d mlx5_0 -g 8a:00.0
Wed Apr  1 10:41:52 2026 [INFO] [examples/verbs_common.cpp]: 255: create_verbs_resources(): Setting GPU device 0 at 8a:00.0
Wed Apr  1 10:41:52 2026 [ERR] [src/doca_gpunetio_sdk_wrapper.cpp]: 110: doca_gpunetio_sdk_wrapper_init(): Failed to find libdoca_common.so library /opt/mellanox/doca/lib/x86_64/libdoca_common.so (DOCA_SDK_LIB_PATH=/opt/mellanox/doca/lib/x86_64)
Wed Apr  1 10:41:52 2026 [WARNING] [src/doca_gpunetio_sdk_wrapper.cpp]: 193: doca_gpu_sdk_wrapper_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64, but DOCA SDK libraries not found. DOCA SDK is not in use
Wed Apr  1 10:41:52 2026 [INFO] [src/doca_gpunetio.cpp]: 131: doca_gpu_create(): Use DOCA GPUNetIO open
Wed Apr  1 10:41:52 2026 [ERR] [src/doca_verbs_dev_sdk_wrapper.cpp]: 87: doca_verbs_sdk_wrapper_init(): Failed to find libdoca_common.so library /opt/mellanox/doca/lib/x86_64/libdoca_common.so (DOCA_SDK_LIB_PATH=/opt/mellanox/doca/lib/x86_64)
Wed Apr  1 10:41:52 2026 [WARNING] [src/doca_verbs_dev_sdk_wrapper.cpp]: 154: doca_verbs_sdk_wrapper_dev_open_from_pd(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64, but DOCA SDK libraries not found. DOCA SDK is not in use
Wed Apr  1 10:41:52 2026 [INFO] [src/doca_verbs_dev.cpp]: 94: doca_verbs_dev_open(): Use DOCA Verbs Dev open
Wed Apr  1 10:41:52 2026 [INFO] [src/doca_verbs_dev.cpp]: 106: doca_verbs_dev_open(): doca_verbs_dev_open=0x564b462a7e00 was created
Wed Apr  1 10:41:52 2026 [ERR] [src/doca_verbs_qp_sdk_wrapper.cpp]: 295: doca_verbs_sdk_wrapper_init(): Failed to find libdoca_common.so library /opt/mellanox/doca/lib/x86_64/libdoca_common.so (DOCA_SDK_LIB_PATH=/opt/mellanox/doca/lib/x86_64)
Wed Apr  1 10:41:52 2026 [WARNING] [src/doca_verbs_qp_sdk_wrapper.cpp]: 1404: doca_verbs_sdk_wrapper_ah_attr_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64, but DOCA SDK libraries not found. DOCA SDK is not in use
Wed Apr  1 10:41:52 2026 [INFO] [src/doca_verbs_qp.cpp]: 2913: doca_verbs_ah_attr_create(): Use DOCA Verbs AH Attr open
Wed Apr  1 10:41:52 2026 [INFO] [src/doca_verbs_qp.cpp]: 2919: doca_verbs_ah_attr_create(): doca_verbs_verbs_ah_open=0x564b462a7e20 was created
Wed Apr  1 10:41:52 2026 [ERR] [src/doca_verbs_cq_sdk_wrapper.cpp]: 133: doca_verbs_sdk_wrapper_init(): Failed to find libdoca_common.so library /opt/mellanox/doca/lib/x86_64/libdoca_common.so (DOCA_SDK_LIB_PATH=/opt/mellanox/doca/lib/x86_64)
Wed Apr  1 10:41:52 2026 [WARNING] [src/doca_verbs_cq_sdk_wrapper.cpp]: 237: doca_verbs_sdk_wrapper_cq_attr_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64, but DOCA SDK libraries not found. DOCA SDK is not in use
Wed Apr  1 10:41:52 2026 [INFO] [src/doca_verbs_cq.cpp]: 338: doca_verbs_cq_attr_create(): Use DOCA Verbs CQ Attr open
Wed Apr  1 10:41:52 2026 [INFO] [src/doca_verbs_cq.cpp]: 344: doca_verbs_cq_attr_create(): doca_verbs_cq_attr_open=0x564b462a7eb0 was created
Wed Apr  1 10:41:52 2026 [ERR] [src/doca_verbs_umem_sdk_wrapper.cpp]: 106: doca_verbs_sdk_wrapper_init(): Failed to find libdoca_gpunetio.so library /opt/mellanox/doca/lib/x86_64/libdoca_gpunetio.so (DOCA_SDK_LIB_PATH=/opt/mellanox/doca/lib/x86_64)
Wed Apr  1 10:41:52 2026 [WARNING] [src/doca_verbs_umem_sdk_wrapper.cpp]: 186: doca_verbs_sdk_wrapper_umem_create(): Env var DOCA_SDK_LIB_PATH set to /opt/mellanox/doca/lib/x86_64, but DOCA SDK libraries not found. DOCA SDK is not in use
Wed Apr  1 10:41:52 2026 [INFO] [src/doca_verbs_umem.cpp]: 161: doca_verbs_umem_create(): Use DOCA Verbs UMEM open
...

示例

本仓库包含两个示例，用于演示用法和测量性能。

请确保在编译示例之前 先构建 libdoca_gpunetio.so。

所有示例都需要在通过网络连接的机器上分别运行一个客户端和一个服务器。

可以通过设置 #define KERNEL_DEBUG_TIMES 1 按操作启用 GPU 计时器（适用于调试，不建议用于性能测试）。

更多示例请参见 NVIDIA DOCA 完整版示例仓库。

以下命令行假设示例运行在 GPU PCIe 地址为 8A:00.0、网卡接口为 mlx5_0 的系统上。

示例 1：gpunetio_verbs_put_bw

本示例是一个类似 GDAKI 版 perftest ib_write_bw 的基准测试：客户端启动一个 CUDA kernel，执行高层 doca_gpu_dev_verbs_put 操作。服务器不启动任何 CUDA kernel：当用户按下 Ctrl+C 时，服务器校验从客户端收到的数据。

预备 ：

insmod nvidia-peermem:

bash 复制代码 
# 1. 检查模块是否存在
modinfo nvidia-peermem

# 2. 加载
sudo modprobe nvidia-peermem

# 3. 确认
lsmod | grep nvidia_peermem

运行（服务器）：

bash 复制代码 
LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/doca-gpunetio/lib DOCA_GPUNETIO_LOG=6 ./gpunetio_verbs_put_bw -g 8A:00.0 -d mlx5_0

运行（客户端）：

bash 复制代码 
LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/doca-gpunetio/lib DOCA_GPUNETIO_LOG=6 ./gpunetio_verbs_put_bw -g 8A:00.0 -d mlx5_0 -c 192.168.1.64

模式：

  • CUDA Thread 执行作用域（默认）。
  • CUDA Warp 执行作用域 ：添加 -e 1。
  • 网卡句柄类型 ：添加 -p <nic_handler 值>，其中 0：AUTO（默认），1：CPU Proxy，2：GPU SM DB。

校验成功消息（服务器）：

复制代码 
Validation successful! Data received correctly from client.

示例 2：gpunetio_verbs_write_lat

本示例是一个类似 GDAKI 版 perftest ib_write_lat 的基准测试：客户端和服务器都启动使用低层 API 的 CUDA kernel。

运行（服务器）：

bash 复制代码 
LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/doca-gpunetio/lib DOCA_GPUNETIO_LOG=6 ./gpunetio_verbs_write_lat -g 8A:00.0 -d mlx5_0 -p 2

运行（客户端）：

bash 复制代码 
LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/doca-gpunetio/lib DOCA_GPUNETIO_LOG=6 ./gpunetio_verbs_write_lat -g 8A:00.0 -d mlx5_0 -p 2 -c <server_ip_address>

模式：

  • 网卡句柄类型 ：添加 -p <nic_handler 值>，其中 0：AUTO（默认），1：CPU Proxy，2：GPU SM DB，6：GPU SM BlueFlame。

示例 3：gpunetio_verbs_write_bw

本示例是一个类似 GDAKI 版 perftest ib_write_bw 的基准测试：客户端和服务器都启动使用低层 API 的 CUDA kernel。

运行（服务器）：

bash 复制代码 
LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/doca-gpunetio/lib DOCA_GPUNETIO_LOG=6 ./gpunetio_verbs_write_bw -g 8A:00.0 -d mlx5_0

运行（客户端）：

bash 复制代码 
LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/doca-gpunetio/lib DOCA_GPUNETIO_LOG=6 ./gpunetio_verbs_write_bw -g 8A:00.0 -d mlx5_0 -c <server_ip_address>

模式：

  • 网卡句柄类型 ：添加 -p <nic_handler 值>，其中 0：AUTO（默认），1：CPU Proxy，2：GPU SM DB。

本示例不支持 GPU SM BlueFlame。

校验成功消息（服务器）：

复制代码 
Validation successful! Data received correctly from client.

致谢

如果您在工作中使用了本软件，请引用官方的 DOCA GPUNetIO 文档。

贡献

本项目由 NVIDIA 内部开发并以开源形式发布。

我们目前不接受外部贡献。

故障排除与反馈

我们感谢社区为支持 DOCA GPUNetIO 开源版用户和开发者所进行的讨论与反馈。我们建议用户：

许可证

参见 <LICENSE.txt> 文件。

相关推荐
guwentian4 小时前
WebGPU 和 WebTransport 2026 真的能上生产了吗？
web·gpu·transport
论文复现现场1 天前
课程作业要跑 PyTorch 训练，学校机房不够用去哪租？云 GPU 选型、环境迁移与防丢数据指南
人工智能·pytorch·深度学习·云计算·gpu·cuda
赋创小助手6 天前
多GPU服务器交付验收：GPU健康、P2P、NCCL与稳定性测试思路
运维·服务器·人工智能·ai·部署·gpu·p2p
Eloudy8 天前
全文 - 05 part - NVIDIA 集合通信库（NCCL）文档
gpu
探索云原生9 天前
Kueue + HAMi vGPU 实战：显存与算力配额管理
docker·ai·云原生·kubernetes·gpu
cubestudio9 天前
海光 DCU 怎么接入 Kubernetes 和 AI 平台？CubeStudio 海光 DCU 适配实操（整卡 / 共享 / 两种 vDCU 虚拟化 + DeepSeek 部署）
人工智能·机器学习·gpu
阿里云大数据AI技术10 天前
EMR Serverless Spark：CPU + GPU 异构计算使用指南
人工智能·spark·gpu
Eloudy12 天前
NVTx 主旨介绍
gpu
Eloudy12 天前
NVLS 简介
gpu
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02历年考研数学一、数学二、数学三真题试卷及答案PDF03GitHub 镜像站点04微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新05蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接062026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？07人工智能（AI）发展史：详细里程碑08ZCode 周末送额度活动开启：3 亿 Token 免费领取09数学公理体系大全:第六章 选择公理的等价形式及证明10【一等奖版】2026 国赛 A题 药材的烘干问题