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.
- "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 enqueue after
doca_ctx_start() succeeded". Answered by the UROM overlay on
the cross-library taxonomy in
the capabilities companion
- the layered ladder in
the tasks companion that escalates to
doca-debug/SKILL.md.
Audience
This skill serves external developers building HPC / UCX / MPI
applications that consume the DOCA UROM library from the host
side — code calling doca_urom_* (directly in C / C++, through
FFI / bindings, or through a UCX-based stack such as OpenMPI /
MPICH wired to use UROM as a transport) to push remote memory
operations onto the BlueField instead of the host CPU. It is not
for NVIDIA developers contributing to DOCA UROM, nor the place to
learn how to deploy / operate the UROM Service on the DPU side
— that goes through the public DOCA UROM Service guide via
doca-public-knowledge-map ## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services).
Language scope. DOCA UROM ships as a host-side C library
(pkg-config module doca-urom); shipped samples under
/opt/mellanox/doca/samples/doca_urom/ are C. C / C++ consumers —
including UCX-based stacks wrapping the library — are the
canonical case the tasks companion assumes. Other-language
consumers (Rust, Go, Python, …) reach the same *.so through FFI;
the skill keeps its lifecycle, capability-discovery,
error-taxonomy, and RDMA-substrate guidance language-neutral and
routes to the public C ABI as the authoritative surface.
When to load this skill
Load this skill when the user is doing hands-on DOCA UROM work
from the host side, in any language. Concretely:
- Initializing a UROM Service context (
doca_urom_service_*) on
a doca_dev mapping to the target BlueField, creating Worker
contexts (doca_urom_worker_*) attached to it, and confirming
the matching DPU-side UROM Service is reachable before the
first enqueue.
- Enqueueing remote memory operations (puts, gets, atomics,
active messages, collectives) through
doca_urom_* and
progressing the DOCA progress engine for completions.
- Calling
doca_urom_service_get_plugins_list on a started
Service to discover which plugins — and therefore which
operation types / atomics / collectives, since these are
plugin-defined — this device + DOCA install + UROM Service
version supports.
- Applying the UROM lifecycle, capability-discovery, and error
rules to a UCX-based HPC stack (OpenMPI, MPICH, custom UCX
consumer) already wired to use UROM. Designing the UCX
transport integration itself remains upstream-stack work.
- Debugging a
DOCA_ERROR_* from doca_urom_* — disambiguating
DPU-side UROM Service unreachable vs operation type
unsupported on this device vs plain doca_dev access denied
vs underlying RDMA transport failure.
- Designing non-C bindings (Rust, Go, Python, …) that wrap the
UROM C ABI and must honor the same lifecycle and error rules.
Do not load this skill for general DOCA orientation, DOCA
install, deployment / operation of the DPU-side UROM Service (a
separate artifact with its own public guide via
doca-public-knowledge-map ## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services)),
or non-UROM library questions. For those, use
doca-public-knowledge-map/SKILL.md.
What this skill provides
This is a thin loader. The body keeps only the orientation
needed to pick the right next file. The substantive
UROM-specific material lives in two companion files:
- the capabilities companion — what the host-side UROM API expresses on
this version + BlueField + UROM Service version: the
paired-contract model (host enqueues; DPU service executes); the
two context types (
doca_urom_service — one per BlueField, bound
to its doca_dev — and attached doca_urom_worker contexts);
the enqueue-side operation surface (puts, gets, atomics, active
messages, collectives) delivered as plugin-defined Worker Command
tasks, named generically because exact symbol shapes are
plugin- and install-bound; the plugin-discovery surface
(doca_urom_service_get_plugins_list); the UROM error taxonomy
mapped onto DOCA_ERROR_*; the observability surface
(completion events, capability snapshots, RDMA counters); and the
safety policy gating env preconditions (UROM Service deployed on
the DPU; host library + DPU service versions agree; RDMA-capable
BlueField + DOCA install).
- the tasks companion — step-by-step workflows for the six in-scope UROM
verbs:
configure, build, modify, run, test,
debug. Plus a Deferred task verbs block that points
out-of-scope questions at the right next skill.
The skill assumes a host + BlueField pair where DOCA is installed,
the UROM Service is deployed and running on the BlueField, the RDMA
transport between them is healthy, and the user has a sketch of the
HPC / UCX / MPI stack to offload. It does not cover installing
DOCA, deploying the UROM Service container, or bringing up
RDMA / RoCE / IB transport — those go through
doca-setup/SKILL.md, the public DOCA UROM
Service guide, and doca-rdma/SKILL.md.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or templates
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:
- Pre-written DOCA UROM application source code, in any
language. The verified UROM source is the shipped C samples at
/opt/mellanox/doca/samples/doca_urom/. The agent routes the
user there and prescribes a minimum-diff modification via the
modify-a-sample workflow in
doca-programming-guide/SKILL.md,
layered with the UROM overrides in the tasks companion.
- An MPI / UCX algorithm or collective implementation. This
library offloads remote memory operations; picking which
puts / gets / atomics / collectives to issue for a given MPI
primitive is the user's HPC stack or domain expertise. Refuse
to invent collective algorithms; route "what algorithm should
my all-reduce use" to upstream MPI / UCX docs — that is a
stack-design question, not a UROM API question.
- Standalone build manifests (
meson.build, CMakeLists.txt,
Cargo.toml, …) parked inside the skill. The agent constructs
the manifest in the user's project against the installed DOCA,
where pkg-config --modversion doca-urom is the source of truth.
- A
samples/, bindings/, or reference/ subtree of any
kind. A mock artifact labeled "reference" reads as buildable and
misleads.
- The DOCA UROM Service surface. That service is a separate
artifact with its own public guide; routing lives in
doca-public-knowledge-map ## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services).
Conflating the library (host-side enqueue) with the service
(DPU-side executor) is the most common UROM first-app design
error.
Loading order
- Read this skill first to confirm the user's question is
in scope (host-side library work; not DPU-side service
deployment, and not MPI / UCX algorithm design).
- For the UROM capability matrix, the paired-contract model
(host library + DPU service), the Service + Worker context
model, the enqueue-side operation surface, the
plugin-discovery rule, the env-precondition policy, the
error taxonomy, the observability surface, and the safety
policy, see the capabilities companion.
- For step-by-step workflows — configure, build, modify,
run, test, debug — see the tasks companion.
Both companion files cross-link to each other, to
doca-version/SKILL.md for canonical
version rules (with the UROM overlay that host library and DPU
service versions must match), to
doca-rdma/SKILL.md for the underlying RDMA
substrate, and to
doca-public-knowledge-map/SKILL.md
whenever the right answer is "look it up in the public UROM
library / Service guide or the on-disk install layout".
Related skills
doca-public-knowledge-map/SKILL.md —
the routing table for every public DOCA documentation source
and the on-disk layout of an installed DOCA package. The
DOCA UROM library public guide is at
https://docs.nvidia.com/doca/sdk/DOCA-UROM/index.html; the
DOCA UROM Service is a different artifact documented
separately under the DOCA services section of that map.
doca-rdma/SKILL.md — the underlying RDMA
transport substrate the BlueField uses to move bytes once UROM
offloads an operation. UROM does NOT replace RDMA; it adds the
DPU-offload contract on top. For simple point-to-point RDMA
where host CPU is not the bottleneck, use doca-rdma directly —
UROM's service-side contract is not worth its overhead there.
doca-setup/SKILL.md — env preparation,
install verification, BlueField setup, and the no install yet
path via the public NGC DOCA container. This skill assumes its
preconditions hold AND the DPU-side UROM Service is deployed and
running.
doca-version/SKILL.md — canonical
DOCA version-handling rules. This skill's ## Version compatibility cross-links the four-way match rule and adds the
host library + DPU service must agree on version overlay.
doca-structured-tools-contract/SKILL.md —
the bundle's structured-tools precedence rule (detect /
prefer / fall back / report). The Command appendix in
the tasks companion honors this contract.
doca-programming-guide/SKILL.md —
general DOCA programming patterns shared by every library:
pkg-config + meson build, modify-a-shipped-sample first-app,
Core-context lifecycle, the cross-library DOCA_ERROR_*
taxonomy, and the debug order. This skill layers UROM specifics
on top.
doca-debug/SKILL.md — the cross-cutting
debug ladder (install / version / build / link / runtime /
program / driver). UROM-specific debug (UROM Service not
reachable, host library + DPU service version skew, RDMA
transport failure underneath, operation type unsupported on
this device + firmware + service version) overlays on top.
The DOCA UROM Service running on the DPU side is deliberately
not in scope — a separate artifact with its own public guide
via
doca-public-knowledge-map ## DOCA services (doca-public-knowledge-map/SKILL.md#doca-services).
Conflating the library and the service is the single most common
UROM first-app design error: surface the split explicitly whenever
a question straddles the two.
1---2license: Apache-2.03name: doca-urom4description: >5 Host-side DOCA UROM library (doca_urom_*): offload an HPC / UCX / MPI6 application's remote memory operations (puts, gets, atomics,7 collectives) from the host CPU onto a BlueField DPU. Trigger on "MPI8 all-reduce burning host CPU", "push UCX traffic onto the BlueField",9 "first doca_urom call returns NOT_PERMITTED", or "host library and DPU10 service look out of sync", even without naming DOCA UROM. An offload11 needs both halves: this host library and the UROM Service on the DPU12 (doca-urom-svc), which owns deploying that container. Covers creating13 UROM Service contexts (doca_urom_service_*) and Worker contexts14 (doca_urom_worker_*) that run plugins on the DPU, discovering plugins15 via doca_urom_service_get_plugins_list, progressing completions, and16 DOCA_ERROR_* from doca_urom_* calls. Route elsewhere for UROM Service17 deployment on the DPU side, MPI / UCX collective algorithm design, and18 RDMA / RoCE / IB substrate bring-up.19metadata:20 source: https://skillmd.com/skills/nvidia/doca-urom21 author: NVIDIA <doca-feedback@nvidia.com>22 kind: library23 doca_version: "3.5"24 tags:25 - doca26 - urom27 - hpc28compatibility: >29 Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu30 22.04/24.04 or RHEL/SLES) on a host paired with a BlueField DPU31 running the DOCA UROM Service at a compatible version. Reads the32 user's local install via `pkg-config doca-urom` and inspects33 /opt/mellanox/doca/{lib,include,samples,applications}; underlying RDMA34 fabric between host and BlueField must be healthy. The validation35 steps require a live DOCA install.36---3738# DOCA UROM3940## Examples4142- **"Push UCX traffic onto the BlueField."** — this is in43 scope. Stay on host-side `doca-urom`; do not deploy the44 DPU-side UROM Service here.45- **"First doca_urom call returns NOT_PERMITTED."** — check46 host/service version alignment and the RDMA substrate first.4748## Instructions4950Follow Loading order below. Open the tasks companion for configure /51offload / debug. Open the capabilities companion for service vs52worker contexts. Do not open every companion file.5354**Where to start:** This skill assumes DOCA is installed on both55host and BlueField, the DOCA UROM Service is deployed and running56on the BlueField, and the user is doing **hands-on UROM work from57the host side** — using `doca-urom` from an HPC / UCX / MPI stack58to enqueue remote memory operations (puts, gets, atomics, active59messages, collectives) the DPU executes on the host's behalf. Open60the tasks companion to *do* something (configure / build / modify /61run / test / debug); open the capabilities companion for *what the62host-side UROM API expresses* on this version + BlueField + UROM63Service version. If DOCA is not installed, route to64`doca-setup/SKILL.md` first; for the **DPU-side65UROM Service** itself (deployment, container, lifecycle), that is a66DIFFERENT artifact — route via67`doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`)68to the public *DOCA UROM Service* guide. This skill is the69**host-side library**; the UROM Service is the **DPU-side70executor**; they are a paired contract.7172**How to use this skill.** Read this file, then search the companion file73for the `## <name>` heading the question needs and read that whole section.74Answer completely from it, quoting only its symbols and commands. Do not75browse docs; use the entry points in `doca-public-knowledge-map`. For76out-of-scope requests, name the skill that owns them and stop.7778## Example questions this skill answers well7980The CLASSES of UROM questions this skill answers, each with one81worked example. The *class* is the load-bearing piece; the worked82example is one instance.8384- **"How do I offload my MPI / UCX remote memory operations from85 the host CPU to the BlueField?"** — worked example: *"my MPI86 all-reduce burns host CPU cycles I'd rather use for compute —87 how do I push that onto the BlueField via UROM?"*. Answered by88 the paired-contract model in89 the capabilities companion90 + the host-side bring-up workflow in91 the tasks companion.92- **"Is the DOCA UROM Service even running on my BlueField, and93 why does that matter before I write `doca_urom_*` code?"** —94 worked example: *"my first `doca_urom_*` call returns95 `DOCA_ERROR_NOT_PERMITTED` on an otherwise-healthy host"*.96 Answered by the env-precondition matrix in97 the capabilities companion98 + the service-deployed check in99 the tasks companion step 1, which100 routes service-side env questions to101 `doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`).102- **"Is this UROM operation type / atomic / collective supported103 on my device + DOCA install + UROM Service version?"** — worked104 example: *"does my BlueField support remote atomic Fetch-and-Add105 for an MPI window?"*. Answered by the plugin-discovery rule106 (`doca_urom_service_get_plugins_list` on a started Service —107 UROM operations are plugin-defined Command tasks, so the108 plugins list is the capability surface) in109 the capabilities companion110 + the discovery step in111 the tasks companion.112- **"How does `doca-urom` relate to `doca-rdma` — am I replacing113 it, layering on top, or something else?"** — worked example:114 *"I already have raw `doca-rdma` working; should I rewrite to115 use UROM?"*. Answered by the path-selection rule in116 the capabilities companion117 (UROM rides the RDMA substrate but adds the DPU-offload118 contract; it is the right tool only when host CPU is the119 bottleneck — simple point-to-point cases stay on `doca-rdma`).120- **"Is this UROM API on my installed DOCA version?"** — worked121 example: *"is the collective-ops plugin discoverable via122 `doca_urom_service_get_plugins_list` on DOCA 3.x"*. Answered by123 the version-compatibility overlay in124 the capabilities companion,125 which cross-links the canonical detection chain in126 `doca-version/SKILL.md` and adds the127 *host library + DPU service versions must match* overlay.128- **"What does this `DOCA_ERROR_*` from a `doca_urom_*` call129 mean and which layer caused it?"** — worked example:130 *"`DOCA_ERROR_NOT_PERMITTED` on the first enqueue after131 `doca_ctx_start()` succeeded"*. Answered by the UROM overlay on132 the cross-library taxonomy in133 the capabilities companion134 + the layered ladder in135 the tasks companion that escalates to136 `doca-debug/SKILL.md`.137138## Audience139140This skill serves **external developers building HPC / UCX / MPI141applications that consume the DOCA UROM library from the host142side** — code calling `doca_urom_*` (directly in C / C++, through143FFI / bindings, or through a UCX-based stack such as OpenMPI /144MPICH wired to use UROM as a transport) to push remote memory145operations onto the BlueField instead of the host CPU. It is *not*146for NVIDIA developers contributing to DOCA UROM, nor the place to147learn how to **deploy / operate the UROM Service** on the DPU side148— that goes through the public *DOCA UROM Service* guide via149`doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`).150151**Language scope.** DOCA UROM ships as a host-side C library152(`pkg-config` module `doca-urom`); shipped samples under153`/opt/mellanox/doca/samples/doca_urom/` are C. C / C++ consumers —154including UCX-based stacks wrapping the library — are the155canonical case the tasks companion assumes. Other-language156consumers (Rust, Go, Python, …) reach the same `*.so` through FFI;157the skill keeps its lifecycle, capability-discovery,158error-taxonomy, and RDMA-substrate guidance language-neutral and159routes to the public C ABI as the authoritative surface.160161## When to load this skill162163Load this skill when the user is doing hands-on DOCA UROM work164**from the host side**, in any language. Concretely:165166- Initializing a UROM Service context (`doca_urom_service_*`) on167 a `doca_dev` mapping to the target BlueField, creating Worker168 contexts (`doca_urom_worker_*`) attached to it, and confirming169 the matching DPU-side UROM Service is reachable before the170 first enqueue.171- Enqueueing remote memory operations (puts, gets, atomics,172 active messages, collectives) through `doca_urom_*` and173 progressing the DOCA progress engine for completions.174- Calling `doca_urom_service_get_plugins_list` on a started175 Service to discover which plugins — and therefore which176 operation types / atomics / collectives, since these are177 plugin-defined — this device + DOCA install + UROM Service178 version supports.179- Applying the UROM lifecycle, capability-discovery, and error180 rules to a UCX-based HPC stack (OpenMPI, MPICH, custom UCX181 consumer) already wired to use UROM. Designing the UCX182 transport integration itself remains upstream-stack work.183- Debugging a `DOCA_ERROR_*` from `doca_urom_*` — disambiguating184 *DPU-side UROM Service unreachable* vs *operation type185 unsupported on this device* vs *plain `doca_dev` access denied*186 vs *underlying RDMA transport failure*.187- Designing non-C bindings (Rust, Go, Python, …) that wrap the188 UROM C ABI and must honor the same lifecycle and error rules.189190Do **not** load this skill for general DOCA orientation, DOCA191install, deployment / operation of the DPU-side UROM Service (a192separate artifact with its own public guide via193`doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`)),194or non-UROM library questions. For those, use195`doca-public-knowledge-map/SKILL.md`.196197## What this skill provides198199This is a **thin loader**. The body keeps only the orientation200needed to pick the right next file. The substantive201UROM-specific material lives in two companion files:202203- the capabilities companion — what the host-side UROM API expresses on204 this version + BlueField + UROM Service version: the205 paired-contract model (host enqueues; DPU service executes); the206 two context types (`doca_urom_service` — one per BlueField, bound207 to its `doca_dev` — and attached `doca_urom_worker` contexts);208 the enqueue-side operation surface (puts, gets, atomics, active209 messages, collectives) delivered as plugin-defined Worker Command210 tasks, named generically because exact symbol shapes are211 plugin- and install-bound; the plugin-discovery surface212 (`doca_urom_service_get_plugins_list`); the UROM error taxonomy213 mapped onto `DOCA_ERROR_*`; the observability surface214 (completion events, capability snapshots, RDMA counters); and the215 safety policy gating env preconditions (UROM Service deployed on216 the DPU; host library + DPU service versions agree; RDMA-capable217 BlueField + DOCA install).218- the tasks companion — step-by-step workflows for the six in-scope UROM219 verbs: `configure`, `build`, `modify`, `run`, `test`,220 `debug`. Plus a `Deferred task verbs` block that points221 out-of-scope questions at the right next skill.222223The skill assumes a host + BlueField pair where DOCA is installed,224the UROM Service is deployed and running on the BlueField, the RDMA225transport between them is healthy, and the user has a sketch of the226HPC / UCX / MPI stack to offload. It does not cover installing227DOCA, deploying the UROM Service container, or bringing up228RDMA / RoCE / IB transport — those go through229`doca-setup/SKILL.md`, the public *DOCA UROM230Service* guide, and `doca-rdma/SKILL.md`.231232## What this skill deliberately does not ship233234This skill is **agent guidance**, not a samples or templates235bundle. To keep the boundary clean, it deliberately does not236contain — and pull requests should not add:237238- **Pre-written DOCA UROM application source code, in any239 language.** The verified UROM source is the shipped C samples at240 `/opt/mellanox/doca/samples/doca_urom/`. The agent routes the241 user there and prescribes a minimum-diff modification via the242 modify-a-sample workflow in243 `doca-programming-guide/SKILL.md`,244 layered with the UROM overrides in the tasks companion.245- **An MPI / UCX algorithm or collective implementation.** This246 library *offloads* remote memory operations; picking which247 puts / gets / atomics / collectives to issue for a given MPI248 primitive is the user's HPC stack or domain expertise. Refuse249 to invent collective algorithms; route *"what algorithm should250 my all-reduce use"* to upstream MPI / UCX docs — that is a251 stack-design question, not a UROM API question.252- **Standalone build manifests** (`meson.build`, `CMakeLists.txt`,253 `Cargo.toml`, …) parked inside the skill. The agent constructs254 the manifest *in the user's project* against the installed DOCA,255 where `pkg-config --modversion doca-urom` is the source of truth.256- **A `samples/`, `bindings/`, or `reference/` subtree** of any257 kind. A mock artifact labeled "reference" reads as buildable and258 misleads.259- **The DOCA UROM Service surface.** That service is a *separate260 artifact* with its own public guide; routing lives in261 `doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`).262 Conflating the library (host-side enqueue) with the service263 (DPU-side executor) is the most common UROM first-app design264 error.265266## Loading order2672681. Read this skill first to confirm the user's question is269 in scope (host-side library work; not DPU-side service270 deployment, and not MPI / UCX algorithm design).2712. **For the UROM capability matrix, the paired-contract model272 (host library + DPU service), the Service + Worker context273 model, the enqueue-side operation surface, the274 plugin-discovery rule, the env-precondition policy, the275 error taxonomy, the observability surface, and the safety276 policy, see the capabilities companion.**2773. **For step-by-step workflows — configure, build, modify,278 run, test, debug — see the tasks companion.**279280Both companion files cross-link to each other, to281`doca-version/SKILL.md` for canonical282version rules (with the UROM overlay that host library and DPU283service versions must match), to284`doca-rdma/SKILL.md` for the underlying RDMA285substrate, and to286`doca-public-knowledge-map/SKILL.md`287whenever the right answer is "look it up in the public UROM288library / Service guide or the on-disk install layout".289290## Related skills291292- `doca-public-knowledge-map/SKILL.md` —293 the routing table for every public DOCA documentation source294 and the on-disk layout of an installed DOCA package. The295 DOCA UROM library public guide is at296 <https://docs.nvidia.com/doca/sdk/DOCA-UROM/index.html>; the297 DOCA UROM Service is a *different artifact* documented298 separately under the *DOCA services* section of that map.299- `doca-rdma/SKILL.md` — the underlying RDMA300 transport substrate the BlueField uses to move bytes once UROM301 offloads an operation. UROM does NOT replace RDMA; it adds the302 DPU-offload contract on top. For simple point-to-point RDMA303 where host CPU is not the bottleneck, use `doca-rdma` directly —304 UROM's service-side contract is not worth its overhead there.305- `doca-setup/SKILL.md` — env preparation,306 install verification, BlueField setup, and the *no install yet*307 path via the public NGC DOCA container. This skill assumes its308 preconditions hold AND the DPU-side UROM Service is deployed and309 running.310- `doca-version/SKILL.md` — canonical311 DOCA version-handling rules. This skill's `## Version312 compatibility` cross-links the four-way match rule and adds the313 *host library + DPU service must agree on version* overlay.314- `doca-structured-tools-contract/SKILL.md` —315 the bundle's structured-tools precedence rule (detect /316 prefer / fall back / report). The Command appendix in317 the tasks companion honors this contract.318- `doca-programming-guide/SKILL.md` —319 general DOCA programming patterns shared by every library:320 `pkg-config` + meson build, modify-a-shipped-sample first-app,321 Core-context lifecycle, the cross-library `DOCA_ERROR_*`322 taxonomy, and the debug order. This skill layers UROM specifics323 on top.324- `doca-debug/SKILL.md` — the cross-cutting325 debug ladder (install / version / build / link / runtime /326 program / driver). UROM-specific debug (UROM Service not327 reachable, host library + DPU service version skew, RDMA328 transport failure underneath, operation type unsupported on329 this device + firmware + service version) overlays on top.330331The **DOCA UROM Service** running on the DPU side is deliberately332**not in scope** — a separate artifact with its own public guide333via334`doca-public-knowledge-map ## DOCA services` (`doca-public-knowledge-map/SKILL.md#doca-services`).335Conflating the library and the service is the single most common336UROM first-app design error: surface the split explicitly whenever337a question straddles the two.