Name: DOCAUROM主机侧库操作Skill
Rating: 5 (1 reviews)
Author: doca-urom

DOCA UROM

如何开始： 本技能假定 DOCA 已同时安装在主机和 BlueField 上，DOCA UROM Service 已在 BlueField 侧部署并运行，且用户正在开展主机侧的 UROM 实际操作 —— 即通过主机上的 HPC / UCX / MPI 栈使用 doca-urom，将远程内存操作（put、get、原子操作、主动消息、集合原语）排队到 BlueField DPU，由其代表主机执行。若用户想做某事（配置/构建/修改/运行/测试/调试），请打开 TASKS.md；若问题是关于“当前版本 + 当前 BlueField + 当前 UROM Service 版本下，主机侧 UROM API 能表达什么”，请打开 CAPABILITIES.md。如果用户尚未安装 DOCA，请先转向 doca-setup；如果用户询问的是 DPU 侧的 UROM Service 本身（部署、容器、生命周期管理），那是另一个工件 —— 请通过 doca-public-knowledge-map ## DOCA services 转向公开的 DOCA UROM Service 指南。本技能关注的是主机侧库；UROM Service 是DPU 侧执行者，它们是一个配对契约。

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

本技能为以下 UROM 问题类别构建了答案，每个类别附带一个示例作为引导，实际承载信息的是“类别”，示例只是单个实例。

“如何将我的 MPI / UCX 远程内存操作从主机 CPU 卸载到 BlueField DPU？” —— 示例：“我的 MPI 全归约消耗了大量主机 CPU 周期，我希望能把这部分工作卸载到 BlueField。” 答案在 CAPABILITIES.md ## Capabilities and modes 的主机库 + DPU 服务配对契约模型，以及 TASKS.md ## configure 的主机侧启动流程中。
“DOCA UROM Service 是否真的在我的 BlueField 上运行，并且在我写任何 doca_urom_* 代码之前为什么这很重要？” —— 示例：“在 DOCA 其他部分正常的主机上，我的第一个 doca_urom_* 调用返回 DOCA_ERROR_NOT_PERMITTED”。答案在 CAPABILITIES.md ## Safety policy 的环境前置条件矩阵，以及 TASKS.md ## configure 第 1 步中检查 service 是否已部署并运行的部分；服务侧环境问题会转向 doca-public-knowledge-map ## DOCA services。
“这种 UROM 操作类型 / 原子操作 / 集合操作在我的设备 + 当前 DOCA 安装 + 当前 UROM Service 版本上受支持吗？” —— 示例：“我的 BlueField 是否支持 MPI 窗口的远程 Fetch-and-Add 原子操作？” 答案在插件发现规则：在已启动的 Service 上调用 doca_urom_service_get_plugins_list（UROM 操作由插件定义的 Command 任务决定，因此支持哪些插件就是能力面），详见 CAPABILITIES.md ## Capabilities and modes 和 TASKS.md ## configure。
“doca-urom 与 doca-rdma 有何关系——是替换、在其上层叠加，还是别的关系？” —— 示例：“我已经能使用原生 doca-rdma，是否应该改用 UROM，还是说那是错误的工具？” 答案在 CAPABILITIES.md ## Capabilities and modes 的路径选择规则中（UROM 在底层使用 RDMA 传输承载，但增加了 DPU 卸载契约；只有主机 CPU 因通信开销成为瓶颈时才值得选用；少量/简单的点到点场景应继续使用 doca-rdma）。
“我安装的 DOCA 版本上是否提供这个 UROM API？” —— 示例：“在 DOCA 3.x 上，能否通过 doca_urom_service_get_plugins_list 发现集合操作插件？” 答案在 CAPABILITIES.md ## Version compatibility 中，它交叉关联 doca-version 的标准检测链，并额外叠加 UROM 特有的“主机库与 DPU 服务版本必须匹配”的层级。
“doca_urom_* 调用返回的某个 DOCA_ERROR_* 是什么意思，由哪一层导致？” —— 示例：“doca_ctx_start() 成功后，第一次 doca_urom_* 入队返回 DOCA_ERROR_NOT_PERMITTED”。答案在 CAPABILITIES.md ## Error taxonomy 中针对跨库分类的 UROM 叠加，以及 TASKS.md ## debug 的分层排查步骤，最终可升级到 doca-debug。

