doca-gpi

DOCA GPI

示例

• “CUDA 内核需要从 GPU 内存发起 RDMA。”——这属于 GPI 的适用范围。使用 GPI domain / channel，而不是 GPUNetIO 的 send/recv 接口。
• “如何将 GPU 句柄传给我的 CUDA 内核？”——使用 doca_gpu_gpi_channel*。不要将此问题转到 DPA 侧的 RDMI。

说明

按照下方的加载顺序操作。需要配置 / 修改 / 调试时，打开任务配套文档。需要了解 GPI 与 GPUNetIO、RDMI 的区别时，打开功能配套文档。不要打开所有配套文件。

从这里开始： 此技能假设 DOCA 已安装，且用户正在一台通过 PCIe 连接了 BlueField / ConnectX 设备和 NVIDIA GPU 的主机上进行实际的 GPI 开发。如果用户想要执行某项操作（安装 / 配置 / 构建 / 修改 / 运行 / 测试 / 调试 / 使用），请打开任务配套文档；如果用户想了解此版本的 GPI 能实现什么——包括 domain + channel 对象模型、GPU 侧句柄传递、与 doca-gpunetio 和 doca-verbs 的关系、属性对象以及安全覆盖层——请打开功能配套文档。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。

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

此技能旨在回答的 GPI 问题类别，每类都附有一个具体示例。Agent 应将类别视为核心内容，具体示例只是单个实例。

• “这种情况应该使用 doca-gpi 还是 doca-gpunetio？”——具体示例：“我的 CUDA 内核需要直接向远程 DPU 的内存发起 RDMA 写入——我应该使用更高层级的 Send/Receive 接口，还是更底层的 channel/queue 接口？”。可通过 ## Capabilities and modes 中的 channel 级别与 Send/Receive 级别选择规则及接口选择表回答。
• “如何启动 GPI channel 并将其连接到远程对等端？”——具体示例：“创建 GPI，设置 domain + channel 属性的容量，创建 channel，与远程端交换端点连接信息，然后连接端点。” 可通过 ## Capabilities and modes 中的 channel 对象生命周期，以及 ## configure 中的配置流程回答。
• “GPU 侧句柄是什么？如何将它传给我的 CUDA 内核？”——具体示例：“doca_gpi_gpu_channel_get 会返回 doca_gpu_gpi_channel*——如何将它加入 CUDA 内核的参数列表？” 可通过 ## Capabilities and modes 中的 GPU 句柄传递模式，以及 ## run 中的运行侧连接方式回答；CUDA 侧编程接口本身另见 doca-gpunetio/SKILL.md。
• “我的 CUDA + GPU + DOCA 版本组合需要满足什么要求？”——具体示例：“我有 BlueField-3 + A100；需要哪个 CUDA Toolkit 和哪个 DOCA 版本？” 可通过 ## Version compatibility 中的版本覆盖层，以及 ## install 中的安装检查回答。
• “如何设置所需 channel 和工作队列的容量？”——具体示例：“我想在一个 domain 中创建 64 个 channel，每个 channel 的 send queue 有 1024 个条目；应该使用哪些 setter？” 可通过 ## Capabilities and modes 中的属性对象容量设置规则（doca_gpi_domain_attr_set_num_channels、doca_gpi_channel_attr_set_sq_wqe_num），以及 ## configure 中的容量设置步骤回答。
• “doca_gpi_* 调用返回的这个 DOCA_ERROR_* 是什么意思？”——具体示例：“doca_gpi_gpu_channel_get 返回 DOCA_ERROR_*。” 可通过 ## Error taxonomy 中针对跨库错误分类的 GPI 覆盖层，以及 ## debug 中逐层排查的流程回答；若需升级处理，请参见 doca-debug/SKILL.md。

受众

本技能面向构建 GPU 驻留型 DOCA 应用、需要直接从 CUDA 内核驱动 RDMA 队列的外部开发者——也就是说，他们的加速器端代码需要从 GPU 内存提交 RDMA 操作，而无需经由主机 CPU 往返传递。典型调用方是在 NVIDIA GPU 上运行的 CUDA 内核，该 GPU 与 BlueField / ConnectX 设备位于同一主机上，可通过 DOCA GPU-NetIO 堆栈以类似 GPUDirect 的方式访问 DPU 的 RDMA 队列，并使用 GPI 通道和队列句柄发起 RDMA 操作。本技能不适用于为 DOCA GPI 本身做贡献的 NVIDIA 开发者，也不适用于更高层、采用以太网形态的 Send/Receive GPU NetIO API——该 API 属于 doca-gpunetio/SKILL.md。

