DOCA PCC Counters (pcc_counters.sh)
Examples
- "How do I read the PCC diagnostic counters on this device?" —
this is in scope. Arm then query; do not treat this as PCC
algorithm tuning.
- "The script printed ERROR: Bad Device." — resolve the mst
path before assuming firmware is broken.
Instructions
Follow Loading order below. Open the tasks companion for run /
debug. Open the capabilities companion for the fixed counter set.
Do not open every companion file.
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
the tasks companion and start at ## run for
the canonical set-then-query sequence, or
## debug when the user reports
"ERROR: Bad Device", "counter stuck at zero", or "the
dump is empty". Open the capabilities companion 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/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/SKILL.md) and it is NOT the
firmware PCC algorithm configuration (that path is firmware
configuration, routed via
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
the capabilities companion
- the
set-then-query invocation in
the tasks companion.
- "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
the tasks companion.
- "The script printed
ERROR: Bad Device — what's wrong?"
— worked example: "my device path is not matching".
Answered by the device-resolution layer in
the capabilities companion
- "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
the tasks companion +
the capabilities companion.
- "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
the capabilities companion,
which redirects to the canonical
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/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/SKILL.md — and not the
place for users who want to configure the factory firmware PCC
algorithm (route via
doca-public-knowledge-map/SKILL.md).
pcc_counters.sh is shipped as a plain bash script
installed under the DOCA tools directory, not a compiled binary and
not a library you link against. The skill uses the bundle's
kind: tool three-file shape (this skill + the capabilities companion
- the tasks companion) so the agent's task-verb contract
(
configure / build / modify / run / test / debug) is uniform
across the bundle.
When to load this skill
Load this skill when the user is — or the agent needs to —
arm and read the device PCC diagnostic counters on a host or
BlueField Arm with the mst tools available and debugfs
mounted. Concretely:
- Arming the diagnostic counters with
set on a target mst
device.
- Reading the armed counters with
query and quoting the
named counter lines verbatim.
- Capturing a counter readout as evidence for a
congestion-control investigation.
Do not load this skill for general DOCA orientation,
custom-PCC algorithm design, the host-side doca-pcc library
API, the factory firmware PCC algorithm, or DOCA / MFT install.
For those, route to
doca-public-knowledge-map/SKILL.md,
doca-pcc/SKILL.md, or
doca-setup/SKILL.md.
What this skill provides
This is a thin loader. Substantive material lives in two
companion files:
- the capabilities companion — what
pcc_counters.sh does: the exact
two-operation surface (set arms the device's diagnostic
counters by writing counter IDs + params to debugfs;
query reads the diag_cnt/dump and prints the named
counters), the FIXED firmware / HW counter set it knows
(PCC_CNP_COUNT, the MAD_RTT_PERF_CONT_*, the
*_EVENT_WRED_DROP family, HANDLED_*_EVENTS, the
DROP_RTT_PORT*/RTT_GEN_PORT* families), how it resolves
an mst device to a PCI address (mst status -v + lspci)
and reaches /sys/kernel/debug/mlx5/<pci>/diag_cnt/, the
install-availability overlay that redirects to
doca-version/SKILL.md, the layered
error taxonomy (script-not-present / bad-device /
not-armed-before-query / debugfs-or-permission /
counter-stuck-at-zero / cross-cutting), and the safety
policy that flags set as a privileged debugfs write and
any CC tuning decision derived from a reading as
high-stakes.
- the tasks companion — step-by-step workflows for the in-scope task
verbs:
configure (route to install + confirm mst /
debugfs / sudo), build (route to install; nothing to
compile — it is a script), modify (refuse — do not patch
the shipped script), run (the set-then-query
sequence), test (confirm the dump contains the named
counters with finite values), debug (the layered
diagnosis ladder), plus a Deferred task verbs block and a
Command appendix.
The skill assumes a host or BlueField where DOCA / MFT is
already installed (mst tools present, debugfs mounted, sudo
available) and the target device is visible to mst status -v.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or scripts
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:
- Invented flags or subcommands.
pcc_counters.sh has
exactly two operations (set, query), takes exactly two
positional arguments, and has NO --help, --version,
list, snapshot, watch, or diff. Do not invent any.
- Pre-baked example counter values. Counter values are
device-, firmware-, and traffic-state-specific; a captured
value will mislead an operator on a different device.
- Wrappers, parsers, or rewritten copies of the script.
The script is the contract; modifying or re-implementing it
is out of scope.
- A specific congestion-control tuning recommendation
derived from a counter reading. That is a high-stakes
domain question — the skill prescribes how to capture the
counters; it refuses to translate a delta into a CC
parameter change without the user's own domain analysis.
- A
samples/ or reference/ subtree. This is a thin
loader for a documented script; substantive material lives
in the script and the public PCC documentation.
Loading order
- Read this skill first to confirm the user's question
is in scope (reading the device's firmware PCC diagnostic
counters; not designing or loading a custom algorithm).
- For what the script does, the fixed counter set, the
debugfs mechanism, the install-availability overlay, the
layered error surface, and the safety posture, see
the capabilities companion.
- For the documented invocations —
configure, build,
modify, run, test, debug, plus the Command appendix — see the tasks companion.
Related skills
doca-pcc/SKILL.md — the host-side
library for writing and loading custom congestion-control
kernels onto the DPA. It is a SEPARATE surface: the
firmware PCC diagnostic counters pcc_counters.sh reads
exist independently of any custom doca-pcc kernel, but an
operator tuning a custom algorithm may read these counters
to observe device-level CC behaviour. Conflating the script
(firmware counter readout) with the library (custom
algorithm load/control) is the most common PCC first-touch
error.
doca-public-knowledge-map/SKILL.md
— routing to the public DOCA / PCC documentation set,
including the firmware PCC algorithm configuration.
doca-version/SKILL.md — canonical
DOCA version-handling rules. The ## Version compatibility
section in the capabilities companion is a concise
overlay that redirects here.
doca-setup/SKILL.md — env preparation,
install verification, mst tools, debugfs, and the
I have no install yet path with the public NGC DOCA
container. This skill assumes its preconditions are
satisfied.
doca-debug/SKILL.md — the
cross-cutting debug ladder. The PCC counter readout slots
in as a read-only device-state evidence source before any
congestion-control tuning recommendation is made.
doca-programming-guide/SKILL.md
— general DOCA programming patterns shared across the
bundle.
1---2license: Apache-2.03name: doca-pcc-counters4description: >5 Use this skill when the user is invoking the DOCA PCC Counters tool —6 the `pcc_counters.sh` bash script under the DOCA tools directory — to7 arm and read the fixed firmware/hardware PCC (Programmable Congestion8 Control) diagnostic counters (CNP, RTT, WRED-drop, etc.) on a ConnectX9 / BlueField device via mst + the mlx5 debugfs `diag_cnt` interface.10 The script takes two positional args — `set | query` and an mst device11 path — with no `--help` or subcommands. Trigger even without12 "pcc_counters.sh" or "PCC counters": "how do I read the CNP / RTT /13 WRED-drop counters", "PCC counter stuck at zero", "the script says Bad14 Device", or "is congestion control dropping packets on this port?".15 Route elsewhere for writing a custom PCC algorithm (doca-pcc), factory16 firmware PCC config, DOCA install, or fleet-wide CC tuning.17metadata:18 source: https://skillmd.com/skills/nvidia/doca-pcc-counters19 author: NVIDIA <doca-feedback@nvidia.com>20 kind: tool21 doca_version: "3.5"22 tags:23 - doca24 - pcc25 - counters26compatibility: >27 Requires DOCA/MFT on Linux with a ConnectX-6 or newer (not28 ConnectX-8) or BlueField29 device, mst tools, mounted debugfs, and root access to the mlx530 diag_cnt interface. The script reads fixed firmware and hardware31 diagnostics independently of custom PCC code. Its set operation32 changes which counters are collected, not congestion-control or33 forwarding behavior; treat later fleet tuning as a separate34 high-stakes action. The validation steps require a live DOCA install.35---3637# DOCA PCC Counters (`pcc_counters.sh`)3839## Examples4041- **"How do I read the PCC diagnostic counters on this device?"** —42 this is in scope. Arm then query; do not treat this as PCC43 algorithm tuning.44- **"The script printed ERROR: Bad Device."** — resolve the mst45 path before assuming firmware is broken.4647## Instructions4849Follow Loading order below. Open the tasks companion for run /50debug. Open the capabilities companion for the fixed counter set.51Do not open every companion file.5253**Where to start:** This is a tool skill for invoking54`pcc_counters.sh` — a small bash script that arms and reads the55device's fixed set of firmware / hardware **PCC diagnostic56counters** (CNP count, RTT-perf, WRED-drop, RTT-gen, handled57events) through the mlx5 debugfs `diag_cnt` interface. Open58the tasks companion and start at `## run` for59the canonical `set`-then-`query` sequence, or60`## debug` when the user reports61*"`ERROR: Bad Device`"*, *"counter stuck at zero"*, or *"the62dump is empty"*. Open the capabilities companion when63the question is *which counters the script reports and how it64reaches them*. If the user has not installed DOCA / MFT yet,65route to `doca-setup/SKILL.md` first.6667This skill is the **firmware / HW PCC counter readout** surface.68It is NOT the host-side control library that loads custom69congestion-control kernels onto the DPA (that is70`doca-pcc/SKILL.md`) and it is NOT the71firmware PCC *algorithm* configuration (that path is firmware72configuration, routed via73`doca-public-knowledge-map/SKILL.md`).74The counters this script reads are device / firmware75diagnostic counters that exist **regardless of whether a custom76`doca-pcc` DPA kernel is running** — do not condition them on a77custom kernel being loaded.7879## Example questions this skill answers well8081The CLASSES of `pcc_counters.sh` questions this skill is built82to answer, each with one worked example. The class is the83load-bearing piece; the worked example is one instance.8485- **"How do I read the PCC diagnostic counters on this86 device?"** — worked example: *"arm and dump the CNP / RTT /87 WRED-drop counters for `/dev/mst/mt41692_pciconf0`"*.88 Answered by the fixed counter set in89 the capabilities companion90 + the `set`-then-`query` invocation in91 the tasks companion.92- **"What is the smallest legal invocation?"** — worked93 example: *"what exactly do I type?"*. Answered by the94 two-positional-argument contract95 (`set | query` + an mst device path) in96 the tasks companion.97- **"The script printed `ERROR: Bad Device` — what's wrong?"**98 — worked example: *"my device path is not matching"*.99 Answered by the device-resolution layer in100 the capabilities companion101 + the tasks companion.102- **"A counter is stuck at zero — is the device idle, the103 counters not armed, or genuinely no events?"** — worked104 example: *"`PCC_CNP_COUNT` reads 0 after `query`"*. Answered105 by the arm-before-read rule and the layered diagnosis in106 the tasks companion +107 the capabilities companion.108- **"Is this script on my install, and where?"** — worked109 example: *"is `pcc_counters.sh` present and where does the110 install put it"*. Answered by the install overlay in111 the capabilities companion,112 which redirects to the canonical113 `doca-version/SKILL.md` rules.114115## Audience116117This skill serves **operators, developers, and AI agents who118need to read a ConnectX / BlueField device's firmware PCC119diagnostic counters** to reason about congestion-control120behaviour (CNP generation, RTT requests/responses, WRED121drops) on a port. Concretely:122123- A network operator confirming whether congestion-control124 events (CNPs, RTT, WRED drops) are occurring on a device.125- A developer correlating a custom `doca-pcc` algorithm's126 effect with the device-level PCC diagnostic counters127 (the script reads the firmware counters; the custom128 algorithm itself is a separate surface owned by129 `doca-pcc/SKILL.md`).130- An AI agent producing a *PCC counter snapshot* as evidence131 for a congestion-control investigation.132133It is **not** for users debugging the script's bash itself,134**not** the place to learn how to write a custom PCC135algorithm — that audience belongs in136`doca-pcc/SKILL.md` — and **not** the137place for users who want to configure the factory firmware PCC138algorithm (route via139`doca-public-knowledge-map/SKILL.md`).140141`pcc_counters.sh` is shipped as a **plain bash script**142installed under the DOCA tools directory, not a compiled binary and143not a library you link against. The skill uses the bundle's144`kind: tool` three-file shape (this skill + the capabilities companion145+ the tasks companion) so the agent's task-verb contract146(`configure / build / modify / run / test / debug`) is uniform147across the bundle.148149## When to load this skill150151Load this skill when the user is — or the agent needs to —152arm and read the device PCC diagnostic counters on a host or153BlueField Arm with the mst tools available and debugfs154mounted. Concretely:155156- Arming the diagnostic counters with `set` on a target mst157 device.158- Reading the armed counters with `query` and quoting the159 named counter lines verbatim.160- Capturing a counter readout as evidence for a161 congestion-control investigation.162163Do **not** load this skill for general DOCA orientation,164custom-PCC algorithm design, the host-side `doca-pcc` library165API, the factory firmware PCC algorithm, or DOCA / MFT install.166For those, route to167`doca-public-knowledge-map/SKILL.md`,168`doca-pcc/SKILL.md`, or169`doca-setup/SKILL.md`.170171## What this skill provides172173This is a **thin loader**. Substantive material lives in two174companion files:175176- the capabilities companion — what `pcc_counters.sh` does: the exact177 two-operation surface (`set` arms the device's diagnostic178 counters by writing counter IDs + params to debugfs;179 `query` reads the `diag_cnt/dump` and prints the named180 counters), the FIXED firmware / HW counter set it knows181 (`PCC_CNP_COUNT`, the `MAD_RTT_PERF_CONT_*`, the182 `*_EVENT_WRED_DROP` family, `HANDLED_*_EVENTS`, the183 `DROP_RTT_PORT*`/`RTT_GEN_PORT*` families), how it resolves184 an mst device to a PCI address (`mst status -v` + `lspci`)185 and reaches `/sys/kernel/debug/mlx5/<pci>/diag_cnt/`, the186 install-availability overlay that redirects to187 `doca-version/SKILL.md`, the layered188 error taxonomy (script-not-present / bad-device /189 not-armed-before-query / debugfs-or-permission /190 counter-stuck-at-zero / cross-cutting), and the safety191 policy that flags `set` as a privileged debugfs write and192 any CC tuning decision derived from a reading as193 high-stakes.194- the tasks companion — step-by-step workflows for the in-scope task195 verbs: `configure` (route to install + confirm mst /196 debugfs / sudo), `build` (route to install; nothing to197 compile — it is a script), `modify` (refuse — do not patch198 the shipped script), `run` (the `set`-then-`query`199 sequence), `test` (confirm the dump contains the named200 counters with finite values), `debug` (the layered201 diagnosis ladder), plus a `Deferred task verbs` block and a202 `Command appendix`.203204The skill assumes a host or BlueField where DOCA / MFT is205already installed (mst tools present, debugfs mounted, sudo206available) and the target device is visible to `mst status -v`.207208## What this skill deliberately does not ship209210This skill is **agent guidance**, not a samples or scripts211bundle. To keep the boundary clean, it deliberately does not212contain — and pull requests should not add:213214- **Invented flags or subcommands.** `pcc_counters.sh` has215 exactly two operations (`set`, `query`), takes exactly two216 positional arguments, and has NO `--help`, `--version`,217 `list`, `snapshot`, `watch`, or `diff`. Do not invent any.218- **Pre-baked example counter values.** Counter values are219 device-, firmware-, and traffic-state-specific; a captured220 value will mislead an operator on a different device.221- **Wrappers, parsers, or rewritten copies of the script.**222 The script is the contract; modifying or re-implementing it223 is out of scope.224- **A specific congestion-control tuning recommendation225 derived from a counter reading.** That is a high-stakes226 domain question — the skill prescribes how to *capture* the227 counters; it refuses to translate a delta into a CC228 parameter change without the user's own domain analysis.229- **A `samples/` or `reference/` subtree.** This is a thin230 loader for a documented script; substantive material lives231 in the script and the public PCC documentation.232233## Loading order2342351. Read this skill first to confirm the user's question236 is in scope (reading the device's firmware PCC diagnostic237 counters; not designing or loading a custom algorithm).2382. **For what the script does, the fixed counter set, the239 debugfs mechanism, the install-availability overlay, the240 layered error surface, and the safety posture, see241 the capabilities companion.**2423. **For the documented invocations — `configure`, `build`,243 `modify`, `run`, `test`, `debug`, plus the `Command244 appendix` — see the tasks companion.**245246## Related skills247248- `doca-pcc/SKILL.md` — the host-side249 library for writing and loading custom congestion-control250 kernels onto the DPA. It is a SEPARATE surface: the251 firmware PCC diagnostic counters `pcc_counters.sh` reads252 exist independently of any custom `doca-pcc` kernel, but an253 operator tuning a custom algorithm may read these counters254 to observe device-level CC behaviour. Conflating the script255 (firmware counter readout) with the library (custom256 algorithm load/control) is the most common PCC first-touch257 error.258- `doca-public-knowledge-map/SKILL.md`259 — routing to the public DOCA / PCC documentation set,260 including the firmware PCC algorithm configuration.261- `doca-version/SKILL.md` — canonical262 DOCA version-handling rules. The `## Version compatibility`263 section in the capabilities companion is a concise264 overlay that redirects here.265- `doca-setup/SKILL.md` — env preparation,266 install verification, mst tools, debugfs, and the267 *I have no install yet* path with the public NGC DOCA268 container. This skill assumes its preconditions are269 satisfied.270- `doca-debug/SKILL.md` — the271 cross-cutting debug ladder. The PCC counter readout slots272 in as a read-only device-state evidence source before any273 congestion-control tuning recommendation is made.274- `doca-programming-guide/SKILL.md`275 — general DOCA programming patterns shared across the276 bundle.