doca-rdma

DOCA RDMA

示例

• “提交后始终收不到完成事件。” — 继续检查 DOCA RDMA 任务和进度引擎路径。不要将其改写为原始 verbs。
• “单边读取返回权限被拒绝。” — 在更改任务类型之前，检查 mmap + RDMA 权限以及 doca_rdma_cap_*。

说明

请遵循下文的加载顺序。打开任务配套文件，了解配置 / 构建 / 运行。打开能力配套文件，了解任务分类和安全策略。不要打开所有配套文件。

不可妥协：交付内容必须使用 DOCA RDMA，而非原始 verbs

当此技能适用时，用户请求的是 DOCA RDMA。你生成的 程序必须链接 libdoca_rdma 并调用 doca_rdma_* API（直接使用 C/C++，或通过其他语言中的轻量 FFI/cgo 封装）。 不要使用原始 libibverbs / librdmacm / RDMA-CM 实现请求后就宣称完成。这些方式虽然能传输字节，却完全绕过 DOCA——这违背了使用此库的初衷，会丢失 DOCA 编程模型（进度引擎、任务/ 事件生命周期、能力发现，以及跨 BlueField/ ConnectX 代际的可移植性），也是最常见的失败模式。

“原始 verbs 代码更少” / “这样可以避免构建 DOCA 绑定层” 不是绕过 DOCA 的可接受理由。对于非 C 语言（Go、Rust、Python 等），正确且低门槛的做法不是重新绑定整个 API——而是从 $(pkg-config --variable=prefix doca)/samples/doca_rdma/ 下随附的 DOCA RDMA 示例开始（将模块替换为目标上解析出的模块），并使用 #cgo pkg-config: doca（Go）或等效方式构建一个轻量 cgo/FFI 封装，来包装其入口函数。该封装只有一个小文件，并非“庞大的自定义绑定层”。请参阅 ## build 第 0 步和

修改。

如果 pkg-config doca 或 DOCA 构建失败，修复构建（模块名、PKG_CONFIG_PATH、示例路径），不要悄悄回退到 verbs。无论是否传输了字节，只要二进制文件的 ldd 输出中没有 libdoca_rdma，就说明 DOCA-RDMA 任务失败。

具体路径（已在 DOCA 3.3、一个 RoCE 端口、两个进程的情况下验证）：

0. **先记录已安装的版本：**运行 pkg-config --modversion doca-rdma 并展示结果。
1. **在原位置构建随附的程序对，输出放在外部。**示例的 meson.build 会读取 ../../../VERSION，因此复制后的示例目录树 无法配置。请从已安装目录构建到自己的构建目录，这不会在 /opt 下写入任何内容： cd /opt/mellanox/doca/samples/doca_rdma/rdma_receive && meson setup <work>/rr && ninja -C <work>/rr （rdma_send 也一样，构建到 <work>/rs）；二进制文件为 doca_rdma_receive、doca_rdma_send。使用 --help 确认标志。
2. **在一条命令中运行两端。**两端都会写入自己的连接 描述符（-ld），然后等待按下 Enter 后再读取对端的描述符 （-re）；接收端必须先收到 Enter： ( sleep 6; echo ) | <work>/rr/doca_rdma_receive -d <dev> -g <gid> -ld <work>/recv.desc -re <work>/send.desc & 然后运行 sleep 2; ( sleep 6; echo ) | <work>/rs/doca_rdma_send -d <dev> -g <gid> -ld <work>/send.desc -re <work>/recv.desc; wait。 成功标志：接收端日志显示 Got from sender: "..."，并且两端都打印 Sample finished successfully。Failed to open the file ... for reading 表示某一端在对端写入前就读取了：请修正顺序， 而不是修改代码。
3. **只有原版运行成功后才扩展。**如需额外输出（校验和或证明行）， 请复制整个示例目录树，并将 /opt/mellanox/doca/VERSION 保留在示例目录上方三级的位置，只修改 负载和接收端的打印内容，并保持相同的运行顺序以及用户要求的任何 程序名称或输出格式。绝不要从头编写新的 RDMA 程序， 不要修改已安装的示例，也不要回退到原始 verbs、 rdma_cm 代码、ib_write_bw、rping 或环回。

**设备和 GID。**使用活动端口的设备，以及已填充的 RoCE v2 GID（/sys/class/infiniband/<dev>/ports/<port>/gids/<i>，并检查 gid_attrs/types/<i>）。如果原版程序对在顺序正确的情况下仍然失败， 请停止并报告设备、GID 表和错误。

