doca-pcc git:20261028.3d06e7eA

Immutable. This exact content never changes and is served at /api/v1/blob/0de942d6c9d057dd.

---
license: Apache-2.0
name: doca-pcc
description: >
  Use this skill when the user is doing hands-on host-side DOCA PCC work
  to load a CUSTOM Programmable Congestion Control algorithm onto a
  BlueField DPU — creating per-port `doca_pcc` contexts, loading a
  `dpacc`-compiled `doca_pcc_app` onto the `doca_dev` for the
  RoCE-bearing port, parameterizing it, walking triple-axis capability
  discovery (DOCA cap-query + DPA-capable BlueField + firmware
  custom-PCC slot enabled), or debugging `DOCA_ERROR_*` from
  `doca_pcc_*`. Trigger even without explicit "DOCA PCC" phrasing —
  implicit forms include "loading my own congestion control onto a BF
  port", "DOCA_ERROR_NOT_PERMITTED on algorithm load",
  "DOCA_ERROR_DRIVER when I attach my custom algorithm", "my custom
  rate-update isn't affecting RoCE traffic", or "load succeeds but no
  on-wire change". Refuse and route elsewhere for DPA-side
  algorithm-body design, the `pcc_counters` CLI, default factory PCC in
  ConnectX firmware, or setting up the RDMA / RoCE traffic — those
  belong to other skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - pcc
    - congestion
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField DPU whose DPA processor is
  exposed to the host AND whose firmware has the custom-PCC slot
  enabled. Also requires the DPACC compiler installed at a version
  matched to DOCA per the DOCA Compatibility Policy. Reads the user's
  local install via `pkg-config doca-pcc` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}. The validation
  steps require a live DOCA install.
---

# 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 installed at
  `/opt/mellanox/doca/tools/pcc_counters.sh`) 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.