Débogage DOCA

Par où commencer : Cette skill est la référence canonique du modèle en couches que doca-setup ## debug et doca-programming-guide ## debug escaladent tous deux. Si le symptôme ne s'inscrit pas clairement dans la classe env ou program, commencez par TASKS.md ## debug — l'échelle en couches complète y réside.

Exemples de questions auxquelles cette skill répond bien

Les CLASSES de questions de débogage auxquelles cette skill est construite pour répondre, chacune avec un exemple travaillé.

« Ma construction / liaison / exécution / programme DOCA a échoué — quelle couche ? » — exemple travaillé : « ld dit undefined reference to doca_flow_init — quelle couche ? » Réponse via l'échelle en couches canonique dans TASKS.md ## debug (couche 4 = Liaison).
« Comment augmenter la verbosité pour n'importe quelle bibliothèque ou outil DOCA ? » — exemple travaillé : « Mon programme DOCA Flow est silencieux — où puis-je obtenir plus de sortie de journal ? » Réponse via la surface de trace / niveau de log dans CAPABILITIES.md ## Observability + le workflow d'exécution avec verbosité dans TASKS.md ## run.
« Comment capturer l'état pour une question de forum ou un rapport de bogue ? » — exemple travaillé : « Je voudrais poser une question sur le forum avec du contexte reproductible — que devrais-je inclure ? » Réponse via le workflow de capture d'un état reproductible dans TASKS.md ## test.
« Que signifie cette sortie d'outil DOCA / quel outil répond à ceci ? » — exemple travaillé : « doca_caps n'a rien retourné pour RDMA — cela signifie-t-il non supporté ? » Réponse via l'arbre de décision outil-vs-capacité dans CAPABILITIES.md ## Capabilities and modes + lien croisé vers doca-caps.
« Je débogue à l'intérieur du conteneur NGC — qu'est-ce qui est observable ? » — exemple travaillé : « hugepages est vide à l'intérieur du conteneur ; est-ce un vrai problème ou quelque chose lié au conteneur ? » Réponse via les contraintes de débogage spécifiques au conteneur dans CAPABILITIES.md ## Safety policy + TASKS.md ## debug couche 5 (Runtime).
« Où demander de l'aide pour ceci ? » — exemple travaillé : « Où se trouve le forum DOCA destiné aux clients et que doit contenir la publication ? » Réponse via la règle de routage Developer-Forum dans TASKS.md ## debug plus doca-public-knowledge-map.

Si le symptôme est purement de classe env, routez vers doca-setup ## debug ; s'il est purement de classe program, routez vers doca-programming-guide ## debug. Cette skill est la couche transversale que les deux appellent.

Quand charger cette skill

Chargez cette skill lorsque l'utilisateur débogue n'importe quoi lié à DOCA — une construction qui ne compile pas, une étape de liaison qui ne peut pas résoudre un symbole doca_*, un appel runtime qui retourne DOCA_ERROR_*, un paquet qui n'apparaît pas sur le fil, un service qui ne démarre pas, ou un outil qui ne retourne rien d'utile. Concrètement :

L'utilisateur signale un symptôme et doit trouver la couche qui l'a causé (install / version / build / link / runtime / program).
L'utilisateur demande « comment obtenir plus de journaux ? » ou « comment augmenter la verbosité ? » pour n'importe quelle bibliothèque ou outil DOCA.
L'utilisateur veut capturer l'état pour une question de forum ou un rapport de bogue interne (le bundle ne possède pas le canal de rapport de bogue interne ; il route vers le forum public DOCA Developer).
L'utilisateur lit une stack trace, une sortie valgrind, ou un core dump d'un programme DOCA et veut savoir où regarder en premier.
L'utilisateur débogue à l'intérieur du conteneur NGC DOCA et doit savoir ce qui est et ce qui n'est pas observable de l'intérieur.

Ne chargez pas cette skill pour :

