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

1. 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).
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 CAPABILITIES.md.
3. 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.*