AutoGineer
Generated banner for Doca Rmax
Generated logo for Doca Rmax

Doca Rmax

NVIDIAOfficialCreated by NVIDIA

  • Skill
  • Tool integration
  • Software development
  • Apache-2.0
  • Medium risk
Download ZIP

From the author

DOCA Rivermax (doca_rmax) receive streams for timing-precise media over IP (SMPTE ST 2110 video / audio, market data, scientific feeds) on a target BlueField DPU (DOCA Rivermax apps run only there), once the Rivermax libraries and license are installed; getting them is doca-setup / doca-public-knowledge-map territory. Trigger on "ST 2110 receive isn't getting frames", "sub-microsecond jitter on my media receiver", "NOT_SUPPORTED from doca_rmax_init", "no recv events after stream start", or "license check failing on a media receiver", even without naming Rivermax. Covers doca_rmax_in_stream sessions, the SDK + license precondition check, doca_rmax_get_*_supported capability queries, pairing with doca-eth queues and doca-flow steering, and DOCA_ERROR_* from Rivermax calls. Refuse and route elsewhere for programming the underlying queue (doca-eth), steering rules (doca-flow), PTP / clock sync (doca-firefly), or best-effort packet I/O.
— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The doca-rmax skill provides technical guidance for developers building applications that consume the DOCA Rivermax integration. It focuses on the C/C++ API for receiving timing-precise media streams, such as SMPTE ST 2110, on NVIDIA BlueField DPUs. The skill covers the lifecycle of doca_rmax_in_stream objects, capability discovery via doca_rmax_get_*_supported queries, and error handling. It emphasizes that Rivermax requires a separately installed SDK and license, and it provides a structured approach to debugging stream issues by coordinating with doca-eth and doca-flow.

What it does

  • Manages the lifecycle of Rivermax receive stream contexts.
  • Provides capability discovery for PTP clocks and packet-placement modes.
  • Maps DOCA_ERROR_* codes to specific Rivermax-related causes.
  • Coordinates Rivermax streams with underlying doca-eth queues and doca-flow steering.
  • Validates mandatory preconditions including Rivermax SDK and license presence.
  • Offers debugging strategies for jitter and stream-start failures.

When to use it

  • When developing applications for SMPTE ST 2110 video/audio or high-throughput scientific feeds.
  • When troubleshooting why a Rivermax stream is not receiving frames.
  • When querying device capabilities for specific packet-placement or clock synchronization.
  • When integrating Rivermax with DOCA networking and steering components.
  • When debugging initialization errors like NOT_SUPPORTED.

Advantages

  • Ensures correct integration of timing-sensitive media streams.
  • Provides a clear separation between Rivermax-specific logic and underlying networking.
  • Reduces configuration errors by enforcing mandatory license and SDK checks.
  • Standardizes the debugging process for complex media-over-IP pipelines.

Usage examples

“ST 2110 receive isn't getting frames.”
The agent will verify the Rivermax license and SDK, check if the stream object started, and guide the user to inspect doca-flow steering rules and doca-eth queue configurations.
“Can this device use ST 2110-20 sequence-number placement?”
The agent will instruct the user to call the appropriate doca_rmax_get_*_supported query to verify hardware support for the requested placement mode.
“NOT_SUPPORTED from doca_rmax_init.”
The agent will guide the user to check the Rivermax SDK installation, license validity, and device compatibility before investigating further code-level issues.

Install

  1. Download the skill as a ZIP:

    https://mp-staging.autogineer.com/agent-skills/nvidia/doca-rmax/download

  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip doca-rmax.zip -d .agents/skills

Documentation by NVIDIA

DOCA Rivermax

Examples

  • "ST 2110 receive isn't getting frames." — this is in scope after Rivermax SDK + license are already present.

  • "How do I obtain / install the Rivermax SDK and its license?" — out of scope for this skill. Say so, give no install or licensing steps, and route: DOCA packages to doca-setup/SKILL.md, the Rivermax SDK + license to the public DOCA Rivermax guide via doca-public-knowledge-map/SKILL.md. Come back here once both are present.

  • "NOT_SUPPORTED from doca_rmax_init." — run the doca_rmax_get_*_supported queries before changing stream setup.

Instructions

Follow Loading order below. Open the tasks companion for configure / stream / debug. Open the capabilities companion for Rivermax preconditions. Do not open every companion file.

