Doca Pcc Counters Agent Skill

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 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 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 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) and it is NOT the

firmware PCC *algorithm* configuration (that path is firmware

configuration, routed via

doca-public-knowledge-map).

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

+ the set-then-query invocation in

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.

• "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

+ 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 +

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,

which redirects to the canonical

doca-version 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).

• 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 — and not the

place for users who want to configure the factory firmware PCC

algorithm (route via

doca-public-knowledge-map).

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 shape (SKILL.md + CAPABILITIES.md

+ TASKS.md) 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,

doca-pcc, or

doca-setup.

What this skill provides

This is a thin loader. Substantive material lives in two

companion files:

• CAPABILITIES.md — 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, 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.

• TASKS.md — 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.md 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

CAPABILITIES.md.**

• **For the documented invocations — configure, build,

modify, run, test, debug, plus the `Command

appendix` — see TASKS.md.**

Related skills

• doca-pcc — 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

— routing to the public DOCA / PCC documentation set,

including the firmware PCC algorithm configuration.

• doca-version — canonical

DOCA version-handling rules. The ## Version compatibility

section in CAPABILITIES.md is a concise

overlay that redirects here.

• doca-setup — 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 — 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

— general DOCA programming patterns shared across the

bundle.