/doca-spcx-cc

license: Apache-2.0
name: doca-spcx-cc
description: >
  Use this skill when the user is invoking `doca_spcx_cc` (the host-side
  CLI under /opt/mellanox/doca/tools/) to load, parameterize, start,
  observe, or stop an SPC-X congestion-control algorithm on
  a BlueField with a DPA processor against a live RDMA / RoCE fabric, or
  picking SPCX vs the established `doca-pcc` surface. Trigger even when
  the user does not say "DOCA SPCX" or "doca_spcx_cc" — typical implicit
  phrasings include "I want to write a custom RTT-based CC algorithm for
  my RoCE fabric", "my SPCX session loaded but throughput / latency
  didn't change", "doca_pcc status shows Active but factory CC seems to
  still be in charge", "DOCA_PCC_PS_ERROR on start", "is the
  programmable-CC surface available on my install", or "DPA-side
  algorithm image won't load". Refuse and route elsewhere for DPA-side
  algorithm authoring detail, factory PCC firmware configuration,
  read-only PCC counter inspection, raw DPA cycle profiling, RDMA
  library programming, or general DOCA install — those belong to other
  skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - pcc
    - spcx
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with the SPCX optional component, a
  BlueField exposing its DPA processor with the firmware custom-PCC slot
  enabled, the DPACC compiler installed and version-matched, and a
  non-prod RDMA / RoCE fabric with controllable contention reachable for
  evaluation. Probes via `pkg-config doca-pcc` and `doca_spcx_cc
  --help`. The validation steps require a live DOCA install.

DOCA SPCX Congestion-Control Tool

Examples

• **"Should I use SPCX or `doca-pcc` for a custom CC

algorithm?"** — this is in scope. Walk the decision tree before loading anything on a live fabric.

• **"SPCX loaded but throughput did not change."** — confirm

the algorithm is in charge before retuning parameters.

Instructions

Follow Loading order below. Open the tasks companion for configure / run. Open the capabilities companion for the SPCX-vs-PCC tradeoff and safety. Do not open every companion file.

**Where to start:** This is a tool skill for invoking `doca_spcx_cc` — the host-side CLI that exercises an SPC-X congestion-control algorithm on a live RDMA / RoCE fabric driven by a BlueField with a DPA processor. Open the tasks companion and start at `## configure` for the SPCX-vs-PCC-vs-factory-firmware decision tree (load-bearing gate before any code), the role decision (RP / NP), the DPA-side algorithm authoring vs consumption split, and the live-link / contention precondition. Open the capabilities companion when the question is *what does SPCX let me express that `doca-pcc` does not*, *what is the SPCX-vs-PCC tradeoff*, *what runtime metrics does the tool surface*, or *what is the safety posture for loading a custom CC algorithm on a production fabric*. If DOCA is not installed yet, route to `doca-setup/SKILL.md` first.

This skill covers the **SPC-X CC tool**. `doca-pcc/SKILL.md` is the established PCC story; SPCX is the documented extension that authors SPCX-class algorithms on the same DPA hardware substrate. The zero-touch RTT-based CC algorithm (ZTR-RTT) is one NVIDIA reference algorithm that can be loaded through either the PCC or SPCX path depending on the install and the user's algorithm choice; the agent surfaces this decision tree explicitly per the capabilities companion.

Example questions this skill answers well

The CLASSES of `doca_spcx_cc` questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• **"Should I use SPCX or `doca-pcc` for my custom CC

algorithm?"** — worked example: *"I want to write a new RTT-based congestion-control algorithm for my RoCE fabric — which surface do I target?"*. Answered by the SPCX-vs-PCC-vs-factory-firmware decision tree in the capabilities companion

• the

*"is SPCX the right surface on this install?"* gate in the tasks companion step 1.

• **"How do I evaluate my authored SPCX algorithm on a

real RDMA link before letting it touch production?"** — worked example: *"I have a DPACC-compiled SPCX algorithm and a non-prod BlueField pair; how do I run a contention-positive evaluation?"*. Answered by the authoring vs consumption split + the live-link precondition in the capabilities companion

• the replica-first evaluation flow in

the tasks companion.

• **"My SPCX algorithm appears to load cleanly but the

link's throughput / latency curve is unchanged — what's going on?"** — worked example: *"the host-side `doca_pcc --status` reports `Active` and a stable session, but my RoCE flows look unchanged"*. Answered by the live-link / contention rule in the capabilities companion

• the

*"algorithm has no signal under no contention"* guidance in the tasks companion + the tasks companion (route through the layered error taxonomy before blaming the algorithm).

> **No contention → no signal → no conclusion.** `Active` plus an > unchanged traffic curve is not evidence that the algorithm failed > to take over from factory CC. A CC algorithm has no observable > behaviour without actual contention on the fabric, so an idle-link > or contention-absent run is uninformative by construction — it > supports no verdict in either direction. Establish that the run > actually generated contention before concluding anything, and never > declare an algorithm either broken or safe on such a run. Rule in > the capabilities companion.

• **"My SPCX algorithm passed replica testing — what's

the gate before I roll it forward to production?"** — worked example: *"my CC algorithm works on the two BlueField pairs in the lab; can I push it to the fleet?"*. Answered by the safety overlay in the capabilities compani