doca-gpunetio

DOCA GPUNetIO

示例

• “CUDA 内核直接从网卡读取数据包。” — 属于此范围。使用 doca_gpu_eth_rxq / _txq 和持久化内核；不要将其改写为由主机 CPU 处理以太网。
• “在 doca_gpu_create 上出现 DOCA_ERROR_DRIVER。” — 更改队列类型之前，先检查 CUDA 设备是否匹配，以及 dmabuf / nvidia-peermem 是否已注册。

说明

遵循下文的加载顺序。需要配置 / 构建 / 运行时，请打开任务配套文档。需要选择 GPU 路径还是主机路径时，请打开功能配套文档。不要打开所有配套文件。

从这里开始： 此技能假设 DOCA 已安装，CUDA 工具包已安装且与 DOCA 安装版本匹配，并且用户正在动手进行 GPUNetIO 开发——也就是说，将 DOCA 网络队列接入 NVIDIA GPU 上的 CUDA 内核。若用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文档；若用户想了解此版本 + 此 GPU 上的 GPUNetIO 能够实现什么，请打开功能配套文档。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md；如果用户尚未设置底层以太网 RX/TX 队列，这是 DOCA Ethernet 问题——请转到 doca-eth/SKILL.md。

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

此技能旨在解答的 GPUNetIO 问题类别，每类各附一个完整示例。Agent 应将类别视为关键所在——完整示例只是一个具体实例。

• “如何让 CUDA 内核直接从网卡接收数据包？” — 完整示例：“单个 GPU 上的持久化内核从基于 representor doca_eth_rxq 构建的 doca_gpu_eth_rxq 接收数据包，并按流计数”。由 ## 功能和模式中的持久化内核模式 + ## configure 中的 GPU 端初始化工作流解答。
• “我能在这块 GPU 上运行 GPUNetIO 吗？” — 完整示例：“我的主机有一块 Ampere 显卡和一块 Turing 显卡；哪块支持 GPU 发起网络通信？”。由 ## 功能和模式中的双重功能发现规则（DOCA cap-query 和针对 CUDA 设备序号的 cudaGetDeviceProperties）+ ## configure 中的设备枚举步骤解答。
• “为什么我的 GPUNetIO 设置会因 DOCA_ERROR_NOT_SUPPORTED 而失败，尽管 doca-eth 已正常启动？” — 完整示例：“未加载 nvidia_peermem，因此 GPUDirect RDMA 不可用”。由 ## 安全策略中的环境前置条件 + ## configure 第 1 步中的环境检查清单解答。
• “如何在 CUDA 分配的缓冲区与 DOCA 队列之间移动数据？” — 完整示例：“使用 cudaMalloc 创建接收缓冲区池，并在启动上下文之前通过 doca_buf_arr_create_* 将其注册到 DOCA”。由 ## 安全策略中的 CUDA 分配器 + DOCA 注册补充说明，以及 ## configure 第 4 步中的缓冲区准备步骤解答。
• “我读到的 GPUNetIO API 是否适用于我安装的 DOCA + CUDA 组合？” — 完整示例：“我使用的 CUDA 工具包版本是否提供持久化内核辅助函数？”。由 ## 版本兼容性中的版本兼容性补充说明解答，该部分交叉链接到 doca-version/SKILL.md 中的规范检测流程，并补充了 GPUNetIO 专属的 DOCA 必须与 CUDA 匹配 说明。
• “GPUNetIO 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？” — 完整示例：“doca_gpu_*_create 上出现 DOCA_ERROR_DRIVER——问题出在 DOCA、CUDA，还是底层的 doca-eth 队列？”。由 ## 错误分类中针对跨库分类的 GPUNetIO 补充说明 + ## debug 中逐层排查的流程解答；该流程会升级至 doca-debug/SKILL.md。

适用对象

此技能面向构建使用 DOCA GPUNetIO 库的应用程序的外部开发者——也就是说，其代码会从主机端 C/C++ 调用 doca_gpu_*，以建立每个 GPU 的上下文和 GPU 可见的队列句柄；其 CUDA 内核（.cu 翻译单元）则会在设备代码中使用这些句柄来发送／接收数据包。典型目标是 GPU Packet Processing 参考应用：在 NVIDIA GPU 上运行的 CUDA 持久化内核，会轮询 GPU 可见的 RX 队列，并在 GPU 上原地处理数据包。此技能不面向为 DOCA GPUNetIO 本身贡献代码的 NVIDIA 开发者。

