doca-pcc git:20261014.bbb601aA

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

---
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@nvidia.com>
  kind: library
  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`](../../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`](../../doca-public-knowledge-map/SKILL.md)
to the public DOCA PCC programming guide and to
[`doca-dpa`](../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`](../../doca-version/SKILL.md) and adds the
  PCC-specific *DOCA must match DPACC* overlay inherited from
  [`doca-dpa`](../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`](../../doca-debug/SKILL.md).

## 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`](../../doca-public-knowledge-map/SKILL.md)).

**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`](../../doca-public-knowledge-map/SKILL.md#doca-tools)).
For all of those, route through
[`doca-public-knowledge-map`](../../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`](../../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`](../../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`](../../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`](../../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`](../../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`](../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`](../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`](../../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`](../../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`](../doca-dpa/SKILL.md)).
- [`doca-structured-tools-contract`](../../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`](../../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`](../../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`](../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.