受众

本技能面向从主机侧使用 DOCA UROM 库构建 HPC / UCX / MPI 应用的外部开发者 —— 即调用 doca_urom_* 的代码（直接用 C / C++，或通过其他语言的 FFI / 绑定，或通过已经将 DOCA UROM 以 UCX transport 方式接入的 OpenMPI / MPICH 等 UCX 栈），目的是把远程内存操作推给 BlueField DPU，而不是在主机 CPU 上执行。它不面向 NVIDIA 内部为 DOCA UROM 贡献代码的开发者，也不是学习如何在 DPU 侧部署 / 运维 DOCA UROM Service 的地方——后者应通过公开的 DOCA UROM Service 指南，经由 doca-public-knowledge-map ## DOCA services 访问。

语言范围。 DOCA UROM 以主机侧 C 库形式提供，pkg-config 模块名为 doca-urom。随附的示例位于 /opt/mellanox/doca/samples/doca_urom/，用 C 编写（NVIDIA 的选择）。C 和 C++ 用户——包括包装该库的 UCX 栈——是规范场景，TASKS.md 中的示例假定这一路径。其他语言用户（Rust、Go、Python 等）通过 FFI 或特定语言绑定使用同一个 *.so；本技能的贡献在于让生命周期、能力发现、服务部署检查、错误分类和 RDMA 传输指导保持语言中立，并引导到公开 C ABI 这一任何封装最终都会调用的权威接口。

何时加载本技能

当用户正在从主机侧开展实际的 DOCA UROM 操作（任何语言）时，加载本技能。具体包括：

在映射到目标 BlueField 的 doca_dev 上初始化 UROM Service 上下文（doca_urom_service_*），接着在该 Service 上创建 Worker 上下文（doca_urom_worker_*），并在首次入队前确认匹配的 DPU 侧 UROM Service 可达。
通过主机侧 doca_urom_* API 入队远程内存操作（put、get、原子操作、主动消息、集合原语），并推进 DOCA 进度引擎以完成。
通过主机侧 UROM API 读取或设置库属性，并调用 doca_urom_service_get_plugins_list（在已开始的 Service 上）发现此设备 + 此 DOCA 安装 + 此 DPU 侧 UROM Service 版本实际支持的插件列表（因此也即支持的操作类型 / 原子操作 / 集合操作，因为它们在插件中定义）。
将主机侧 UROM 的生命周期、能力发现和错误规则应用到已接入 UROM 的基于 UCX 的 HPC 栈（OpenMPI、MPICH、自定义 UCX 消费者）。设计 UCX 传输集成本身属于上层栈的工作。
调试 doca_urom_* 调用返回的 DOCA_ERROR_* —— 尤其是区分 DPU 侧 UROM Service 不可达、此设备不支持该操作类型、标准 doca_dev 访问被拒、底层 RDMA 传输失败。
设计或扩展封装 UROM C ABI 的非 C 绑定（Rust、Go、Python……）—— 封装必须遵循生命周期、服务运行检查、能力发现和错误分类规则。

不要为一般性的 DOCA 方向、DOCA 安装、DPU 侧 DOCA UROM Service 的部署 / 运维（这是独立工件，有单独公开指南，可通过 doca-public-knowledge-map ## DOCA services 访问）或非 UROM 库问题加载本技能。这些应使用 doca-public-knowledge-map。

本技能提供什么

这是一个轻加载器。正文只保留选择下一个正确文件所需的定向信息。UROM 特有的实用性材料在两个伴生文件中：

