Doca Spcx Cc

NVIDIAOfficialCreated by NVIDIA

Skill
Tool integration
Software development
Apache-2.0
Medium risk

From the author

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.

— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The doca-spcx-cc skill provides guidance for using the host-side doca_spcx_cc CLI tool to load, parameterize, and monitor SPC-X congestion-control algorithms on NVIDIA BlueField DPU hardware. It focuses on the operational workflow of deploying custom algorithms onto a DPA processor and evaluating their performance against live RDMA/RoCE fabric traffic. The skill emphasizes the critical requirement of generating actual fabric contention to observe algorithm behavior, provides a decision framework for choosing between SPCX and standard PCC surfaces, and outlines safety protocols for testing and production deployment.

What it does

Provides operational guidance for the doca_spcx_cc CLI tool.
Facilitates the loading, parameterization, and lifecycle management of SPC-X congestion-control algorithms.
Defines the decision tree for selecting between SPCX, doca-pcc, and factory firmware PCC.
Outlines the evaluation workflow for testing algorithms on non-production RDMA/RoCE fabrics.
Surfaces diagnostic procedures for common errors like DOCA_PCC_PS_ERROR.
Establishes safety and observability gates for transitioning algorithms to production.

When to use it

When you need to load or manage a custom SPC-X congestion-control algorithm on a BlueField DPU.
When evaluating the performance of a congestion-control algorithm under controlled fabric contention.
When deciding whether to implement a custom algorithm via the SPCX or doca-pcc surface.
When troubleshooting an SPCX session that is loaded but shows no impact on throughput or latency.
When preparing to roll out a custom congestion-control algorithm to a production environment.

Advantages

Provides a structured approach to high-stakes congestion-control deployment.
Prevents common pitfalls by enforcing a contention-positive evaluation requirement.
Clarifies the complex version-matching dependencies between the tool, library, compiler, and firmware.
Offers a clear safety framework for production cutovers.
Reduces ambiguity by explicitly defining the scope boundaries between SPCX, PCC, and DPA authoring.

Usage examples

“I want to write a new RTT-based congestion-control algorithm for my RoCE fabric — which surface do I target?”: The agent will guide you through the SPCX-vs-PCC-vs-factory-firmware decision tree to determine if SPCX is the appropriate surface based on your specific install and algorithm requirements.
“My SPCX algorithm appears to load cleanly but the link's throughput is unchanged — what's going on?”: The agent will help you verify if the link is experiencing actual contention, as congestion-control algorithms have no observable effect on idle links, and guide you through the error taxonomy.
“My CC algorithm works on the lab BlueField pairs; can I push it to the production fleet?”: The agent will evaluate your request against the safety overlay, requiring evidence from contention-positive testing, a documented rollback plan, and an established observability gate.
“doca_spcx_cc exits with DOCA_PCC_PS_ERROR on start.”: The agent will walk you through the layered error taxonomy to isolate whether the issue stems from the device, firmware slot, DPA image, or algorithm configuration.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/doca-spcx-cc/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip doca-spcx-cc.zip -d .agents/skills

Documentation by NVIDIA

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

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

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.

Files

ATTRIBUTION.mdAdded by AutoGineer894 B
BENCHMARK.md9.9 KiB
CAPABILITIES.md24.0 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md17.3 KiB
SKILLCARD.yaml2.7 KiB
TASKS.md29.8 KiB
evals/evals.json3.3 KiB
skill-card.md5.3 KiB
skill.oms.sig5.1 KiB

CAPABILITIES.md

DOCA SPCX Congestion-Control Tool — Capabilities

Where to start: doca_spcx_cc is the operator-side CLI for the documented SPC-X congestion-control surface — an extension on top of the established doca-pcc/SKILL.md story. The pattern overview below names the recurring doca_spcx_cc-class questions. Pick the pattern first, then drill into the H2 that owns the substance. For the how of executing each pattern, jump to TASKS.md.

This file is loaded by SKILL.md. It documents what SPCX expresses that PCC does not (and where the surfaces overlap), the SPCX-vs-PCC-vs-factory-firmware decision tree, the algorithm-authoring vs algorithm-consumption split, the role decision (RP / NP) and the documented probe-packet format axis, the live-link / contention precondition that makes any signal meaningful, the runtime observability surface, the version overlay, the layered error and observability surfaces, and the heavily-overlaid safety posture — deploying a wrong CC algorithm on a production fabric can melt it. For step-by- step invocations and the prepare → smoke → contention- positive evaluation workflow, see TASKS.md.

Pattern overview

