/doca-urom

license: Apache-2.0
name: doca-urom
description: >
  Host-side DOCA UROM library (doca_urom_*): offload an HPC / UCX / MPI
  application's remote memory operations (puts, gets, atomics,
  collectives) from the host CPU onto a BlueField DPU. Trigger on "MPI
  all-reduce burning host CPU", "push UCX traffic onto the BlueField",
  "first doca_urom call returns NOT_PERMITTED", or "host library and DPU
  service look out of sync", even without naming DOCA UROM. An offload
  needs both halves: this host library and the UROM Service on the DPU
  (doca-urom-svc), which owns deploying that container. Covers creating
  UROM Service contexts (doca_urom_service_*) and Worker contexts
  (doca_urom_worker_*) that run plugins on the DPU, discovering plugins
  via doca_urom_service_get_plugins_list, progressing completions, and
  DOCA_ERROR_* from doca_urom_* calls. Route elsewhere for UROM Service
  deployment on the DPU side, MPI / UCX collective algorithm design, and
  RDMA / RoCE / IB substrate bring-up.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - urom
    - hpc
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) on a host paired with a BlueField DPU
  running the DOCA UROM Service at a compatible version. Reads the
  user's local install via `pkg-config doca-urom` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}; underlying RDMA
  fabric between host and BlueField must be healthy. The validation
  steps require a live DOCA install.

DOCA UROM

Examples

• **"Push UCX traffic onto the BlueField."** — this is in

scope. Stay on host-side `doca-urom`; do not deploy the DPU-side UROM Service here.

• **"First doca_urom call returns NOT_PERMITTED."** — check

host/service version alignment and the RDMA substrate first.

Instructions

Follow Loading order below. Open the tasks companion for configure / offload / debug. Open the capabilities companion for service vs worker contexts. Do not open every companion file.

**Where to start:** This skill assumes DOCA is installed on both host and BlueField, the DOCA UROM Service is deployed and running on the BlueField, and the user is doing **hands-on UROM work from the host side** — using `doca-urom` from an HPC / UCX / MPI stack to enqueue remote memory operations (puts, gets, atomics, active messages, collectives) the DPU executes on the host's behalf. Open the tasks companion to *do* something (configure / build / modify / run / test / debug); open the capabilities companion for *what the host-side UROM API expresses* on this version + BlueField + UROM Service version. If DOCA is not installed, route to `doca-setup/SKILL.md` first; for the **DPU-side UROM Service** itself (deployment, container, lifecycle), that is a DIFFERENT artifact — route via `doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`) to the public *DOCA UROM Service* guide. This skill is the **host-side library**; the UROM Service is the **DPU-side executor**; they are a paired contract.

**How to use this skill.** Read this file, then search the companion file for the `## <name>` heading the question needs and read that whole section. Answer completely from it, quoting only its symbols and commands. Do not browse docs; use the entry points in `doca-public-knowledge-map`. For out-of-scope requests, name the skill that owns them and stop.

Example questions this skill answers well

The CLASSES of UROM questions this skill answers, each with one worked example. The *class* is the load-bearing piece; the worked example is one instance.

• **"How do I offload my MPI / UCX remote memory operations from

the host CPU to the BlueField?"** — worked example: *"my MPI all-reduce burns host CPU cycles I'd rather use for compute — how do I push that onto the BlueField via UROM?"*. Answered by the paired-contract model in the capabilities companion

• the host-side bring-up workflow in

the tasks companion.

• **"Is the DOCA UROM Service even running on my BlueField, and

why does that matter before I write `doca_urom_*` code?"** — worked example: *"my first `doca_urom_*` call returns `DOCA_ERROR_NOT_PERMITTED` on an otherwise-healthy host"*. Answered by the env-precondition matrix in the capabilities companion

• the service-deployed check in

the tasks companion step 1, which routes service-side env questions to `doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`).

• **"Is this UROM operation type / atomic / collective supported

on my device + DOCA install + UROM Service version?"** — worked example: *"does my BlueField support remote atomic Fetch-and-Add for an MPI window?"*. Answered by the plugin-discovery rule (`doca_urom_service_get_plugins_list` on a started Service — UROM operations are plugin-defined Command tasks, so the plugins list is the capability surface) in the capabilities companion

• the discovery step in

the tasks companion.

• **"How does `doca-urom` relate to `doca-rdma` — am I replacing

it, layering on top, or something else?"** — worked example: *"I already have raw `doca-rdma` working; should I rewrite to use UROM?"*. Answered by the path-selection rule in the capabilities companion (UROM rides the RDMA substrate but adds the DPU-offload contract; it is the right tool only when host CPU is the bottleneck — simple point-to-point cases stay on `doca-rdma`).

• **"Is this UROM API on my installed DOCA version?"** — worked

example: *"is the collective-ops plugin discoverable via `doca_urom_service_get_plugins_list` on DOCA 3.x"*. Answered by the version-compatibility overlay in the capabilities companion, which cross-links the canonical detection chain in `doca-version/SKILL.md` and adds the *host library + DPU service versions must match* overlay.

• **"