Index of every page on this site: llms.txt
All skills
nvidia avatar

/doca-pcc-counters

@6b75e9e
by NVIDIA Corporationnvidia/skills4.1k stars
547
Run it yourself

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.

Use this Skill: https://skilld.dev/gh/nvidia/skills/doca-pcc-counters

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈211 tokens for metadata: the name and description. ≈2.8k when used: this file. ≈13k more on demand in 6 files.

Description uses 10.5% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈838 characters, or 10.5%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

DOCA PCC Counters (pcc_counters.sh)

Examples

  • Any counter answer starts with the version match. The installed doca-pcc-counters package version (dpkg-query -W -f='${Version}' doca-pcc-counters, or rpm -q doca-pcc-counters; the script itself has no --version), pkg-config --modversion doca-pcc and doca_caps --version must agree (doca-version); a mismatch goes to doca-version ## debug layer 2 before any counter is quoted.
  • "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.
  • "Can I trust these counters on my install?" Match versions before quoting any counter: the installed doca-pcc-counters package version, pkg-config --modversion doca-pcc and doca_caps --version, checked against the DOCA Compatibility Policy through doca-version; any disagreement goes to doca-version ## debug layer 2 (partial install) first.

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

  1. 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).
  2. 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.
  3. 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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts15d3 checks · Risk SAFE
  • Gen Agent Trust Hub20d

    The skill provides instructions for using the `pcc_counters.sh` diagnostic tool, requiring root privileges to interact with hardware congestion control counters via the Linux debugfs interface. It includes explicit safety guidance for executing root-level commands.

  • Socket15d

    No alerts

  • Snyk20d

    Risk: LOW · No issues

Signed by skilld at 6b75e9e. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 days ago
Other metadata
metadata
{
  "author": "NVIDIA <doca-feedback@nvidia.com>",
  "kind": "tool",
  "doca_version": "3.6",
  "tags": [
    "doca",
    "pcc",
    "counters"
  ]
}
compatibility
Requires DOCA/MFT on Linux with a ConnectX-7 or BlueField-3 device only (BlueField-3: Arm in DPU mode, host in NIC mode), mst tools, mounted debugfs, and root on 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. The validation steps require a live DOCA install.

README badge

README badge for nvidia/skills/doca-pcc-counters