Doca Pcc

DOCA PCC

Where to start: This skill assumes DOCA is already installed,

the user's BlueField has a DPA processor that the host can see

through DOCA, the BlueField firmware has the custom-PCC slot

enabled, and the user is doing **hands-on custom PCC work from

the host side** — i.e. using doca-pcc to load a DPA-side

congestion control algorithm onto the BlueField, attach it to a

port handling RDMA / RoCE traffic, and parameterize it from the

host. Open TASKS.md if the user wants to *do*

something (configure / build / modify / run / test / debug);

open CAPABILITIES.md when the question is

*what can the host-side PCC API express* on this version + this

BlueField generation + this firmware. If the user has not

installed DOCA yet, route to

doca-setup first; if the user is

asking how to *write* the DPA-side congestion-control algorithm

itself (the code that runs on the DPA processor, compiled by

dpacc), that is a different scope — route via

doca-public-knowledge-map

to the public DOCA PCC programming guide and to

doca-dpa for the host-side DPA

lifecycle this skill builds on. If the user only wants to

*inspect* PCC counters at runtime without writing a custom

algorithm, that is the pcc_counters CLI tool — route via

doca-public-knowledge-map ## DOCA tools;

this skill is for *custom* algorithms only.

Example questions this skill answers well

The CLASSES of PCC questions this skill is built to answer,

each with one worked example. The agent should treat the *class*

as the load-bearing piece — the worked example is a single

instance.

• **"How do I deploy my own custom congestion control algorithm

onto a BlueField port carrying RDMA / RoCE traffic?"** —

worked example: *"load a small DPA-side PCC algorithm and

attach it to the BlueField port that handles my RoCE traffic"*.

Answered by the two-side-program model + the host-side

load-and-attach workflow in

CAPABILITIES.md ## Capabilities and modes

+ the bring-up steps in

TASKS.md ## configure.

• **"Does this BlueField + firmware actually allow a custom PCC

algorithm, and which PCC features does my DOCA install

expose?"** — worked example: *"my host has a BlueField and the

default factory PCC works; can I drop in a custom algorithm

instead?"*. Answered by the triple-axis precondition rule

(BlueField generation must carry a DPA, firmware must have the

custom-PCC slot enabled, doca_pcc_cap_* against the active

doca_devinfo must agree) in

CAPABILITIES.md ## Capabilities and modes

+ the env-precondition checklist in

TASKS.md ## configure step 1.

• **"Why does my custom PCC fail with DOCA_ERROR_NOT_PERMITTED

even though I have doca_dev access?"** — worked example:

*"the BlueField firmware in this host has the custom-PCC slot

disabled"*. Answered by the permission matrix in

CAPABILITIES.md ## Safety policy

+ the firmware-side env fix in

TASKS.md ## configure step 1.

• **"Is this doca-pcc library the right tool for what I want,

or do I want the default firmware PCC or the

pcc_counters CLI?"** — worked example: *"I just want to

read PCC counters without touching the algorithm"*. Answered

by the path-selection rule in

CAPABILITIES.md ## Capabilities and modes

+ the deferred-topic boundaries in

CAPABILITIES.md ## Deferred topic boundaries

which route to

doca-public-knowledge-map ## DOCA tools

for the counter tool.

• **"Is the host-side PCC API I'm reading about on my installed

DOCA?"** — worked example: *"is the host-side load helper I

see in the docs available against the DOCA + DPACC versions on

this host?"*. Answered by the version-compatibility overlay in

CAPABILITIES.md ## Version compatibility

which cross-links the canonical detection chain in

doca-version and adds the

PCC-specific *DOCA must match DPACC* overlay inherited from

doca-dpa.

• **"What does this DOCA_ERROR_* from a doca_pcc_* call mean

and which layer caused it?"** — worked example:

*"DOCA_ERROR_DRIVER on the host-side algorithm-load call —

is it DOCA, the firmware-side custom-PCC slot, or the DPACC-

produced image?"*. Answered by the PCC overlay on the

cross-library taxonomy in

CAPABILITIES.md ## Error taxonomy

+ the layered ladder in

TASKS.md ## debug that escalates to

doca-debug.

Audience

This skill serves **external developers building applications

that consume the DOCA PCC library from the host side** — i.e.,

users whose code calls doca_pcc_* from host C / C++ to stand

up the per-PCC-instance context, load a DPA-side PCC algorithm

image that dpacc produced from their DPA-side source, attach

it to the BlueField port that carries the RDMA / RoCE traffic

the algorithm is meant to control, parameterize the algorithm,

start the context, and observe runtime reports back from the

algorithm. It is *not* for NVIDIA developers contributing to

DOCA PCC itself, nor is it the place to learn how to *write*

the DPA-side congestion-control algorithm itself (that path

goes through the public DOCA PCC programming guide and the

companion DOCA DPA / DPACC guides via

doca-public-knowledge-map).

