doca-urom

DOCA UROM

示例

• “将 UCX 流量推送到 BlueField 上。”——这属于本技能范围。请专注于主机端的 doca-urom；不要在此处部署 DPU 端的 UROM Service。
• “首次调用 doca_urom 时返回 NOT_PERMITTED。”——首先检查主机与服务的版本是否匹配，以及 RDMA 基础设施。

说明

请遵循下方的加载顺序。要进行配置／卸载／调试，请打开任务配套文件。要了解服务与工作进程上下文，请打开功能配套文件。不要打开所有配套文件。

从这里开始：本技能假定 DOCA 已安装在主机和 BlueField 上，DOCA UROM Service 已部署并运行于 BlueField 上，并且用户正在主机端亲自操作 UROM——通过 HPC／UCX／MPI 技术栈使用 doca-urom，将远程内存操作（put、get、原子操作、主动消息、集合通信）加入队列，由 DPU 代表主机执行。如果要执行某项操作（配置／构建／修改／运行／测试／调试），请打开任务配套文件；如果要了解此版本 + BlueField + UROM Service 版本中主机端 UROM API 能表达什么，请打开功能配套文件。如果未安装 DOCA，请先转到 doca-setup/SKILL.md；若涉及 DPU 端的 UROM Service 本身（部署、容器、生命周期），那是另一项制品——请通过 doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）转到公开的 DOCA UROM Service 指南。本技能介绍的是主机端库；UROM Service 是 DPU 端执行器；两者是一份配套契约。

如何使用本技能。 阅读此文件，然后在配套文件中搜索问题所需的 ## <name> 标题，并阅读该完整章节。仅依据该章节完整作答，引用其中的符号和命令即可。不要浏览文档；请使用 doca-public-knowledge-map 中的入口。对于超出范围的请求，请指出负责该请求的技能，然后停止。

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

此技能擅长解答的 UROM 问题类别，每类附有一个 完整示例。类别是关键所在；完整 示例只是其中一个实例。

• “如何将 MPI / UCX 远程内存操作从 主机 CPU 卸载到 BlueField？”——完整示例：“我的 MPI all-reduce 会消耗本可用于计算的主机 CPU 周期—— 如何通过 UROM 将其转移到 BlueField 上？”。答案由 capabilities 配套文档中的成对契约模型
  • tasks 配套文档中的主机端启动工作流提供。
• “DOCA UROM Service 在我的 BlueField 上运行了吗？ 为什么我在编写 doca_urom_* 代码之前就需要知道这一点？”—— 完整示例：“主机运行状况正常，但我第一次调用 doca_urom_* 时 返回 DOCA_ERROR_NOT_PERMITTED”。 答案由 capabilities 配套文档中的环境前置条件矩阵
  • tasks 配套文档第 1 步中的服务部署检查提供；该步骤会将服务端环境问题 转交给 doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）。
• “我的设备 + DOCA 安装 + UROM Service 版本是否支持这种 UROM 操作类型 / 原子操作 / 集体操作？”——完整示例：“我的 BlueField 是否支持 MPI 窗口的远程原子 Fetch-and-Add 操作？”。答案由 capabilities 配套文档中的插件发现规则 （在已启动的 Service 上调用 doca_urom_service_get_plugins_list—— UROM 操作是由插件定义的 Command 任务，因此插件列表就是能力范围）
  • tasks 配套文档中的发现步骤提供。
• “doca-urom 与 doca-rdma 有什么关系——我应该替换它、在其基础上构建，还是采取其他方式？”——完整示例：“我已经让原始 doca-rdma 正常运行；应该改写为使用 UROM 吗？”。答案由 capabilities 配套文档中的路径选择规则提供 （UROM 基于 RDMA 底层构建，但增加了 DPU 卸载契约；只有在主机 CPU 成为 瓶颈时，UROM 才是合适的工具——简单的点对点场景仍应使用 doca-rdma）。
• “我安装的 DOCA 版本是否提供这个 UROM API？”——完整示例：“在 DOCA 3.x 上，能否通过 doca_urom_service_get_plugins_list 发现 collective-ops 插件？”。答案由 capabilities 配套文档中的版本兼容性补充说明提供， 其中交叉链接到 doca-version/SKILL.md 中的规范检测流程，并补充了 主机库版本与 DPU 服务版本必须匹配这一要求。
• “doca_urom_* 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪一层导致的？”——完整示例：“doca_ctx_start() 成功后，第一次入队时返回 DOCA_ERROR_NOT_PERMITTED”。答案由 capabilities 配套文档中针对跨库错误分类的 UROM 补充说明
  • tasks 配套文档中的分层排查流程提供；该流程会进一步升级到 doca-debug/SKILL.md。