语言范围。 DOCA GPUNetIO 以 C / CUDA 库的形式提供，pkg-config 模块名称为 doca-gpunetio。主机端 API 使用 C；设备端 API 是在 .cu 内核中使用的 CUDA C++。随附的示例和 GPU Packet Processing 参考应用采用 C + CUDA C++ 编写（这是 NVIDIA 的选择）。实际上，其他语言的使用者受到限制——设备端 API 没有 FFI 变通方案，因为内核必须是 CUDA 翻译单元——但使用 Rust / Go / Python 编写主机端封装、驱动主机端 doca_gpu_* 设置并启动单独构建的 CUDA 内核，仍然很有用；此技能中的生命周期、能力发现、环境前置条件和错误分类指导也与语言无关。

何时加载此技能

用户使用任意主机语言配合 CUDA 实际开发 DOCA GPUNetIO 时，加载此技能。具体包括：

• 在一台配备一块或多块 NVIDIA GPU 的主机上，针对特定 CUDA 设备序号初始化 doca_gpu。
• 在 DOCA Ethernet 提供的现有 doca_eth_rxq / doca_eth_txq 上创建 GPU 可见的队列句柄（doca_gpu_eth_rxq、doca_gpu_eth_txq），并将句柄传入 CUDA 内核供设备端使用。
• 编写或修改持久化 CUDA 内核，使其在长时间运行的循环中清空 GPU 可见的 RX 队列（典型的 GPU Packet Processing 模式）。
• 通过 cudaMalloc 分配 GPU 缓冲区，并在 doca_ctx_start() 之前使用 doca_buf_arr_create_* 系列 API 将其注册到 DOCA。
• 检查当前 doca_devinfo 支持哪些 GPUNetIO 功能（DOCA 能力查询系列 API），以及候选 CUDA 设备支持哪些功能（cudaGetDeviceProperties 和 CUDA 驱动程序版本检查）。
• 调试 GPUNetIO 调用返回的 DOCA_ERROR_*——尤其是区分缺少 DOCA 能力、CUDA 设备过旧、未加载 nvidia_peermem 和 CUDA 驱动程序与 DOCA 版本不匹配。
• 为非 C 语言设计主机端绑定，以驱动单独构建的 CUDA 内核——此技能中的环境前置条件和能力发现规则仍然适用。

对于通用 DOCA 概览、安装 DOCA 或 CUDA 工具包、底层 DOCA Ethernet 队列设置，或非 GPUNetIO 库问题，不要加载此技能。对于这些问题，请通过 doca-public-knowledge-map/SKILL.md 转到相应的上游指南。

此技能提供的内容

这是一个轻量加载器。正文仅保留选择合适下一文件所需的导引信息。实质性的 GPUNetIO 专属内容位于两个配套文件中：

• 能力配套文件——说明此版本和这块 GPU 上的 GPUNetIO 能实现什么： doca_gpu 每设备上下文、基于 doca-eth 的 GPU 可见 RX / TX 队列句柄、作为默认用法形式的持久 CUDA 内核模式、能力查询接口（DOCA 侧的 doca-eth doca_eth_rxq.h 中的 doca_eth_rxq_cap_is_type_supported / doca_eth_rxq_cap_get_* 系列，以及相应的 doca_eth_txq_cap_* 系列；CUDA 侧的 cudaGetDeviceProperties）、映射到跨库 DOCA_ERROR_* 集合的 GPUNetIO 错误分类、可观测性接口（CUDA 侧计数器 + DOCA 侧逐任务完成情况），以及控制环境前提条件的安全策略（CUDA + DOCA 版本匹配、dmabuf 或 nvidia-peermem 注册）。
• 任务配套文件——涵盖范围内六种 GPUNetIO 动词的分步工作流：configure、build、modify、run、test、 debug。此外还包括一个 ## rollback 叠加章节（GPUNetIO 专属的五步拆除流程：通知持久内核排空、按注册顺序反向注销 GPU 缓冲区，并保留父级 doca-eth 队列），以及附加到 ## debug 的五阶段通用调试循环实例。 还包括一个 Deferred task verbs 区块，将范围外的问题指向合适的下一技能。