Every doca_spcx_cc-class question this skill teaches resolves into one of SIX patterns. The patterns are CLASSES — they apply across every SPCX-class algorithm and every RDMA / RoCE fabric topology the tool can drive, not just one.

`doca_spcx_cc` pattern	Class shape	Where the substance lives
1. SPCX vs PCC vs factory firmware	Picking the right programmable-CC surface for the user's algorithm + install. SPCX is the SPC-X CC extension this tool drives; `doca-pcc/SKILL.md` is the library for writing your own algorithm; factory PCC is the firmware-resident default that needs no host-side code. The agent surfaces all three before committing.	`## Capabilities and modes` decision-tree table + TASKS.md ## configure step 1
2. Authoring vs consumption	The DPA-side algorithm body is either user-authored (the user wrote the algorithm and DPACC compiled it) or consumed (the user is deploying a documented shipped reference such as the zero-touch RTT-based algorithm; see the ZTR-RTT CC documentation via `doca-public-knowledge-map`). The tool's harness is the same; the algorithm-side discipline differs.	`## Capabilities and modes` authoring-vs-consumption table + TASKS.md ## configure step 3
3. Role + probe packet format	The host-side role (Reaction Point / Notification Point per the public DOCA PCC documentation), the probe-packet format (e.g. CCMAD as the public default; the tool's `--probe-packet-format` axis exposes the documented set), and the threads / cores axis.	`## Capabilities and modes` role + probe-packet table + TASKS.md ## configure step 4
4. Live link + contention	The load-bearing safety invariant. A CC algorithm has no observable signal without actual contention on the fabric. Evaluating SPCX on an idle link tells you nothing; evaluating on a saturated link is the test. The agent refuses any "my algorithm is broken because nothing changed" conclusion drawn from an idle link.	`## Safety policy` live-link rule + TASKS.md ## test
5. Diagnose a session failure	Walk the error taxonomy in `## Error taxonomy` — install / device-binding / fw-slot / DPA-image / algorithm-precondition / live-link-precondition / runtime / version / cross-cutting — instead of guessing.	`## Error taxonomy` + TASKS.md ## debug
6. Roll-forward vs roll-back decision	A CC algorithm that "works" on a replica is not the same as a CC algorithm that is safe on production. The skill's `## use` verb is the documented decision gate: blast-radius bounded, observability gate proven, OOB reachable, factory-PCC rollback rehearsed, escalation path documented.	`## Safety policy` roll-forward gate + TASKS.md ## use

Two cross-cutting rules that apply to every pattern above:

A CC algorithm has no signal under no contention. The agent's rule for any "my SPCX algorithm changed nothing" report: the FIRST question is "was the link actually congested when you observed", not "is the algorithm broken". Idle-link evaluations are non-results.
Production CC is high-stakes. Deploying a wrong or unstable CC algorithm on a production RDMA fabric can cascade into flow collapse, queue blow-up, or persistent link instability. The bundle-wide hardware-safety meta-policy in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) applies heavily here; the per-artifact overlay in ## Safety policy layers SPCX-specific rules on top.

Capabilities and modes

doca_spcx_cc is shipped as a single CLI binary under /opt/mellanox/doca/tools/ on every DOCA install that includes the SPCX optional component. It links the host-side doca-pcc/SKILL.md library and loads a DPA-side SPCX algorithm image produced by the DPACC compiler onto the BlueField's DPA processor. The interaction model is the doca-pcc/SKILL.md two-side-program model extended with the SPCX-side runtime; the agent does not separately invent a new lifecycle for SPCX.

SPCX-vs-PCC-vs-factory-firmware decision tree. The load-bearing routing rule before any code:

Surface	When it is the right choice	Where it lives
Factory PCC (firmware-resident default)	The user wants a documented, supported CC algorithm with no custom code; firmware-level configuration is sufficient; no programmable-CC slot is required.	Firmware configuration via `mlxconfig`-class knobs; route via `doca-public-knowledge-map/SKILL.md`.
`doca-pcc/SKILL.md` (stable, established)	The user wants a custom CC algorithm on the established PCC surface; the install supports it; the BlueField generation + firmware exposes the custom-PCC slot.	`doca-pcc/SKILL.md` host-side lifecycle + DPA-side algorithm via DPACC.
`doca_spcx_cc` / SPCX (SPC-X CC extension)	The user wants the documented SPCX-class flexibility (the extension surface this tool drives), the install has SPCX exposed, and the user accepts that SPCX is the newer of the two surfaces (potentially preview / limited HW on some installs).	This skill (operator side) + the DPA-side SPCX algorithm via DPACC.