适用对象

本技能面向从主机端使用 DOCA UROM 库构建 HPC / UCX / MPI 应用的外部开发者——通过 doca_urom_* 调用（直接使用 C / C++，通过 FFI / 绑定，或通过配置为使用 UROM 作为传输的 UCX 技术栈，例如 OpenMPI / MPICH），将远程内存操作转交给 BlueField，而不是由主机 CPU 执行。本技能不适用于为 DOCA UROM 做贡献的 NVIDIA 开发者，也不是学习如何在 DPU 端部署 / 运行 UROM 服务的地方——相关内容请参阅公开的 DOCA UROM Service 指南：doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）。

语言范围。 DOCA UROM 以主机端 C 库的形式提供（pkg-config 模块 doca-urom）；/opt/mellanox/doca/samples/doca_urom/ 下提供的示例均为 C。任务配套内容默认面向 C / C++ 使用者——包括封装该库的 UCX 技术栈。其他语言（Rust、Go、Python，等等）的使用者通过 FFI 调用相同的 *.so；本技能提供与语言无关的生命周期、能力发现、错误分类和 RDMA 基础传输层指导，并将公开的 C ABI 作为权威接口。

何时加载本技能

当用户正在从主机端（使用任意语言）实际使用 DOCA UROM 时，请加载本技能。具体包括：

• 在映射到目标 BlueField 的 doca_dev 上初始化 UROM 服务上下文（doca_urom_service_*），创建附加到该上下文的 Worker 上下文（doca_urom_worker_*），并在首次入队前确认可访问匹配的 DPU 端 UROM 服务。
• 通过 doca_urom_* 将远程内存操作（put、get、原子操作、主动消息、集合通信）入队，并推进 DOCA 进度引擎以处理完成事件。
• 在已启动的服务上调用 doca_urom_service_get_plugins_list，以发现该设备、DOCA 安装版本和 UROM 服务版本支持哪些插件，以及由插件定义的操作类型 / 原子操作 / 集合通信。
• 将 UROM 生命周期、能力发现和错误处理规则应用于已接入 UROM 的 UCX 技术栈（OpenMPI、MPICH、自定义 UCX 使用者）。设计 UCX 传输集成本身仍属于上游技术栈的工作。
• 调试来自 doca_urom_* 的 DOCA_ERROR_*，区分 DPU 端 UROM 服务不可访问、此设备不支持该操作类型、普通的 doca_dev 访问被拒绝 和 底层 RDMA 传输失败。
• 设计封装 UROM C ABI、且必须遵守相同生命周期和错误处理规则的非 C 语言绑定（Rust、Go、Python，等等）。

以下情况不要加载本技能：一般性的 DOCA 概览、DOCA 安装、DPU 端 UROM 服务的部署 / 运行（这是独立的构件，有自己的公开指南：doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）），或非 UROM 库相关问题。对于这些情况，请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个精简加载器。正文仅保留用于选择正确后续文件所需的指引。实质性的 UROM 专属内容位于两个配套文件中：

• capabilities 配套文件 — 说明此版本 + 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 错误分类；可观测性接口（完成事件、能力快照、RDMA 计数器）；以及安全策略，用于检查环境前置条件（UROM Service 已部署在 DPU 上；主机库与 DPU 服务版本一致；具备 RDMA 能力的 BlueField + DOCA 安装）。
• tasks 配套文件 — 针对六个范围内 UROM 动词的分步工作流：configure、build、modify、run、test、debug。另有一个 Deferred task verbs 区块，将范围外的问题指向合适的后续技能。

此技能假设主机与 BlueField 已配对，DOCA 已安装，UROM Service 已部署并在 BlueField 上运行，两者之间的 RDMA 传输正常，并且用户已大致了解要卸载的 HPC / UCX / MPI 堆栈。此技能不涵盖安装 DOCA、部署 UROM Service 容器或启用 RDMA / RoCE / IB 传输 — 这些内容请参阅 doca-setup/SKILL.md、公开的 DOCA UROM Service 指南和 doca-rdma/SKILL.md。