Where to start: This skill assumes DOCA is already installed on the target BlueField DPU (DOCA Rivermax apps run only on the target DPU), AND that the Rivermax libraries (doca-sdk-rmax / libdoca-sdk-rmax-dev from the DOCA repo) are installed with a valid Rivermax license present on the DPU. The agent's FIRST action on any Rivermax question is to confirm both — without the Rivermax libraries + license, doca-rmax cannot function regardless of how clean the DOCA-side code is, and this is the #1 first-app confusion (the Rivermax license, and the driver per the Rivermax SDK page, are obtained separately from DOCA). Open the tasks companion if the user wants to do something (configure / build / modify / run / test / debug); open the capabilities companion when the question is what can DOCA Rivermax express on this version + this Rivermax install. If the user has not installed DOCA yet, route to doca-setup/SKILL.md first; for the Rivermax SDK + license install itself, route to the public DOCA Rivermax guide (slug DOCA-Rivermax) via doca-public-knowledge-map/SKILL.md. If the user is asking "how do I get packets to land on my Rivermax input stream at all", the answer is layered: doca-rmax is the Rivermax integration surface, doca-eth/SKILL.md is the queue surface that carries the packets, and doca-flow/SKILL.md is the steering surface that directs them.

Example questions this skill answers well

The CLASSES of DOCA Rivermax 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.

  • "Can I even use doca-rmax on this host?" — worked example: "the public docs mention doca-rmax; is it usable without doing anything else?". Answered by the Rivermax-SDK + license precondition rule in

    Safety policy

    • the env-prep checklist in

    configure step 1, which

    routes the install-side question to the public Rivermax guide via doca-public-knowledge-map/SKILL.md and refuses to recommend a fallback to doca-eth alone that would silently lose the timing properties.

  • "How do I set up a SMPTE ST 2110 video receive stream?" — worked example: "line up an inbound Rivermax stream on a representor of a BlueField port for first-run testing". Answered by the per-stream object lifecycle in

    configure +

    Capabilities and modes

    input stream capability table.

  • "Which doca_rmax_get_*_supported query do I have to call before picking a PTP clock or hardware packet-placement order?" — worked example: "can this device + this Rivermax install use ST 2110-20 sequence-number placement?". Answered by the capability-query rule in

    Capabilities and modes

    • step 3 in

    configure.

  • "My stream is set up but no packets arrive — why?" — worked example: "the Rivermax stream object started cleanly but no recv events fire". Answered by the precondition matrix in

    Safety policy

    • the env-prep checklist in

    configure step 1, which

    routes the steering side to doca-flow/SKILL.md, the queue side to doca-eth/SKILL.md, and the license side back to the Rivermax-side precondition.

  • "Is this Rivermax integration capability available on my device + my installed DOCA + my Rivermax SDK?" — worked example: "does this device + this Rivermax version advertise the PTP clock or placement mode I need". Answered by the capability-query rule in

    Capabilities and modes

    • the version-and-device overlay in

    Version compatibility,

    which adds the Rivermax-side version is a second axis rule on top of the canonical DOCA version-handling chain in doca-version/SKILL.md.

  • "What does this DOCA_ERROR_* from a Rivermax call mean and which layer caused it?" — worked example: "DOCA_ERROR_NOT_SUPPORTED from doca_rmax_init()". Answered by the Rivermax overlay on the cross-library taxonomy in

    Error taxonomy

    • the layered ladder in

    debug that escalates to

    doca-debug/SKILL.md, and which preserves the installed header's call-specific mapping: init-time _NOT_SUPPORTED routes first to Rivermax SDK / license checks; later errors are interpreted from the exact failing call rather than generalized into a license diagnosis.

Audience

This skill serves external developers building applications that consume the DOCA Rivermax integration — i.e., users whose code calls doca_rmax_* (directly in C/C++, or through FFI/bindings from another language) to drive timing-precise media-over-IP streams (SMPTE ST 2110, real-time market data, high-throughput scientific instrument streams) on top of a separately-installed NVIDIA Rivermax SDK on a BlueField or ConnectX host. It is not for NVIDIA developers contributing to DOCA Rivermax itself, and it is not for users who want best-effort packet I/O — for that, route to doca-eth/SKILL.md directly.

