doca-rmax

# DOCA Rivermax

**Where to start:** This skill assumes DOCA is already installed,
**AND** that the NVIDIA Rivermax SDK is separately installed with a
valid Rivermax license present on the host. The agent's FIRST
action on any Rivermax question is to confirm both — without
Rivermax SDK + license, `doca-rmax` cannot function regardless
of how clean the DOCA-side code is, and this is the #1 first-app
confusion (DOCA does *not* bundle Rivermax; it wraps it). Open
[`TASKS.md`](TASKS.md) if the user wants to *do* something
(configure / build / modify / run / test / debug); open
[`CAPABILITIES.md`](CAPABILITIES.md) 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`](../../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`](../../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`](../doca-eth/SKILL.md) is the *queue* surface that
carries the packets, and [`doca-flow`](../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
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the env-prep checklist in
  [`TASKS.md ## configure`](TASKS.md#configure) step 1, which
  routes the install-side question to the public Rivermax guide
  via
  [`doca-public-knowledge-map`](../../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
  [`TASKS.md ## configure`](TASKS.md#configure) +
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + step 3 in
  [`TASKS.md ## configure`](TASKS.md#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
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the env-prep checklist in
  [`TASKS.md ## configure`](TASKS.md#configure) step 1, which
  routes the steering side to
  [`doca-flow`](../doca-flow/SKILL.md), the queue side to
  [`doca-eth`](../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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the version-and-device overlay in
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#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`](../../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
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  + the layered ladder in
  [`TASKS.md ## debug`](TASKS.md#debug) that escalates to
  [`doca-debug`](../../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`](../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 `TASKS.md` assume that path. Other-language
consumers (Rust, Go, Python, …) consume the same `*.so` through
FFI or language-specific bindings; the sk