/doca-urom

license: Apache-2.0
name: doca-urom
description: >
  Use this skill when the user is doing hands-on DOCA UROM library work
  from the host side — wiring doca-urom under an HPC / UCX / MPI stack
  to OFFLOAD remote memory operations (puts, gets, atomics, collectives)
  onto a BlueField DPU, creating a UROM Service context
  (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, or
  debugging DOCA_ERROR_* from a doca_urom_* call. Trigger even without
  "DOCA UROM": "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". Route elsewhere for
  UROM Service deployment on the DPU side, MPI / UCX collective
  algorithm design, and RDMA / RoCE / IB substrate bring-up.
metadata:
  kind: library
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.

DOCA UROM

**Where to start:** This skill assumes DOCA is already installed on both the host and the BlueField, the DOCA UROM Service is deployed and running on the BlueField side, and the user is doing **hands-on UROM work from the host side** — i.e. using `doca-urom` from an HPC / UCX / MPI stack on the host to enqueue remote memory operations (puts, gets, atomics, active messages, collective primitives) that the BlueField DPU will execute on the host's behalf. Open [`TASKS.md`](TASKS.md) if the user wants to *do* something (configure / build / modify / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can the host-side UROM API express* on this version + this BlueField + this UROM Service version. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first; if the user is asking about the **DPU-side UROM Service** itself (deployment, container, operation lifecycle on the DPU side), 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**, and they are a paired contract.

Example questions this skill answers well

The CLASSES of UROM questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance.

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

the host CPU to the BlueField DPU?"** — worked example: *"my MPI all-reduce is consuming host CPU cycles I'd rather use for compute — how do I push that work onto the BlueField via UROM?"*. Answered by the host-library-plus-DPU-service paired-contract model in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the host-side bring-up workflow in

[`TASKS.md ## configure`](TASKS.md#configure).

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

why does that matter before I write any `doca_urom_*` code?"** — worked example: *"my first `doca_urom_*` call returns `DOCA_ERROR_NOT_PERMITTED` on a host where DOCA is otherwise healthy"*. Answered by the env-precondition matrix in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the service-deployed-and-running check in

[`TASKS.md ## configure`](TASKS.md#configure) 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 + this DOCA install + this 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 supported-plugins list is the capability surface) in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the discovery step in

[`TASKS.md ## configure`](TASKS.md#configure).

• **"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, or is that the wrong tool?"*. Answered by the path-selection rule in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) (UROM uses the RDMA transport substrate underneath but adds the DPU-offload contract on top, and is the right tool only when host CPU is the bottleneck due to communication overhead — small / 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 [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which cross-links the canonical detection chain in [`doca-version`](../../doca-version/SKILL.md) and adds the UROM-specific *host library and DPU service versions must match* overlay.

• **"What does this `DOCA_ERROR_*` from a `doca_urom_*` call

mean and which layer caused it?"** — worked example: *"`DOCA_ERROR_NOT_PERMITTED` on the first `doca_urom_*` enqueue after `doca_ctx_start()` succeeded"*. Answered by the URO