doca-rdmi

DOCA RDMA Initiator

示例

• “DPA 内核需要向远程响应端发起 RDMA 写操作。” —— 这属于适用范围。继续使用 doca_rdmi_*；不要将其改写为 主机 CPU 的 doca-rdma。
• *“链接时找不到 doca_rdmi_ 上的函数。”**——审查 该符号在此 DOCA 版本中是否为 EXPERIMENTAL，再考虑是否需要 备用 API。

说明

请遵循下方的加载顺序。需要配置／ 构建／调试时，打开任务配套文档。需要了解 RDMI 与 RDMA 的区别以及 实验性符号规则时，打开功能配套文档。不要打开所有配套文件。

从这里开始： 此技能假设 DOCA 已安装，且用户正在主机或 BlueField 上进行实际 RDMI 工作，使用的 DOCA 软件包包含 doca-rdmi 库。用户想要执行某项操作 （安装／配置／构建／修改／运行／测试／调试／使用）时，打开任务配套文档； 问题涉及此版本的 RDMI 能实现什么时，打开功能配套文档——包括对象模型、 DPA 侧句柄类型、与 doca-rdma 的关系、EXPERIMENTAL 标记策略以及 安全性补充说明。

端到端的“带我了解 doca-rdmi”问题完全可以仅凭此技能解答。 直接转到

端到端（快速参考），

其中包含自包含的安装检查 → 设备／能力 发现 → 示例 → pkg-config 构建 → 运行 → 调试指南， 以及准确的命令。回答 RDMI 构建／运行／调试问题时， 无需打开 doca-setup 或 doca-programming-guide。如果 DOCA 前置条件缺失、 不完整或版本不匹配，则转到 doca-setup/SKILL.md。

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

此技能旨在解答的 RDMI 问题类别，每类均附带一个实际示例。Agent 应将 类别视为关键内容——实际示例只是其中一种情况。

• “这种情况应该使用 doca-rdmi 还是 doca-rdma？”—— 实际示例：“我有一个 DPA 内核，需要向远程响应端发起 1 MB RDMA 写操作；应该使用哪个库？”。答案来自

  功能和模式

  中的发起端侧与通用库选择规则表，以及在用例涉及双端或由主机 CPU 发起时， 转至 doca-rdma/SKILL.md 的说明。
• “如何在 DPA 数据通路上建立 RDMI 连接？”—— 实际示例：“创建 doca_rdmi_connection，附加 DPA completion context，并将 DPA 侧句柄交给我的内核”。 答案来自

  功能和模式

  中的连接对象生命周期 和 ## 配置 中的配置流程。
• “connection 和 poster 有什么关系——什么时候两者都需要？” —— 实际示例：“我的应用既接收工作请求，也发起 RDMA 写操作；我需要 doca_rdmi_connection 和 doca_rdmi_poster 两者，还是只要其中一个？”。 答案来自

  功能和模式

  中的双对象模型 和 ## 修改 中基于示例的修改项表。
• “如何在 DPA 侧处理 completions？”——实际 示例：“将连接关联到 doca_dpa_completion，让我的内核直接轮询 completions”。答案来自

  功能和模式

  中的 DPA 侧 completion 附加模式 和 ## 运行 中的运行侧连接方式，并链接到 doca-dpa/SKILL.md，了解 DPA 编程 接口本身。
• “我想要的符号是否可用——其稳定性是否足以用于正式发布？”—— 实际示例：“doca_rdmi_poster_post 在我安装的 DOCA 版本中是 GA， 还是仍为 EXPERIMENTAL？”。答案来自

  版本兼容性

  中的 EXPERIMENTAL 标记策略 和 ## 配置 中的版本发现规则 （pkg-config --modversion doca-rdmi）。
• “doca_rdmi_* 调用返回的这个 DOCA_ERROR_* 是什么意思？”—— 实际示例：“doca_rdmi_connection_dpa_completion_attach 返回 DOCA_ERROR_BAD_STATE”。答案来自

  错误分类

  中对跨库错误分类的 RDMI 补充说明 和 ## 调试 中分层递进的排查步骤， 最终可升级至 doca-debug/SKILL.md。

适用对象

