DOCA UROM
本指南概述了 DOCA 统一资源和卸载管理器 (UROM) API 的概览和配置说明。
此库目前仅在 alpha 级别受支持。
DOCA 统一资源和卸载管理器 (UROM) 为将部分并行计算任务（例如与 HPC 或 AI 工作负载和框架相关的任务）从主机卸载到 NVIDIA DPU 提供了框架。此框架包括 UROM 服务，该服务负责资源发现、主机和 DPU 之间的协调以及执行并行计算任务的 UROM 工作器的管理。
当应用程序利用 UROM 框架进行卸载时，它由两个主要组件组成：主机部分和 DPU 上的 UROM 工作器。主机部分负责与 DOCA UROM API 交互，并作为应用程序的一部分运行，目的是将任务卸载到 DPU。此组件与 UROM 服务建立连接并启动卸载请求。为了响应卸载请求，UROM 服务为工作器提供网络标识符，这些工作器由 UROM 服务生成。如果 UROM 服务作为 Kubernetes POD 运行，则工作器在 POD 内生成。每个工作器负责执行单个卸载或多个卸载，具体取决于主机应用程序的要求。
基于 TCP 套接字传输的 DOCA UROM 主机和 DPU 部分之间的通信通道需要 UCX。这是一种将命令从主机传输到 DPU 上的 UROM 服务并接收来自 DPU 的响应的机制。
默认情况下，UCX 会扫描机器上的所有可用设备，并根据性能特征选择最佳设备。环境变量UCX_NET_DEVICES=<dev1>,<dev2>,...将 UCX 限制为仅使用指定的设备。例如，UCX_NET_DEVICES=eth2使用以太网设备 eth2 进行 TCP 套接字传输。
有关 UCX 的更多信息，请参阅 DOCA UCX 编程指南。
UROM 部署
该图说明了标准的 UROM 部署，其中每个 DPU 都需要托管服务进程实例和一组工作器进程。
UROM 服务的典型用法包括以下步骤
并行应用程序中的每个进程都发现 UROM 服务。
UROM 处理身份验证并提供服务详细信息。
主机应用程序通过 UROM 服务接收本地 DPU 上可用的卸载插件。
主机应用程序选择所需的插件信息，并通过 UROM 服务在 DPU 上触发 UROM 工作器插件实例。
应用程序将特定任务委派给 UROM 工作器。
UROM 工作器执行这些任务并返回结果。
UROM 框架
此图显示了 DOCA UROM 框架的高级概述。
UROM 卸载插件是 AI/HPC 卸载的开发人员实现其自身卸载逻辑的地方，同时使用 DOCA UROM 作为传输层和资源管理器。每个插件定义了在 DPU 上执行逻辑的命令以及返回给主机应用程序的通知。每种支持的卸载类型都对应于一种不同的 DOCA UROM 插件类型。例如，开发人员可能需要 UCC 插件才能将 UCC 功能卸载到 DPU。每个插件都实现了一个 DPU 端插件 API，并公开了相应的主机端接口。
UROM 守护程序在运行时加载插件 DPU 版本 (.so 文件)，作为本地插件发现的一部分。
插件任务卸载流程
UROM 安装
DOCA UROM 是 DOCA SDK 安装包的组成部分。根据您的系统架构和启用的卸载插件，UROM 由几个组件组成，这些组件可以分为两个主要部分：主机上的组件和 DPU 上的组件。
DOCA UROM 库组件
libdoca_urom共享对象 – 包含 DOCA UROM APIlibdoca_urom_components_comm_ucp_am– 包括 UROM 通信通道接口 API
DOCA UROM 标头
标头文件包括以下描述的 DOCA UROM 的定义
DOCA UROM 主机接口 (
doca_urom.h) – 此标头包括三个基本组件：上下文、任务和插件。服务上下文 (
doca_urom_service) – 此上下文充当 UROM 服务进程的抽象。在此上下文中发布的任务包括 DPU 上工作器的身份验证、生成和终止。工作器上下文 (
doca_urom_worker) – 此上下文抽象了 DPU UROM 工作器，该工作器代表主机应用程序插件（卸载）运行。在此上下文中发布的任务涉及代表特定卸载插件（例如，用于通信操作的卸载功能）将命令从主机应用程序中继到工作器。域上下文 (
doca_urom_domain) – 此上下文封装了属于同一主机应用程序的一组工作器。此概念类似于 MPI（消息传递接口）编程模型中的 MPI 通信器或 PyTorch 的进程组。插件不需要使用 UROM 域。
DOCA UROM 插件接口 (
doca_urom_plugin.h) – 此标头包括用户可用于构建其自身卸载插件的主机和 DPU 组件的主要结构和定义UROM 插件接口结构 (
urom_plugin_iface) – 此接口包括一组要由 UROM 工作器执行的操作UROM 工作器命令结构 (
urom_worker_cmd) – 此结构定义了工作器实例命令格式UROM 工作器通知结构 (
urom_worker_notify) – 此结构定义了工作器实例通知格式
下图显示了 DOCA UROM 的各种软件组件
DOCA Core – 涉及 DOCA 设备发现、DOCA 进度引擎、DOCA 上下文等。
DOCA UROM Core – 包括 UROM 库功能
DOCA UROM 主机 SDK – 供主机应用程序使用的 UROM API
DOCA UROM DPU SDK – 供 NVIDIA® BlueField ® 网络平台（DPU 或 SuperNIC）使用的 UROM API
DOCA UROM 主机插件 – 用户插件主机版本
DOCA UROM DPU 插件 – 用户插件 DPU 版本
DOCA UROM 应用 – 用户 UROM 主机应用程序
DOCA UROM 工作器 – 执行卸载逻辑的卸载功能组件
DOCA UROM 守护程序 – 负责资源发现、主机和 DPU 之间的协调以及管理 BlueField 上的工作器
有关 DOCA UROM API 的更多信息，请参见 DOCA 库 API。
UROM 库的 pkg-config (*.pc 文件) 是 doca-urom。
以下部分提供了有关库 API 的更多详细信息。
DOCA_UROM_SERVICE_FILE
此环境变量设置 UROM 服务文件的路径。在创建 UROM 服务对象（请参阅 doca_urom_service_create）时，UROM 会使用此文件、应用程序运行的主机名以及关联的 DOCA 设备的 PCIe 地址执行查找，以识别与 UROM 服务关联的网络地址和网络设备。
此文件每行包含一个条目，描述每个 UROM 服务的location，UROM 可以使用这些服务。每行的格式必须如下所示
<app_hostname> <service_type> <dev_hostname> <dev_pci_addr> <net,devs>
示例
app_host1 dpu dpu_host1 03:00.0 dev1:1,dev2:1
字段在下表中描述
字段 | 描述 |
| 此行适用的节点的网络主机名（或 IP 地址） |
| UROM 服务类型。有效类型为 |
| 关联的 DOCA 设备的网络主机名（或 IP 地址） |
| 关联的 DOCA 设备的 PCIe 地址。这必须与 DOCA 提供的 PCIe 地址匹配。 |
| 主机和 DOCA 设备之间共享的网络设备的逗号分隔列表 |
doca_urom_service
表示 DOCA UROM 服务的不透明结构。
struct doca_urom_service;
doca_urom_service_plugin_info
DOCA UROM 插件信息结构。UROM 为 UROM 服务运行的本地 DPU 上的每个插件生成此结构，并且服务返回可用插件的数组，供主机应用程序选择要使用的插件。
struct doca_urom_service_plugin_info {
uint64_t id;
uint64_t version;
char plugin_name[DOCA_UROM_PLUGIN_NAME_MAX_LEN];
};
id– 用于向插件发送命令的唯一 ID，UROM 生成此 IDversion– 插件 DPU 版本，用于验证插件主机接口是否具有相同的版本plugin_name– 没有 “.so” 的.so插件文件名。该名称用于查找所需的插件。
doca_urom_service_get_workers_by_gid_task
表示 DOCA 服务获取按组 ID 划分的工作器任务的不透明结构。
struct doca_urom_service_get_workers_by_gid_task;
doca_urom_service_create
在执行任何 UROM 服务操作（生成工作器、销毁工作器等）之前，必须创建 doca_urom_service 对象。服务对象在 DOCA_CTX_STATE_IDLE 状态下创建。创建后，用户可以使用 setter 方法配置服务（例如，doca_urom_service_set_dev()）。
在使用之前，必须使用 doca_ctx_start() 接口将服务对象转换为 DOCA_CTX_STATE_RUNNING 状态。典型的调用如下所示：doca_ctx_start(doca_urom_service_as_ctx(service_ctx))。
doca_error_t doca_urom_service_create(struct doca_urom_service **service_ctx);
service_ctx [in/out]– 要创建的doca_urom_service对象返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
多个应用程序进程可以创建不同的服务对象，这些对象表示/连接到 DPU 上的同一工作器。
doca_urom_service_destroy
销毁 doca_urom_service 对象。
doca_error_t doca_urom_service_destroy(struct doca_urom_service *service_ctx);
service_ctx[in]– 要销毁的doca_urom_service对象。它由doca_urom_service_create()创建。返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_service_set_max_comm_msg_size
设置 UROM 通信通道中消息的最大大小。默认消息大小为 4096B。
务必确保插件的命令和通知以及 UROM 结构的大小总和不超过此最大大小。
一旦服务状态正在运行，用户就无法更新消息的最大大小。
doca_error_t doca_urom_service_set_max_comm_msg_size(struct doca_urom_service *service_ctx, size_t msg_size);
service_ctx[in]– 指向要设置新消息大小的doca_urom_service对象的指针msg_size[in]– 要设置的新消息大小返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_service_as_ctx
将 doca_urom_service 对象转换为 DOCA 对象。
struct doca_ctx *doca_urom_service_as_ctx(struct doca_urom_service *service_ctx);
service_ctx[in]– 指向doca_urom_service对象的指针返回 – 成功时返回指向
doca_ctx对象的指针，否则返回NULL
doca_urom_service_get_plugins_list
检索 UROM 服务上支持的插件列表。
doca_error_t doca_urom_service_get_plugins_list(struct doca_urom_service *service_ctx, const struct doca_urom_service_plugin_info **plugins, size_t *plugins_count);
service_ctx[in]– 指向doca_urom_service对象的指针plugins[out]– 指向doca_urom_service_plugin_info对象的指针数组plugins_count[out]– 插件数量返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_service_get_cpuset
获取 BlueField 上 UROM 服务允许的 CPU 集，该 CPU 集可在生成工作器以设置处理器亲和性时使用。
doca_error_t doca_urom_service_get_cpuset(struct doca_urom_service *service_ctx, doca_cpu_set_t *cpuset);
service_ctx[in]– 指向doca_urom_service对象的指针cpuset[out]– 允许的 CPU 集返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_service_get_workers_by_gid_task_allocate_init
分配按 GID 获取工作器服务任务并设置任务属性。
doca_error_t doca_urom_service_get_workers_by_gid_task_allocate_init(struct doca_urom_service *service_ctx,
uint32_t gid,
doca_urom_service_get_workers_by_gid_task_completion_cb_t cb,
struct doca_urom_service_get_workers_by_gid_task **task);
service_ctx[in]– 指向doca_urom_service对象的指针gid[in]– 要设置的组 IDcb[in]– 用户任务完成回调task[out]– 新的按 GID 获取工作器服务任务返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_service_get_workers_by_gid_task_release
释放按 GID 获取工作器服务任务和任务资源。
doca_error_t doca_urom_service_get_workers_by_gid_task_release(struct doca_urom_service_get_workers_by_gid_task *task);
task[in]– 要释放的服务任务返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_service_get_workers_by_gid_task_as_task
将 doca_urom_service_get_workers_by_gid_task 对象转换为 DOCA 任务对象。
在创建服务任务并使用 setter 方法（例如，doca_urom_service_get_workers_by_gid_task_set_gid()）或作为任务分配的一部分配置服务任务之后，用户应通过调用 doca_task_submit 来提交任务。
典型的调用如下所示：doca_task_submit(doca_urom_service_get_workers_by_gid_task_as_task(task))。
struct doca_task *doca_urom_service_get_workers_by_gid_task_as_task(struct doca_urom_service_get_workers_by_gid_task *task);
task[in]– 按 GID 获取工作器服务任务返回 – 成功时返回指向
doca_task对象的指针，否则返回NULL
doca_urom_service_get_workers_by_gid_task_get_workers_count
获取为请求的 GID 返回的工作器数量。
size_t doca_urom_service_get_workers_by_gid_task_get_workers_count(struct doca_urom_service_get_workers_by_gid_task *task);
task[in]– 按 GID 获取工作器服务任务返回 – 工作器 ID 数组大小
doca_urom_service_get_workers_by_gid_task_get_worker_ids
获取服务获取工作器任务 ID 数组。
const uint64_t *doca_urom_service_get_workers_by_gid_task_get_worker_ids(struct doca_urom_service_get_workers_by_gid_task *task);
task[in]– 按 GID 获取工作器服务任务返回 – 工作器 ID 数组，否则返回
NULL
doca_urom_worker
表示 DOCA UROM 工作器上下文的不透明结构。
struct doca_urom_worker;
doca_urom_worker_cmd_task
表示 DOCA UROM 工作器命令任务上下文的不透明结构。
struct doca_urom_worker_cmd_task;
doca_urom_worker_cmd_task_completion_cb_t
工作器命令任务完成回调类型。工作器任务完成后会调用它。
typedef void (*doca_urom_worker_cmd_task_completion_cb_t)(struct doca_urom_worker_cmd_task *task,
union doca_data task_user_data,
union doca_data ctx_user_data);
task[in]– 指向工作器命令任务的指针task_user_data[in]– 用户任务数据ctx_user_data[in]– 用户工作器上下文数据
doca_urom_worker_create
此方法创建 UROM 工作器上下文。
工作器在 DOCA_CTX_STATE_IDLE 状态下创建。创建后，用户可以使用 setter 方法配置工作器（例如，doca_urom_worker_set_service()）。在使用之前，必须使用 doca_ctx_start() 接口将工作器转换为 DOCA_CTX_STATE_RUNNING 状态。典型的调用如下所示：doca_ctx_start(doca_urom_worker_as_ctx(worker_ctx))。
doca_error_t doca_urom_worker_create(struct doca_urom_worker **worker_ctx);
worker_ctx [in/out]– 要创建的doca_urom_worker对象返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_destroy
销毁 UROM 工作器上下文。
doca_error_t doca_urom_worker_destroy(struct doca_urom_worker *worker_ctx);
worker_ctx [in]– 要销毁的doca_urom_worker对象。它由doca_urom_worker_create()创建。返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_set_service
将 UROM 服务附加到工作器上下文。工作器在提供的服务上下文管理的 DOCA 设备上启动。
doca_error_t doca_urom_worker_set_service(struct doca_urom_worker *worker_ctx, struct doca_urom_service *service_ctx);
service_ctx [in]– 要设置的服务上下文返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_set_id
此方法设置工作器上下文 ID，用于标识工作器。工作器 ID 使应用程序能够与 DOCA 设备上运行的同一工作器进程建立多个连接。
工作器 ID 对于 UROM 服务必须是唯一的。
如果指定
DOCA_UROM_WORKER_ID_ANY，则服务会为新创建的工作器分配唯一的 ID。如果使用特定的 ID，则服务会查找具有匹配 ID 的现有工作器。如果存在，则服务会与现有工作器建立新连接。如果不存在匹配的工作器，则会使用指定的工作器 ID 创建新工作器。
doca_error_t doca_urom_worker_set_id(struct doca_urom_worker *worker_ctx, uint64_t worker_id);
worker_ctx [in]–doca_urom_worker对象worker_id [in]– 工作器 ID返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_set_gid
设置工作器组 ID。必须在启动工作器上下文之前设置此 ID。
通过服务按 GID 获取工作器任务，应用程序可以获得在 DOCA 设备上运行并且属于同一组 ID 的工作器 ID 列表。
doca_error_t doca_urom_worker_set_gid(struct doca_urom_worker *worker_ctx, uint32_t gid);
worker_ctx [in]–doca_urom_worker对象gid [in]– 工作器组 ID返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_set_plugins
为 DPU 上的 UROM 工作器支持的插件添加插件掩码。应用程序最多可以使用 62 个插件。
doca_error_t doca_urom_worker_set_plugins(struct doca_urom_worker *worker_ctx, uint64_t plugins);
worker_ctx[in]–doca_urom_worker对象plugins[in]– 工作器插件 ID 的 OR 集合返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_set_env
通过 DOCA UROM 服务在 DPU 端生成工作器时，设置工作器环境变量。必须在启动工作器上下文之前设置它们。
如果工作器已在 DPU 上生成，则此调用将失败。
doca_error_t doca_urom_worker_set_env(struct doca_urom_worker *worker_ctx, char *const env[], size_t count);
worker_ctx [in]–doca_urom_worker对象env [in]– 环境变量数组count [in]– 数组大小返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_as_ctx
将 doca_urom_worker 对象转换为 DOCA 对象。
struct doca_ctx *doca_urom_worker_as_ctx(struct doca_urom_worker *worker_ctx);
worker_ctx[in]– 指向doca_urom_worker对象的指针返回 – 成功时返回指向
doca_ctx对象的指针，否则返回NULL
doca_urom_worker_cmd_task_allocate_init
分配工作器命令任务并设置任务属性。
doca_error_t doca_urom_worker_cmd_task_allocate_init(struct doca_urom_worker *worker_ctx, uint64_t plugin, struct doca_urom_worker_cmd_task **task);
worker_ctx [in]– 指向doca_urom_worker对象的指针plugin [in]– 任务插件 IDtask [out]– 设置工作器命令新任务返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_cmd_task_release
释放工作器命令任务。
doca_error_t doca_urom_worker_cmd_task_release(struct doca_urom_worker_cmd_task *task);
task[in]– 要释放的工作器任务返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_worker_cmd_task_set_plugin
设置工作器命令任务插件 ID。插件 ID 由 UROM 服务创建，插件主机接口应保留该 ID 以创建 UROM 工作器命令任务。
void doca_urom_worker_cmd_task_set_plugin(struct doca_urom_worker_cmd_task *task, uint64_t plugin);
task [in]– 工作器任务plugin [in]– 要设置的任务插件
doca_urom_worker_cmd_task_set_cb
设置工作器命令任务完成回调。
void doca_urom_worker_cmd_task_set_cb(struct doca_urom_worker_cmd_task *task, doca_urom_worker_cmd_task_completion_cb_t cb);
task[in]– 工作器任务plugin[in]– 要设置的任务回调
doca_urom_worker_cmd_task_get_payload
获取工作器命令任务有效负载。插件接口通过插件命令结构填充此缓冲区。有效负载大小是 DOCA UROM 通信通道中的最大消息大小（用户可以通过调用 doca_urom_service_set_max_comm_msg_size() 配置大小）。要更新有效负载缓冲区，用户应调用 doca_buf_set_data()。
struct doca_buf *doca_urom_worker_cmd_task_get_payload(struct doca_urom_worker_cmd_task *task);
task [in]– 工作器任务返回 – 表示任务有效负载的
doca_buf
doca_urom_worker_cmd_task_get_response
获取工作器命令任务响应。要获取响应的缓冲区，用户应调用 doca_buf_get_data()。
struct doca_buf *doca_urom_worker_cmd_task_get_response(struct doca_urom_worker_cmd_task *task);
task [in]– 工作器任务返回 – 表示任务响应的
doca_buf
doca_urom_worker_cmd_task_get_user_data
获取要填充的工作器命令用户数据。数据是指用户在调用完成回调时可以获取的任务内部的保留数据。最大数据大小为 32 字节。
void *doca_urom_worker_cmd_task_get_user_data(struct doca_urom_worker_cmd_task *task);
task [in]– 工作器任务返回 – 指向用户数据内存的指针
doca_urom_worker_cmd_task_as_task
将 doca_urom_worker_cmd_task 对象转换为 DOCA 任务对象。
在创建工作器命令任务并使用 setter 方法（例如，doca_urom_worker_cmd_task_set_plugin()）或作为任务分配的一部分配置工作器命令任务之后，用户应通过调用 doca_task_submit 来提交任务。
典型的调用如下所示：doca_task_submit(doca_urom_worker_cmd_task_as_task(task))。
struct doca_task *doca_urom_worker_cmd_task_as_task(struct doca_urom_worker_cmd_task *task);
task[in]– 工作器命令任务返回 – 成功时返回指向
doca_task对象的指针，否则返回NULL
doca_urom_domain
表示 DOCA UROM 域上下文的不透明结构。
struct doca_urom_domain;
doca_urom_domain_allgather_cb_t
非阻塞 all-gather 操作的回调。
typedef doca_error_t (*doca_urom_domain_allgather_cb_t)(void *sbuf, void *rbuf, size_t msglen, void *coll_info, void **req);
sbuf [in]– 要发送到其他进程的本地缓冲区rbuf [in]– 包含其他进程的源缓冲区的全局缓冲区msglen [in]– 源缓冲区长度coll_info [in]– 收集信息req [in]– allgather 请求数据返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_domain_req_test_cb_t
用于测试非阻塞 allgather 请求状态的回调。
typedef doca_error_t (*doca_urom_domain_req_test_cb_t)(void *req);
req [in]– 要检查状态的 allgather 请求数据返回 – 成功时返回
DOCA_SUCCESS，否则返回DOCA_ERROR_IN_PROGRESS
doca_urom_domain_req_free_cb_t
用于释放非阻塞 allgather 请求的回调。
typedef doca_error_t (*doca_urom_domain_req_free_cb_t)(void *req);
req [in]– 要释放的 allgather 请求数据。返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_domain_oob_coll
用于域创建的带外通信描述符。
struct doca_urom_domain_oob_coll {
doca_urom_domain_allgather_cb_t allgather;
doca_urom_domain_req_test_cb_t req_test;
doca_urom_domain_req_free_cb_t req_free;
void *coll_info;
uint32_t n_oob_indexes;
uint32_t oob_index;
};
allgather– 非阻塞 allgather 回调req_test– 请求测试回调req_free– 请求释放回调coll_info– OOB 集合所需的上下文或元数据n_oob_indexes– 参与 OOB 操作的端点数（例如，表示域工作器的客户端进程数）oob_index– 一个整数值，表示调用进程在给定 OOB 操作中的位置。由src_buf指定的数据放置在recv_buf中的偏移量 “oob_index*size” 处。注意oob_index在每个调用进程中必须是唯一的，并且应在 [0:n_oob_indexes) 范围内。
doca_urom_domain_create
创建 UROM 域上下文。域在 DOCA_CTX_STATE_IDLE 状态下创建。创建后，用户可以使用 setter 方法配置域（例如，doca_urom_domain_set_workers()）。在使用之前，必须使用 doca_ctx_start() 接口将域转换为 DOCA_CTX_STATE_RUNNING 状态。典型的调用如下所示：doca_ctx_start(doca_urom_domain_as_ctx(worker_ctx))。
doca_error_t doca_urom_domain_create(struct doca_urom_domain **domain_ctx);
domain_ctx [in/out]– 要创建的doca_urom_domain对象返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_domain_destroy
销毁 UROM 域上下文。
doca_error_t doca_urom_domain_destroy(struct doca_urom_domain *domain_ctx);
domain_ctx [in]– 要销毁的doca_urom_domain对象；它由doca_urom_domain_create()创建返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_domain_set_workers
设置域中工作器的列表。
doca_error_t doca_urom_domain_set_workers(struct doca_urom_domain *domain_ctx, uint64_t *domain_worker_ids, struct doca_urom_worker **workers, size_t workers_cnt);
domain_ctx [in]–doca_urom_domain对象domain_worker_ids [in]– 域工作器 ID 列表workers [in]– 应该是域一部分的 UROM 工作器上下文数组workers_cnt [in]– 给定数组中的工作器数量返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_domain_add_buffer
将本地缓冲区属性附加到域。应在调用 doca_urom_domain_set_buffers_count() 后调用。
本地缓冲区将与属于该域的所有工作器共享。
doca_error_t doca_urom_domain_add_buffer(struct doca_urom_domain *domain_ctx, void *buffer, size_t buf_len, void *memh, size_t memh_len, void *mkey, size_t mkey_len);
domain_ctx [in]–doca_urom_domain对象buffer [in]– 准备好远程访问的缓冲区，该缓冲区提供给域buf_len [in]– 缓冲区长度memh [in]– 导出缓冲区的内存句柄。（应打包）memh_len [in]– 内存句柄大小mkey [in]– 导出缓冲区的内存密钥。（应打包）mkey_len [in]– 内存密钥大小返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_domain_set_oob
设置 OOB 通信信息以用于域初始化。
doca_error_t doca_urom_domain_set_oob(struct doca_urom_domain *domain_ctx, struct doca_urom_domain_oob_coll *oob);
domain_ctx [in]–doca_urom_domain对象oob [in]– 要设置的 OOB 通信信息返回 – 成功时返回
DOCA_SUCCESS，否则返回错误代码
doca_urom_domain_as_ctx
将 doca_urom_domain 对象转换为 DOCA 对象。
struct doca_ctx *doca_urom_domain_as_ctx(struct doca_urom_domain *domain_ctx);
domain_ctx[in]– 指向doca_urom_domain对象的指针返回 – 成功时返回指向
doca_ctx对象的指针，否则返回NULL
本节介绍了在创建 DOCA UROM 应用程序和卸载功能时使用的基本构建模块背后的通用概念。
程序流程
DPU
启动 DOCA UROM 服务
应在主机上运行应用程序以将命令卸载到 BlueField 之前运行 DOCA UROM 服务。有关更多信息，请参阅 DOCA UROM 服务指南。
主机
初始化 UROM 服务上下文
创建服务上下文：在控制平面内与进度引擎一起建立服务上下文。
设置服务上下文属性：配置服务上下文的特定属性。必需的属性是
doca_dev。启动服务上下文：通过调用
doca_ctx_start函数来启动服务上下文。发现 BlueField 可用性：UROM 库标识可用的 BlueField 设备。
连接到 UROM 服务：库建立与 UROM 服务的连接。连接过程是同步的，这意味着主机进程和 BlueField 服务进程将被阻止，直到建立连接。
使用 UROM 服务文件执行查找：使用 UROM 服务文件执行查找操作。此文件的路径应在
DOCA_UROM_SERVICE_FILE环境变量中指定。有关更多信息，请参见doca_urom.h。
将上下文状态切换到
DOCA_CTX_STATE_RUNNING：此时上下文状态转换为DOCA_CTX_STATE_RUNNING。服务上下文等待工作器引导请求：服务上下文现在处于等待和处理工作器引导请求的状态。
/* Create DOCA UROM service instance */
doca_urom_service_create(&service);
/* Connect service context to DOCA progress engine */
doca_pe_connect_ctx(pe, doca_urom_service_as_ctx(service));
/* Set service attributes */
doca_urom_service_set_max_workers(service, nb_workers)
doca_urom_service_set_dev(service, dev);
/* Start service context */
doca_ctx_start(doca_urom_service_as_ctx(service));
/* Handling workers bootstrap requests */
do {
doca_pe_progress(pe);
} while (!are_all_workers_started);
选择 UROM 工作器卸载功能
一旦服务上下文状态为“运行中”，应用程序可以调用 doca_urom_service_get_plugins_list() 以获取本地 BlueField 设备上可用的插件列表，UROM 服务在该设备上运行。
UROM 服务为每个插件生成一个标识符，应用程序负责将此 ID 转发到主机插件接口，以便通过调用 urom_<plugin_name>_init(<plugin_id>, <plugin_version>) 发送命令和接收通知。
const char *plugin_name = "worker_rdmo";
struct doca_urom_service *service;
const struct doca_urom_service_plugin_info *plugins, *rdmo_info;
/* Create and Start UROM service context. */
..
/* Get worker plugins list. */
doca_urom_service_get_plugins_list(*service, &plugins, &plugins_count);
/* Check if RDMO plugin exists. */
for (i = 0; i < plugins_count; i++) {
if (strcmp(plugin_name, plugins[i].plugin_name) == 0) {
rdmo_info = &plugins[i];
break;
}
}
/* Attach RDMO plugin ID and DPU plugin version for compatibility check */
urom_rdmo_init(rdmo_info->id, rdmo_info->version);
初始化 UROM 工作器上下文
创建一个服务上下文，并将工作器上下文连接到 DOCA Progress Engine (PE)。
设置工作器上下文属性（在以下示例中，工作器插件为 RDMO）。
启动工作器上下文，提交操作会在服务上下文中内部衍生工作器请求。
工作器上下文状态更改为
DOCA_CTX_STATE_STARTING（此过程是异步的）。等待工作器上下文状态更改为
DOCA_CTX_STATE_RUNNING当调用
doca_pe_progress时，检查来自服务上下文的响应，以确认 BlueField 上的衍生工作器已完成。如果工作器在 BlueField 上衍生，则连接到它并将状态更改为“运行中”。
const struct doca_urom_service_plugin_info *rdmo_info;
/* Create DOCA UROM worker instance */
doca_urom_worker_create(&worker);
/* Connect worker context to DOCA progress engine */
doca_pe_connect_ctx(pe, doca_urom_worker_as_ctx(worker));
/* Set worker attributes */
doca_urom_worker_set_service(worker, service);
doca_urom_worker_set_id(worker, worker_id);
doca_urom_worker_set_max_inflight_tasks(worker, nb_tasks);
doca_urom_worker_set_plugins(worker, rdmo_info->id);
doca_urom_worker_set_cpuset(worker, cpuset);
/* Start UROM worker context */
doca_ctx_start(doca_urom_worker_as_ctx(worker));
/* Progress until worker state changes to running or error happened */
do {
doca_pe_progress(pe);
result = doca_ctx_get_state(doca_urom_worker_as_ctx(worker), &state);
} while (state == DOCA_CTX_STATE_STARTING);
卸载插件任务
一旦工作器上下文状态为 DOCA_CTX_STATE_RUNNING，工作器就可以执行卸载任务。以下示例用于卸载 RDMO 命令。
准备 RDMO 任务参数（例如，完成回调）。
从插件主机接口调用任务函数。
通过调用
doca_pe_progress轮询完成情况。通过用户回调获取完成通知。
int ret;
struct doca_urom_worker *worker;
struct rdmo_result res = {0};
union doca_data cookie = {0};
size_t server_worker_addr_len;
ucp_address_t *server_worker_addr;
cookie.ptr = &res;
res.result = DOCA_SUCCESS;
ucp_worker_create(*ucp_context, &worker_params, server_ucp_worker);
ucp_worker_get_address(*server_ucp_worker, &server_worker_addr, &server_worker_addr_len);
/* Create and submit RDMO client init task */
urom_rdmo_task_client_init(worker, cookie, 0, server_worker_addr, server_worker_addr_len, urom_rdmo_client_init_finished);
/* Wait for completion */
do {
ret = doca_pe_progress(pe);
ucp_worker_progress(*server_ucp_worker);
} while (ret == 0 && res.result == DOCA_SUCCESS);
/* Check task result */
if (res.result != DOCA_SUCCESS)
DOCA_LOG_ERR("Client init task finished with error");
初始化 UROM 域上下文
在控制平面 PE 上创建域上下文。
设置域上下文属性。
通过调用
doca_ctx_start启动域上下文。在所有工作器之间交换内存描述符。
等待域上下文状态为“运行中”。
/* Create DOCA UROM domain instance */
doca_urom_domain_create(&domain);
/* Connect domain context to DOCA progress engine */
doca_pe_connect_ctx(pe, doca_urom_domain_as_ctx(domain));;
/* Set domain attributes */
doca_urom_domain_set_oob(domain, oob);
doca_urom_domain_set_workers(domain, worker_ids, workers, nb_workers);
doca_urom_domain_set_buffers_count(domain, nb_buffers);
for each buffer:
doca_urom_domain_add_buffer(domain);
/* Start domain context */
doca_ctx_start(doca_urom_domain_as_ctx(domain));
/* Loop till domain state changes to running */
do {
doca_pe_progress(pe);
result = doca_ctx_get_state(doca_urom_domain_as_ctx(domain), &state);
} while (state == DOCA_CTX_STATE_STARTING && result == DOCA_SUCCESS);
销毁 UROM 域上下文
通过调用
doca_ctx_stop请求域上下文停止。通过销毁域上下文来清理资源。
/* Request domain context stop */doca_ctx_stop(doca_urom_domain_as_ctx(domain));/* Destroy domain context */doca_urom_domain_destroy(domain);
销毁 UROM 工作器上下文
通过调用
doca_ctx_stop并将销毁命令发布到服务上下文，请求工作器上下文停止。等待接收到销毁命令的完成通知。
将工作器状态更改为空闲。
清理资源。
/* Stop worker context */doca_ctx_stop(doca_urom_worker_as_ctx(worker));/* Progress till receiving a completion */do{ doca_pe_progress(pe); doca_ctx_get_state(doca_urom_worker_as_ctx(worker), &state); }while(state != DOCA_CTX_STATE_IDLE);/* Destroy worker context */doca_urom_worker_destroy(worker);
销毁 UROM 服务上下文
等待 UROM 工作器上下文命令完成。
一旦所有 UROM 工作器都已成功销毁，通过调用
doca_ctx_stop启动服务上下文停止。断开与 UROM 服务的连接。
执行资源清理。
/* Handling workers teardown requests*/do{ doca_pe_progress(pe); }while(!are_all_workers_exited);/* Stop service context */doca_ctx_stop(doca_urom_service_as_ctx(service));/* Destroy service context */doca_urom_service_destroy(service);
插件开发
在 DPU 上开发卸载插件
实现
struct urom_plugin_iface方法。open()方法初始化插件连接状态，并且可以创建端点以执行与其他进程/工作器的通信。staticdoca_error_t urom_worker_rdmo_open(struct urom_worker_ctx *ctx) { ucp_context_h ucp_context; ucp_worker_h ucp_worker; struct urom_worker_rdmo *rdmo_worker; rdmo_worker = calloc(1, sizeof(*rdmo_worker));if(rdmo_worker == NULL)returnDOCA_ERROR_NO_MEMORY; ctx->plugin_ctx = rdmo_worker;/* UCX transport layer initialization */. . ./* Create UCX worker Endpoint */ucp_worker_create(ucp_context, &worker_params, &ucp_worker); ucp_worker_get_address(ucp_worker, &rdmo_worker->ucp_data.worker_address, &rdmo_worker->ucp_data.ucp_addrlen);/* Resources initialization */rdmo_worker->clients = kh_init(client); rdmo_worker->eps = kh_init(ep);/* Init completions list, UROM worker checks completed requests by calling progress() method */ucs_list_head_init(&rdmo_worker->completed_reqs);returnDOCA_SUCCESS; }addr()方法返回在open()期间生成的插件端点的地址（如果存在）（例如，用于与其他 UROM 工作器通信的 UCX 端点）。worker_cmd()方法用于解析和开始处理插件的传入命令。staticdoca_error_t urom_worker_rdmo_worker_cmd(struct urom_worker_ctx *ctx, ucs_list_link_t *cmd_list) { struct urom_worker_rdmo_cmd *rdmo_cmd; struct urom_worker_cmd_desc *cmd_desc; struct urom_worker_rdmo *rdmo_worker = (struct urom_worker_rdmo *)ctx->plugin_ctx;while(!ucs_list_is_empty(cmd_list)) {/* Get new RDMO command from the list */cmd_desc = ucs_list_extract_head(cmd_list, struct urom_worker_cmd_desc, entry);/* Unpack and deserialize RDMO command */urom_worker_rdmo_cmd_unpack(&cmd_desc->worker_cmd, cmd_desc->worker_cmd.len, &cmd); rdmo_cmd = (struct urom_worker_rdmo_cmd *)cmd->plugin_cmd;/* Handle command according to it's type */switch(rdmo_cmd->type) {caseUROM_WORKER_CMD_RDMO_CLIENT_INIT:/* Handle RDMO client init command */status = urom_worker_rdmo_client_init_cmd(rdmo_worker, cmd_desc);break;caseUROM_WORKER_CMD_RDMO_RQ_CREATE:/* Handle RDMO RQ create command */status = urom_worker_rdmo_rq_create_cmd(rdmo_worker, cmd_desc);break; . . .default: DOCA_LOG_INFO("Invalid RDMO command type: %lu", rdmo_cmd->type); status = DOCA_ERROR_INVALID_VALUE;break; } free(cmd_desc);if(status != DOCA_SUCCESS)returnstatus; }returnstatus; }progress()方法用于为插件代码提供 CPU 时间，以推进异步任务。staticdoca_error_t urom_worker_rdmo_progress(struct urom_worker_ctx *ctx, ucs_list_link_t *notif_list) { struct urom_worker_notif_desc *nd; struct urom_worker_rdmo *rdmo_worker = (struct urom_worker_rdmo *)ctx->plugin_ctx;/* RDMO UCP worker progress */ucp_worker_progress(rdmo_worker->ucp_data.ucp_worker);/* Check if completion list is empty */if(ucs_list_is_empty(&rdmo_worker->completed_reqs))returnDOCA_ERROR_EMPTY;/* Pop completed commands from the list */while(!ucs_list_is_empty(&rdmo_worker->completed_reqs)) { nd = ucs_list_extract_head(&rdmo_worker->completed_reqs, struct urom_worker_notif_desc, entry); ucs_list_add_tail(notif_list, &nd->entry); }returnDOCA_SUCCESS; }notif_pack()方法用于序列化通知，然后再将其发送回主机。
实现并公开以下符号
doca_error_t urom_plugin_get_version(uint64_t *version);返回存储在
.so文件中的编译时常量值，用于验证主机和 DPU 插件版本是否兼容。doca_error_t urom_plugin_get_iface(struct urom_plugin_iface *iface);获取
urom_plugin_iface结构，其中包含插件实现的方法。
将用户插件编译为
.so文件，并将其放置在 UROM 服务可以访问的位置。有关更多详细信息，请参阅 NVIDIA DOCA UROM 服务指南中“插件发现和报告”部分。
创建插件主机任务
分配并初始化工作器命令任务。
通过任务命令填充有效负载缓冲区。
打包和序列化命令。
设置用户数据。
提交任务。
doca_error_t urom_rdmo_task_client_init(struct doca_urom_worker *worker_ctx, union doca_data cookie, uint32_t id,
void*addr, uint64_t addr_len, urom_rdmo_client_init_finished cb) { doca_error_t result; size_t pack_len =0; struct doca_buf *payload; struct doca_urom_worker_cmd_task *task; struct doca_rdmo_task_data *task_data; struct urom_worker_rdmo_cmd *rdmo_cmd;/* Allocate task */doca_urom_worker_cmd_task_allocate_init(worker_ctx, rdmo_id, &task);/* Get payload buffer */payload = doca_urom_worker_cmd_task_get_payload(task); doca_buf_get_data(payload, (void**)&rdmo_cmd); doca_buf_get_data_len(payload, &pack_len);/* Populate commands attributes */rdmo_cmd->type = UROM_WORKER_CMD_RDMO_CLIENT_INIT; rdmo_cmd->client_init.id = id; rdmo_cmd->client_init.addr = addr; rdmo_cmd->client_init.addr_len = addr_len;/* Pack and serialize the command */urom_worker_rdmo_cmd_pack(rdmo_cmd, &pack_len, (void*)rdmo_cmd);/* Update payload data size */doca_buf_set_data(payload, rdmo_cmd, pack_len);/* Set user data */task_data = (struct doca_rdmo_task_data *)doca_urom_worker_cmd_task_get_user_data(task); task_data->client_init_cb = cb; task_data->cookie = cookie;/* Set task plugin callback */doca_urom_worker_cmd_task_set_cb(task, urom_rdmo_client_init_completed);/* Submit task */doca_task_submit(doca_urom_worker_cmd_task_as_task(task));returnDOCA_SUCCESS; }
本节提供基于 BlueField 的 DOCA UROM 库示例实现。
这些示例说明了如何使用 DOCA UROM API 来执行以下操作
定义和创建用于卸载 HPC/AI 任务的 UROM 插件主机和 DPU 版本
构建主机应用程序，这些应用程序使用插件通过 DOCA UROM 服务和工作器在 BlueField 上执行作业
本节中描述的所有 DOCA 示例均受 BSD-3 软件许可协议管辖。
示例前提条件
示例 | 类型 | 先决条件 |
沙箱 | 插件 | 一个卸载 UCX 标签发送/接收 API 的插件 |
图表 | 插件 | 该插件使用 UCX 数据结构和 UCX 端点 |
UROM Ping Pong | 程序 | 该示例使用 Open MPI 包作为启动器框架来并行启动两个进程 |
运行示例
请参阅以下文档
Linux 版 DOCA 安装指南，了解如何安装 BlueField 相关软件的详细信息
DOCA 故障排除，以解决您在 DOCA 示例的安装、编译或执行过程中可能遇到的任何问题
构建给定示例
cd /opt/mellanox/doca/samples/doca_urom/<sample_name> meson /tmp/build ninja -C /tmp/build
信息二进制文件
doca_<sample_name>在/tmp/build/下创建。UROM 示例参数
示例
参数
描述
UROM 多工作器引导
-d, --device <IB 设备名称>IB 设备名称
UROM Ping Pong
-d, --device <IB 设备名称>IB 设备名称
-m, --message指定 ping pong 消息
有关每个示例的更多信息，请使用
-h选项/tmp/build/doca_<sample_name> -h
UROM 插件示例
DOCA UROM 插件示例有两个组件。第一个是主机组件，它与 UROM 主机程序链接。第二个是 DPU 组件，它被编译为 .so 文件，并在运行时由 DOCA UROM 服务（守护程序、工作器）加载。
构建给定插件
cd /opt/mellanox/doca/samples/doca_urom/plugins/worker_<plugin_name>
meson /tmp/build
ninja -C /tmp/build
二进制文件 worker_<sample_name>.so 在 /tmp/build/ 下创建。
图表
此插件提供了一个创建 UROM 插件接口的简单示例。它仅公开一个简单的环回命令，在命令中发送特定值，并期望从 UROM 工作器接收相同的值作为通知。
参考
/opt/mellanox/doca/samples/doca_urom/plugins/worker_graph/meson.build/opt/mellanox/doca/samples/doca_urom/plugins/worker_graph/urom_graph.h/opt/mellanox/doca/samples/doca_urom/plugins/worker_graph/worker_graph.c/opt/mellanox/doca/samples/doca_urom/plugins/worker_graph/worker_graph.h
沙箱
此插件提供了一组命令，用于使用卸载的 ping pong 通信操作。
参考
/opt/mellanox/doca/samples/doca_urom/plugins/worker_sandbox/meson.build/opt/mellanox/doca/samples/doca_urom/plugins/worker_sandbox/urom_sandbox.h/opt/mellanox/doca/samples/doca_urom/plugins/worker_sandbox/worker_sandbox.c/opt/mellanox/doca/samples/doca_urom/plugins/worker_sandbox/worker_sandbox.h
UROM 程序示例
DOCA UROM 程序示例只能在主机端运行，并且至少需要一个在 BlueField 上运行的 DOCA UROM 服务实例。
环境变量应设置为 DOCA_UROM_SERVICE_FILE，指向 UROM 服务文件的路径。
UROM 多工作器引导
此示例说明了如何正确初始化 DOCA UROM 接口，以及如何使用 API 在同一应用程序进程上衍生多个工作器。
该示例启动四个线程作为 UROM 工作器并发执行，主线程作为 UROM 服务运行。它根据工作器的 ID 将其分为两组，奇数工作器在一组，偶数工作器在另一组。
每个工作器都使用 Graph 插件执行数据环回命令，发送特定值，并期望在通知中接收相同的值。
示例逻辑包括
打开 DOCA IB 设备。
初始化所需的 DOCA 核心结构。
创建并启动 UROM 服务上下文。
通过附加生成的插件 ID 来启动 Graph 插件主机接口。
启动 4 个线程，并为每个线程执行以下操作
创建并启动 UROM 工作器上下文。
一旦工作器上下文切换到运行状态，发送环回 graph 命令，等待接收通知。
验证接收到的数据。
等待接收到中断信号。
主线程检查衍生工作器的待处理作业（4 个作业，每个线程一个）。
等待接收到中断信号。
主线程检查销毁工作器的待处理作业（4 个作业，每个线程一个）以退出。
清理并退出。
参考
/opt/mellanox/doca/samples/doca_urom/urom_multi_workers_bootstrap/urom_multi_workers_bootstrap_sample.c/opt/mellanox/doca/samples/doca_urom/urom_multi_workers_bootstrap/urom_multi_workers_bootstrap_main.c/opt/mellanox/doca/samples/doca_urom/urom_multi_workers_bootstrap/meson.build/opt/mellanox/doca/samples/doca_urom/urom_common.c/opt/mellanox/doca/samples/doca_urom/urom_common.h
UROM Ping Pong
此示例说明了如何正确初始化 DOCA UROM 接口，以及如何使用其 API 创建两个不同的工作器，并使用基于 Sandbox 插件的 UCX 在它们之间运行 ping pong。
该示例使用 Open MPI 启动两个不同的进程，一个进程作为服务器，第二个进程作为客户端，流程根据进程 rank 确定。
每个进程的示例逻辑包括
初始化 MPI。
打开 DOCA IB 设备。
创建并启动 UROM 服务上下文。
通过附加生成的插件 ID 来启动 Sandbox 插件主机接口。
创建并启动 UROM 工作器上下文。
创建并启动域上下文。
通过域上下文，示例进程交换工作器的详细信息，以便在 BlueField 端相互通信以进行 ping pong 流程。
在进程之间启动 ping pong 流程，每个进程都将其命令卸载到 BlueField 侧的工作器。
验证 ping pong 是否成功完成。
销毁域上下文。
销毁工作器上下文。
销毁服务上下文。
参考
/opt/mellanox/doca/samples/doca_urom/urom_ping_pong/urom_ping_pong_sample.c/opt/mellanox/doca/samples/doca_urom/urom_ping_pong/urom_ping_pong_main.c/opt/mellanox/doca/samples/doca_urom/urom_ping_pong/meson.build/opt/mellanox/doca/samples/doca_urom/urom_common.c/opt/mellanox/doca/samples/doca_urom/urom_common.h