/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:
  kind: library
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}.

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 ma