从哪里开始：此技能假定 DOCA 已安装，且用户正在 BlueField / ConnectX / 装有 DOCA 的主机上亲自进行 RDMA 操作。如果用户想要执行 某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文档； 如果问题是关于此版本的 RDMA 可以实现哪些功能，请打开功能配套文档。 如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。

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

此技能旨在回答以下几类 RDMA 问题，每类各有一个完整示例。Agent 应将问题类别视为核心内容，而完整示例只是其中一个具体实例。

• “如何建立 RDMA 上下文并连接两端？” — 完整示例：“在单台主机上使用 RDMA CM 设置发送端和接收端，以进行首次运行测试”。由 ## configure 中的生命周期和连接工作流

  • Capabilities and modes 中的连接方式选择提供解答。

• “哪种 RDMA 任务类型适合这种数据传输模式？” — 完整示例：“单边写入 + 通过带 Immediate 的 Send 完成小型控制消息的传输”。由 ## Capabilities and modes 中的任务分类

  • modify 中的任务配置工作流提供解答。

• “此任务需要哪些 mmap 权限？我必须导出 mmap 吗？” — 完整示例：“我的 Read 任务因权限不足而失败”。由 ## Safety policy 中的权限矩阵

  • test 中的 mmap 导出检查清单提供解答。

• “我的设备和传输方式是否支持此 RDMA 能力？” — 完整示例：“此设备是否支持通过 RoCE 执行 Atomic Compare-and-Swap”。由 ## Capabilities and modes 中的能力查询规则 （针对 doca_devinfo 调用 doca_rdma_cap_task_*_is_supported）

  • configure 中的发现步骤提供解答。

• “我安装的 DOCA 版本是否提供此 RDMA API？” — 完整示例：“DOCA 2.6.0 中是否有 RDMA CM”。由 ## Version compatibility 中的版本兼容性章节

  • configure 中固定的版本发现规则（pkg-config --modversion doca）提供解答。

• “RDMA 调用返回的 DOCA_ERROR_* 表示什么？是由哪一层导致的？” — 完整示例：“doca_rdma_connection_disconnect 返回 DOCA_ERROR_BAD_STATE”。由 ## Error taxonomy 中对跨库错误分类的 RDMA 补充说明

  • debug 中逐层排查流程提供解答，必要时升级至

  doca-debug/SKILL.md。

适用对象

此技能面向构建使用 DOCA RDMA 库的应用程序的外部开发者——也就是说，用户的代码会调用 doca_rdma_*（直接使用 C/C++，或通过其他语言的 FFI／绑定），在两端之间执行 RDMA 数据传输（主机↔主机、主机↔BlueField、DPU↔DPU，或 BlueField 上的 SF↔SF）。此技能不面向为 DOCA RDMA 本身做贡献的 NVIDIA 开发者。

语言范围。 DOCA RDMA 通常作为 C 库包含在统一的 doca pkg-config 模块中（公共头文件 doca_rdma.h，共享对象 libdoca_rdma.so）；拆分安装可能会提供单独的库模块。请始终在目标环境中发现模块（pkg-config --list-all | grep -i doca），不要假设安装布局。随附示例使用 C 编写（这是 NVIDIA 的选择）。C 和 C++ 用户是典型场景，任务配套示例也以此为基础。其他语言的用户（Rust、Go、Python 等）通过 FFI 或特定语言的绑定使用相同的 *.so；此技能在这种情况下的作用，是确保生命周期、能力发现、权限矩阵、错误分类和连接方式方面的指导与语言无关，并引导 Agent 将公共 C ABI 作为权威接口，因为任何封装最终都会调用它。非 C 交付物仍然是 DOCA 程序：在随附的 doca_rdma 示例之上构建轻量级 cgo／FFI shim，并链接 libdoca_rdma（#cgo pkg-config: doca）——绝不能为了避免封装 DOCA 而选择用 raw-libibverbs 重新实现（参见本文件顶部的要求）。

何时加载此 skill

当用户正在使用任意语言进行 DOCA RDMA 实操时，加载此 skill。具体包括：