Language scope. DOCA Rivermax ships as a C library with pkg-config module name doca-rmax. The shipped samples live under /opt/mellanox/doca/samples/doca_rmax/ and are written in C. C and C++ consumers are the canonical case; the worked examples in the tasks companion 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 precondition rule (Rivermax SDK + license), per-stream lifecycle, capability-discovery, permission, scheduling-discipline, and error-taxonomy 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 Rivermax work, in any language. Concretely:

  • Confirming that the NVIDIA Rivermax SDK and a valid Rivermax license are present on the host before any DOCA-side code is written — this is a mandatory precondition, not an error path; without it the answer is "doca-rmax cannot be used; pick a different library", not "let's try and see what fails".

  • Initializing the global DOCA Rivermax engine with doca_rmax_init() / doca_rmax_release(), then creating a doca_rmax_in_stream (receive) context with doca_rmax_in_stream_create() on a doca_dev opened against a physical port, a representor, or an SF, and converting it via doca_rmax_in_stream_as_ctx() before doca_ctx_start(). The public DOCA Rivermax API is receive-only — there is no transmit/output stream object.

  • Configuring a Rivermax input stream for SMPTE ST 2110 audio + video over IP, real-time market data feeds, or a scientific instrument stream — with awareness that PTP-clock and hardware packet-placement-order support are device- and Rivermax-conditional and gate on the matching doca_rmax_get_*_supported query.

  • Reading or setting Rivermax stream properties via doca_rmax_in_stream_set_* and querying device + Rivermax capability via the doca_rmax_get_*_supported family before assuming PTP-clock or hardware packet-placement-order support.

  • Pairing the Rivermax stream with the doca-eth queue surface that carries the packets and the doca-flow rules that steer them — Rivermax does not program steering itself.

  • Designing the real-time scheduling discipline for the streaming threads (the underlying Rivermax stack expects real-time priority for sub-microsecond jitter; the canonical scheduling guidance lives in the Rivermax SDK docs reachable through doca-public-knowledge-map/SKILL.md).

  • Debugging a DOCA_ERROR_* returned from a Rivermax call (lifecycle vs. license / permission vs. capability vs. driver-below) where the cause may live in the DOCA-side wrapper, the underlying Rivermax stack, or the licensing layer.

  • Designing or extending non-C bindings (Rust, Go, Python, …) that wrap the DOCA Rivermax C ABI — for the precondition rule, lifecycle, capability, permission, and scheduling rules the wrapper must honor.

Do not load this skill for general DOCA orientation, for installing DOCA itself, for installing the Rivermax SDK or managing the Rivermax license file (those live in the public Rivermax SDK guide reachable through doca-public-knowledge-map/SKILL.md), for best-effort packet I/O without timing requirements (use doca-eth/SKILL.md directly), or for pure host-side data processing without networking. For DOCA documentation orientation, 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 Rivermax-specific material lives in two companion files:

  • the capabilities companion — what DOCA Rivermax can express on this version and this Rivermax SDK install: the Rivermax-as-hard-dependency rule, the receive-only doca_rmax_in_stream object model, the capability-query surface (doca_rmax_get_*_supported), the Rivermax error taxonomy (mapped onto the cross-library DOCA_ERROR_* set, with Rivermax-specific causes called out per row), the observability surface (per-stream progress engine events, capability snapshots, Rivermax-side license + driver state), and the safety policy that gates the Rivermax-SDK-present / license-present / device-access / scheduling-discipline preconditions.

  • the tasks companion — step-by-step workflows for the six in-scope Rivermax verbs: configure, build, modify, run, test, debug. Plus a Deferred task verbs block that points out-of-scope questions (installing Rivermax, managing the license, programming steering, programming the underlying queue) at the right next skill, and a Command appendix of the recurring commands the agent reaches for.

The skill assumes a host or BlueField where DOCA is already installed at the standard location, the NVIDIA Rivermax SDK is installed at its expected location with a valid license, and the user has the privileges their public install profile expects (typically sudo or mlnx-group membership to open a doca_dev against a port). It does not cover installing DOCA — that path goes through doca-setup/SKILL.md. It does not cover installing Rivermax or its license — that path goes through the public Rivermax SDK guide reachable through doca-public-knowledge-map/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 Rivermax application source code, in any language. The verified Rivermax source code is the shipped C samples at /opt/mellanox/doca/samples/doca_rmax/<name>/. 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/SKILL.md, layered with the Rivermax-specific overrides in

    modify.

  • 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-rmax is the source of truth.

  • Quoted Rivermax symbol names beyond the public family pattern (doca_rmax_get_*_supported for capability discovery, receive-only doca_rmax_in_stream session objects driven by the standard DOCA Core context lifecycle). Exact Rivermax symbol names are install-bound and Rivermax-SDK-version- bound; the agent should read them from the installed headers at $(pkg-config --variable=includedir doca-common) and from the public DOCA Rivermax guide rather than rely on agent memory.

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

