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 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 ).

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 host and BlueField — those paths go through doca-setup, the public DOCA UROM Service guide, and doca-rdma respectively.

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 code is the shipped C samples at /opt/mellanox/doca/samples/doca_urom/. The agent's job is to route the user to those files and prescribe a minimum-diff modification on them via the universal modify-a-sample workflow in doca-programming-guide, layered with the UROM-specific overrides in TASKS.md ## modify.
• An MPI / UCX algorithm or collective implementation. This library offloads remote memory operations; the algorithm selecting which puts / gets / atomics / collectives to issue for a given MPI primitive is the user's HPC stack (OpenMPI, MPICH, custom UCX consumer) or the user's domain expertise. The agent must refuse to invent collective algorithms and must route any "what algorithm should my all-reduce use" question to the upstream MPI / UCX documentation — that is a research / 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 build manifest in the user's project directory against the user's installed DOCA, where pkg-config --modversion doca-urom is the source of truth.
• A samples/, bindings/, or reference/ subtree of any kind. A mock or incomplete artifact in this skill's tree, even one labeled "reference", is misleading: users will read it as buildable.
• The DOCA UROM Service surface. That service is a separate artifact with its own public guide; routing for its deployment / operation lives in doca-public-knowledge-map ## DOCA services. Conflating the library (this skill, host-side enqueue) with the service (DPU-side executor) is the single most common UROM first-app design error.

Loading order

1. Read this SKILL.md 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).
2. 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 CAPABILITIES.md.
3. For step-by-step workflows — configure, build, modify, run, test, debug — see TASKS.md.

Both companion files cross-link to each other, doca-version for the canonical DOCA version-handling rules (with the UROM overlay that the host library version and the DPU service version must match), doca-rdma for the underlying RDMA transport substrate UROM offloads ride on top of, and doca-public-knowledge-map whenever the right answer is "look it up in the public DOCA UROM library guide, the public DOCA UROM Service guide, or in the on-disk install layout" rather than "UROM host-side-specific guidance".

Related skills

• doca-public-knowledge-map — 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 — the underlying RDMA transport substrate the BlueField uses to actually move bytes between nodes once UROM has offloaded a remote memory operation. UROM does NOT replace RDMA; it adds the DPU-offload contract on top so the host CPU does not have to post the verbs itself. When the user's intent is simple point-to-point RDMA and the host CPU is not the bottleneck, the right tool is doca-rdma directly — UROM adds the service-side contract that isn't worth its overhead for that case.
• doca-setup — env preparation, install verification, BlueField setup, and the I have no install yet path with the public NGC DOCA container. This skill assumes its preconditions are satisfied AND that the DPU-side UROM Service is deployed and running on the BlueField.
• doca-version — canonical DOCA version-handling rules. This skill's ## Version compatibility cross-links the four-way match rule and adds the UROM-specific host library and DPU service must agree on version overlay.
• doca-structured-tools-contract — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in TASKS.md honors this contract.
• doca-programming-guide — general DOCA programming patterns shared by every library: the canonical pkg-config + meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal Core-context lifecycle, the cross-library DOCA_ERROR_* taxonomy, and the program-side debug order. This skill layers UROM specifics on top.
• doca-debug — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). UROM-specific debug (DPU-side UROM Service not running / not reachable, host library + DPU service version skew, RDMA transport failure underneath the UROM offload, operation type not in this device + firmware + service version) overlays on top of that ladder.

The DOCA UROM Service that runs on the DPU side is deliberately not in scope for this skill — it is a separate artifact with its own public guide, reachable through doca-public-knowledge-map ## DOCA services. Conflating the library and the service is the single most common UROM first-app design error: the agent must surface the library / service split explicitly whenever the question straddles the two.