doca-pcc-counters

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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
  + the tasks 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 (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 (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:

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills