Compteurs DOCA PCC (pcc_counters.sh)

Par où commencer : Il s'agit d'une skill outil pour invoquer pcc_counters.sh — un petit script bash qui arme et lit l'ensemble fixe de compteurs de diagnostic PCC du firmware / matériel du périphérique (compte CNP, RTT-perf, WRED-drop, RTT-gen, événements traités) via l'interface diag_cnt debugfs du mlx5. Ouvrez TASKS.md et commencez par ## run pour la séquence canonique set-puis-query, ou ## debug quand l'utilisateur signale "ERROR: Bad Device", "compteur bloqué à zéro", ou "le dump est vide". Ouvrez CAPABILITIES.md si la question porte sur quels compteurs le script rapporte et comment il les atteint. Si l'utilisateur n'a pas encore installé DOCA / MFT, dirigez-le d'abord vers doca-setup.

Cette skill est la surface de lecture des compteurs PCC firmware / HW. Elle N'EST PAS la bibliothèque de contrôle côté hôte qui charge des kernels de contrôle de congestion personnalisés sur la DPA (c'est doca-pcc) et elle N'EST PAS la configuration de l'algorithme PCC firmware (ce chemin relève de la configuration firmware, routé via doca-public-knowledge-map). Les compteurs que ce script lit sont des compteurs de diagnostic device / firmware qui existent indépendamment du fait qu'un kernel DPA doca-pcc personnalisé soit en cours d'exécution — ne les conditionnez pas à un kernel personnalisé chargé.

Exemples de questions que cette skill répond bien

Les CLASSES de questions pcc_counters.sh que cette skill est construite pour répondre, chacune avec un exemple travaillé. La classe est le élément porteur ; l'exemple travaillé est une instance.

• "Comment lire les compteurs de diagnostic PCC sur ce périphérique ?" — exemple travaillé : "armer et dumper les compteurs CNP / RTT / WRED-drop pour /dev/mst/mt41692_pciconf0". Répondu par l'ensemble de compteurs fixe dans CAPABILITIES.md ## Capabilities and modes
  • l'invocation set-puis-query dans TASKS.md ## run.
• "Quelle est la plus petite invocation légale ?" — exemple travaillé : "que dois-je exactement taper ?". Répondu par le contrat à deux arguments positionnels (set | query + un chemin de périphérique mst) dans TASKS.md ## run.
• "Le script a affiché ERROR: Bad Device — qu'est-ce qui ne va pas ?" — exemple travaillé : "mon chemin de périphérique ne correspond pas". Répondu par la couche de résolution de périphérique dans CAPABILITIES.md ## Error taxonomy
  • TASKS.md ## debug.
• "Un compteur est bloqué à zéro — le périphérique est-il inactif, les compteurs ne sont-ils pas armés, ou aucun événement réel ?" — exemple travaillé : "PCC_CNP_COUNT lit 0 après query". Répondu par la règle arm-avant-lecture et le diagnostic par couches dans TASKS.md ## debug + CAPABILITIES.md ## Error taxonomy.
• "Ce script est-il sur ma machine, et où ?" — exemple travaillé : "est-ce que pcc_counters.sh est présent et où l'installation le place-t-elle". Répondu par le recouvrement d'installation dans CAPABILITIES.md ## Version compatibility, qui redirige vers les règles canoniques doca-version.

Audience

Cette skill sert les opérateurs, développeurs et agents IA qui ont besoin de lire les compteurs de diagnostic PCC firmware d'un périphérique ConnectX / BlueField pour raisonner sur le comportement du contrôle de congestion (génération CNP, requêtes/réponses RTT, drops WRED) sur un port. Concrètement :

