Outil d'administration du canal Comm DOCA

CRITIQUE — comment lire le corps de cette skill (drain / restart / inspect / framing d'opération changeant d'état). Le binaire doca_comm_channel_admin livré est un outil SINGLE-SHOT, READ-ONLY, SCAN-AND-PRINT. Il enregistre ZÉRO argument au niveau application dans register_comm_channel_admin_params() (seuls les défauts ARGP sont enregistrés), il appelle resourcedump (MFT) par appareil, et il affiche deux tables ASCII. Il N'Y A PAS de sous-commande drain, PAS de sous-commande restart, PAS de sous-commande inspect <channel-id>, PAS d'opération changeant d'état, et PAS de workflow list-first → inspect-one → drain-or-restart exposé PAR CE BINAIRE. Partout où les sections ci-dessous (## Example questions, CAPABILITIES.md, TASKS.md) disent « drain a channel », « restart it », « per-channel inspect step », « state-changing operation gate », ou « smoke-before-bulk », lisez ceux-ci comme des actions conceptuelles de l'opérateur que l'opérateur effectue via AUTRES CHEMINS APRÈS avoir lu les tables de cet outil — pas comme des sous-commandes que le binaire admin lui-même livre. Concrètement : l'opérateur draine/réinitialise/reconnecte en allant du côté programme via doca-comch (le cycle de vie reconnect de la bibliothèque comch doca_ctx_stop() → reset → doca_ctx_start()), ou en rechargeant le pilote / mode BlueField via doca-setup + doca-hardware-safety, ou par réinitialisation RShim / BFB pour les cas les plus profonds — JAMAIS en réinvoquant le binaire admin avec un drapeau, car aucun tel drapeau n'existe. Le corps ci-dessous utilise les noms hérités drain/restart/inspect/state-changing car ils décrivent le modèle mental de l'opérateur ; cette bannière est le mappage faisant autorité entre ce modèle et la surface binaire réelle.

Par où commencer : Ceci est une skill d'outil pour invoquer l'outil d'administration du canal Comm DOCA — l'inventaire read-only équivalent CLI de la bibliothèque doca-comch. Le binaire doca_comm_channel_admin livré prend aucun argument au-delà des défauts ARGP (--help, --version, --log-level, --sdk-log-level, --json) et effectue une passe d'inventaire par invocation : il parcourt chaque doca_dev de ce côté, filtre les appareils compatibles comch, appelle resourcedump (MFT) sur chacun, et affiche deux tables ASCII (SERVERS et CONNECTIONS). Il n'y a pas de sous-commande list, pas de sous-commande inspect, pas de drapeau drain, et pas de drapeau restart — ceux-ci ne font pas partie de la surface de l'outil. Ouvrez TASKS.md et commencez à ## run pour l'invocation single-shot, ou ## debug quand l'utilisateur signale que l'outil voit un ensemble de canaux différent du programme. Ouvrez CAPABILITIES.md quand la question est ce que les tables affichées signifient réellement et ce qui n'est pas dans le champ d'application de cet outil. Si l'utilisateur n'a pas encore installé DOCA, routez vers doca-setup en premier ; si l'utilisateur a besoin de MFT (mst start + resourcedump sur PATH et privilèges root/sudo pour l'invoquer), doca-setup + doca-public-knowledge-map couvrent cela. Si l'utilisateur dispose de docs antérieures à 2.5 mentionnant « Comm Channel », routez vers doca-comch CAPABILITIES.md ## Version compatibility pour la règle de renommage. Si l'utilisateur veut changer l'état du canal (reset / drain / restart), routez vers le cycle de vie reconnect du côté programme dans doca-comch ou vers le mode BlueField / rechargement du pilote dans doca-setup + doca-hardware-safety — pas vers cet outil.

Exemples de questions que cette skill répond bien

Les CLASSES de questions d'outils admin que cette skill est construite pour répondre, chacune avec un exemple travaillé. La classe est la pièce portante ; l'exemple travaillé est une instance.

