---

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 if the user wants to do something (configure / build / modify / run / test / debug); open 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 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 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
  • the host-side bring-up workflow in 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
  • the service-deployed-and-running check in TASKS.md ## configure step 1, which routes service-side env questions to doca-public-knowledge-map ## 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
  • the discovery step in 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 (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, which cross-links the canonical detection chain in doca-version 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 UROM overlay on the cross-library taxonomy in CAPABILITIES.md ## Error taxonomy
  • the layered ladder in TASKS.md ## debug that escalates to doca-debug.

Audience

This skill serves external developers building HPC / UCX / MPI applications that consume the DOCA UROM library from the host side — i.e., users whose code calls doca_urom_* (directly in C / C++, or through FFI / bindings from another language, or through a UCX-based stack such as OpenMPI / MPICH that has been wired to use DOCA UROM as a UCX transport) to push remote memory operations onto the BlueField DPU instead of executing them on the host CPU. It is not for NVIDIA developers contributing to DOCA UROM itself, nor is it the place to learn how to deploy / operate the DOCA UROM Service on the DPU side — that goes through the public DOCA UROM Service guide via doca-public-knowledge-map ## DOCA services.

Language scope. DOCA UROM ships as a host-side C library with pkg-config module name doca-urom. The shipped samples under /opt/mellanox/doca/samples/doca_urom/ are written in C (NVIDIA's choice). C and C++ consumers — including UCX-based stacks that wrap the library — are the canonical case and the worked examples in TASKS.md assume that path. Other-language consumers (Rust, Go, Python, …) consume the same *.so through FFI or language-specific bindings; the skill's contribution in that case is to keep the lifecycle, capability-discovery, service-deployed-and-running, error-taxonomy, and RDMA-substrate guidance language-neutral, and to route the agent to the public C ABI as the authoritative surface that any wrapper will eventually call.

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 that maps to the BlueField the user wants to offload to, then creating Worker contexts (doca_urom_worker_*) attached to that Service, and confirming the matching DPU-side UROM Service is reachable before the first enqueue.
• Enqueueing remote memory operations (puts, gets, atomics, active messages, collective primitives) through the host-side doca_urom_* API and progressing the DOCA progress engine for completions.
• Reading or setting library properties via the host-side UROM API and 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 + this DOCA install + this DPU-side UROM Service version actually supports.
• Applying the host-side UROM lifecycle, capability-discovery, and error rules to a UCX-based HPC stack (OpenMPI, MPICH, custom UCX consumer) that is already wired to use UROM. Designing the UCX transport integration itself remains upstream-stack work.
• Debugging a DOCA_ERROR_* returned from a doca_urom_* call — in particular disambiguating DPU-side UROM Service not reachable from operation type not supported on this device from standard doca_dev access denied from underlying RDMA transport failure.
• Designing or extending non-C bindings (Rust, Go, Python, …) that wrap the UROM C ABI — for the lifecycle, service-deployed-and-running, capability-discovery, and error-taxonomy rules the wrapper must honor.

Do not load this skill for general DOCA orientation, install of DOCA itself, deployment / operation of the DOCA UROM Service on the DPU side (a separate artifact, with its own public guide reachable via doca-public-knowledge-map ## DOCA services), or non-UROM library questions. For those, use doca-public-knowledge-map.

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:

• CAPABILITIES.md — what the host-side UROM API can express on this version + this BlueField + this UROM Service version: the paired-contract model (host library enqueues; DPU service executes); the two host-side context types — the doca_urom_service (one per BlueField, bound to its doca_dev) and the doca_urom_worker contexts attached to it; the enqueue-side operation surface (puts, gets, atomics, active messages, collective primitives) delivered as plugin-defined Worker Command tasks and 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 the cross-library DOCA_ERROR_* set; the observability surface (completion events on the DOCA progress engine, capability snapshots, infrastructure-side RDMA counters); and the safety policy that gates env preconditions (DOCA UROM Service deployed and running on the DPU side; host library and DPU service versions agreeing; an RDMA-capable BlueField + DOCA install).
• TASKS.md — 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 already installed at the standard location, the DOCA UROM Service is already deployed and running on the BlueField, the underlying RDMA transport between host and BlueField is healthy, and the user already has at least a sketch of the HPC / UCX / MPI stack they want to offload. It does not cover installing DOCA, deploying the UROM Service container on the BlueField, or bringing up RDMA / RoCE / IB transport between ho