About this skill
---
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.