doca-spcx-cc · git:20260717.f64fa0e · 2026-07-17 · sha256 3d7dc41f12dc36eb
doca-spcx-cc git:20260717.f64fa0eA
Immutable. This exact content is served forever at /api/v1/blob/3d7dc41f12dc36eb.
--- 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-compatibility), which redirects to the canonical [`doca-version`](../../doca-version/SKILL.md) chain and adds the *tool ↔ `doca-pcc` library ↔ DPACC compiler ↔ firmware custom-PCC slot* match rule. - **"My SPCX session errored — is it the tool, the algorithm, the device, or the firmware?"** — worked example: *"`doca_spcx_cc` exits with `DOCA_PCC_PS_ERROR` on start"*. Answered by the layered error taxonomy in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) + the layered walk in [`TASKS.md ## debug`](TASKS.md#debug). ## Audience This skill serves **external developers, platform operators, and AI agents authoring, loading, and evaluating an SPCX-class Programmable Congestion Control algorithm on a BlueField with a DPA processor, against a live RDMA / RoCE fabric**. Concretely: - A CC researcher / developer who has authored an SPCX-class DPA-side algorithm (or who is consuming a documented shipped reference such as the zero-touch RTT-based algorithm via [`doca-pcc-ztr-rttcc-algo`](../../libs/doca-pcc-ztr-rttcc-algo/SKILL.md) on the SPCX path when the install + algorithm support it) and needs the operator-side harness to load, parameterize, start, observe, and stop the algorithm. - A platform operator running a programmable-CC pilot on a non-prod RDMA fabric to characterise the algorithm's behaviour under controlled contention. - An AI agent producing a *"is this SPCX algorithm safe to roll forward"* answer honestly — with evidence from a contention-positive evaluation, a documented rollback to the factory PCC, and an explicit blast- radius bound — instead of a guess from datasheet prose. It is **not** for users debugging the `doca_spcx_cc` binary itself, **not** a substitute for the live public DOCA SPCX / DOCA PCC programming guides, **not** the right place for the DPA-side algorithm authoring detail (that path goes through the public DOCA SPCX programming guide and the [`doca-pcc`](../../libs/doca-pcc/SKILL.md) + [`doca-dpa`](../../libs/doca-dpa/SKILL.md) skills), and **not** the right place for default factory PCC configuration (no host-side library or SPCX tool needed; route via [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)). The tool is shipped as a **CLI binary** under `/opt/mellanox/doca/tools/`, not a library you link against. The skill uses the same `kind: tool` three-file shape as the rest of the bundle so the agent's task-verb contract is uniform across libraries, services, and tools. ## Language scope `doca_spcx_cc` is a C host-side CLI that links the host-side [`doca-pcc`](../../libs/doca-pcc/SKILL.md) library and loads a DPA-side SPCX algorithm image built by the DPACC compiler. The algorithm body is a separate DPA-side translation unit written in the language DPACC accepts. The skill keeps workflow guidance language-neutral and routes per-language questions to the public DOCA SPCX / DOCA PCC / DPACC guides via [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md). ## When to load this skill Load this skill when the user is — or the agent needs to — invoke `doca_spcx_cc` on a real host with DOCA installed, paired with a BlueField that has its DPA processor exposed AND the firmware custom-PCC slot enabled, against a port carrying RDMA / RoCE traffic with **actual contention**. Concretely: - Loading an authored SPCX algorithm (or a documented shipped reference) onto the BlueField via the SPCX surface, parameterizing it, starting it, and observing its effect on the live link. - Evaluating an SPCX algorithm on a non-prod replica before any production rollout — capturing the contention-positive run as evidence. - Comparing SPCX vs `doca-pcc` paths for the same algorithm class on the same install (where both paths are available) and deciding which to commit to. - Producing a *"safe to roll forward"* recommendation with the documented evidence + rollback plan, or refusing the recommendation when the evidence / rollback is missing per [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy). - Diagnosing a `DOCA_PCC_PS_ERROR` or a silent-no-effect symptom against the layered error taxonomy. Do **not** load this skill for general DOCA orientation, DPA-side algorithm authoring detail, raw cycle profiling of the DPA, the factory PCC algorithm shipped in the firmware, or DOCA install. For those, route to [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md), [`doca-pcc`](../../libs/doca-pcc/SKILL.md), [`doca-dpa`](../../libs/doca-dpa/SKILL.md), or [`doca-setup`](../../doca-setup/SKILL.md). ## What this skill provides This is a **thin loader**. Substantive material lives in two companion files: - `CAPABILITIES.md` — what SPCX expresses that PCC does not (and where the surfaces overlap), the SPCX-vs-PCC-vs-factory-firmware decision tree, the authoring vs consumption split, the role decision (RP / NP), the documented probe-packet format axis, the live-link / contention precondition rule (the load-bearing safety invariant — *"a CC algorithm has no signal under no contention"*), the runtime observability surface (per-port / per-flow trace formats + the host-side status surface), the triple-axis precondition rule ([`doca-pcc`](../../libs/doca-pcc/SKILL.md): DPA-capable BlueField + firmware custom-PCC slot enabled + `doca_pcc_cap_*` agreement) extended with SPCX-specific availability, the version overlay (tool ↔ library ↔ DPACC ↔ firmware), the layered error taxonomy (install / device-binding / fw-slot / DPA-image / algorithm-precondition / live-link-precondition / runtime / version / cross-cutting), the observability surface, and the heavily-overlaid safety posture (a wrong CC algorithm on production can melt the fabric). - `TASKS.md` — step-by-step workflows for the in-scope task verbs: `install` (host-side DOCA install + DPA prerequisites + firmware custom-PCC slot), `configure` (SPCX-vs-PCC decision + role + algorithm + parameters + probe-packet format), `build` (route to install — the host-side tool is shipped; the DPA-side algorithm is user-built by DPACC), `modify` (refuse — do not patch the binary; modify the invocation, algorithm, and parameters), `run` (the prepare → smoke → contention-positive evaluation flow), `test` (iterative loop on the replica before production), `debug` (walk the error taxonomy), `use` (the *"safe to roll forward"* decision with evidence + rollback + escalation), plus a `Deferred task verbs` block. The skill assumes a host where DOCA is already installed, a BlueField with a DPA processor and the firmware-level custom-PCC slot enabled is present and visible, the DPACC compiler is installed at a version matched to the host-side DOCA, the user already knows how (at sketch level) to write the DPA-side SPCX algorithm (or has a shipped reference algorithm to consume), and a non-prod RDMA / RoCE fabric with controllable contention is available for evaluation. ## What this skill deliberately does not ship This skill is **agent guidance**, not a samples or scripts bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add: - **A specific congestion-control algorithm.** SPCX *loads* an algorithm the user supplies; the skill refuses to invent algorithm bodies and routes any *"what algorithm should I write"* question to the public DOCA SPCX / DOCA PCC programming guides and to the user's own domain expertise. - **Pre-baked example output** (throughput / latency curves, per-flow counter snapshots). Output is device-, firmware-, fabric-topology-, and workload-specific; pinning one would mislead operators elsewhere. - **Specific flag strings, subcommand names, probe-packet format tokens, or metric names beyond what the public DOCA SPCX page and `--help` document.** The SPCX surface is the newer of the programmable-CC surfaces and the documented flag set evolves; the installed `--help` is the authoritative inventory. - **Wrappers, parsers, or scripts** in any language that consume the tool's output. The output format is documented; users who want to script against it should read the live guide and write the parser against their installed version. - **A specific tuning recommendation derived from a single observation.** CC tuning on a live fabric is high-stakes; the skill prescribes how to *capture evidence and compare against the factory PCC baseline* and refuses to translate a single observation into a parameter-change recommendation without the user's own domain analysis. - **A `samples/` or `reference/` subtree.** This is a thin loader for a shipped CLI; substantive material lives on the public page, in `--help`, and in [`doca-pcc`](../../libs/doca-pcc/SKILL.md) + [`doca-dpa`](../../libs/doca-dpa/SKILL.md). ## Loading order 1. Read this `SKILL.md` first to confirm the user's question is in scope (SPCX-side custom CC work, not factory firmware PCC, not raw DPA cycle profiling, and not algorithm authoring detail). 2. **For the SPCX-vs-PCC decision tree, the authoring vs consumption split, the live-link precondition, the version overlay, the error taxonomy, the observability surface, and the safety posture, see [CAPABILITIES.md](CAPABILITIES.md).** 3. **For the documented invocations and the prepare → smoke → contention-positive evaluation workflow — `install`, `configure`, `build`, `modify`, `run`, `test`, `debug`, `use` — see [TASKS.md](TASKS.md).** ## Related skills - [`doca-pcc`](../../libs/doca-pcc/SKILL.md) — the established host-side library for Programmable Congestion Control. The SPCX tool builds on and links this library; the SPCX-vs-PCC decision tree in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) is the load-bearing routing rule. Conflating the two is the most common programmable-CC first-touch error. - [`doca-pcc-ztr-rttcc-algo`](../../libs/doca-pcc-ztr-rttcc-algo/SKILL.md) — the shipped reference zero-touch RTT-based CC algorithm. When the user wants to deploy a documented reference algorithm via the SPCX path (rather than author one), this is the algorithm-side skill paired with this tool's operator-side workflow. - [`doca-dpa`](../../libs/doca-dpa/SKILL.md) — the host-side DPA control library the SPCX algorithm's DPA-side body builds on. For DPA-level questions (kernel-launch model, DPACC build flags, DPA-side comms / verbs), this is the skill the agent loads alongside. - [`doca-rdma`](../../libs/doca-rdma/SKILL.md) — the library whose RDMA / RoCE flows on the attached BlueField port the SPCX algorithm is controlling. Without RDMA traffic in flight and contention on the fabric, the algorithm has no signal — surface this precondition with the user before any evaluation. - [`doca-pcc-counters`](../doca-pcc-counters/SKILL.md) — the sibling tool for read-only PCC counter inspection. SPCX exposes its own runtime observability surface; the PCC counter tool is the cheaper *"is anything happening on this port"* first step before / during an SPCX evaluation. - [`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md) — the bundle-wide hardware-safety meta-policy (pre-flight inventory, OOB requirement, replica-first, observability-before-workload, rollback discipline, escalation). The `## Safety policy` overlay in this skill is heavily layered on the meta-policy; deploying a wrong CC algorithm on a production fabric is a *meta-policy STOP* case. - [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) — routing to the public DOCA SPCX programming guide, the public DOCA PCC programming guide, the public DOCA DPA / DPACC guides, and the rest of the public DOCA documentation set. - [`doca-version`](../../doca-version/SKILL.md) — canonical DOCA version-handling rules. The `## Version compatibility` section in [`CAPABILITIES.md`](CAPABILITIES.md) is a concise overlay that redirects here for the body and adds the *tool ↔ `doca-pcc` library ↔ DPACC ↔ firmware custom-PCC slot* matching rule. - [`doca-setup`](../../doca-setup/SKILL.md) — env preparation, install verification, DPACC compiler install / verification, BlueField firmware configuration (custom-PCC slot enablement is a firmware-level setting), and the *I have no install yet* path with the public NGC DOCA container. - [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting debug ladder. SPCX-specific debug layers on top of that ladder; cross-link the captured runtime evidence + counter snapshots into a `doca-debug` session when the cause is below DOCA. - [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md) — the bundle's detect → prefer → fall back → report contract for structured helper tools. The command appendix in [`TASKS.md`](TASKS.md) honors this contract. - [`doca-programming-guide`](../../doca-programming-guide/SKILL.md) — general DOCA programming patterns shared by every library / tool surface, including the cross-library `DOCA_ERROR_*` taxonomy this tool's host-side error layer overlays on top of. The default factory PCC algorithms shipped inside ConnectX firmware are **not in scope** for this skill — those work without `doca_spcx_cc` and are configured through firmware-level knobs, not through any host-side library or tool API. Route via [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md). Conflating the factory PCC story with SPCX is the single most common programmable-CC first-touch error.