Loading order

  1. Read this skill first to confirm the user's question is in scope and that the Rivermax-SDK + license precondition has been considered.

  2. For the Rivermax capability matrix, the receive-only input stream model, capability-query rules, error taxonomy, observability, and safety policy, see the capabilities companion.

  3. For step-by-step workflows — configure, build, modify, run, test, debug — see the tasks companion.

Both companion files cross-link to each other, doca-version/SKILL.md for the canonical DOCA version-handling rules (Rivermax adds a Rivermax-SDK- version axis on top), doca-eth/SKILL.md for the queue surface that carries the packets, doca-flow/SKILL.md for the steering side that decides which packets land on which queue, and doca-public-knowledge-map/SKILL.md whenever the right answer is "look it up in the public Rivermax SDK guide or the installed package layout" rather than "Rivermax-integration-specific guidance".

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 Rivermax URL slug is DOCA-Rivermax; the public Rivermax SDK guide (separate product) is reachable from the same routing table when the user asks how to install Rivermax or its license.

  • doca-setup/SKILL.md — env preparation, install verification, port-state checks (devlink dev show, ip link), permission and group-membership requirements for opening a doca_dev. This skill assumes its preconditions are satisfied; the Rivermax-SDK + license preconditions are layered on top.

  • doca-version/SKILL.md — canonical DOCA version-handling rules. This skill's ## Version compatibility cross-links the four-way match rule and adds the Rivermax-specific overlay (Rivermax SDK version is a second axis; the capability set on this host is the intersection of DOCA-side cap-query results and Rivermax-side capabilities).

  • 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: the canonical pkg-config + meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-library DOCA_ERROR_* taxonomy, and the program-side debug order. This skill layers Rivermax specifics on top.

  • doca-eth/SKILL.md — the queue surface that carries the packets a Rivermax stream produces or consumes. DOCA Rivermax does not program the underlying queue itself; it integrates with the queue programmed via doca-eth. The two skills' lifecycles are independent.

  • doca-flow/SKILL.md — the steering surface that decides which packets land on which queue. DOCA Rivermax does not program steering itself; an empty Rivermax input stream almost always means a missing or wrong Flow rule (or a missing Rivermax license), not a Rivermax bug.

  • doca-debug/SKILL.md — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). Rivermax-specific debug (license precondition gaps, stream-type / packet-rate capability mismatches, scheduling-discipline jitter symptoms) overlays on top of that ladder.

Files

CAPABILITIES.md

DOCA Rivermax capabilities, version overlay, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (input stream object / capabilities / Rivermax SDK

  • license / errors / safety) and read that section end-to-end. The tables in each section are the load-bearing content; the prose around them is interpretation.

Read this file when the loader sent you here from SKILL.md. For the how of executing each pattern (the verbs configure / build / modify / run / test / debug), jump to TASKS.md. For the canonical DOCA version-handling rules that this skill layers a Rivermax overlay on top of, see doca-version/SKILL.md. For the queue surface that carries the packets a Rivermax stream produces or consumes, defer to doca-eth/SKILL.md; for the steering side (which Flow rule sends which packet to which queue) defer to doca-flow/SKILL.md. DOCA Rivermax is the Rivermax integration surface, not the queue surface and not the steering surface.

Pattern overview

Every DOCA Rivermax question this skill teaches resolves into one of FIVE patterns. The patterns are CLASSES — they apply across every DOCA Rivermax release, every host / BlueField, and every supported Rivermax SDK version.

PatternWhen it applies (class shape)Where the substance lives
1. Confirm the Rivermax preconditionBefore any other concern, verify that the NVIDIA Rivermax SDK is installed AND a valid Rivermax license is readable on the host; without both, doca-rmax cannot function and there is no in-library fallback## Safety policy precondition matrix + TASKS.md ## configure step 1
2. Stand up the receive streamInitialize the global DOCA Rivermax engine (doca_rmax_init() / doca_rmax_release()), then create the receive-only doca_rmax_in_stream session object via doca_rmax_in_stream_create() and drive it through its own DOCA Core lifecycle. The public API is receive-only — there is no transmit/output stream## Capabilities and modes input stream table + TASKS.md ## configure step 2
3. Discover capabilitiesQuery the doca_rmax_get_*_supported family against the active doca_devinfo for PTP-clock and packet-placement-order support before assuming any timing-precise configuration is feasible on this device + this Rivermax SDK## Capabilities and modes capability-query rule + TASKS.md ## configure step 3
4. Honor preconditionsVerify the device opens under the user's access (DOCA-side: sudo or mlnx group; Rivermax-side: license file readable, real-time scheduling on streaming threads), the underlying port is up, and traffic is steered to the queue the Rivermax stream is attached to (via DOCA Flow)## Safety policy precondition matrix + TASKS.md ## configure step 1
5. Diagnose a Rivermax errorMap symptom (DOCA_ERROR_BAD_STATE, _NOT_PERMITTED, _NOT_SUPPORTED, _INVALID_VALUE, _DRIVER) to root cause WITHOUT collapsing the DOCA-side / Rivermax-side / license-side / driver-below layers into one## Error taxonomy + TASKS.md ## debug

Two cross-cutting rules that apply to every pattern above:

  • DOCA Rivermax is a wrapper, not the engine. The timing-precise media-streaming engine lives in the NVIDIA Rivermax SDK; doca-rmax is the DOCA-side integration that exposes Rivermax sessions through the DOCA Core context lifecycle. Treating doca-rmax as a self-contained library is the most common first-app design error: there is no fallback path inside DOCA that recovers timing precision without a real Rivermax install + license behind it.

  • Sub-microsecond jitter is the library's whole point. If the user does not need timing-precise streaming, the right answer is to route them to doca-eth/SKILL.md for best-effort packet I/O — not to layer doca-rmax on top of a workload it was not built for, and not to silently downgrade their timing expectations.

Capabilities and modes

The DOCA Rivermax public API is receive-only: the one selection axis for any design is timestamp format / packet- placement order / scatter type (device- and Rivermax-conditional). The engine itself is a process-global singleton; choose stream parameters only after the matching capability-query confirms they are supported.

Object model — a global engine plus a receive-only input stream. There is no per-integration context object: the library is initialized process-wide with doca_rmax_init() and torn down with doca_rmax_release(). The only stream object is the receive-side doca_rmax_in_stream; a doca_rmax_flow attaches match criteria to it. Read exact symbol names from the headers at $(pkg-config --variable=includedir doca-common) rather than from agent memory beyond the family pattern below.

ObjectWhat it doesFamily of callsSizing inputs
Global Rivermax engine (process singleton)Process-wide initialization of the underlying Rivermax SDK integration; must be initialized before any stream is created and released after all streams are destroyed. Holds no per-device state itselfdoca_rmax_init() / doca_rmax_release() / doca_rmax_interrupt(), plus doca_rmax_set_cpu_affinity_mask() and doca_rmax_set_clock()None — it is a singleton; the device is selected per input stream
doca_rmax_in_stream (receive)The one Rivermax session object — a receive stream for SMPTE ST 2110 inbound video / audio, real-time market data feeds, instrument streams. Created on a doca_dev, converted to a DOCA Core context via doca_rmax_in_stream_as_ctx(), and surfaces inbound data via the Rx-data PE event with Rivermax doing the timing-precise reassemblydoca_rmax_in_stream_create() / _destroy() / _as_ctx(), doca_rmax_in_stream_set_* setters, doca_rmax_in_stream_event_rx_data_register()A doca_dev opened against the target port / representor / SF (must have a valid IPv4 address); doca_rmax_get_*_supported queries against the active doca_devinfo
doca_rmax_flow (steering filter)A match filter (src/dst IPv4, src/dst port, tag) attached to an input stream so only the intended media flow lands on itdoca_rmax_flow_create() / _destroy() / _attach() / _detach() + doca_rmax_flow_set_{src,dst}_{ip,port} / _set_tagThe IP/port 5-tuple of the inbound media flow

The input stream sits on top of the underlying packet queue (doca_eth_rxq); the queue itself is programmed through doca-eth/SKILL.md, and the steering that gets matching packets to it is programmed through doca-flow/SKILL.md. Treating the Rivermax stream as a stand-in for the queue / steering surfaces is wrong: it conflates three independent libraries that each own their own lifecycle.