此技能假定主机上已在标准位置安装 DOCA、已实际配备 NVIDIA GPU、已安装 CUDA 工具包且其版本依照 DOCA 兼容性政策与 DOCA 安装版本匹配，并且底层 DOCA Ethernet RX/TX 队列已配置完毕（此技能基于 doca-eth 构建，而非位于其下层）。此技能不涵盖 DOCA 或 CUDA 工具包的安装——相关流程请参阅 doca-setup/SKILL.md。

此技能有意不提供的内容

此技能是面向 Agent 的指导，而非示例或模板合集。为明确界限，此技能有意不包含以下内容，且不应在拉取请求中添加：

• 预先编写的 DOCA GPUNetIO 应用程序源代码或 CUDA 内核源代码，无论使用何种语言。 已验证的 GPUNetIO 源代码是随附的 C + CUDA 示例，位于 /opt/mellanox/doca/samples/doca_gpunetio/，以及 GPU Packet Processing 参考应用程序。Agent 的职责是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用修改示例工作流，在这些文件上执行最小差异修改， 再叠加 ## modify 中的 GPUNetIO 专属覆盖规则。
• 单独的构建清单（meson.build、 CMakeLists.txt，……）放在技能目录中。Agent 会在用户的项目 目录中，根据用户已安装的 DOCA + CUDA 工具包构建清单，并以 pkg-config --modversion doca-gpunetio、 pkg-config --modversion doca-common 和 nvcc --version 作为版本检查依据。
• 任何类型的 samples/、bindings/ 或 reference/ 子目录。此技能目录中的模拟或不完整制品，即使标注为“参考”，也会造成误导：用户会误以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其适用范围。
2. 有关 GPUNetIO 能力矩阵、doca_gpu 按设备划分的上下文、持久化内核模式、双重能力查询、环境前置条件策略、错误分类、可观测性范围和安全策略，请参阅能力配套文档。
3. 有关分步工作流——配置、构建、修改、运行、测试和调试——请参阅任务配套文档。

这两个配套文件会彼此交叉引用， doca-version/SKILL.md（其中包含规范的 DOCA 版本处理规则，以及 GPUNetIO 的补充要求：DOCA 必须与 CUDA 匹配），以及 doca-public-knowledge-map/SKILL.md， 以便在正确答案是“查阅公开的 DOCA GPUNetIO 指南、DOCA 兼容性政策、CUDA 工具包文档或磁盘上的安装布局”，而非 “GPUNetIO 专属指导”时，提供相应指引。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源及已安装 DOCA 软件包磁盘布局的路由表。公开的 GPUNetIO 指南位于 https://docs.nvidia.com/doca/sdk/DOCA-GPUNetIO/index.html； GPU Packet Processing 参考应用可从该页面访问。CUDA 工具包和 DOCA 兼容性政策的链接也位于同一张路由表中。
• doca-setup/SKILL.md — 环境准备、 安装验证、CUDA 工具包安装和验证，以及使用公开的 NGC DOCA 容器的 尚未安装任何内容 路径。此技能假定其前置条件已满足，且 CUDA 已安装，版本与 DOCA 匹配。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。此技能的 ## Version compatibility 会交叉引用四方匹配规则，并根据 DOCA 兼容性政策补充 GPUNetIO 专属的 DOCA 和 CUDA 必须匹配 要求。
• doca-structured-tools-contract/SKILL.md — 此套件的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的命令附录遵循此约定。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式： 规范的 pkg-config + meson 构建模式、 通用的优先修改已提供示例来构建首个应用的工作流、通用生命周期、跨库的 DOCA_ERROR_* 分类，以及程序端调试顺序。此技能在此基础上补充 GPUNetIO 专属内容。
• doca-debug/SKILL.md — 涵盖各方面的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。GPUNetIO 专属调试（CUDA + DOCA 版本不匹配、缺少 nvidia_peermem、持久化内核无响应挂起、CUDA 分配器与 DOCA 注册不匹配） 在此阶梯基础上补充说明。

DOCA Ethernet 是 GPUNetIO 必须搭配使用的库：GPU 可见的 RX / TX 队列句柄构建在 DOCA Ethernet 的 doca_eth_rxq / doca_eth_txq 之上。有关底层队列设置，请参阅 doca-eth/SKILL.md。