/doca-pcc

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 compa