/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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: service
  doca_version: "3.5"
  tags:
    - doca
    - urom
    - 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. The validation steps
  require a live DOCA install.

DOCA UROM Service

**Scope first.** This skill operates the DPU-side service container. Writing the host-side application code that submits offloaded operations (from an MPI or UCX job, for example) is not this skill: route it to `doca-urom/SKILL.md`, the host library, and come back here only for the service it pairs with.

Examples

• **"Slow UCX collectives on a BlueField pair."** — this is

in scope for the DPU-side service container; host app code belongs to the `doca-urom` library skill.

• **"Unexpected NOT_PERMITTED after start."** — verify Comch

pairing and least-privilege memory regions before widening exposure.

Instructions

Follow Loading order below. Open the tasks companion for configure / pair / debug. Open the capabilities companion for queues and UCX components.

**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, start at the tasks companion `## 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 the capabilities companion. If DOCA is not installed on the BlueField yet, route to `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/SKILL.md` — the host-side library; this service is the DPU-side executor that library offloads to.

**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 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 the capabilities companion

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

the capabilities companion

• the env-prep checklist in

the tasks companion.

• **"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 the capabilities companion

• the paired-version step in

the tasks companion + `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 the capabilities companion

• the config-authoring step in

the tasks companion.

• **"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 the capabilities companion

• the layered ladder in

the tasks companion, 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 the capabilities companion

• the layered ladder in

the tasks companion, 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