此技能面向构建驻留于 DPA 的 DOCA 应用、且需要向远程响应端发起单边 RDMA 操作的外部开发者——也就是说，用户的加速器端代码需要直接从加速器发起发送、写入或读取操作，而无需经由主机 CPU 往返。典型调用方是使用 doca-dpacc-compiler 编译、并运行在 BlueField DPA 数据通路上的 DPA 内核；驱动 DPU 的 RDMA 队列的 GPU 端调用方则属于相关场景，应转至 doca-gpi/SKILL.md。此技能不适用于参与开发 DOCA RDMI 本身的 NVIDIA 开发者，也不适用于一般的主机 CPU 双边 RDMA——这类内容应参阅 doca-rdma/SKILL.md。

语言范围

DOCA RDMI 以 C 库的形式提供，其 pkg-config 模块名称为 doca-rdmi。该库的主机端接口（doca_rdmi_connection_*、doca_rdmi_poster_*）使用 C；加速器内核使用的 DPA 端接口同样使用 C，并通过 doca-dpa/SKILL.md 中说明的 DOCA DPA 工具链编译。使用其他语言的开发者（Rust、Go、Python 等）通过 FFI 调用主机端 *.so；在这种情况下，此技能的作用是确保连接器／发送器的生命周期、EXPERIMENTAL 标签策略、DPA 端交接规则和安全覆盖层使用语言无关的表述，并引导 Agent 以公开的 C ABI 作为权威接口，因为任何包装层最终都会调用该接口。DPA 端接口无法用其他语言封装——它会直接编译并链接到 DPA 二进制文件中。

何时加载此技能

用户在已安装 DOCA 的主机或 BlueField 上实际开展 DOCA RDMI 工作时，加载此技能。具体包括：

• 为运行于 DPA 数据通路的新单边 RDMA 工作负载，在 doca-rdmi 和 doca-rdma 之间进行选择。
• 创建 doca_rdmi_connection 或 doca_rdmi_poster，附加 doca_dpa_completion 或 doca_verbs_cq，并在 DPA 数据通路上启动上下文。
• 将 doca_rdmi_connection_get_dpa_handle／doca_rdmi_poster_get_dpa_handle 返回的 DPA 端句柄接入 DPA 内核，该内核会调用相应的设备端头文件（doca_rdmi_dev_connection.h、doca_rdmi_dev_poster.h、doca_rdmi_dev_cqe.h）。
• DPA 内核处理接收完成项后，在主机端通过 doca_rdmi_connection_recv_ack 确认这些完成项。
• 在将使用 RDMI 的组件声明为适用于生产环境之前，审核已安装的 DOCA 版本中哪些 RDMI 符号标记为 EXPERIMENTAL。
• 调试 doca_rdmi_* 调用返回的 DOCA_ERROR_*，并判断原因是配置错误、生命周期顺序问题、此设备不支持相关功能，还是 DOCA 以下层级的问题。

一般的 DOCA 概览、安装 DOCA 本身或双边主机 CPU RDMA 问题，请勿加载此技能。对于这些问题，请分别使用 doca-public-knowledge-map/SKILL.md、doca-setup/SKILL.md 和 doca-rdma/SKILL.md。

此技能提供的内容

这是一个轻量级加载器。正文仅保留了用于选择合适后续文件所需的指引。实质性的 RDMI 专属内容位于两个配套文件中：

• capabilities 配套文件 — 说明此版本的 RDMI 能表达什么：doca_rdmi_connection 和 doca_rdmi_poster 对象模型、DPA 侧的 completion-attach 模式、与 doca-verbs 的关系（RDMI 基于 doca_verbs_context 构建）以及与 doca-dpa 的关系（加速器侧数据通路）、版本处理的 EXPERIMENTAL 标签规则、跨库 DOCA_ERROR_* 分类体系中 RDMI 的扩展、可观测性接口（PE 上的完成事件 / DPA 侧完成），以及对从加速器内核向远程响应端内存提交操作的安全策略。
• tasks 配套文件 — 针对八个适用动词的分步工作流：install、configure、build、modify、run、test、debug、use。此外还有 ## rollback 扩展（针对 verbs / connection / DPA-attach / MR 堆栈的 RDMI 专属五步拆除流程），以及附加到 ## debug 的通用五阶段调试循环实例。另有一个 Deferred task verbs 区块，将范围外的问题指向合适的后续技能。

此技能假定主机或 BlueField 上已在标准位置安装 DOCA，且用户拥有其公开安装配置预期的权限。此技能不涵盖 DOCA 本身的安装 — 该流程请参阅 doca-setup/SKILL.md。

此技能有意不包含的内容

此技能提供的是Agent 指引，而非示例或模板包。为明确边界，此技能有意不包含以下内容 — Pull Request 也不应添加：

• 任何语言的预编写 DOCA RDMI 应用程序源代码。 Agent 的职责是引导用户使用其已安装 DOCA 中经过验证的参考代码，并通过 doca-programming-guide/SKILL.md 中的通用修改示例工作流，辅以 ## modify 中的 RDMI 专属覆盖项，规定最小差异修改。由于撰写本文时所有 RDMI 符号都带有 EXPERIMENTAL 标记，此技能不会根据文档描述编写 RDMI 源代码 — API 可能在不同发行版之间发生变化，生成的代码甚至可能无法编译。
• 独立的构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）。Agent 会在用户的项目目录中，基于用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-rdmi 是事实依据。
• DPA 侧内核模板。 DPA 侧接口归 doca-dpa/SKILL.md 所有；RDMI 的 DPA 侧头文件由其中记录的 DPA 编程模型使用。此技能会说明 RDMI 专属的交接内容（DPA 句柄类型、completion-attach 调用），但不会编写 DPA 内核。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 此技能目录树中的模拟或不完整产物，即使标注为“reference”，也会造成误导：用户会以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其范围。
2. RDMI 对象模型、DPA 侧交接模式、EXPERIMENTAL 标签策略、错误分类体系、可观测性和安全策略，请参阅 capabilities 配套文件。
3. 分步工作流 — install、configure、build、modify、run、test、debug、use — 请参阅 tasks 配套文件。

当正确答案是“查阅公开文档或已安装的软件包布局”，而非“RDMI 专属指引”时，两个配套文件都会相互交叉链接，并链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-rdma/SKILL.md — 更高层级的 RDMA 库，涵盖双边通信和由主机 CPU 发起的 RDMA。RDMI 是专注于发起端的接口；对于大多数 RDMA 用例， doca-rdma 才是合适的选择。## Capabilities and modes 中的选择表是关键的决策辅助工具。
• doca-dpa/SKILL.md — DOCA DPA 编程 接口。RDMI 返回 DPA 端句柄 （doca_dpa_dev_rdmi_connection_t、doca_rdmi_dev_poster_t）， DPA 内核通过设备端头文件 （doca_rdmi_dev_connection.h、doca_rdmi_dev_poster.h、 doca_rdmi_dev_cqe.h）使用这些句柄；DPA 工具链、内核构建 和执行模型由该技能负责。
• doca-gpi/SKILL.md — 本技能在 GPU 端的 对应技能。GPI 是 CUDA 内核用于发起 RDMA 的通道／队列接口； RDMI 则是 DPA 端接口。两者都基于相同的 DOCA RDMA／verbs 底层机制；具体使用哪一个，取决于发起端位于 DPA 还是 GPU 上。
• 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_* 分类体系。本技能在此基础上补充 RDMI 特有内容。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装／版本／构建／链接／运行时／ 程序／驱动）。RDMI 特有的调试内容在此基础上补充。
• doca-hardware-safety/SKILL.md — 适用于整个套件的硬件安全元策略。能力说明配套文档中的 ## Safety policy 补充部分会交叉引用该技能。
• doca-version/SKILL.md — 版本 检测／四方匹配规则，每个组件的 ## Version compatibility 锚点都会以此为基础。本技能仅引用 RDMI 特有的补充内容。
• doca-structured-tools-contract/SKILL.md — Agent 优先使用的结构化辅助工具（环境探测、能力快照、版本矩阵 查询）的 JSON schema 合约；任务配套文档中的 ## Command appendix 会优先 使用这些辅助工具，之后再回退到手动流程。