• Un opérateur réseau confirmant si les événements de contrôle de congestion (CNP, RTT, drops WRED) se produisent sur un périphérique.
• Un développeur corrélant l'effet de l'algorithme personnalisé doca-pcc avec les compteurs de diagnostic PCC au niveau du périphérique (le script lit les compteurs firmware ; l'algorithme personnalisé lui-même est une surface séparée détenue par doca-pcc).
• Un agent IA produisant un snapshot de compteur PCC comme preuve pour une enquête de contrôle de congestion.

Ce n'est pas pour les utilisateurs déboguant le bash du script lui-même, pas le lieu pour apprendre à écrire un algorithme PCC personnalisé — cette audience appartient à doca-pcc — et pas le lieu pour les utilisateurs qui veulent configurer l'algorithme PCC firmware d'usine (route via doca-public-knowledge-map).

pcc_counters.sh est fourni comme un simple script bash installé sous le répertoire outils DOCA (par install_data dans tools/pcc_counters/meson.build), pas un binaire compilé et pas une bibliothèque contre laquelle vous liez. La skill utilise la forme kind: tool à trois fichiers du bundle (SKILL.md + CAPABILITIES.md

• TASKS.md) afin que le contrat de verbe de tâche de l'agent (configure / build / modify / run / test / debug) soit uniforme dans tout le bundle.

Quand charger cette skill

Chargez cette skill quand l'utilisateur — ou l'agent — a besoin d'armer et lire les compteurs de diagnostic PCC du périphérique sur un hôte ou un BlueField Arm avec les outils mst disponibles et debugfs monté. Concrètement :

• Armer les compteurs de diagnostic avec set sur un périphérique mst cible.
• Lire les compteurs armés avec query et citer les lignes de compteur nommées textuellement.
• Capturer une lecture de compteur comme preuve pour une enquête de contrôle de congestion.

Ne chargez pas cette skill pour l'orientation générale DOCA, la conception d'algorithme PCC personnalisé, l'API de la bibliothèque doca-pcc côté hôte, l'algorithme PCC firmware d'usine, ou l'installation DOCA / MFT. Pour cela, routez vers doca-public-knowledge-map, doca-pcc, ou doca-setup.

Ce que cette skill fournit

Ceci est un chargeur mince. Le matériel substantiel réside dans deux fichiers compagnons :

• CAPABILITIES.md — ce que pcc_counters.sh fait : la surface à deux opérations exacte (set arme les compteurs de diagnostic du périphérique en écrivant les IDs de compteur + paramètres dans debugfs ; query lit le diag_cnt/dump et affiche les compteurs nommés), l'ensemble FIXE de compteurs firmware / HW qu'il connaît (PCC_CNP_COUNT, les MAD_RTT_PERF_CONT_*, la famille *_EVENT_WRED_DROP, HANDLED_*_EVENTS, les familles DROP_RTT_PORT*/RTT_GEN_PORT*), comment il résout un périphérique mst en adresse PCI (mst status -v + lspci) et accède à /sys/kernel/debug/mlx5/<pci>/diag_cnt/, le recouvrement de disponibilité d'installation qui redirige vers doca-version, la taxonomie d'erreur par couches (script-non-présent / bad-device / not-armed-before-query / debugfs-ou-permission / counter-stuck-at-zero / transversal), et la politique de sécurité qui marque set comme une écriture debugfs privilégiée et toute décision de réglage CC dérivée d'une lecture comme haute-priorité.
• TASKS.md — flux de travail étape par étape pour les verbes de tâche en scope : configure (route vers installation + confirmer mst / debugfs / sudo), build (route vers installation ; rien à compiler — c'est un script), modify (refuser — ne pas patcher le script fourni), run (la séquence set-puis-query), test (confirmer que le dump contient les compteurs nommés avec des valeurs finies), debug (l'échelle de diagnostic par couches), plus un bloc Deferred task verbs et un Command appendix.

La skill suppose un hôte ou BlueField où DOCA / MFT est déjà installé (outils mst présents, debugfs monté, sudo disponible) et le périphérique cible est visible pour mst status -v.

Ce que cette skill délibérément ne livre pas

Cette skill est un guide d'agent, pas un bundle de samples ou scripts. Pour garder la limite claire, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

• Flags ou sous-commandes inventés. pcc_counters.sh a exactement deux opérations (set, query), prend exactement deux arguments positionnels, et n'a PAS de --help, --version, list, snapshot, watch, ou diff. N'en inventez aucun.
• Valeurs de compteur d'exemple pré-cuites. Les valeurs de compteur sont spécifiques au périphérique, au firmware et à l'état du trafic ; une valeur capturée induira en erreur un opérateur sur un périphérique différent.
• Wrappers, parseurs, ou copies réécrites du script. Le script est le contrat ; le modifier ou le réimplémente sort du scope.
• Une recommandation de réglage de contrôle de congestion spécifique dérivée d'une lecture de compteur. C'est une question de domaine haute-priorité — la skill prescrit comment capturer les compteurs ; elle refuse de traduire un delta en changement de paramètre CC sans l'analyse de domaine propre de l'utilisateur.
• Un sous-arbre samples/ ou reference/. C'est un chargeur mince pour un script documenté ; le matériel substantiel réside dans le script et la documentation PCC publique.

Ordre de chargement

1. Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est en scope (lire les compteurs de diagnostic PCC firmware du périphérique ; pas concevoir ou charger un algorithme personnalisé).
2. Pour ce que le script fait, l'ensemble de compteurs fixe, le mécanisme debugfs, le recouvrement de disponibilité d'installation, la surface d'erreur par couches, et la posture de sécurité, voir CAPABILITIES.md.
3. Pour les invocations documentées — configure, build, modify, run, test, debug, plus le Command appendix — voir TASKS.md.

Skills connexes

• doca-pcc — la bibliothèque côté hôte pour écrire et charger des kernels de contrôle de congestion personnalisés sur la DPA. C'est une surface SÉPARÉE : les compteurs de diagnostic PCC firmware que pcc_counters.sh lit existent indépendamment de tout kernel doca-pcc personnalisé, mais un opérateur réglant un algorithme personnalisé peut lire ces compteurs pour observer le comportement CC au niveau du périphérique. Confondre le script (lecture de compteur firmware) avec la bibliothèque (charge/contrôle d'algorithme personnalisé) est l'erreur PCC de premier contact la plus courante.
• doca-public-knowledge-map — routage vers l'ensemble de documentation DOCA / PCC public, incluant la configuration de l'algorithme PCC firmware.
• doca-version — règles canoniques de gestion des versions DOCA. La section ## Version compatibility dans CAPABILITIES.md est un recouvrement concis qui redirige ici.
• doca-setup — préparation d'env, vérification d'installation, outils mst, debugfs, et le chemin je n'ai pas d'installation encore avec le container DOCA NGC public. Cette skill suppose que ses préconditions sont satisfaites.
• doca-debug — l'échelle de debug transversale. La lecture du compteur PCC s'encastre comme source de preuve d'état de périphérique en lecture seule avant toute recommandation de réglage de contrôle de congestion.
• doca-programming-guide — modèles de programmation DOCA généraux partagés dans tout le bundle.