Capability discovery — the only rule. Before assuming a PTP-synced timestamp format or hardware-accelerated packet placement order is feasible, call the matching doca_rmax_get_*_supported query against the active doca_devinfo:

CapabilityQuery functionWhy the agent must ask
PTP clock supported on this device + Rivermax versiondoca_rmax_get_ptp_clock_supportedPTP-synced timestamps require device + Rivermax support; assuming PTP is on every device is a canonical hallucination failure mode. Required before doca_rmax_set_clock() and the PTP-synced timestamp format.
Hardware-accelerated RTP sequence-number packet placementdoca_rmax_get_packet_placement_order_rtp_seqn_supportedRTP-seqn placement ordering is device- and Rivermax-version-conditional; query before enabling it via doca_rmax_in_stream_set_packet_placement_order_rtp_seqn.
Hardware-accelerated SMPTE ST 2110-20 sequence-number placementdoca_rmax_get_packet_placement_order_st2110_20_seqn_supportedST 2110-20 placement ordering is device- and Rivermax-version-conditional; query before enabling it via doca_rmax_in_stream_set_packet_placement_order_st2110_20_seqn.

The capability-query rule is the runtime authority: when the cap query says false, that is the answer for this host, regardless of what the public docs claim about the feature in general. Quote the queried value back to the user; do not substitute a value the user remembered from another install.

Configuration shape. Mandatory configurations before doca_ctx_start() on the input stream: the scatter type, timestamp format, and memory-block / element-count layout set per the user's intent (timestamp format and packet-placement order gated on the matching doca_rmax_get_*_supported query), the underlying queue context wired in (allocated and started via doca-eth/SKILL.md), and the Rx-data event registered via doca_rmax_in_stream_event_rx_data_register(). Optional configurations (hardware-accelerated packet-placement order, PTP-synced timestamps, receive timeout / min-max packet batching) gate on the matching doca_rmax_get_*_supported query and the corresponding doca_rmax_in_stream_set_* setter; the agent should consult the public DOCA Rivermax guide (slug DOCA-Rivermax via doca-public-knowledge-map/SKILL.md) for the canonical setter names on the installed version rather than quote them from memory.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.

The Rivermax-specific overlay is:

  • The Rivermax SDK version is a second compatibility axis. DOCA Rivermax is a wrapper; the underlying timing-precise engine ships with the NVIDIA Rivermax SDK and its own version. A capability advertised by doca-rmax headers but rejected at runtime usually means the installed Rivermax SDK is older than the feature requires. The agent's rule: always quote both the DOCA version (per pkg-config --modversion doca-rmax) and the Rivermax SDK version (per the Rivermax SDK's own version query, documented in the public Rivermax SDK guide via doca-public-knowledge-map/SKILL.md) before promising a feature.

  • doca_rmax_get_*_supported is the runtime authority, not the public docs. Per the cross-cutting cap-query rule in doca-version CAPABILITIES.md ## Observability (doca-version/CAPABILITIES.md#observability), the agent must call the matching capability query against the active doca_devinfo before promising the user that a PTP clock or hardware-accelerated packet-placement order is on this device + DOCA version + Rivermax SDK version. Quoting a feature from memory is the canonical hallucination failure mode for this library.

  • doca-rmax.pc and doca-common.pc must both match doca_caps --version at the four-way-match check (per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility)). Use pkg-config --modversion doca-rmax as the build-time anchor; disagreement with doca_caps --version is a partial-install hazard and must be routed to doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) layer 2 before any Rivermax-layer diagnosis. A missing doca-rmax.pc does NOT imply the Rivermax SDK is missing — those are two independent install layers and the agent must check both.

Error taxonomy

Rivermax-specific overlays on the cross-library DOCA_ERROR_* taxonomy. The cross-library taxonomy itself lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy); the rows below are the Rivermax surface meaning that the agent must disambiguate before falling back to the cross-library response.

