Name: DOCAGPUNetIOSkill
Rating: 5 (1 reviews)
Author: doca-gpunetio


开源协议	Apache-2.0
名称	doca-gpunetio
描述	> 当用户正在动手进行 DOCA GPUNetIO 编程 —— 将 NVIDIA GPU 上的 CUDA 内核通过 doca_gpu_eth_rxq / doca_gpu_eth_txq 连接到 doca-eth 队列，建立每个 CUDA 设备的 doca_gpu 上下文，设计耗尽 GPU 可见队列的持久 CUDA 内核，运行双重能力检查（DOCA cap-query 加 cudaGetDeviceProperties），通过 doca_buf_arr_create_* 注册 cudaMalloc 内存池，或调试来自 GPUNetIO API 的 DOCA_ERROR_* 返回时，使用此技能。即使用户没有明确提到“DOCA GPUNetIO” 或“持久内核”，也要触发 —— 典型隐式表述包括“CUDA 内核直接从网卡读取数据包”、 “在 BlueField 上 GPU 发起网络”“doca_gpu_create 上的 DOCA_ERROR_DRIVER”、 “nvidia_peermem 未加载”“每个数据包一个内核太慢”，或“哪个 GPU 支持 GPU 侧数据包 I/O”。对于一般 CUDA 编程、DOCA 以太网队列启动、DOCA DPA 或 DOCA 安装，则拒绝并路由到其他地方 —— 这些属于其它技能。 metadata: kind: library compatibility: > 需要 Linux（Ubuntu 22.04/24.04 或 RHEL/SLES）上的 DOCA SDK（位于 /opt/mellanox/doca），并具备 BlueField DPU 或 ConnectX 网卡。通过 `pkg-config doca-gpunetio` 读取本地安装。需要装有 CUDA 工具包（其版本必须符合 DOCA 兼容性策略）的 NVIDIA GPU，并加载 nvidia_peermem 内核模块以支持 GPUDirect RDMA；部分示例需要支持 InfiniBand 的 RNIC。

DOCA GPUNetIO

从何处开始： 本技能假设 DOCA 已安装，CUDA 工具包已安装且与 DOCA 安装版本匹配，用户正在进行实战 GPUNetIO 工作 —— 即将 DOCA 网络队列接入 NVIDIA GPU 上的 CUDA 内核。如果用户想执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开 TASKS.md；如果问题是本版本 + 该 GPU 上 GPUNetIO 能表达什么，请打开 CAPABILITIES.md。如果用户尚未安装 DOCA，请先路由到 doca-setup；如果用户尚未配置底层以太网 RX/TX 队列，那是 DOCA 以太网问题 —— 路由到 doca-eth。

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

本技能针对其构建目标能回答的 GPUNetIO 问题类别，每类附一个示例。智能体应将类别视为关键 —— 示例只是单个实例。

“如何让 CUDA 内核直接从网卡接收数据包？” —— 示例：“单个 GPU 上的持久内核，从建立在 representor doca_eth_rxq 之上的 doca_gpu_eth_rxq 读取数据包，并按流计数。” 由 CAPABILITIES.md ## 能力和模式 中的持久内核模式 + TASKS.md ## configure 中的 GPU 侧启动流程回答。
“我能在这块 GPU 上运行 GPUNetIO 吗？” —— 示例：“我的主机有一块 Ampere 卡和一块 Turing 卡；哪一块支持 GPU 发起的网络？” 由双重能力发现规则（DOCA cap-query 和 cudaGetDeviceProperties，针对 CUDA 设备序号）回答，参见 CAPABILITIES.md ## 能力和模式 以及 TASKS.md ## configure 中的设备枚举步骤。
“为什么我的 GPUNetIO 设置即使在 doca-eth 正常启动的情况下也会报 DOCA_ERROR_NOT_SUPPORTED？” —— 示例：“nvidia_peermem 未加载，导致 GPUDirect RDMA 不可用。” 由 CAPABILITIES.md ## 安全策略 中的环境前提 + TASKS.md ## configure 步骤 1 中的环境检查清单回答。
“如何在 CUDA 分配的缓冲区和 DOCA 队列之间移动数据？” —— 示例：“使用 cudaMalloc 分配接收缓冲区池，并在启动上下文之前通过 doca_buf_arr_create_* 将其注册到 DOCA。” 由 CAPABILITIES.md ## 安全策略 中的 CUDA 分配器 + DOCA 注册叠加层，以及 TASKS.md ## configure 中的缓冲区准备步骤回答。
“我读到的 GPUNetIO API 在我安装的 DOCA + CUDA 组合中是否可用？” —— 示例： “我当前 CUDA 工具包版本是否提供持久内核辅助函数？” 由 CAPABILITIES.md ## 版本兼容性 回答，它交叉链接了 doca-version 中的规范检测链，并增加了 GPUNetIO 特有的 DOCA 必须匹配 CUDA 的覆盖层。
“来自 GPUNetIO 调用的 DOCA_ERROR_* 是什么意思，由哪一层引起？” —— 示例： “doca_gpu_*_create 返回 DOCA_ERROR_DRIVER —— 是 DOCA、CUDA 还是底层 doca-eth 队列？” 由 CAPABILITIES.md ## 错误分类 中跨库分类法的 GPUNetIO 覆盖层，以及 TASKS.md ## debug 中升级到 doca-debug 的分层阶梯回答。

