/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 a Programmable Congestion
  Control (SPCX) 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:
  kind: tool
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`.

DOCA SPCX Congestion-Control Tool

**Where to start:** This is a tool skill for invoking `doca_spcx_cc` — the documented host-side CLI that exercises an SPCX-class Programmable Congestion Control algorithm on a live RDMA / RoCE fabric driven by a BlueField with a DPA processor. Open [`TASKS.md`](TASKS.md) and start at [`## configure`](TASKS.md#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 [`CAPABILITIES.md`](CAPABILITIES.md) 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`](../../doca-setup/SKILL.md) first.

This skill is the **next-gen programmable-CC surface**. [`doca-pcc`](../../libs/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. [`doca-pcc-ztr-rttcc-algo`](../../libs/doca-pcc-ztr-rttcc-algo/SKILL.md) is one shipped reference algorithm (zero-touch RTT-based CC) 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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).

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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the

*"is SPCX the right surface on this install?"* gate in [`TASKS.md ## configure`](TASKS.md#configure) 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 [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the replica-first evaluation flow in

[`TASKS.md ## test`](TASKS.md#test).

• **"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 like the factory algorithm is still in charge"*. Answered by the live-link / contention rule in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the

*"algorithm has no signal under no contention"* guidance in [`TASKS.md ## test`](TASKS.md#test) + [`TASKS.md ## debug`](TASKS.md#debug) (route through the layered error taxonomy before blaming the algorithm).

• **"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 [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy) (heavily cross-linked to [`doca-hardware-safety CAPABILITIES.md ## Safety policy`](../../doca-hardware-safety/CAPABILITIES.md#safety-policy)): blast-radius bounded, observability gate proven, OOB reachable, factory-PCC rollback rehearsed, escalation path documented before any production cutover.

• **"Is `doca_spcx_cc` on my install, and is it paired

with the matching `doca-pcc` library and DPACC compiler version?"** — worked example: *"is the SPCX surface available on my DOCA install?"*. Answered by the version-overlay in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibi