Name: doca-rdmiSkill
Rating: 5 (1 reviews)
Author: doca-rdmi


开源协议	Apache-2.0
名称	doca-rdmi
描述	> 当用户在进行DOCA RDMI（RDMA发起者）的实际编程时使用本技能——包括为加速器发起的一侧RDMA流程选择doca-rdmi还是doca-rdma，建立doca_rdmi_connection或doca_rdmi_poster，在doca_ctx_start()之前附加doca_dpa_completion或doca_verbs_cq，获取DPA侧句柄以用于DPA内核，审查当前DOCA上某个doca_rdmi_符号是否为EXPERIMENTAL（实验性），或调试RDMI调用返回的DOCA_ERROR_错误。即使用户没有提到“DOCA RDMI”或“发起者”，也应触发本技能——隐含的表述包括“我的DPA内核需要向远程响应者发RDMA写操作”、 “DPA内核看不到完成通知”、“链接时找不到doca_rdmi_*函数”、“从完成附加操作返回DOCA_ERROR_BAD_STATE”，或“DPA已发布但工作请求从未到达”。对于双侧或主机CPU发起的RDMA、DPA编程模型、GPU侧RDMA发起或通用RDMA/IB/RoCE概念，应拒绝并转至其他技能。 metadata: kind: library compatibility: > 需要Linux上已安装DOCA SDK（位于/opt/mellanox/doca，Ubuntu 22.04/24.04或RHEL/SLES），并连接BlueField DPU或ConnectX网卡。当数据通路运行在DPA上时，还需要DOCA DPA工具链和支持DPA的BlueField。通过`pkg-config doca-rdmi`（以及doca-common、doca-verbs、doca-dpa）读取用户的本地安装，并检查/opt/mellanox/doca/{lib,include,samples}。

DOCA RDMA 发起者

开始向导： 本技能假设DOCA已经安装完毕，用户正在安装了 doca-rdmi 库的 DOCA 包集的主机上或 BlueField 上进行 实际的 RDMI 工作。如果用户想要执行某项操作（安装 / 配置 / 构建 / 修改 / 运行 / 测试 / 调试 / 使用），请打开 TASKS.md；当问题是 此版本上的 RDMI 能表达什么（对象模型、DPA 侧句柄类型、与 doca-rdma 的关系、EXPERIMENTAL 标记策略、安全覆盖）时，请打开 CAPABILITIES.md。

端到端的“带我完整走一遍 doca-rdmi”类问题可完全由本技能回答。 直接转到 TASKS.md ## end-to-end (quickref)，它提供自包含的安装检查 → 设备/能力发现 → 示例 → pkg-config 构建 → 运行 → 调试的完整演练及精确命令。回答 RDMI 构建/运行/调试问题不需要打开 doca-setup 或 doca-programming-guide。当所需的 DOCA 先决条件缺失、不完整或版本不匹配时，请转向 doca-setup。

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

本技能旨在回答的 RDMI 问题类别，每一类都带一个示例。代理应将类别视为关键部分——示例只是一个独立实例。

“这种情况我该用 doca-rdmi 还是 doca-rdma？” — 示例：“我有一个 DPA 内核需要向远程响应者发送 1 MB RDMA 写；用哪个库？”。由 CAPABILITIES.md ## Capabilities and modes 中的 发起侧 vs 通用 选择表和表面选择表回答；当用例是双侧或主机 CPU 发起时，会路由回 doca-rdma。
“如何在 DPA 数据通路上建立起 RDMI 连接？” — 示例：“创建一个 doca_rdmi_connection，附加一个 DPA 完成上下文，把 DPA 侧句柄交给我的内核”。由 CAPABILITIES.md ## Capabilities and modes 中的连接对象生命周期 + TASKS.md ## configure 中的配置流程回答。
“连接和发布者如何关联——何时两者都需要？” — 示例：“我的应用既接收工作请求又发布 RDMA 写；我需要 doca_rdmi_connection 加 doca_rdmi_poster，还是只用一个？”。由 CAPABILITIES.md ## Capabilities and modes 中的双对象模型 + TASKS.md ## modify 中的从示例修改的槽位表回答。
“如何在 DPA 侧驱动完成通知？” — 示例：“将连接挂接到 doca_dpa_completion，使我的内核直接轮询完成”。由 CAPABILITIES.md ## Capabilities and modes 中的 DPA 侧完成附加模式 + TASKS.md ## run 中的运行侧布线回答，并交叉关联 doca-dpa 了解 DPA 编程表面本身。
“我要用的符号是否可用——并且足够稳定可以发布？” — 示例：“doca_rdmi_poster_post 在我安装的 DOCA 上是 GA 还是仍然是 EXPERIMENTAL？”。由 CAPABILITIES.md ## Version compatibility 中的 EXPERIMENTAL 标记策略 + TASKS.md ## configure 中固定的版本发现规则（pkg-config --modversion doca-rdmi）回答。
“doca_rdmi_* 调用返回的 DOCA_ERROR_* 是什么意思？” — 示例：“从 doca_rdmi_connection_dpa_completion_attach 返回 DOCA_ERROR_BAD_STATE”。由 CAPABILITIES.md ## Error taxonomy 中的跨库分类法上的 RDMI 覆盖层 + TASKS.md ## debug 的分层阶梯回答，该阶梯可升级到 doca-debug。

受众