此技能有意不提供的内容

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

• 任何语言编写的预先编写 DOCA UROM 应用程序源代码。 已验证的 UROM 源代码是随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_urom/。Agent 会引导用户前往该目录，并通过 doca-programming-guide/SKILL.md 中的修改示例工作流，结合 tasks 配套文件中的 UROM 覆盖项，规定最小差异修改。
• MPI / UCX 算法或集体通信实现。 此库会卸载远程内存操作；针对特定 MPI 原语选择要执行的 put / get / 原子操作 / 集体通信，属于用户的 HPC 堆栈或领域专业知识范畴。拒绝凭空编造集体通信算法；对于*"我的 all-reduce 应该使用什么算法"*，应引导用户查阅上游 MPI / UCX 文档 — 这是堆栈设计问题，而非 UROM API 问题。
• 独立的构建清单（meson.build、CMakeLists.txt、Cargo.toml、…），放在技能目录中。Agent 会在用户的项目中，针对已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-urom 是事实依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 标为“reference”的模拟产物会让人误以为它可以构建，从而造成误导。
• DOCA UROM Service 接口。 该服务是一个独立产物，有自己的公开指南；路由信息位于 doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）。混淆库（主机端入队）和服务（DPU 端执行器），是 UROM 首个应用设计中最常见的错误。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其范围（主机端库工作；不包括 DPU 端服务部署，也不包括 MPI / UCX 算法设计）。
2. 有关 UROM 能力矩阵、配对契约模型（主机库 + DPU 服务）、Service + Worker 上下文模型、入队端操作接口、插件发现规则、环境前置条件策略、错误分类、可观测性接口和安全策略，请参阅能力配套文档。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

这两个配套文件彼此交叉链接，并链接到 doca-version/SKILL.md 以了解规范版本规则（另有 UROM 特别规定：主机库和 DPU 服务的版本必须匹配），链接到 doca-rdma/SKILL.md 以了解底层 RDMA 基础，以及在正确答案是“查阅公开 UROM 库 / Service 指南或磁盘上的安装布局”时，链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包在磁盘上的布局。DOCA UROM 库公开指南位于 https://docs.nvidia.com/doca/sdk/DOCA-UROM/index.html；DOCA UROM Service 是一个不同的构件，在该地图的 DOCA services 部分单独说明。
• doca-rdma/SKILL.md — 底层 RDMA 传输基础；UROM 卸载操作后，BlueField 通过它传输字节。UROM 不会取代 RDMA；它是在其上添加 DPU 卸载契约。对于主机 CPU 并非瓶颈的简单点对点 RDMA，请直接使用 doca-rdma——UROM 的服务端契约在此类场景中不值得其开销。
• doca-setup/SKILL.md — 环境准备、 安装验证、BlueField 设置，以及通过公开 NGC DOCA 容器进行的尚未安装路径。此技能假设其前置条件均已满足，且 DPU 端 UROM Service 已部署并运行。
• doca-version/SKILL.md — DOCA 规范的 版本处理规则。此技能的 ## Version compatibility 交叉链接到四方匹配规则，并补充了主机库 + DPU 服务必须使用相同版本这一特别规定。
• doca-structured-tools-contract/SKILL.md — 此工具包的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的命令附录遵循此契约。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式： pkg-config + meson 构建、优先修改随附示例来开发首个应用、Core 上下文生命周期、跨库的 DOCA_ERROR_* 错误分类，以及调试顺序。此技能在此基础上叠加 UROM 专属内容。
• doca-debug/SKILL.md — 跨领域的 调试流程（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。UROM 专属调试问题（UROM Service 无法访问、主机库与 DPU 服务版本不匹配、底层 RDMA 传输失败、此设备 + 固件 + 服务版本不支持操作类型）叠加在此流程之上。

在 DPU 端运行的 DOCA UROM Service 特意不在此技能的范围内——它是一个独立构件，通过 doca-public-knowledge-map ## DOCA services（doca-public-knowledge-map/SKILL.md#doca-services）提供自己的公开指南。 混淆库与服务，是 UROM 首个应用设计中最常见的错误：凡是问题涉及两者，都要明确说明它们的区别。