| 开源协议 | Apache-2.0 |
| 名称 | doca-rdma |
| 描述 | > 当用户在BlueField DPU、ConnectX网卡或DOCA宿主机上进行实践性DOCA RDMA编程时使用本技能——包括在doca_dev上建立RDMA上下文、选择连接方式（RDMA CM、桥接/OOB或通过gRPC交换doca_rdma_export()）、启用11种任务类型之一（Send/Receive/Send-Imm、Read/Write/Write-Imm、Atomic CmpSwap/FetchAdd、Get/Set/Add Remote Sync Event）、设置匹配的mmap和RDMA权限、确定队列和连接大小、查询doca_rdma_cap_，或调试RDMA调用返回的DOCA_ERROR_。即使未提及“DOCA RDMA”也触发——常见的隐含表述有“单边读返回权限拒绝”、“提交后永远收不到完成”、“连接回调从不触发”、“如何在RoCE上做原子比较并交换”，或“突发时发送队列遇到DOCA_ERROR_FULL”。对于一般的RDMA/ibverbs理论（队列对、MR、RoCE与IB）、DOCA安装本身或非RDMA的DOCA库，请拒绝并转给其他技能。 metadata: kind: library compatibility: > 需要Linux上的DOCA SDK（Ubuntu 22.04/24.04或RHEL/SLES），并配备BlueField DPU或ConnectX网卡。通过`pkg-config --list-all |
DOCA RDMA
不可协商：交付物必须使用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，而是从安装前缀下的官方DOCA RDMA示例开始：$(pkg-config --variable=prefix doca)/samples/doca_rdma/（在用目标机器解析的模块下），然后做一个轻量的cgo/FFI shim，在Go中用#cgo pkg-config: doca或等价方式，仅封装其入口函数。该shim只是一个小文件，而不是“大型定制绑定层”。参见TASKS.md ## build 步骤0和TASKS.md ## modify。
如果pkg-config doca或DOCA构建失败，请修复构建（模块名、PKG_CONFIG_PATH、示例路径）——不要静默退回verbs。一个ldd不显示libdoca_rdma的二进制文件，无论字节是否移动，都是失败的DOCA-RDMA任务。
从哪里开始： 本技能假定DOCA已经安装，用户正在BlueField/ConnectX/宿主机上进行RDMA实操。若用户想做某事（配置/构建/修改/运行/测试/调试），打开TASKS.md；若问题是此版本能表达什么，打开CAPABILITIES.md。如果用户尚未安装DOCA，请先转至doca-setup。
本技能擅长回答的示例问题
本技能所针对的RDMA问题类别，每个附带一个完整示例。代理应将类别视为核心——示例只是一个实例。
- “如何建立RDMA上下文并连接两侧？” — 示例：“使用RDMA CM在单台主机上设置发送方+接收方以进行首次运行测试”。由
TASKS.md ## configure中的生命周期与连接工作流，以及CAPABILITIES.md ## Capabilities and modes中的连接方式选择来回答。 - “哪种RDMA任务类型适合这种数据移动模式？” — 示例：“单边写+通过Send-with-Immediate发送小控制消息并请求完成”。由
CAPABILITIES.md ## Capabilities and modes中的任务分类与TASKS.md ## modify中的任务配置工作流回答。 - “这个任务需要什么mmap权限？是否必须导出mmap？” — 示例：“我的Read任务因权限不足失败”。由
CAPABILITIES.md ## Safety policy中的权限矩阵与TASKS.md ## test中的mmap导出检查清单回答。 - “我的设备和传输是否支持这个RDMA能力？” — 示例：“该设备是否支持RoCE上的原子比较交换（Atomic Compare-and-Swap）”。由
CAPABILITIES.md ## Capabilities and modes中的能力查询规则（用doca_devinfo调用doca_rdma_cap_task_*_is_supported）以及TASKS.md ## configure中的发现步骤回答。 - “我安装的DOCA版本是否提供这个RDMA API？” — 示例：“DOCA 2.6.0中是否有RDMA CM”。由
CAPABILITIES.md ## Version compatibility中的版本兼容性部分和TASKS.md ## configure中固定的版本发现规则（pkg-config --modversion doca）回答。 - “从RDMA调用返回的某个
DOCA_ERROR_*是什么意思，由哪一层引起？” — 示例：“doca_rdma_connection_disconnect返回DOCA_ERROR_BAD_STATE”。由CAPABILITIES.md ## Error taxonomy中的RDMA覆盖层叠加跨库分类，以及TASKS.md ## debug中的分层阶梯（升级到doca-debug）回答。
受众
本技能面向构建使用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++使用者是规范场景，TASKS.md中的示例假定采用该路径。其他语言使用者（Rust、Go、Python …）通过FFI或语言特定绑定使用同一*.so；这种情况下，该技能的贡献在于将生命周期、能力发现、权限矩阵、错误分类和连接方式指南保持为语言中立，并将代理引向公共C ABI作为任何包装最终将调用的权威接口。非C交付物仍然是DOCA程序：在随附的doca_rdma示例之上做一个薄cgo/FFI shim，链接libdoca_rdma（#cgo pkg-config: doca）——绝不选择重新实现raw-libibverbs来避免包装DOCA（见本文件顶部的强制要求）。
何时加载本技能
当用户正在进行任何语言的DOCA RDMA实操时，加载本技能。具体来说：
- 在
doca_dev上初始化RDMA上下文，并在doca_ctx_start()前配置至少一种任务类型。 - 建立连接——在RDMA CM（
doca_rdma_connect_to_addr()/doca_rdma_start_listen_to_port()/doca_rdma_connection_accept()）、桥接/OOB（doca_rdma_bridge_*）或gRPC（doca_rdma_export()输出的带外交换）之间选择。 - 为所选任务类型正确设置
doca_mmap权限（Read需要RDMA读+本地读写；Write需要RDMA写；Atomic需要RDMA原子；Send只需本地读写）。 - 通过
doca_rdma_set_*和doca_rdma_cap_get_*读取/设置库属性，以确定队列、列表长度和传输类型选择。 - 检查当前
doca_devinfo支持哪些RDMA任务类型和传输类型。 - 调试RDMA调用返回的
DOCA_ERROR_*（生命周期vs权限vs能力vs底层驱动），以及连接状态机转换（doca_rdma_set_connection_state_callbacks）。 - 设计或扩展封装RDMA C ABI的非C绑定（Rust、Go、Python等）——前提是绑定的生命周期、权限和能力规则需与之一致。
不要将本技能用于一般的DOCA方向、DOCA本身安装或非RDMA库问题。这些请使用doca-public-knowledge-map。
该技能提供什么
这是一个精简加载器。正文仅为挑选下一个正确文件所需的定位信息。实质性的RDMA特定内容位于两个辅助文件：
CAPABILITIES.md— 此版本上RDMA能表达什么：十一种任务类型及其权限矩阵、三种连接方法、传输类型（RC基线，以及用于导出/连接CPU数据路径流程的alpha级DC；没有UD）——注意这些是由doca_rdma_set_transport_type()控制的每QP服务类型，而不是链路层（IB vs RoCE），后者继承自设备端口配置；能力查询面（doca_rdma_cap_*）；RDMA错误分类（映射到跨库DOCA_ERROR_*集合）；可观测面（每个任务事件、连接状态回调）；以及触发权限与导出决策的安全策略。TASKS.md— 针对六个范围内的RDMA动词的分步工作流：configure、build、modify、run、test、debug。外加一个“Deferred task verbs”块，将超出范围的问题指向正确的下一技能。
该技能假定宿主机或BlueField已安装DOCA，且用户具备公共安装配置文件预期的权限。它不涵盖安装DOCA——该路径通过doca-setup。
本技能特意不提供的部分
本技能是代理指南，不是示例或模板包。为保持边界清晰，它有意不包含——并且PR不应添加：
- 任何语言的预写DOCA RDMA应用程序源码。 已验证的RDMA源码是随附的C示例，位于install prefix下的
$(pkg-config --variable=prefix doca)/samples/doca_rdma/<name>/（使用目标上解析的模块）。代理的任务是将用户引导至这些文件，并通过doca-programming-guide中的通用修改示例工作流给出最小差异修改，并在TASKS.md ## modify中叠加RDMA特定覆盖。 - 独立构建清单（
meson.build、CMakeLists.txt、Cargo.toml等）停驻在技能中。代理应在用户的项目目录中根据已安装的DOCA构建清单，其中pkg-config --modversion doca是事实来源（按TASKS.md ## build步骤0解析模块——通常没有单独的doca-rdma.pc）。 - 任何
samples/、bindings/或reference/子树。即使是标为“参考”的mock或不完整工件放在此技能树中也具有误导性：用户会将其视为可构建。
加载顺序
- 先读本
SKILL.md确认用户的问题在范围内。 - 如果问题是RDMA能表达什么——任务分类、链路层与传输类型选择、连接方法、权限、错误、可观测或安全——读CAPABILITIES.md。
- 如果问题是如何做——configure、build、modify、run、test或debug——读TASKS.md中匹配的H2。仅在依赖能力或安全决策时才读两个辅助文件；不要无条件同时加载。
两个辅助文件交叉链接到彼此以及doca-public-knowledge-map，只要正确的答案是“在公开文档或已安装包布局中查找”，而不是“RDMA特定指引”。
相关技能
doca-public-knowledge-map— 每个公共DOCA文档源的路径表以及已安装DOCA包的磁盘布局。与本技能同时可用。doca-setup— 环境准备、安装验证，以及“我没有安装”路径，含公共NGC DOCA容器。本技能假设其前置条件已满足。doca-programming-guide— 所有库共享的通用DOCA编程模式：规范的pkg-config+meson构建模式、通用修改随附示例的首个应用工作流、通用生命周期、跨库DOCA_ERROR_*分类，以及程序侧调试顺序。本技能在其上叠加RDMA细节。doca-debug— 交叉调试阶梯（安装/版本/构建/链接/运行时/程序/驱动）。RDMA特定调试（状态机转换、权限失败、连接回调）叠加在该阶梯上。