/doca-pcc-counters

license: Apache-2.0
name: doca-pcc-counters
description: >
  Use this skill when the user is invoking the DOCA PCC Counters tool
  — the `pcc_counters.sh` bash script under the DOCA tools directory —
  to arm and read the fixed firmware/hardware PCC (Programmable
  Congestion Control) diagnostic counters (CNP, RTT, WRED-drop, etc.)
  on a ConnectX / BlueField device via mst + the mlx5 debugfs
  `diag_cnt` interface. The script takes two positional args —
  `set | query` and an mst device path — with no `--help` or
  subcommands. Trigger even without "pcc_counters.sh" or "PCC
  counters": "how do I read the CNP / RTT / WRED-drop counters",
  "PCC counter stuck at zero", "the script says Bad Device", or "is
  congestion control dropping packets on this port?". Route elsewhere
  for writing a custom PCC algorithm (doca-pcc), factory firmware PCC
  config, DOCA install, or fleet-wide CC tuning.
metadata:
  kind: tool
compatibility: >
  Requires DOCA/MFT on Linux with a ConnectX-6 or newer or BlueField
  device, mst tools, mounted debugfs, and root access to the mlx5
  diag_cnt interface. The script reads fixed firmware and hardware
  diagnostics independently of custom PCC code. Its set operation
  changes which counters are collected, not congestion-control or
  forwarding behavior; treat later fleet tuning as a separate
  high-stakes action.

DOCA PCC Counters (`pcc_counters.sh`)

**Where to start:** This is a tool skill for invoking `pcc_counters.sh` — a small bash script that arms and reads the device's fixed set of firmware / hardware **PCC diagnostic counters** (CNP count, RTT-perf, WRED-drop, RTT-gen, handled events) through the mlx5 debugfs `diag_cnt` interface. Open [`TASKS.md`](TASKS.md) and start at [`## run`](TASKS.md#run) for the canonical `set`-then-`query` sequence, or [`## debug`](TASKS.md#debug) when the user reports *"`ERROR: Bad Device`"*, *"counter stuck at zero"*, or *"the dump is empty"*. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *which counters the script reports and how it reaches them*. If the user has not installed DOCA / MFT yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first.

This skill is the **firmware / HW PCC counter readout** surface. It is NOT the host-side control library that loads custom congestion-control kernels onto the DPA (that is [`doca-pcc`](../../libs/doca-pcc/SKILL.md)) and it is NOT the firmware PCC *algorithm* configuration (that path is firmware configuration, routed via [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)). The counters this script reads are device / firmware diagnostic counters that exist **regardless of whether a custom `doca-pcc` DPA kernel is running** — do not condition them on a custom kernel being loaded.

Example questions this skill answers well

The CLASSES of `pcc_counters.sh` questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• **"How do I read the PCC diagnostic counters on this

device?"** — worked example: *"arm and dump the CNP / RTT / WRED-drop counters for `/dev/mst/mt41692_pciconf0`"*. Answered by the fixed counter set in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the `set`-then-`query` invocation in

[`TASKS.md ## run`](TASKS.md#run).

• **"What is the smallest legal invocation?"** — worked

example: *"what exactly do I type?"*. Answered by the two-positional-argument contract (`set | query` + an mst device path) in [`TASKS.md ## run`](TASKS.md#run).

• **"The script printed `ERROR: Bad Device` — what's wrong?"**

— worked example: *"my device path is not matching"*. Answered by the device-resolution layer in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)

• [`TASKS.md ## debug`](TASKS.md#debug).
• **"A counter is stuck at zero — is the device idle, the

counters not armed, or genuinely no events?"** — worked example: *"`PCC_CNP_COUNT` reads 0 after `query`"*. Answered by the arm-before-read rule and the layered diagnosis in [`TASKS.md ## debug`](TASKS.md#debug) + [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).

• **"Is this script on my install, and where?"** — worked

example: *"is `pcc_counters.sh` present and where does the install put it"*. Answered by the install overlay in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which redirects to the canonical [`doca-version`](../../doca-version/SKILL.md) rules.

Audience

This skill serves **operators, developers, and AI agents who need to read a ConnectX / BlueField device's firmware PCC diagnostic counters** to reason about congestion-control behaviour (CNP generation, RTT requests/responses, WRED drops) on a port. Concretely:

• A network operator confirming whether congestion-control

events (CNPs, RTT, WRED drops) are occurring on a device.

• A developer correlating a custom `doca-pcc` algorithm's

effect with the device-level PCC diagnostic counters (the script reads the firmware counters; the custom algorithm itself is a separate surface owned by [`doca-pcc`](../../libs/doca-pcc/SKILL.md)).

• An AI agent producing a *PCC counter snapshot* as evidence

for a congestion-control investigation.

It is **not** for users debugging the script's bash itself, **not** the place to learn how to write a custom PCC algorithm — that audience belongs in [`doca-pcc`](../../libs/doca-pcc/SKILL.md) — and **not** the place for users who want to configure the factory firmware PCC algorithm (route via [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md)).

`pcc_counters.sh` is shipped as a **plain bash script** installed under the DOCA tools directory (per `install_data` in `tools/pcc_counters/meson.build`), not a compiled binary and not a library you link against. The skill uses the bundle's `kind: tool` three-file shap