语言范围

DOCA GPI 以 C 库的形式提供，其 pkg-config 模块名为 doca-gpi。该库的主机端接口（doca_gpi_*）使用 C；GPU 端接口——doca_gpu_gpi_channel* 句柄，以及 CUDA 内核通过该句柄调用的设备端函数——使用 nvcc 编译，并依赖 doca-gpunetio/SKILL.md 中所述的 DOCA GPU NetIO 设备端头文件集。其他语言的使用者（Rust、Go、Python，……）通过 FFI 使用主机端 *.so；在这种情况下，本技能负责确保通道 / 队列生命周期、GPU 句柄交接、版本要求和安全说明不依赖特定语言，并引导 Agent 将公共 C ABI 视为权威接口，因为任何封装最终都会调用它。GPU 端接口无法用其他语言封装——它会直接编译并链接到 CUDA 二进制文件中。

何时加载此技能

当用户在同时配备 BlueField / ConnectX 设备和 NVIDIA GPU 的主机上实际使用 DOCA GPI时，加载此技能。具体包括：

• 为新的 GPU 发起 RDMA 工作负载，在 doca-gpi（较低层的通道 / 队列接口）和 doca-gpunetio（较高层的 Send/Receive 接口）之间做出选择。
• 在 doca_dev 上创建 doca_gpi，通过 doca_gpi_set_* 系列函数（域数量、GID 索引、端口）进行配置，并在调用 doca_gpi_start() 前，通过 doca_gpi_domain_attr_* / doca_gpi_channel_attr_* 设置函数确定域和通道的大小。
• 使用 doca_gpi_channel_create 创建通道，并通过 doca_gpi_gpu_channel_get 获取其 GPU 端句柄，然后将该句柄传递给 CUDA 内核。
• 使用 doca_gpi_channel_ep_conn_info_create / doca_gpi_channel_ep_connect 与远程对端交换端点连接信息，以建立端到端的 GPU 驱动通道。
• 将内存区域附加到 GPI 域，使用 doca_gpi_domain_attach_local_mmap / doca_gpi_domain_attach_remote_mmap（各自均依赖应用创建的 doca_mmap）。
• 调试 doca_gpi_* 调用返回的 DOCA_ERROR_*，并判断原因是生命周期顺序错误、GPU 数据路径分配不当、CUDA 版本不匹配，还是 DOCA 下层的问题。

对于一般 DOCA 入门、安装 DOCA、由主机 CPU 发起的 RDMA，或更高层、采用以太网形态的 GPU NetIO Send/Receive API，不要加载此技能。对于这些情况，分别使用 doca-public-knowledge-map/SKILL.md、doca-setup/SKILL.md、doca-rdma/SKILL.md 和 doca-gpunetio/SKILL.md。 如果一个问题同时涉及 GPI 通道生命周期和 CUDA 端 GPU NetIO 行为，请同时加载这两个技能：本技能负责 GPI 对象的创建、连接和拆除，而 doca-gpunetio 负责内核启动和设备端执行。如果阅读两者的适用范围后仍无法确定边界，请先询问故障发生在哪一侧，不要自行推断。

此技能提供的内容

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

• capabilities 配套文件——说明 GPI 在此版本中可以表达什么：doca_gpi / doca_gpi_domain / doca_gpi_channel 对象模型、GPU 侧句柄交接、与 doca-gpunetio/SKILL.md（负责 GPU 侧 doca_gpu_gpi_channel* 设备接口）的关系，以及与 doca-verbs/SKILL.md 和 doca-dpa/SKILL.md（GPI 所依赖的传输层和 DPA 层）的关系；域和通道属性对象；成熟度声明（每个 doca_gpi_* 符号都标记为 DOCA_EXPERIMENTAL）；GPI 对跨库 DOCA_ERROR_* 分类体系的补充；可观测性接口（CUDA 侧通道轮询、mmap 挂接交换）；以及限制 GPU 侧发起 RDMA 的安全策略。
• tasks 配套文件——针对八项范围内动词的分步工作流：install、configure、build、modify、run、test、debug、use。此外还包含一个 Deferred task verbs 区块，将超出范围的问题指向正确的后续技能。

此技能假设主机上已在标准位置安装 DOCA，已安装与该 DOCA 兼容的 CUDA Toolkit，并且用户拥有其公开安装配置所要求的权限。此技能不涵盖安装 DOCA——相关流程请参阅 doca-setup/SKILL.md。