The agent's rule: probe before committing. Confirm which surfaces are exposed on the user's install (via doca_pcc_cap_* + the SPCX availability per the public guide + doca_spcx_cc --help on the installed version); do not assume SPCX is available just because the user asked for it.

Authoring vs consumption table. The DPA-side algorithm body comes from one of two sources:

Source	What the user has	Skill pairing
User-authored algorithm	A DPA-side translation unit the user wrote and DPACC compiled.	This skill (operator harness) + `doca-pcc/SKILL.md` (library) + `doca-dpa/SKILL.md` (DPA programming model) + the public DOCA PCC programming guide.
Shipped reference algorithm	A documented NVIDIA reference algorithm such as the zero-touch RTT-based CC (ZTR-RTT).	This skill (operator harness) + the ZTR-RTT CC documentation via `doca-public-knowledge-map` (parameters and counters).

The operator-side flow is the same in both cases; the algorithm-side discipline (review, parameter tuning, rollback to the previous algorithm version) differs.

Role + probe-packet format axis. SPCX inherits the PCC two-role model documented in the public DOCA PCC programming guide:

Role	What it is	When it is loaded
Reaction Point (RP)	The role that REACTS to congestion signal by adjusting send rate. The shipped `doca_spcx_cc` binary runs in this role and registers no runtime `--role` flag (confirm with `--help`). The agent does NOT quote `--role RP`; it loads RP by running the shipped binary as-is.	The standard custom-CC role; loaded on the side of the fabric that is sourcing the RDMA / RoCE traffic and that needs to be rate-adjusted.
Notification Point (NP)	The role that GENERATES the congestion signal — typically the receive side or a switch ASIC. The shipped binary exposes no NP switch; route NP-side questions to the public SPC-X CC documentation via `doca-public-knowledge-map ## DOCA tools` and confirm on `--help`. The agent does NOT invent a runtime `--role` flag that the binary does not register.	When the SPCX algorithm needs a custom NP-side behaviour different from the documented factory behaviour.

The probe-packet format axis (--probe-packet-format) selects between the documented formats (CCMAD per the public default; the full set is on the installed --help). The two halves of the deployment must agree on the probe-packet format.

The thread / core axis follows the PCC convention from doca-pcc/SKILL.md: host-side threads pinned to specific cores process the host-side half of the SPCX session. The shipped sample documents a default thread count and core list; the agent re-confirms against --help on the installed binary.

Live-link + contention rule (load-bearing). SPCX algorithms are programmable congestion-control algorithms; they only modulate behaviour when there is congestion to respond to. The evaluation precondition:

A live RDMA / RoCE link is up between two BlueField endpoints (or one BlueField endpoint + a documented peer).
Actual contention exists — concurrent flows sharing a bottleneck, queue occupancy non-trivial, ECN / RTT signals firing. An idle link with no flows shows nothing regardless of how the algorithm is written.
The contention pattern matches the algorithm's designed signal — e.g. an RTT-based CC algorithm needs RTT variation; a marking-based algorithm needs ECN-capable receivers.

The agent's rule for evaluation: refuse to draw a conclusion from an idle-link or contention-absent run; the run is uninformative by construction.

SPCX runtime observability surface. The host-side tool prints a status indicator (per the doca-pcc/SKILL.md status surface the agent observed in the shipped sample: Active, Standby, Deactivated, Error) and produces tracer- style per-port / per-flow runtime captures the user can correlate against the algorithm's intended behaviour. The exact metric names + tracer formats are authoritative on --help on the installed binary and the DOCA release notes.

Companion observation surfaces. Beyond the tool's own output, the agent typically pairs SPCX evaluation with:

doca-pcc-counters/SKILL.md for read-only per-port / per-flow PCC counter snapshots (the cheaper "is anything happening on this port" surface).
doca-rdma/SKILL.md for the RDMA-side observation primitives the algorithm is meant to modulate (throughput, latency, completion ordering).
The host-OS RDMA observability surface (counters, perfquery, etc.) when the cause is below DOCA.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.

The doca_spcx_cc-specific overlay is:

Tool ↔ library ↔ DPACC ↔ firmware quadruple pairing. The host-side tool, the doca-pcc/SKILL.md library it links, the DPACC compiler that built the DPA-side algorithm image, and the firmware-level custom-PCC slot exposure must agree per the doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility) four-way match rule plus the DPA-specific DOCA must match DPACC overlay doca-dpa/SKILL.md carries plus the firmware-slot precondition doca-pcc/SKILL.md carries.
SPCX availability is install-specific. SPCX is the newer of the programmable-CC surfaces; the public DOCA release notes document the BlueField generations and DOCA versions on which it is available. The agent does NOT assume SPCX is available; the gate is doca_spcx_cc --help succeeding on the installed binary + the DOCA release notes naming the user's BlueField + DOCA combination.
Role / probe-packet format / metric names are versioned. The documented role tokens (RP / NP), probe-packet format tokens, and metric names evolve across releases; re-verify against the installed --help and the DOCA release notes rather than against this skill's prose.
--help and the DOCA release notes are the source of truth for the tool's command-line surface. When they disagree with this skill, they win.