ErrorDOCA Rivermax context where it shows upRivermax-specific cause
DOCA_ERROR_BAD_STATEAny call after doca_ctx_stop() or before doca_ctx_start(); using an input stream whose underlying doca_eth_rxq queue has not been started; calling a doca_rmax_in_stream_set_* setter after the context has left idleLifecycle violation. Walk the input stream's state against the universal lifecycle in doca-programming-guide CAPABILITIES.md ## Capabilities and modes (doca-programming-guide/CAPABILITIES.md#capabilities-and-modes); the most common case is treating the input stream lifecycle as covered by the process-global doca_rmax_init() call.
DOCA_ERROR_NOT_PERMITTEDDevice open behind doca_rmax_in_stream_create()DOCA-side device access denied (no sudo / not in mlnx group), same as every DOCA library — confirm via the precondition matrix in ## Safety policy. Note that a missing / expired / unreadable Rivermax license surfaces instead as DOCA_ERROR_NOT_SUPPORTED from doca_rmax_init() (per the header), so check the init return code separately.
DOCA_ERROR_NOT_SUPPORTEDdoca_rmax_init() (invalid / missing Rivermax license); timestamp-format / packet-placement-order settersEither the Rivermax license is invalid or missing (from doca_rmax_init()), or the chosen stream parameter is not supported on this device + this Rivermax SDK version. Re-run the matching doca_rmax_get_*_supported query against the active doca_devinfo; if it says not-supported, that is the answer — the device or the Rivermax version does not support the request. The fix is to change the request, supply a valid license, or upgrade the Rivermax SDK, not to retry.
DOCA_ERROR_INVALID_VALUEdoca_rmax_in_stream_set_* setters with an out-of-range element count, memory-block size, or packet batch boundThe user passed a value outside the valid set for the chosen stream configuration. The fix is at the configure step, not in the program's runtime loop.
DOCA_ERROR_DRIVERAny submit / completion callThe layer below DOCA reported failure — which for Rivermax may be either the DOCA driver layer (mlx5 / ConnectX firmware) OR the underlying Rivermax driver / stack. Capture state from both sides (`dmesg

The agent's rule: never recommend a retry loop on DOCA_ERROR_* without first identifying which of the rows above is the cause. For DOCA Rivermax there is no retry-on- error row at all — every Rivermax error wants investigation, not retry. And "no packets arriving" is never a DOCA_ERROR_* — it is one of: a missing Rivermax license, a missing or wrong Flow rule on the steering side (route to doca-flow/SKILL.md), or an unstarted underlying doca_eth_rxq (route to doca-eth/SKILL.md).

Observability

The DOCA Core progress engine (PE) is the single source of observability for the Rivermax input stream: every Rx-data event (success or failure) arrives as an event on the PE that the input stream context is registered against. DOCA Rivermax does not maintain per-stream counters of its own; its observability surface is event-driven, not poll-driven, with three add-on signals (capability snapshot + Rivermax-side state + port-state).

Four primary signals the agent should reach for:

  1. Rx-data event completions on the PE. The input stream produces an Rx-data event (via doca_rmax_in_stream_event_rx_data_register()) on every received batch of packets per the chosen stream type. Absence of completions on a started stream is always either a missing doca_pe_progress() call or a missing-license / steering / underlying-queue precondition gap. Route to ## Safety policy first.

  2. Capability snapshot at configure time. The output of every doca_rmax_get_*_supported query is a snapshot of what the library + the Rivermax SDK said was possible before any task was submitted. Save it as the baseline; if a task later returns DOCA_ERROR_NOT_SUPPORTED the diff against this snapshot is the bug (and usually the bug is that a different doca_devinfo was used at submit time than at cap-query time).

  3. Rivermax-side state. The Rivermax SDK has its own logging / status surface documented in the public Rivermax SDK guide; the agent should route to it via doca-public-knowledge-map/SKILL.md when the cause is suspected to be Rivermax-side (license, stream config, scheduling jitter) rather than DOCA-side. The agent must NOT invent Rivermax-side commands or paths from memory.

  4. Port and link state from the env side. devlink dev show, ip -j link show <dev>, and ethtool <dev> together tell the agent whether the port the user opened is up at the driver layer at all. A linkdown port is a silent Rivermax stream; the agent must check it before any Rivermax-layer diagnosis. Defer to doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability) for the env-side observability primitives.

For the cross-library debug-time observability (DOCA_LOG_LEVEL=trace, --sdk-log-level, the trace build flavor) see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability).

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

DOCA Rivermax's safety surface is the Rivermax SDK + license precondition first, then DOCA-side access, port state, and steering, and finally the real-time scheduling discipline on streaming threads. The single most common first-app failure is "I'm calling doca-rmax but doca_rmax_init() returns DOCA_ERROR_NOT_SUPPORTED / silently fails" — and the answer is usually that the user assumed DOCA bundles Rivermax (it does not) and never installed the Rivermax SDK or arranged the license file.

The precondition matrix the agent must walk for any new DOCA Rivermax setup. The first row is the gate that determines whether the rest of the matrix is even relevant.

PreconditionWhat must be true before doca_ctx_start()How the agent verifiesWhere to fix
Rivermax SDK installed (hard external dep)The NVIDIA Rivermax SDK is installed on the host at the location Rivermax expectsExecute the programmatic install or version probe documented for the installed Rivermax SDK release in the public Rivermax SDK guide (slug DOCA-Rivermax via doca-public-knowledge-map/SKILL.md); copy the exact probe from that guide rather than inventing a command or path. Do not assume from a successful pkg-config doca-rmax (that only confirms the DOCA-side wrapper, not the SDK behind it). If no programmatic result can be obtained, treat the SDK status as unverified and stop at this gateRoute to the public Rivermax SDK guide via doca-public-knowledge-map/SKILL.md; this is OUT OF SCOPE for doca-rmax. If the SDK is not installed or its status cannot be verified, doca-rmax cannot be used — there is no DOCA-side fallback
Valid Rivermax license readableA current, unexpired Rivermax license file is present at the location the Rivermax SDK expects, readable by the user the streaming process will run asExecute the Rivermax SDK's own license check documented for the installed release; the installed header also documents DOCA_ERROR_NOT_SUPPORTED from doca_rmax_init() for an invalid or missing license. If neither programmatic result can be obtained, treat the license status as unverified and stop at this gate. Do not assign a later DOCA_ERROR_NOT_PERMITTED to licensing without call-specific documentationRoute to the public Rivermax SDK guide via doca-public-knowledge-map/SKILL.md; this is OUT OF SCOPE for doca-rmax
DOCA-side device accessThe doca_dev was opened against a port / representor / SF the user has permission to use (typically requires sudo or mlnx-group membership)id for group membership; the open call failing with DOCA_ERROR_NOT_PERMITTED is the runtime symptom, distinct from the Rivermax-side license cause abovedoca-setup/SKILL.md for the env-side; do not modify the program
Port upThe underlying port reports linkup at the driver layer (devlink dev show reports state: PORT_ACTIVE; ip link shows the device UP,LOWER_UP)devlink dev show; ip -j link show <dev>; ethtool <dev>doca-setup CAPABILITIES.md ## Capabilities and modes (doca-setup/CAPABILITIES.md#capabilities-and-modes) port-bring-up; do not modify the program
Traffic reaches the underlying queueA DOCA Flow rule steers matching packets to the doca_eth_rxq the Rivermax input stream is attached to (input direction only)Inspect the flow rule programmed for the queue; programmatic via the doca-flow/SKILL.md skill's ## test workflowdoca-flow/SKILL.md for the steering side; this is OUT OF SCOPE for doca-rmax
Real-time scheduling on streaming threadsThe streaming thread runs at real-time priority (per the Rivermax SDK's recommended scheduling discipline) so timing-precise emission / reception holdsRoute to the Rivermax SDK's own docs via doca-public-knowledge-map/SKILL.md for the canonical scheduling guidanceOut of scope for doca-rmax; the canonical scheduling discipline lives in the Rivermax SDK guide

Do not invent a "fallback transport" for Rivermax. When the Rivermax SDK or license is unavailable, the right answer is to tell the user honestly that doca-rmax cannot be used and to route them to doca-eth/SKILL.md for best-effort packet I/O (or doca-gpunetio/SKILL.md for GPU-initiated best-effort I/O) — and to clearly state that the best-effort path loses the sub-microsecond-jitter timing guarantee that is the whole point of Rivermax. Silently substituting doca-eth for doca-rmax is a user-visible regression dressed up as helpfulness.

Smoke before scale-up. Before driving traffic at full stream rate, the agent must walk the user through a single-frame smoke (one frame / chunk of the configured stream type, one PE progress, one completion event). A failure here narrows cleanly: license, steering, queue, or program. A failure at full stream rate without the smoke pass is a much harder bisection across the DOCA-side / Rivermax-side / scheduling-discipline boundary.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: Requires DOCA SDK at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) on the target BlueField DPU (DOCA Rivermax apps run only there), with `doca-sdk-rmax` from the DOCA repo AND a separately obtained Rivermax license readable by the user. Reads the local install via `pkg-config doca-rmax`; route Rivermax SDK install/license questions to the public Rivermax guide. The validation steps require a live DOCA install.

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by
NVIDIA
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/doca-rmax · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-rmax.zip