/doca-urom-svc

license: Apache-2.0
name: doca-urom-svc
description: >
  Operate the DOCA UROM Service container on BlueField Arm for remote
  memory operations (puts, gets, atomics, collectives) enqueued by a
  paired host using `doca-urom`: pull the NGC image, choose the UCX
  component, size queues, configure Comch pairing, and align host and
  service versions. SECURITY: the service has no standalone access
  control; Comch pairing and RDMA permissions are the boundary. Pair
  only intended hosts, expose least-privilege memory regions, and
  verify both views before start. Trigger for slow UCX collectives,
  unexpected NOT_PERMITTED, or missing completions. Do not use for
  host application code, MPI/UCX integration design, or DOCA install.
metadata:
  kind: service
compatibility: >
  BlueField-Arm-only DOCA service container; pulled from NVIDIA
  NGC and started under the BlueField OS container runtime.
  Host-side install is irrelevant — the host's relationship to
  this service is via the paired `doca-urom` library over a
  `doca-rdma` substrate.

DOCA UROM Service

**Where to start:** This skill is for *operating the DOCA UROM Service container* on the BlueField Arm side. It is *not* for *linking against* a library, and it is *not* the host-side enqueue surface. If the user wants to *deploy* or *run* the service container, open [`TASKS.md`](TASKS.md) and start at [`## configure`](TASKS.md#configure). If the question is *what shape of service is DOCA UROM Service, what does it execute, and how does it pair with the host-side library*, start at [`CAPABILITIES.md`](CAPABILITIES.md). If DOCA is not installed on the BlueField yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first. If the user's real question is about *writing host-side code that enqueues remote memory operations through the paired API*, the right skill is [`doca-urom`](../../libs/doca-urom/SKILL.md) — the host-side library; this service is the DPU-side executor that library offloads to.

Example questions this skill answers well

The CLASSES of DOCA UROM Service questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• **"Is DOCA UROM Service the right thing to deploy on my

BlueField, or do I just need the host library?"** — worked example: *"my MPI cluster's host nodes link against `doca-urom`; what runs on the BlueField side and why must it also be there?"*. Answered by the publisher / executor paired-contract model in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the deploy-this-when path-selection rule in

[`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the env-prep checklist in

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

• **"Which library / service version pair am I supposed to

run together?"** — worked example: *"the host fleet upgraded to a newer `doca-urom`; do I have to upgrade the service containers on every BlueField, or is the pairing flexible?"*. Answered by the version-contract overlay in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility)

• the paired-version step in

[`TASKS.md ## configure`](TASKS.md#configure) + [`doca-version`](../../doca-version/SKILL.md) as the canonical body.

• **"What does the service configure — UCX components,

collectives, queue depths, how the host pairs over Comch?"** — worked example: *"my upstream stack wants to offload all-reduce collectives; how do I tell the service to expose that collective family and how does the host pair to it over DOCA Comch?"*. Answered by the configuration-axes table in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the config-authoring step in

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

• **"Host's `doca-urom` calls fail with `NOT_PERMITTED` even

though `doca_dev` access is fine — is this the service?"** — worked example: *"first enqueue from host returns `DOCA_ERROR_NOT_PERMITTED` after a clean `doca_ctx_start()`"*. Answered by the Comch-pairing / RDMA-permissions layer in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)

• the layered ladder in

[`TASKS.md ## debug`](TASKS.md#debug), which surfaces *"is the DOCA Comch endpoint pair correctly established and is the underlying RDMA permission stack happy"* BEFORE blaming a service-side authz layer (no such layer exists in the shipped binary — `NOT_PERMITTED` here is a Comch / RDMA signal, not a UROM-service authz signal).

• **"Operations enqueue but never complete — service or

substrate?"** — worked example: *"host enqueue succeeds, the progress engine never sees the completion, what layer is hung"*. Answered by the service-vs-substrate split in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)

• the layered ladder in

[`TASKS.md ## debug`](TASKS.md#debug), which separates *service queue full / handler stuck* from *underlying RDMA transport down* before recommending a fix on either side.

• **"Performance with offload is worse than the host-CPU

baseline — is the service the bottleneck?"** — worked example: *"we deployed the service, the workload runs, but collectives are slower than when the host CPU posted them itself"*. Answered by the offload-isn't-free rule in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the smoke-before-scale step in

[`TASKS.md ## test`](TASKS.md#test), which surfaces *the workload's pattern may not actually benefit from DPU offload* as a legitimate diagnosis, not a service bug.

Audience

This skill serves **external operators and platform teams who deploy and operate the DOCA UROM Service container** on BlueField to receive and execute the remote memory operations HPC / UCX / MPI workloads on the host enqueue through `doca-urom`. Concretely: people running the service