Error taxonomy

doca_spcx_cc's error surface spans the host install, the device / firmware-slot binding, the DPA-side algorithm image, the algorithm's own preconditions, the live-link / contention precondition, the runtime session, and the cross-cutting partial-install / mixed-version layer. The agent distinguishes these layers in escalating order; jumping layers wastes the user's time on the wrong fix.

Install. Binary missing under /opt/mellanox/doca/tools/; SPCX optional component not installed; the host-side doca-pcc/SKILL.md library not linked. Routing: route to doca-setup ## install (doca-setup/TASKS.md#configure) and confirm the version per doca-version TASKS.md ## configure (doca-version/TASKS.md#configure).
Device-binding. Tool runs but cannot bind the target BlueField device. Cause: device PCIe address / IB name does not exist; the BlueField is not visible to DOCA. Routing: confirm device visibility per doca-pcc TASKS.md ## configure (doca-pcc/TASKS.md#configure) step 1.
Firmware custom-PCC slot. Device bound but the firmware-level custom-PCC slot is disabled on the running firmware. Cause: the BlueField's firmware configuration does not have the custom-PCC slot enabled; mlxconfig-class configuration is required to flip it. Routing: walk doca-pcc TASKS.md ## configure (doca-pcc/TASKS.md#configure) step 1's env-precondition checklist + the bundle-wide hardware-safety overlay in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) for the mlxconfig-class change discipline.
DPA-image. Custom-PCC slot enabled but the DPA-side SPCX algorithm image does not load. Cause: image was built against a different DPACC version than the host-side DOCA; image is corrupted; image is the wrong algorithm class (PCC-class loaded into the SPCX harness, or vice versa). Routing: confirm version pairing per ## Version compatibility; re-build the DPA-side image via DPACC if needed.
Algorithm-precondition. Image loaded but the algorithm refuses to start because its own preconditions are not met. Cause: the parameters passed are outside the algorithm's documented ranges; the algorithm requires a probe-packet format the install does not expose; the algorithm requires a peer NP that is not present. Routing: walk the algorithm's own documentation (the public DOCA PCC programming guide for user-authored algorithms, or the ZTR-RTT CC documentation via doca-public-knowledge-map for the shipped reference algorithm).
Live-link / contention. Algorithm running but no observable effect. Cause: the link is idle, the contention is below the algorithm's signal floor, or the contention pattern does not match what the algorithm is designed to react to. Routing: this is NOT a tool / algorithm failure — re-walk the live-link rule in ## Capabilities and modes and the evaluation flow in TASKS.md ## test; generate the appropriate contention before drawing a conclusion.
Runtime. Algorithm running on a live, congested link but the captured behaviour is wrong (rate collapse, oscillation, persistent under-utilisation, queue blow-up). Cause: algorithm bug, parameter mis-tuning, or the algorithm is correct but mis- matched to the fabric topology. Routing: do NOT roll forward; capture the runtime evidence and walk doca-pcc TASKS.md ## debug (doca-pcc/TASKS.md#debug); the rollback path (## Safety policy) is the immediate operational response.
Version. Cross-cutting partial-install / mixed-version per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility). Routing: walk doca-version TASKS.md ## debug (doca-version/TASKS.md#debug) before any further investigation.
Cross-cutting. Cause is below DOCA — driver, firmware, BlueField mode, NUMA, host kernel. Routing: hand off to doca-debug ## debug (doca-debug/SKILL.md) and doca-setup ## debug (doca-setup/TASKS.md#debug).

For the cross-library DOCA_ERROR_* taxonomy at the program-side level (the host-side doca-pcc/SKILL.md calls the SPCX tool internally drives), see doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy).

Observability

doca_spcx_cc's observability surface is the runtime session state + the captured per-port / per-flow trace behaviour + the host-side status surface, paired with read-only counter inspection via doca-pcc-counters/SKILL.md and RDMA-side observation via doca-rdma/SKILL.md.