本技能面向 需要在 DPA 上构建 DOCA 应用、并能向远程响应者发起一侧 RDMA 操作的外部开发者 —— 即其加速器侧代码希望直接从加速器发布发送、写入或读取，而无需通过主机 CPU 往返的开发者。典型调用者是用 doca-dpacc-compiler 编译并在 BlueField DPA 数据通路上运行的 DPA 内核；驱动 DPU RDMA 队列的 GPU 侧调用者是姊妹场景，路由到 doca-gpi。本技能不适用于为 DOCA RDMI 本身做贡献的 NVIDIA 开发者，也不适用于通用主机 CPU 双侧 RDMA——后者属于 doca-rdma。

语言范围

DOCA RDMI 作为C库发布，pkg-config 模块名为 doca-rdmi。该库的 主机侧 接口（doca_rdmi_connection_*、doca_rdmi_poster_*）是 C；加速器内核使用的 DPA 侧 接口也是 C，需针对 doca-dpa 中记载的 DOCA DPA 工具链编译。其他语言的使用者（Rust、Go、Python 等）通过 FFI 使用主机侧 *.so；在这种情况下，本技能的贡献是保持连接/发布者生命周期、EXPERIMENTAL 标记策略、DPA 侧移交规则和安全覆盖的语言无关性，并将代理引导到公共 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 侧句柄接入调用匹配设备侧头文件（doca_rdmi_dev_connection.h、doca_rdmi_dev_poster.h、doca_rdmi_dev_cqe.h）的 DPA 内核。
在 DPA 内核消费完成之后，通过 doca_rdmi_connection_recv_ack 在主机侧确认接收完成。
在声明使用 RDMI 的组件可稳定投入生产之前，审查已安装 DOCA 版本上哪些 RDMI 符号是 EXPERIMENTAL。
调试 doca_rdmi_* 调用返回的 DOCA_ERROR_*，并判断原因是配置错误、生命周期顺序问题、该设备不支持该能力，还是 DOCA 之下的层。

不要将本技能用于通用 DOCA 方向、DOCA 本身的安装或双侧主机 CPU RDMA 问题。对于这些，请分别使用 doca-public-knowledge-map、doca-setup 和 doca-rdma。

本技能提供什么

这是一个 轻量装载器。正文只保留选择下一个正确文件所需的导向信息。RDMI 特异性实质内容位于两个伴生文件中：

CAPABILITIES.md —— 此版本上 RDMI 能表达什么：doca_rdmi_connection 和 doca_rdmi_poster 对象模型、DPA 侧完成附加模式、与 doca-verbs（RDMI 构建在 doca_verbs_context 上）及 doca-dpa（加速器侧数据通路）的关系、版本处理的 EXPERIMENTAL 标记规则、跨库 DOCA_ERROR_* 分类法上的 RDMI 覆盖层、可观测性表面（PE 上的完成事件 / DPA 侧完成），以及安全策略（限制从加速器内核向远程响应者内存发布工作）。
TASKS.md —— 八个范围内动词的分步工作流：install、configure、build、modify、run、test、debug、use。另有一个 ## rollback 覆盖（RDMI 特有的五步拆除：verbs / connection / DPA-attach / MR 栈）以及附加到 ## debug 的 5 阶段通用调试循环实例。还有一个 Deferred task verbs 块，将范围外的问题指向正确的下一个技能。

本技能假设主机或 BlueField 上已在标准位置安装 DOCA，并且用户拥有其公共安装配置所预期的权限。它不涵盖安装 DOCA 本身——该路径通过 doca-setup。

本技能刻意不携带的内容

本技能是 代理指南，而不是示例或模板包。为保持边界清晰，它刻意不包含——也不应通过 PR 添加：

任何语言的预写 DOCA RDMI 应用程序源代码。 代理的职责是引导用户使用其已安装 DOCA 上经过验证的参考代码，并通过 doca-programming-guide 中的通用“修改示例”工作流，结合 TASKS.md ## modify 中的 RDMI 特定覆盖层，来规定最小差异修改。由于在撰写本文时每个 RDMI 符号均为 EXPERIMENTAL，本技能拒绝仅凭文档描述编造 RDMI 源代码——API 可能随版本变化，结果代码甚至可能无法编译。
独立构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）存放在技能内。代理 在用户的项目目录中 依据用户已安装的 DOCA 构造构建清单，其中 pkg-config --modversion doca-rdmi 是权威来源。
DPA 侧内核模板。 DPA 侧表面归 doca-dpa 所有；RDMI 的 DPA 侧头文件被该处记载的 DPA 编程模型消费。本技能只命名 RDMI 特有的移交（DPA 句柄类型、完成附加调用），但不编写 DPA 内核。
任何 samples/、bindings/ 或 reference/ 子树。 技能树中的模拟或不完整工件，即使标记为“reference”，也会误导人：用户会将其视为可构建。

加载顺序

首先阅读本 SKILL.md，确认用户的问题在范围内。
关于 RDMI 对象模型、DPA 侧移交模式、EXPERIMENTAL 标记策略、错误分类法、可观测性和安全策略，请参阅 CAPABILITIES.md。
关于分步工作流——安装、配置、构建、修改、运行、测试、调试、使用——请参阅 TASKS.md。

两个伴生文件彼此交叉链接，并在正确答案是“在公共文档或已安装包布局中查找”而非“RDMI 特定指导”时，与 doca-public-knowledge-map 交叉链接。

doca-rdmiSkill doca-rdmi