Language scope. DOCA PCC ships as a host-side C library

with pkg-config module name doca-pcc. The host-side API is

C; the DPA-side congestion-control algorithm is a separate

translation unit written in the language the DPACC compiler

accepts and compiled by dpacc into a binary that the host

packages into the executable as the PCC algorithm image. The

shipped samples under /opt/mellanox/doca/samples/doca_pcc/

are written in C plus DPA-side source (NVIDIA's choice).

Other-language consumers are limited in practice — the

DPA-side algorithm has no FFI escape hatch because it must be

a translation unit dpacc accepts — but a Rust / Go / Python

host-side wrapper that drives doca_pcc_* setup and loads a

PCC algorithm image built separately is still useful, and the

skill keeps the lifecycle, capability-discovery,

env-precondition, and error-taxonomy guidance language-neutral.

When to load this skill

Load this skill when the user is doing hands-on DOCA PCC work

from the host side for a custom congestion control

algorithm, in any host language plus a DPA-side translation

unit built by dpacc. Concretely:

• Initializing a doca_pcc against a doca_dev that maps to

the BlueField port carrying the RDMA / RoCE traffic to be

controlled.

• Loading a PCC algorithm image (doca_pcc_app) that dpacc

produced from the user's DPA-side congestion-control algorithm

source, into the doca_pcc context.

• Parameterizing the loaded algorithm with the host-side knobs

the algorithm exposes, and starting the doca_pcc Core

context so the algorithm begins affecting RDMA / RoCE

traffic on the attached port.

• Checking which PCC features are supported on the active

doca_devinfo via the doca_pcc_cap_* family — BlueField

generations and firmware revisions differ in whether they

permit a custom PCC algorithm.

• Debugging a DOCA_ERROR_* returned from a doca_pcc_* call

— in particular disambiguating *firmware-level custom-PCC

slot disabled* from *device does not support custom PCC at

all* from *algorithm image incompatible with this device*

from *standard doca_dev access denied*.

• Designing host-side bindings in a non-C language that drive

a custom PCC algorithm image they built separately with

dpacc — the env-precondition and capability-discovery rules

in this skill still apply.

Do not load this skill for general DOCA orientation, install

of DOCA or the DPACC compiler, the DPA-side programming model

itself (how to write the congestion-control algorithm body that

runs on the DPA), questions about the default factory PCC

algorithm shipped in ConnectX firmware (no host-side doca-pcc

code needed — that path is firmware-only configuration), or

questions about the pcc_counters diagnostic CLI (route via

doca-public-knowledge-map ## DOCA tools).

For all of those, route through

doca-public-knowledge-map

to the matching upstream guide.

What this skill provides

This is a thin loader. The body keeps only the orientation

needed to pick the right next file. The substantive

PCC-specific material lives in two companion files:

• CAPABILITIES.md — what the host-side PCC API can express on

this version + this BlueField generation + this firmware: the

per-PCC-instance doca_pcc context, the loaded doca_pcc_app

algorithm image produced by dpacc, the attach-to-port

semantics that bind the algorithm to the RDMA / RoCE traffic

it will control, the capability-query surface

(doca_pcc_cap_*), the PCC error taxonomy mapped onto the

cross-library DOCA_ERROR_* set, the observability surface

(host-side reports plus the public PCC counter tool reachable

via doca-public-knowledge-map), and the safety policy that

gates env preconditions (DPA-capable BlueField, firmware-level

custom-PCC slot enabled, matched DOCA + DPACC versions,

algorithm image and host-side expectations agree).

• TASKS.md — step-by-step workflows for the six in-scope PCC

verbs: configure, build, modify, run, test,

debug. Plus a Deferred task verbs block that points

out-of-scope questions at the right next skill.

The skill assumes a host where DOCA is already installed at

the standard location, a BlueField with a DPA processor is

physically present and visible to the host, the BlueField

firmware has the custom-PCC slot enabled, the DPACC compiler

is installed at a version matched to the DOCA install per the

DOCA Compatibility Policy, and the user already knows how

(at least at a sketch level) to write the DPA-side PCC

algorithm that dpacc will compile. It does not cover

installing DOCA, installing the DPACC compiler, or flipping

firmware-level configuration — those paths go through

doca-setup.

What this skill deliberately does not ship

This skill is agent guidance, not a samples or templates

bundle. To keep the boundary clean, it deliberately does not

contain — and pull requests should not add:

• **Pre-written DOCA PCC application source code or DPA-side

algorithm source, in any language.** The verified PCC source

is the shipped C + DPA-side samples at

/opt/mellanox/doca/samples/doca_pcc/. The agent's job is to

route the user to those files and prescribe a minimum-diff

modification on them via the universal modify-a-sample

workflow in

doca-programming-guide,

layered with the PCC-specific overrides in

TASKS.md ## modify.

• A specific congestion control algorithm. This library

*loads* an algorithm the user supplies; it does *not* define

one. The agent must refuse to invent algorithm bodies and

must route any *"what algorithm should I write"* question to

the public DOCA PCC programming guide and the user's own

domain expertise — that is a research question, not an API

question.

• Standalone build manifests (meson.build,

CMakeLists.txt, …) parked inside the skill. The agent

constructs the build manifest *in the user's project

directory* against the user's installed DOCA + DPACC

compiler, where pkg-config --modversion doca-pcc and the

installed dpacc are the two sources of truth.

• A samples/, bindings/, or reference/ subtree of any

kind. A mock or incomplete artifact in this skill's tree,

even one labeled "reference", is misleading: users will read

it as buildable.

• pcc_counters tool surface. That CLI is a *separate

artifact* (the real tool is the pcc_counters.sh script under

tools/pcc_counters/) with its own public page; routing for it lives in

doca-public-knowledge-map ## DOCA tools.

Conflating it with the doca-pcc library is the single most

common PCC first-app design error.

Loading order

• Read this SKILL.md first to confirm the user's question is

in scope (host-side custom PCC work, not DPA-side algorithm

design and not the counter tool).

• **For the PCC capability matrix, the two-side-program model,

the doca_pcc per-instance context, the loaded doca_pcc_app

algorithm image, the attach-to-port semantics, the

triple-axis precondition rule, the env-precondition policy,

the error taxonomy, the observability surface, and the

safety policy, see CAPABILITIES.md.**

• **For step-by-step workflows — configure, build, modify,

run, test, debug — see TASKS.md.**

Both companion files cross-link to each other,

doca-version for the canonical

DOCA version-handling rules (with the PCC overlay that DOCA

must match the DPACC compiler), and

doca-public-knowledge-map

whenever the right answer is "look it up in the public DOCA

PCC programming guide, the public DPA / DPACC guides, the

pcc_counters tool guide, or in the on-disk install

layout" rather than "PCC host-side-specific guidance".

Related skills

• doca-public-knowledge-map —

the routing table for every public DOCA documentation

source and the on-disk layout of an installed DOCA package.

The PCC public guide is at

<https://docs.nvidia.com/doca/sdk/DOCA-PCC/index.html>; the

pcc_counters diagnostic CLI lives under the DOCA Tools

umbrella as a *companion surface* rather than a redefined

artifact here.

• doca-dpa — the host-side DPA

control library that PCC depends on conceptually: the

custom PCC algorithm *is* DPA-side code, compiled by the

DPACC compiler, and the host-side doca-pcc Core lifecycle

follows the same shape as the doca-dpa Core lifecycle. The

agent loads doca-dpa alongside this skill when the user

has DPA-level questions (kernel-launch model, DPA-side

libraries) that PCC is layered on top of.

• doca-rdma — the library whose

traffic the custom PCC algorithm is controlling. The custom

PCC algorithm affects RDMA / RoCE flows on the attached

BlueField port; if the user has not yet set up RDMA / RoCE

traffic on that port, there is nothing for the algorithm to

act on, and doca-rdma is the skill that brings that

traffic up.

• doca-setup — env preparation,

install verification, DPACC compiler install / verification,

BlueField firmware configuration (including the custom-PCC

slot enable), and the *I have no install yet* path with the

public NGC DOCA container. This skill assumes its

preconditions are satisfied AND that DPACC is installed at a

version that matches DOCA AND that the firmware-level

custom-PCC slot is enabled.

• doca-version — canonical

DOCA version-handling rules. This skill's `## Version

compatibility` cross-links the four-way match rule and adds

the PCC-specific *DOCA-and-DPACC must match* overlay per the

DOCA Compatibility Policy (inherited from

doca-dpa).

• doca-structured-tools-contract —

the bundle's structured-tools precedence rule (detect /

prefer / fall back / report). The Command appendix in

TASKS.md honors this contract.

• doca-programming-guide —

general DOCA programming patterns shared by every library:

the canonical pkg-config + meson build pattern, the

universal modify-a-shipped-sample first-app workflow, the

universal Core-context lifecycle, the cross-library

DOCA_ERROR_* taxonomy, and the program-side debug order.

This skill layers PCC specifics on top.

• doca-debug — the cross-cutting

debug ladder (install / version / build / link / runtime /

program / driver). PCC-specific debug (custom-PCC slot not

enabled in firmware, DPACC + DOCA version skew, algorithm

image rejected as incompatible with the device, traffic on

the attached port not being affected because the algorithm

body has no effect path) overlays on top of that ladder.

The default factory PCC algorithms shipped inside ConnectX

firmware are not in scope for this skill — those work

without doca-pcc and are configured through firmware-level

knobs, not through any host-side library API. The

pcc_counters diagnostic CLI is also not in scope —

it is a separate artifact for *inspecting* runtime PCC

counters and lives under the public DOCA Tools umbrella.

Conflating either of those with the doca-pcc library is the

single most common PCC first-app design error.