CAPABILITIES.md —— 当前版本 + 当前 BlueField + 当前 UROM Service 版本下，主机侧 UROM API 能表达什么：配对契约模型（主机库入队；DPU 服务执行）；两个主机侧上下文类型——doca_urom_service（每个 BlueField 一个，绑定到其 doca_dev）及关联的 doca_urom_worker 上下文；入队侧操作面（put、get、原子操作、主动消息、集合原语），并以“插件定义的 Worker Command 任务”方式交付（确切的符号形状受插件和安装版本绑定）；插件发现面（doca_urom_service_get_plugins_list）；映射到跨库 DOCA_ERROR_* 集合上的 UROM 错误分类；可观察性面（DOCA 进度引擎上的完成事件、能力快照、基础设施侧 RDMA 计数器）；以及安全策略（环境前置条件：DPU 侧已部署并运行 UROM Service；主机库与 DPU 服务版本一致；支持 RDMA 的 BlueField + DOCA 安装）。
TASKS.md —— 六个范围内的 UROM 动词的分步工作流：configure、build、modify、run、test、debug。外加一个 Deferred task verbs 块，将范围外问题指向正确的下一个技能。

该技能假定主机 + BlueField 对已安装 DOCA（标准位置），DOCA UROM Service 已部署并在 BlueField 上运行，主机和 BlueField 之间的底层 RDMA 传输健康，且用户至少已设想出想要卸载的 HPC / UCX / MPI 栈。不涵盖安装 DOCA、在 BlueField 上部署 UROM Service 容器，或建立主机与 BlueField 之间的 RDMA / RoCE / IB 传输——这些路径请分别参考 doca-setup、公开 DOCA UROM Service 指南和 doca-rdma。

本技能刻意不包含的内容

本技能是智能体指导，不是示例或模板包。为保持边界清晰，它刻意不包含——且 PR 不应添加：

任何语言的预写 DOCA UROM 应用源码。 经过验证的 UROM 源码是随 DOCA 提供的 C 示例，位于 /opt/mellanox/doca/samples/doca_urom/。智能体的职责是引导用户到这些文件，并通过 doca-programming-guide 中的通用“修改示例”工作流给出最小差异修改建议，再叠加 TASKS.md ## modify 中的 UROM 特定覆盖规则。
MPI / UCX 算法或集合实现。 本库卸载远程内存操作；为某个 MPI 原语选择发出哪些 put / get / 原子 / 集合操作，是用户 HPC 栈（OpenMPI、MPICH、自定义 UCX 消费者）或用户专业领域的事。智能体必须拒绝发明集合算法，并且必须将任何 “我的 all-reduce 应该用什么算法” 的问题转向上游 MPI / UCX 文档——这是研究 / 栈设计问题，不是 UROM API 问题。
独立构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）放在技能仓库内。智能体应在用户的项目目录中、基于用户已安装的 DOCA 创建构建清单，pkg-config --modversion doca-urom 是权威事实来源。
任何形式的 samples/、bindings/ 或 reference/ 子树。 即使标注为“参考”，本仓库中的 mock 或不完整工件也具有误导性：用户会当作可构建代码来读。
DOCA UROM Service 面。 该服务是独立工件，有单独公开指南；其部署 / 运维的转路由 doca-public-knowledge-map ## DOCA services 管理。将库（本技能，主机侧入队）与服务（DPU 侧执行）混为一谈，是 UROM 首个应用最常见的设计错误。

加载顺序

先阅读本 SKILL.md，确认用户问题在范围内（主机侧库工作；不是 DPU 侧服务部署，也不是 MPI / UCX 算法设计）。
关于 UROM 能力矩阵、配对契约模型（主机库 + DPU 服务）、Service + Worker 上下文模型、入队操作面、插件发现规则、环境前置条件策略、错误分类、可观察性面和安全策略，见 CAPABILITIES.md。
关于分步工作流——configure、build、modify、run、test、debug——见 TASKS.md。

两个伴生文件都相互交叉链接，并链接到 doca-version（获取规范的 DOCA 版本处理规则，并叠加“主机库与 DPU 服务版本必须匹配”的 UROM 覆盖规则）、doca-rdma（UROM 卸载所依托的底层 RDMA 传输层），以及 doca-public-knowledge-map（当正确答案是“去查公开 DOCA UROM 库指南、公开 DOCA UROM Service 指南，或本地磁盘上的安装布局”而不是“UROM 主机侧特有指导”时）。

DOCAUROM主机侧库操作Skill doca-urom