« Quels canaux comch sont actuellement actifs sur ce BlueField ? » — exemple travaillé : « énumérez chaque canal comch que le serveur DPU accepte actuellement des clients hôtes ». Répondu par l'énumération de canal dans CAPABILITIES.md ## Capabilities and modes
- l'invocation list-first dans TASKS.md ## run.
« Quel est l'état de ce canal ? » — exemple travaillé : « un client hôte signale que sa send-task est suspendue ; le canal est-il HEALTHY, draining, ou stuck ». Répondu par la surface d'inspection channel-state dans CAPABILITIES.md ## Capabilities and modes
- l'étape per-channel inspect dans TASKS.md ## run.
« Un canal est bloqué — dois-je le drainer ou le redémarrer ? » — exemple travaillé : « un fast-path producer / consumer n'a aucune completion depuis 30 secondes et le processus consumer est toujours vivant ». Répondu par la règle de décision drain-vs-restart dans TASKS.md ## debug + la porte state-changing-operation dans CAPABILITIES.md ## Safety policy.
« Comment savoir que la vue de l'outil admin correspond à ce que mon programme Comch voit ? » — exemple travaillé : « le programme signale CONNECTED mais l'outil admin répertorie zéro canaux ». Répondu par le motif de cross-checking dans TASKS.md ## test et la couche representor-binding dans CAPABILITIES.md ## Error taxonomy.
« Cet outil admin est-il sur ma version DOCA installée, et correspond-il à la version de la bibliothèque comch ? » — exemple travaillé : « l'outil est-il disponible sur DOCA 2.4 ». Répondu par l'overlay dans CAPABILITIES.md ## Version compatibility, qui redirige vers les règles canoniques de doca-version et ajoute les spécificités de l'outil Comm Channel Admin.
« L'outil n'affiche rien — l'installation est-elle cassée ou n'y a-t-il vraiment pas de canal ? » — exemple travaillé : « list a retourné un résultat vide sur un hôte avec un client Comch de bonne qualité ». Répondu par les règles d'interprétation empty-output dans TASKS.md ## debug + CAPABILITIES.md ## Error taxonomy.

Audience

Cette skill sert les opérateurs externes et agents IA qui ont besoin d'inspecter ou d'intervenir sur un canal comch host-DPU de l'extérieur — après que la bibliothèque doca-comch ait été utilisée pour créer le canal depuis un programme. Concrètement :

Un opérateur de plateforme qui exécute un service utilisant Comch sur BlueField et a besoin de confirmer que le canal est sain avant de déclarer le service prêt.
Un développeur d'un consommateur Comch qui voit DOCA_ERROR_AGAIN ou un stall silencieux du côté programme et veut lire l'état du canal de l'extérieur du programme plutôt que de deviner.
Un agent IA pilotant une étape de triage opérationnel « le canal comch est-il bloqué » avant de recommander un changement de code ou un redémarrage de processus.

Ce n'est pas pour les utilisateurs déboguant l'outil admin lui-même, pas un substitut au guide public DOCA Comm Channel Admin Tool en direct, et pas le bon endroit pour les utilisateurs apprenant l'API comch — cette audience appartient à doca-comch.

L'outil est livré comme un binaire CLI sous /opt/mellanox/doca/tools/, pas une bibliothèque à lier. La skill utilise la même forme three-file kind: tool que le reste du bundle afin que le contrat task-verb de l'agent (configure / build / modify / run / test / debug) soit uniforme sur les bibliothèques, services et outils.

Quand charger cette skill

Chargez cette skill quand l'utilisateur est — ou l'agent doit — invoquer l'outil d'administration du canal Comm DOCA sur un vrai hôte ou BlueField Arm avec DOCA installé (ou dans le conteneur public NGC DOCA avec le bon device passthrough). Concrètement :

Lister les canaux comch actuellement actifs sur un hôte ou DPU.
Inspecter l'état d'un canal nommé avant de décider de le laisser tranquille, le drainer, ou le redémarrer.
Parcourir la décision drain-vs-restart pour un canal bloqué signalé par une application utilisant Comch.
Cross-checker la vue de l'outil admin par rapport à l'état du callback de connexion du côté programme quand les deux semblent en désaccord.
Capturer un snapshot de canal sans side-effect comme preuve préalable pour une session de debug ultérieure qui traverse les couches programme / canal / pilote.