此技能有意不提供的内容

此技能提供的是Agent 指引，而不是样例或模板合集。为明确边界，以下内容有意不包含在内，且不应由拉取请求添加：

• 任何语言的预编写 DOCA GPI 应用源代码。 Agent 的职责是引导用户使用经过验证的参考代码（已安装软件包集中的 DOCA GPU-NetIO 样例是 GPU 侧交接的权威实操示例），并依据 doca-programming-guide/SKILL.md 中的通用样例修改工作流，规定最小差异修改方案。 由于公共头文件中的每个 GPI 符号都标记为 DOCA_EXPERIMENTAL，此技能不会根据文档说明编写 GPI 源代码。
• 独立的构建清单（meson.build、CMakeLists.txt、Cargo.toml 等），不得放在此技能中。Agent 会在用户的项目目录中，根据用户已安装的 DOCA 构建清单；pkg-config --modversion doca-gpi 是判定依据。
• CUDA 内核模板。 CUDA 侧接口由 doca-gpunetio/SKILL.md 负责；GPI 的 GPU 侧句柄由该文件所述的 CUDA 编程模型使用。此技能会说明 GPI 专属的交接方式（doca_gpu_gpi_channel* 类型、通道连接调用），但不会编写 CUDA 内核。
• 任何形式的 samples/、bindings/ 或 reference/ 子树。 即使标注为“reference”，此技能目录中的模拟或不完整内容也会造成误导：用户会以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其范围。
2. 有关 GPI 对象模型、GPU 侧交接模式、域和通道属性对象、版本兼容性规则、错误分类体系、可观测性及安全策略，请参阅 capabilities 配套文件。
3. 有关分步工作流——install、configure、build、modify、run、test、debug、use——请参阅 tasks 配套文件。

如果正确答案是“查阅公共文档或已安装软件包布局”，而不是“GPI 专属指引”，两个配套文件都会通过交叉链接指向彼此以及 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-gpunetio/SKILL.md — GPU NetIO 库，为 CUDA 内核提供 Send/Receive 形式的以太网 I/O，并拥有 GPI 移交给它的 GPU 侧设备接口：doca_gpu_gpi_channel* 类型及其设备侧 .cuh API 位于 doca-gpunetio 中，且 doca_gpi.h 会包含 doca_gpunetio.h。两者可在同一应用中共存。 ## Capabilities and modes 中的选择表是关键决策指南。
• doca-verbs/SKILL.md 和 doca-dpa/SKILL.md — GPI 构建于其上的传输层和 DPA 层。dependencies/meson.build 列出了 doca-dpa、doca-gpunetio 和 doca-verbs（以及 libmlx5 / libibverbs 外部依赖）；doca_gpi_get_dpa 会返回 由 GPI 拥有的 doca_dpa*，用于调整 DPA 属性。RDMA 传输类型、GID / 端口选择以及权限语义 位于 verbs 层；GPI 使用该层，而不是绑定到 doca-rdma 队列。
• doca-rdmi/SKILL.md — 配套的 DPA 侧 发起接口。GPI 和 RDMI 都旨在实现“从加速器发起 RDMA 操作，且数据路径不经过主机 CPU”；GPI 面向 GPU，RDMI 面向 DPA。
• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的 路由表，以及已安装 DOCA 软件包在磁盘上的布局。
• doca-setup/SKILL.md — 环境准备、 安装验证，以及通过公开 NGC DOCA 容器处理尚未安装的情况。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的修改随附示例以构建首个应用的工作流、通用的 Core 上下文生命周期，以及跨库的 DOCA_ERROR_* 分类。本技能在此基础上叠加 GPI 专属内容。
• doca-debug/SKILL.md — 涵盖各方面的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。GPI 专属调试内容在此基础上叠加。
• doca-hardware-safety/SKILL.md — 适用于整个技能包的硬件安全元策略。能力配套文档中的 ## Safety policy 叠加说明会交叉引用该技能。
• doca-version/SKILL.md — 每个工件中的 ## Version compatibility 锚点所依据的版本检测 / 四方匹配规则。本技能仅摘录 GPI 专属叠加说明（DOCA 侧 .pc 加上 CUDA Toolkit 维度）。
• doca-structured-tools-contract/SKILL.md — Agent 优先使用的结构化辅助工具的 JSON schema 契约；任务配套文档中的 ## Command appendix 会在回退到手动链式操作之前先参考这些契约。