Doca Spcx Cc Agent Skill

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.

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 +

doca-dpa.

Loading order

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

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

• **For the documented invocations and the

prepare → smoke → contention-positive evaluation

workflow — install, configure, build,

modify, run, test, debug, use — see

TASKS.md.**

Related skills

• doca-pcc — 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

is the load-bearing routing rule. Conflating the

two is the most common programmable-CC first-touch

error.

• doca-pcc-ztr-rttcc-algo

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

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

— 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

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

canonical DOCA version-handling rules. The

## Version compatibility section in

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

— the bundle's detect → prefer → fall back →

report contract for structured helper tools. The

command appendix in TASKS.md

honors this contract.

• doca-programming-guide

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

Conflating the factory PCC story with SPCX is the

single most common programmable-CC first-touch error.