Ne chargez pas cette skill pour l'orientation générale DOCA, l'API de programmation comch, l'installation de bibliothèque, ou la conception du protocole comch. Pour ceux-ci, routez vers doca-public-knowledge-map, doca-comch, ou doca-setup.

Ce que cette skill fournit

C'est un thin loader. Le matériel substantiel vit dans deux fichiers complémentaires :

CAPABILITIES.md — ce que l'outil Comm Channel Admin rapporte et change : la surface channel-state documentée, la division read-only vs state-changing operation, l'overlay version-availability qui redirige vers doca-version, la taxonomie d'erreur en couches (tool-not-installed / device-binding / channel-discovery / channel-state-stuck / permission / version / cross-cutting), le rôle de l'outil comme primitive d'observabilité pour les sessions de debug doca-comch, et la politique de sécurité qui rend drain et restart des opérations à enjeux élevés avec porte sur une inspection propre en premier.
TASKS.md — workflows étape par étape pour les verbes de tâche in-scope : configure (route vers install), build (route vers install), modify (refuser), run (list-then-inspect), test (smoke-before-bulk capability check), debug (la ladders de diagnostic en couches), plus un bloc Deferred task verbs et un Command appendix qui honore le préambule du bundle doca-structured-tools-contract.

La skill suppose un hôte ou BlueField où DOCA est déjà installé (ou le conteneur public NGC DOCA s'exécute avec le bon device passthrough) et l'opérateur a quels que soient les privilèges que le guide public DOCA Comm Channel Admin Tool exige.

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

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

Les inventaires de drapeau verbatim, noms de sous-commandes, ou noms de colonnes de sortie. Le guide public DOCA Comm Channel Admin Tool sur docs.nvidia.com et le --help installé sur la version de l'utilisateur sont la source de vérité conjointe ; les copier ici épingle la skill à une release et pourrit silencieusement quand l'outil évolue. La skill route l'agent vers ces sources à la place.
Les exemples de sortie pré-cuits. La sortie est install-, version-, et channel-state-spécifique. Un exemple capturé trompera un opérateur sur une plateforme / état différent.
Les wrappers, parsers, ou scripts dans n'importe quel langage qui consomment la sortie de l'outil admin. Le format de sortie est documenté ; les utilisateurs qui veulent scripter contre lui doivent lire le guide en direct et écrire le parser par rapport à leur version installée.
Un sous-arbre samples/ ou reference/. C'est un thin loader pour un CLI documenté ; le matériel substantiel vit sur la page publique et dans --help.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est dans le champ d'application (l'utilisateur veut inspecter ou intervenir sur un canal comch de l'extérieur, pas apprendre l'API comch).
Pour ce que l'outil rapporte, la division read-only vs state-changing, la disponibilité de version, la surface d'erreur en couches, l'observabilité, et la posture de sécurité, voir CAPABILITIES.md.
Pour les invocations documentées et le workflow smoke-before-bulk — configure, build, modify, run, test, debug, plus le Command appendix — voir TASKS.md.

Skills connexes

doca-comch — la bibliothèque dont cet outil inspecte les canaux. Associez-les dans chaque session de triage : le callback de connexion du côté programme et l'état du canal de l'outil admin sont les deux moitiés du même tableau.
doca-public-knowledge-map — routage vers le guide public DOCA Comm Channel Admin Tool et le reste de l'ensemble de documentation DOCA publique.
doca-version — règles canoniques de gestion de version DOCA. La section ## Version compatibility dans CAPABILITIES.md est un overlay concis qui redirige ici pour le corps.
doca-structured-tools-contract — le contrat detect → prefer → fall back → report du bundle pour les outils helper structurés. Le Command appendix dans TASKS.md honore ce contrat.
doca-setup — préparation env, vérification d'install, vérifications de visibilité des representors, et le chemin I have no install yet avec le conteneur DOCA NGC public. Cette skill suppose que ses préconditions sont satisfaites.
doca-debug — la ladders de debug cross-cutting. L'outil Comm Channel Admin s'insère à la couche runtime comme la surface d'inspection read-only avant que n'importe quel changement de code soit recommandé.

doca-comm-channel-admin