« Qu'est-ce que DOCA_ERROR_BAD_STATE ? », « quels codes d'erreur DOCA retourne-t-il ? » — c'est la taxonomie d'erreur inter-bibliothèques, possédée par doca-programming-guide CAPABILITIES.md ## Error taxonomy. Cette skill consomme cette taxonomie ; elle ne la redéfinit pas.
« Mon pkg-config ne peut pas trouver doca-flow », « les hugepages ne sont pas montées », « mon representor n'est pas visible » — ce sont des symptômes de classe env, possédés par doca-setup ## debug. Cette skill est le pointeur canonique auquel l'échelle de débogage de classe env redirige une fois que le symptôme escalade au-delà des prérequis install / version / build.
Débogage spécifique à la bibliothèque (Flow pipe trace, état de queue-pair RDMA, statistiques de canal Comch) — ceux-ci vivent dans la skill de bibliothèque correspondante (ex. doca-flow ## debug). Cette skill fournit l'échelle de débogage transversale ; les skills de bibliothèque superposent leur surface de débogage spécifique à la bibliothèque par-dessus.

Ce que cette skill fournit

Ceci est un chargeur léger. Le corps ne conserve que l'orientation nécessaire pour choisir le bon fichier suivant. Le matériel de débogage substantiel réside dans deux fichiers compagnons :

CAPABILITIES.md — quelles sortes de surface de débogage DOCA expose : le modèle de débogage en couches (install / version / build / link / runtime / program), la position read-only-first, la disponibilité de version des outils de débogage (ex. doca_caps depuis DOCA 2.6.0), la taxonomie d'erreur inter-bibliothèques (lien croisé uniquement — possédée par doca-programming-guide), les primitives d'observabilité que DOCA émet (journaux stderr, --sdk-log-level, la saveur de build doca-<lib>-trace, compteurs de bibliothèque), et les contraintes de sécurité sur les actions de débogage (read-only first, ne mutez pas l'arborescence install pendant l'investigation).
TASKS.md — les workflows de débogage réels : ## configure (configurer env pour le débogage haute-verbosité), ## test (capturer un état reproductible), ## debug (l'échelle en couches canonique, le point d'entrée universel auquel chaque ## debug de bibliothèque redirige), et le routage Où demander de l'aide (NVIDIA DOCA Developer Forum). Trois autres ancres (build, modify, run) existent pour la conformité lint et routent vers doca-programming-guide, qui possède ces verbes après la scission env / program.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que le symptôme de l'utilisateur est un débogage transversal (non purement classe env, non purement classe program, non purement interne à la bibliothèque).
Pour le modèle de débogage en couches, la position read-only, la disponibilité de version des outils de débogage, et la surface d'observabilité que DOCA émet, voir CAPABILITIES.md.
Pour l'échelle de débogage en couches canonique et le workflow de capture-et-rapport, voir TASKS.md. Les ancres build, modify, et run dans TASKS.md sont des stubs qui routent vers doca-programming-guide ; leur substance y réside.
Si le symptôme de l'utilisateur s'avère être de classe env (install / build prerequisites), cédez à doca-setup ## debug. S'il est de classe program, cédez à doca-programming-guide ## debug. S'il est interne à la bibliothèque, cédez à la skill de bibliothèque correspondante ## debug (ex. doca-flow ## debug).

Les deux fichiers compagnons se renvoient mutuellement et vers doca-public-knowledge-map chaque fois que la bonne réponse est « consultez la doc publique ou l'organisation du paquet installé » plutôt que « conseils spécifiques au débogage ».

Skills associées

doca-public-knowledge-map — routage de la documentation DOCA publique et organisation sur disque d'un paquet DOCA installé. Cette skill diffère toutes les questions « où X est documenté », « où sur disque Y », et « comment vérifier la version installée » à la knowledge-map.
doca-setup — débogage de classe env (install / build prerequisites) : échecs pkg-config, hugepages manquantes, representors invisibles, décalages de version header-vs-runtime. doca-setup ## debug est l'échelle en couches de classe env ; cette skill est l'échelle de débogage transversale que les deux échelles env et program escaladent.
doca-programming-guide — débogage de classe program (ordre du cycle de vie, interprétation DOCA_ERROR_*, usage de doca_error_get_descr(), règle validate-before-commit). doca-programming-guide ## debug est l'échelle en couches de classe program ; cette skill prend le relais quand le symptôme implique des outils inter-bibliothèques (gdb, valgrind, introspection de conteneur, core dumps).
Skills de bibliothèque (ex. doca-flow, doca-dms, doca-caps) — overlays de débogage spécifiques à la bibliothèque. Le ## debug de chaque bibliothèque s'appuie sur l'échelle transversale définie ici, puis ajoute ses propres compteurs, traces, et outils d'inspection.

doca-debug