Doca Spcx Cc

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 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 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 first.

This skill is the next-gen programmable-CC surface. doca-pcc 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 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.

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
  • the "is SPCX the right surface on this install?" gate in 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
  • the replica-first evaluation flow in 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
  • the "algorithm has no signal under no contention" guidance in TASKS.md ## test + 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 (heavily cross-linked to 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, which redirects to the canonical doca-version 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
  • the layered walk in 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 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 + doca-dpa 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).

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 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.

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.
• 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-pcc, doca-dpa, or doca-setup.

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: 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.