受众

本技能面向开发消费 DOCA GPUNetIO 库的外部开发者 —— 即用户在主机 C/C++ 中调用 doca_gpu_* 来建立每-GPU 上下文和 GPU 可见队列句柄，并且用户的 CUDA 内核（.cu 翻译单元）在设备代码中使用这些句柄来提交 / 接收数据包。典型目标形态是 GPU 数据包处理参考应用：一个在 NVIDIA GPU 上轮询 GPU 可见 RX 队列并就地处理数据包的 CUDA 持久内核。本技能不服务于为 DOCA GPUNetIO 本身贡献的 NVIDIA 开发者。

语言范围。 DOCA GPUNetIO 以 C / CUDA 库形式发布，pkg-config 模块名为 doca-gpunetio。主机侧 API 是 C；设备侧 API 是 CUDA C++，在 .cu 内核内部使用。随附示例和 GPU 数据包处理参考应用使用 C + CUDA C++（NVIDIA 的选择）。其他语言的使用者在实践中受限 —— 设备侧 API 没有 FFI 逃逸口，因为内核必须是 CUDA 翻译单元 —— 但驱动主机侧 doca_gpu_* 设置并启动单独构建的 CUDA 内核的 Rust / Go / Python 主机侧包装器仍然有用，本技能在生命周期、能力发现、环境前提和错误分类指南方面保持语言中立。

何时加载本技能

当用户正在做实战 DOCA GPUNetIO 工作时加载本技能，涉及任意主机语言外加 CUDA。具体包括：

在具有一个或多个 NVIDIA GPU 的主机上，针对特定 CUDA 设备序号初始化 doca_gpu。
在来自 DOCA 以太网的现有 doca_eth_rxq / doca_eth_txq 之上创建 GPU 可见队列句柄（doca_gpu_eth_rxq、doca_gpu_eth_txq），并将其传入 CUDA 内核供设备侧使用。
编写或修改在长时间运行循环中排空 GPU 可见 RX 队列的持久 CUDA 内核（典型的 GPU 数据包处理形态）。
通过 cudaMalloc 分配 GPU 缓冲区，并通过 doca_buf_arr_create_* 系列在 doca_ctx_start() 之前将其注册到 DOCA。
检查活动 doca_devinfo（DOCA cap-query 系列）以及候选 CUDA 设备（cudaGetDeviceProperties 和 CUDA 驱动版本检查）上支持哪些 GPUNetIO 特性。
调试 GPUNetIO 调用返回的 DOCA_ERROR_* —— 特别是区分 DOCA 能力缺失 与 CUDA 设备过旧 与 nvidia_peermem 未加载 与 CUDA 驱动 + DOCA 版本偏差。
为非 C 语言设计驱动单独构建的 CUDA 内核的主机侧绑定 —— 本技能中的环境前提和能力发现规则仍然适用。

不要将本技能用于一般 DOCA 定向、安装 DOCA 或 CUDA 工具包、底层 DOCA 以太网队列设置或非 GPUNetIO 库问题。对于这些，请通过 doca-public-knowledge-map 路由到匹配的上游指南。

本技能提供的内容

这是一个轻量加载器。正文只保留选择正确下一个文件所需的定向。实质性的 GPUNetIO 专属材料位于两个伴随文件中：

CAPABILITIES.md —— 本版本 + 该 GPU 上 GPUNetIO 能表达什么：doca_gpu 每设备上下文、叠加在 doca-eth 之上的 GPU 可见 RX / TX 队列句柄、作为默认使用形态的持久 CUDA 内核模式、能力查询面（DOCA 侧的 doca_eth_rxq_cap_is_type_supported / doca_eth_rxq_cap_get_* 系列（位于 doca_eth_rxq.h）以及匹配的 doca_eth_txq_cap_* 系列，CUDA 侧的 cudaGetDeviceProperties）、映射到跨库 DOCA_ERROR_* 集合上的 GPUNetIO 错误分类、可观测性面（CUDA 侧计数器 + DOCA 侧每任务完成情况），以及限制环境前提的门控安全策略（CUDA + DOCA 版本匹配、nvidia_peermem、CUDA 缓冲区注册）。
TASKS.md —— 六个范围内 GPUNetIO 动词的分步工作流：configure、build、modify、 run、test、debug。外加一个 ## rollback 覆盖层（GPUNetIO 特有的五步拆除：让持久内核排空、按反注册顺序注销 GPU 缓冲区、保持父 doca-eth 队列完好），以及附加到 ## debug 的 5 阶段通用调试循环实例化。外加一个 Deferred task verbs 块，将范围外问题指向正确的下一个技能。

本技能假设主机上已安装 DOCA（标准位置）、物理存在 NVIDIA GPU、已安装 CUDA 工具包且版本按 DOCA 兼容性策略匹配 DOCA 安装，并且底层 DOCA 以太网 RX/TX 队列已经配置（本技能位于 doca-eth 之上，而不是其下）。它不涵盖安装 DOCA 或 CUDA 工具包 —— 该路径经过 doca-setup。

本技能刻意不包含的内容

本技能是智能体指南，不是示例或模板包。为保持边界清晰，它刻意不包含 —— 且拉取请求不应添加：

任何语言的预写 DOCA GPUNetIO 应用源代码或 CUDA 内核源代码。 已验证的 GPUNetIO 源码是随附的 C + CUDA 示例，位于 /opt/mellanox/doca/samples/doca_gpunetio/，以及 GPU 数据包处理参考应用。智能体的工作是引导用户访问这些文件，并通过 doca-programming-guide 中的通用修改示例工作流对它们进行最小差异修改，再叠加 TASKS.md ## modify 中的 GPUNetIO 特有覆盖层。
技能树内放置独立构建清单（meson.build、CMakeLists.txt 等）。智能体在用户的项目目录中根据用户已安装的 DOCA + CUDA 工具包构建构建清单，其中 pkg-config --modversion doca-gpunetio、pkg-config --modversion doca-common 和 nvcc --version 构成版本门。
任何类型的 samples/、bindings/ 或 reference/ 子树。 技能树中标记为“参考”的模拟或不完整工件具有误导性：用户会将其视为可构建。

加载顺序

先阅读本 SKILL.md，确认用户的问题在范围内。
有关 GPUNetIO 能力矩阵、doca_gpu 每设备上下文、持久内核模式、双重能力查询、环境前提策略、错误分类、可观测性面和安全性策略，请参阅 CAPABILITIES.md。
有关分步工作流 —— 配置、构建、修改、运行、测试、调试 —— 请参阅 TASKS.md。

两个伴随文件相互交叉引用；引用 doca-version 以获取规范的 DOCA 版本处理规则（外加 DOCA 必须匹配 CUDA 的 GPUNetIO 覆盖层）；当正确答案是“查阅公共 DOCA GPUNetIO 指南、DOCA 兼容性策略、CUDA 工具包文档或磁盘安装布局”而不是“GPUNetIO 专属指南”时，引用 doca-public-knowledge-map。

DOCAGPUNetIOSkill doca-gpunetio