Host-side status indicator. The host-side tool prints a status indicator following the doca-pcc/SKILL.md process state set: Active, Standby, Deactivated, Error. The agent treats Active as "loaded and exercising the link" and Standby / Deactivated / Error as states that need to be acknowledged before any evaluation conclusion.
Per-port / per-flow runtime captures. The documented tracer-style runtime output the tool produces — re-verify field names + format against --help on the installed binary and the public DOCA release notes.
Companion PCC counter snapshots. Per doca-pcc-counters/SKILL.md — the cheaper "is anything happening on this port" surface. Useful as a sanity check before and during an SPCX evaluation.
RDMA-side metrics. Per doca-rdma/SKILL.md — the throughput / latency / completion-ordering surface the algorithm is meant to modulate.
Captured-evidence tuple. The minimum metadata to attach to any evaluation artifact: (DOCA version, DPACC compiler version, BlueField identity + firmware, algorithm name + version + parameter set, probe-packet format, role assignment per endpoint, fabric topology + contention shape, capture window). Without all of these the evidence is not comparable to the next run.

For the cross-cutting env-side observability primitives (PCIe scans, devlink, mlxconfig), see doca-setup CAPABILITIES.md ## Observability (doca-setup/CAPABILITIES.md#observability). For the program-side observability surface (DOCA log levels, DOCA_LOG_LEVEL, --sdk-log-level), see doca-programming-guide CAPABILITIES.md ## Observability (doca-programming-guide/CAPABILITIES.md#observability).

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

doca_spcx_cc is a high-stakes tool: it loads a custom congestion-control algorithm onto a BlueField that participates directly in an RDMA / RoCE fabric's rate-control loop. A wrong or unstable algorithm on production can cascade into flow collapse, queue blow- up, or persistent link instability — the kind of failure mode that takes a fabric down and is expensive to recover. The rules:

Replica-first is mandatory, not optional. The meta-policy's replica-first rule applies here without modification: every SPCX algorithm is first exercised on a non-prod replica that matches production on BlueField generation, firmware level, host kernel, and fabric topology class, with a contention pattern that exercises the algorithm's design. Skipping the replica because the algorithm "looks small" is the canonical "small CC change becomes a fabric outage" failure.
No contention → no signal → no conclusion. A CC algorithm has no observable behaviour without actual contention on the fabric. The agent refuses to declare an algorithm safe based on an idle-link or contention-absent run; the run is uninformative by construction.
Bounded blast radius before any production cutover. The agent does not recommend loading an SPCX algorithm fleet-wide at first cutover. The rollout is incremental — one BlueField pair, then a small bounded set, then progressively larger bounded sets — with observability + rollback rehearsed at each step.
Factory-PCC rollback is the always-available escape hatch. Every SPCX deployment plan names the rollback path as "revert to the factory PCC algorithm in firmware" (or to the previous programmable-CC algorithm if one was already in place). The rollback is documented and rehearsed on the replica before production is exposed. A plan without a documented rollback is refused per doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) no-rollback rule.
Observability-before-workload. The captured per-port / per-flow tracer output and the companion PCC counter snapshots must be readable end-to-end before the algorithm is asked to handle production traffic. An algorithm running without observability is an algorithm whose next failure has no diagnostic signal to work from.
OOB management path required for production rollout. If the cutover plan touches a BlueField that the operator is managing over the same RDMA link the SPCX algorithm controls, an out-of-band management path is mandatory per doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) OOB rule.
Maintenance-window discipline. Production cutovers run inside an explicit, time-boxed maintenance window with operations notified, per the meta-policy. CC algorithm cutovers are NOT business-hours operations.
Do not invent algorithm parameters, role tokens, probe-packet format tokens, or metric names. The documented surface lives on the DOCA release notes and in --help on the installed binary; prose-derived names are the most common hallucination failure for this skill, and a wrong parameter on a production fabric is exactly the kind of failure the agent exists to prevent.
Refuse the cutover when any gate fails. The agent surfaces failed gates as blocking and does NOT find a creative workaround. The escalation path is the operator's change-control process per doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) no-documented-rollback → refuse-and-escalate rule.

Public-source pointer

The public sources for doca_spcx_cc are the installed --help and the DOCA release notes (Known Issues, Changes and New Features), reachable through doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools). The companion programming-model surface lives in the public DOCA PCC, DOCA DPA, and DPACC guides on the same site; the shipped reference zero-touch RTT-based algorithm lives in the ZTR-RTT CC documentation via doca-public-knowledge-map. Do not invent flags, role tokens, probe-packet format tokens, or metric names beyond what those public sources document, and re-verify against --help on the installed binary.

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

The author says: 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.

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/doca-spcx-cc · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download doca-spcx-cc.zip