doca-spcx-cc

license: Apache-2.0name: doca-spcx-ccdescription: >  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    - spcxcompatibility: >  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 companion (heavily cross-linked to doca-hardware-safety/SKILL.md): 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 the capabilities companion, which redirects to the canonical 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 the capabilities companion
  • the layered walk in the tasks companion.

Audience

This skill serves external developers, platform operators, and AI agents authoring, loading, and evaluating an SPC-X 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 the ZTR-RTT CC documentation via doca-public-knowledge-map 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 PCC programming guide and the doca-pcc/SKILL.md + 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/SKILL.md).

The tool is shipped as a CLI binary under /opt/mellanox/doca/tools/, not a library you link against; it uses the same kind: tool three-file shape as the rest of the bundle.

Language scope

doca_spcx_cc is a C host-side CLI that links the host-side 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 PCC / DPACC guides via 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 the capabilities companion.
• 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/SKILL.md, doca-pcc/SKILL.md, doca-dpa/SKILL.md, or doca-setup/SKILL.md.

What this skill provides

This is a thin loader. Substantive material lives in two companion files:

• the capabilities companion — 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/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).
• the tasks companion — 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 PCC programming guide 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.
• Flag strings, subcommand names, probe-packet format tokens, or metric names beyond the DOCA release notes and --help. This surface still evolves; the installed --help is the authoritative inventory.
• Wrappers, parsers, or scripts consuming the tool's output. The format is documented; script against your installed version using the release notes.
• A 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 turn one observation into a parameter change without the user's own domain analysis.
• A samples/ or reference/ subtree. This is a thin loader for a shipped CLI; substantive material lives in the release notes, in --help, and in doca-pcc/SKILL.md + doca-dpa/SKILL.md.

Loading order

1. Read this skill 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 the capabilities companion.
3. For the documented invocations and the prepare → smoke → contention-positive evaluation workflow — install, configure, build, modify, run, test, debug, use — see the tasks companion.

Related skills

• doca-pcc/SKILL.md — the host-side Programmable Congestion Control library SPCX builds on and links. The SPCX-vs-PCC decision tree in the capabilities companion is the load-bearing routing rule; conflating the two is the most common programmable-CC first-touch error.
• doca-dpa/SKILL.md — the DPA control library the algorithm's DPA-side body builds on: kernel-launch model, DPACC build flags, DPA-side comms / verbs.
• doca-rdma/SKILL.md — the RDMA / RoCE flows being controlled. Without traffic in flight and contention on the fabric the algorithm has no signal; surface this precondition before any evaluation.
• doca-pcc-counters/SKILL.md — read-only PCC counter inspection; the cheaper "is anything happening on this port" step before or during an SPCX evaluation.
• doca-hardware-safety/SKILL.md — the bundle-wide hardware-safety meta-policy this skill's ## Safety policy layers on. Deploying a wrong CC algorithm on a production fabric is a meta-policy STOP case.
• doca-public-knowledge-map/SKILL.md — routing to the public SPCX, PCC, and DPA / DPACC guides.
• doca-version/SKILL.md — canonical DOCA version handling. ## Version compatibility in the capabilities companion adds the tool ↔ doca-pcc ↔ DPACC ↔ firmware custom-PCC slot matching rule.
• doca-setup/SKILL.md — env preparation, install and DPACC compiler verification, BlueField firmware configuration (the custom-PCC slot is a firmware-level setting), and the no install yet path via the public NGC DOCA container.
• doca-debug/SKILL.md — the cross-cutting debug ladder. Cross-link runtime evidence and counter snapshots into a doca-debug session when the cause sits below DOCA.
• doca-structured-tools-contract/SKILL.md — the detect → prefer → fall back → report contract the command appendix in the tasks companion honors.
• doca-programming-guide/SKILL.md — shared DOCA programming patterns, including the cross-library DOCA_ERROR_* taxonomy this tool's error layer overlays.

The factory PCC algorithms inside ConnectX firmware are not in scope: they work without doca_spcx_cc and are configured through firmware knobs, not a host-side API. Route via doca-public-knowledge-map/SKILL.md.