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`](TASKS.md) if the user wants to *do*
something (configure / build / modify / run / test / debug);
open [`CAPABILITIES.md`](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`](../../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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the bring-up steps in
  [`TASKS.md ## configure`](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`](CAPABILITIES.md#capabilities-and-modes)
  + the env-precondition checklist in
  [`TASKS.md ## configure`](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`](CAPABILITIES.md#safety-policy)
  + the firmware-side env fix in
  [`TASKS.md ## configure`](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`](CAPABILITIES.md#capabilities-and-modes)
  + the deferred-topic boundaries in
  [`CAPABILITIES.md ## Deferred topic boundaries`](CAPABILITIES.md#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
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#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
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  + the layered ladder in
  [`TASKS.md ## debug`](TASKS.md#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-sid