• 在 doca_dev 上初始化 RDMA 上下文。Core 顺序为：创建 → 配置（任务 set_conf + mmap/RDMA 权限 + 可选的 set_*）→ 启动 → 连接 → 使用 → 停止 → 销毁。 必须在调用 doca_ctx_start() 之前完成配置。
• 建立连接——选择 RDMA CM（doca_rdma_connect_to_addr() / doca_rdma_start_listen_to_port() / doca_rdma_connection_accept()）、bridge / OOB（doca_rdma_bridge_*）或 gRPC（通过带外方式交换 doca_rdma_export() 输出）。
• 根据所选任务类型正确设置 doca_mmap 的权限（Read 需要 RDMA-read + 本地读写权限；Write 需要 RDMA-write；Atomic 需要 RDMA-atomic；Send 仅需要本地读写权限）。
• 通过 doca_rdma_set_* 和 doca_rdma_cap_get_* 读取 / 设置库属性，以确定队列大小、列表长度和传输类型选择。
• 检查活动 doca_devinfo 支持哪些 RDMA 任务类型和传输类型。
• 调试 RDMA 调用返回的 DOCA_ERROR_*（生命周期、权限、能力或底层驱动问题），以及连接状态机的状态转换（doca_rdma_set_connection_state_callbacks）。
• 设计或扩展封装 RDMA C ABI 的非 C 绑定（Rust、Go、Python 等）——确保封装遵守生命周期、权限和能力规则。

不要在一般 DOCA 概览、安装 DOCA 本身或非 RDMA 库相关问题中加载此 skill。此类问题请使用 doca-public-knowledge-map/SKILL.md。

此 skill 提供的内容

这是一个轻量加载器。正文只保留了用于选择下一个文件所需的概览信息。实质性的 RDMA 专属资料位于两个配套文件中：

• 能力配套文件——介绍此版本的 RDMA 能实现什么：十一种任务类型及其权限矩阵、三种连接方式、传输类型（RC 基线，以及用于 export/connect CPU 数据路径流程的 alpha 级 DC；不支持 UD）——请注意，这些是由 doca_rdma_set_transport_type() 控制的每个 QP 服务类型，而非链路层（IB 与 RoCE），后者继承自设备端口配置；能力查询接口（doca_rdma_cap_*）、RDMA 错误分类（映射到跨库的 DOCA_ERROR_* 集）、可观测性接口（每任务事件、连接状态回调），以及对权限和导出决策进行约束的安全策略。
• 任务配套文件——针对六种适用的 RDMA 动词提供分步工作流：configure、build、modify、run、test、debug。此外，还有一个 Deferred task verbs 区块，将范围外的问题指向合适的下一个 skill。

此 skill 假设主机或 BlueField 已在标准位置安装 DOCA，且用户拥有其公开安装配置文件所要求的权限。此 skill 不涵盖 DOCA 安装——相关流程请参见 doca-setup/SKILL.md。

本技能刻意不提供的内容

本技能提供的是 Agent 指引，而不是示例或模板合集。 为明确界限，本技能刻意不包含以下内容，也不应在拉取请求中添加：

• 任何语言的预先编写 DOCA RDMA 应用程序源代码。 已验证的 RDMA 源代码是随包提供的 C 示例，位于安装前缀下的 $(pkg-config --variable=prefix doca)/samples/doca_rdma/<name>/ （使用在目标环境上解析出的模块）。Agent 的职责是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用修改示例工作流，对其进行最小差异修改；同时应用

  modify 中针对 RDMA 的专属覆盖说明。

• 停放在本技能中的独立构建清单（meson.build、CMakeLists.txt、 Cargo.toml 等）。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单，且以 pkg-config --modversion doca 为准（按 ## build Step 0 解析模块——优先使用可解析的 doca-rdma）。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。本技能目录树中的模拟或不完整内容，即使标注为“reference”，也会造成误导：用户会以为它可以构建。

加载顺序

1. 首先阅读本技能，以确认用户的问题属于适用范围。
2. 如果问题是RDMA 能实现什么——任务分类、链路层与传输类型的选择、连接方法、权限、错误、可观测性或安全性——请阅读能力配套文档。
3. 如果问题是如何实现——配置、构建、修改、运行、测试或调试——请阅读任务配套文档中对应的 H2。仅当工作流取决于能力或安全性决策时才同时阅读两份配套文档；不要无条件全部加载。

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

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源及已安装 DOCA 软件包磁盘布局的路由表。始终与本技能一并提供。
• doca-setup/SKILL.md — 环境准备、安装验证，以及使用公开 NGC DOCA 容器的我还没有安装路径。本技能假设已满足其前置条件。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的基于已提供示例修改的首个应用工作流、通用生命周期、跨库 DOCA_ERROR_* 分类，以及程序端调试顺序。本技能在此基础上补充 RDMA 专属内容。
• doca-debug/SKILL.md — 跨领域调试阶梯（安装／版本／构建／链接／运行时／程序／驱动程序）。RDMA 专属调试（状态机转换、权限失败、连接回调）叠加在该阶梯之上。