doca-pcc

DOCA PCC

Examples

• "Loading my own congestion control onto a BF port." — this is in scope. Stay on host-side doca_pcc + a DPACC-built doca_pcc_app; do not rewrite the algorithm body here.
• "DOCA_ERROR_NOT_PERMITTED on algorithm load." — check the firmware custom-PCC slot and DPA exposure before changing the load call.

Instructions

Follow Loading order below. Open the tasks companion for configure / load / debug. Open the capabilities companion for the triple-axis cap query. Do not open every companion file.

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 the tasks companion if the user wants to do something (configure / build / modify / run / test / debug); open the capabilities companion 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/SKILL.md 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/SKILL.md to the public DOCA PCC programming guide and to doca-dpa/SKILL.md 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 (doca-public-knowledge-map/SKILL.md#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 and modes

  • the bring-up steps in

  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 and modes

  • the env-precondition checklist in

  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

  Safety policy

  • the firmware-side env fix in

  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 and modes

  • the deferred-topic boundaries in

  Deferred topic boundaries

  which route to doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#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

  Version compatibility

  which cross-links the canonical detection chain in doca-version/SKILL.md and adds the PCC-specific DOCA must match DPACC overlay inherited from doca-dpa/SKILL.md.
• "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

  Error taxonomy

  • the layered ladder in

  debug that escalates to

  doca-debug/SKILL.md.

Audience

This skill serves external developers consuming the DOCA PCC library from the host side — code that calls doca_pcc_* to stand up the per-port context, load the dpacc-produced doca_pcc_app image, attach it to the RoCE-bearing BlueField port, parameterize it, start it, and observe runtime reports. It is not for NVIDIA developers contributing to DOCA PCC, nor the place to learn how to write the DPA-side algorithm body (route via doca-public-knowledge-map/SKILL.md to the public PCC / DPA / DPACC guides).

Language scope. DOCA PCC ships as a host-side C library (pkg-config module doca-pcc). The DPA-side algorithm is a separate translation unit dpacc compiles into the PCC algorithm image — no FFI escape hatch. A Rust / Go / Python host-side wrapper driving doca_pcc_* is still useful; the skill keeps its 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. Concretely:

• Initializing a doca_pcc against a doca_dev that maps to the BlueField port carrying the RDMA / RoCE traffic to be controlled.
• Loading the dpacc-produced doca_pcc_app algorithm image into the doca_pcc context.
• Parameterizing the algorithm and starting the doca_pcc Core context so it begins affecting RoCE traffic on the port.
• Checking which PCC features the active doca_devinfo supports via doca_pcc_cap_* — BlueField generations and firmware revisions differ on permitting a custom PCC algorithm.
• Debugging a DOCA_ERROR_* from doca_pcc_* — disambiguating firmware custom-PCC slot disabled vs device cannot do custom PCC vs image incompatible vs plain doca_dev access denied.
• Designing non-C host-side bindings that drive a separately dpacc-built algorithm image — the env-precondition and capability rules still apply.

Do not load this skill for general DOCA orientation, DOCA / DPACC install, the DPA-side programming model itself, the factory PCC algorithm shipped in ConnectX firmware (firmware- only, no host-side code), or the pcc_counters diagnostic CLI. For those, route through doca-public-knowledge-map/SKILL.md 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:

• the capabilities companion — 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).
• the tasks companion — 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/SKILL.md.

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/SKILL.md, layered with the PCC-specific overrides in

  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 pcc_counters.sh script under tools/pcc_counters/) with its own page; routing lives in doca-public-knowledge-map ## DOCA tools (doca-public-knowledge-map/SKILL.md#doca-tools). Conflating it with the library is the most common PCC first-app design error.

Loading order

1. Read this skill 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).
2. 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 the capabilities companion.
3. For step-by-step workflows — configure, build, modify, run, test, debug — see the tasks companion.

Both companion files cross-link to each other, doca-version/SKILL.md for the canonical DOCA version-handling rules (with the PCC overlay that DOCA must match the DPACC compiler), and doca-public-knowledge-map/SKILL.md 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/SKILL.md — 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/SKILL.md — 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/SKILL.md — 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/SKILL.md — 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/SKILL.md — 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/SKILL.md).
• doca-structured-tools-contract/SKILL.md — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in the tasks companion honors this contract.
• doca-programming-guide/SKILL.md — 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/SKILL.md — 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, a loaded algorithm producing no on-wire change because doca_pcc_start() was never called or the attached port carries no RoCE traffic) overlays on top of that ladder.

"It loads but nothing changes on the wire" is a host-side question. A successful load is not a live algorithm: doca_pcc_start() is the moment it goes live on the port, and PCC only modulates RoCE traffic that already exists on the doca_dev the doca_pcc was created against. Settle both here and do not audit the DPA-side algorithm body: that is doca-dpa/SKILL.md's surface, and reports firing already proves the body runs — what is unproven is that it is bound and live. Ordered checks in

debug.