Extension DOCA Bench

Par où commencer : Ceci est une skill d'outil pour le framework d'extension / plug-in qui augmente doca-bench — ce n'est PAS une skill de forme de charge de travail en soi. Ouvrez TASKS.md et commencez à ## configure pour vous engager sur la décision à trois axes (la classe de charge de travail n'est pas réellement couverte par les modes intégrés de doca-bench × la surface de l'API d'extension correspond × le co-chargement de l'outil parent est acceptable), puis ## build pour la façon dont une extension personnalisée est compilée et organisée, puis ## run pour la façon dont doca-bench découvre et appelle l'extension, puis ## test pour la boucle smoke-before-bulk que l'agent applique à chaque nouvelle extension. Ouvrez CAPABILITIES.md quand la question porte sur ce qu'une extension peut faire que les modes doca-bench intégrés ne peuvent pas, à quoi ressemble la surface de l'API d'extension en gros traits (les points d'entrée C DOCA_EXPERIMENTAL que la référence livrée expose), comment fonctionne le flux de build / registration / discovery, ou comment la durée de vie de l'extension est délimitée par l'invocation doca-bench parente. Si doca-bench lui-même est la question, dirigez vers doca-bench. Si la question est « quel mode doca-bench intégré dois-je choisir ? », c'est aussi doca-bench — les extensions sont la voie de sortie pour les charges de travail que les modes intégrés ne couvrent pas.

Exemples de questions auxquelles cette skill répond bien

« Ma classe de charge de travail est <X> — est-ce que doca-bench la mesure nativement, ou ai-je besoin d'une extension ? » — la question décision extension-vs-intégré. L'agent ramène l'utilisateur à l'inventaire des modes intégrés de doca-bench EN PREMIER et ne dirige vers le framework d'extension que si aucun mode intégré ne s'applique.
« Je veux benchmarker une charge de travail CUDA / GPU qui pilote les files d'attente DOCA GPUNetIO RX et TX. Par où commencer ? Y a-t-il une extension de référence que je peux copier ? » — l'agent expose l'extension livrée doca_bench_cuda sous /opt/mellanox/doca/tools/bench_extension/doca_bench_cuda/ comme exemplar de référence et guide l'opérateur à travers sa surface d'API et sa forme de build.
« Comment doca-bench découvre-t-elle et charge-t-elle réellement mon extension personnalisée à l'exécution ? Est-ce une bibliothèque partagée versionnée ? À quoi mon point d'entrée doit-il ressembler ? » — la question du flux de build / registration / discovery. L'agent guide à travers la forme de la bibliothèque partagée construite avec Meson, le versioning, et le chemin de découverte à l'exécution de l'outil parent (que l'agent n'invente pas de mémoire — la meson.build de l'extension livrée et la documentation DOCA Bench publique sur docs.nvidia.com sont la source de vérité).
« Les en-têtes d'API que j'ai sont marqués DOCA_EXPERIMENTAL. Qu'est-ce que cela signifie pour la stabilité de mon extension entre les versions de DOCA ? Vais-je devoir la reconstruire à chaque version ? » — la question de la surface expérimentale et de la compatibilité de version.
« Une fois que j'ai construit mon extension, quel est le smoke le moins coûteux que je puisse exécuter avant de pointer ma véritable charge de travail dessus ? Comment sais-je que doca-bench l'a réellement chargée, appelée, et que l'appel a renvoyé les données que l'outil parent attendait ? » — la question smoke-before-bulk.
« Mon extension personnalisée se construit, mais doca-bench dit qu'elle ne peut pas la trouver / charger / appeler. Où regarder en premier ? » — la question de debug en couches qui distingue les défaillances de build, les défaillances de chargement, les incompatibilités de registration, et les défaillances d'appel à l'exécution.

Audience

Les agents IA expérimentés et les ingénieurs platform / performance qui utilisent déjà doca-bench pour les modes de charge de travail intégrés et qui ont désormais une classe de charge de travail que les modes intégrés ne couvrent pas. Les lecteurs sont censés être à l'aise avec les systèmes de build natifs (Meson, dans cette codebase), l'empaquetage de bibliothèques partagées sur Linux, et le contrat de stabilité de l'API DOCA_EXPERIMENTAL. Si l'utilisateur pose des questions sur le benchmarking côté GPU via l'extension de référence livrée doca_bench_cuda, le lecteur est également censé être familiarisé avec les bases de DOCA GPUNetIO et de la chaîne d'outils CUDA — ces domaines vivent dans leurs propres skills, pas ici.

Cette skill n'est PAS pour :

les opérateurs qui peuvent exprimer leur charge de travail avec l'un des modes intégrés de doca-bench — c'est doca-bench ;
les opérateurs qui veulent benchmarker une primitive DOCA différente (Flow, Comch, RMAX) via l'outil de mesure de cette primitive — dirigez vers cet outil ;
les contributeurs qui créent ou modifient les extensions dans l'arborescence (cette skill s'adresse aux opérateurs externes consommant le framework, pas aux contributeurs internes de DOCA).

Périmètre linguistique

Une extension doca-bench se présente sous la forme :

Une bibliothèque partagée versionnée sous Linux (.so avec soversion correspondant à la version de DOCA), construite via les règles Meson doca-bench-extension dans /opt/mellanox/doca/tools/bench_extension/meson.build fourni et le sous-répertoire par extension (l'exemplar de référence est doca_bench_cuda/).
Un petit ensemble de points d'entrée C marqués DOCA_EXPERIMENTAL que le doca-bench parent appelle — c'est-à-dire la surface d'API déclarée dans le fichier en-tête de l'extension. Le doca_bench_cuda/doca_bench_cuda.h fourni est la référence pour ce à quoi cette surface ressemble en pratique (*_init, *_device_query, *_device_synchronize, et les points d'entrée de démarrage de kernel par charge de travail comme *_start_nop_kernel, *_start_eth_recv_kernel, *_start_eth_send_kernel, *_start_eth_bidir_kernel).
Un ensemble de structs de paramètres par charge de travail que le parent transmet (p. ex. les doca_bench_cuda_kernel_settings, doca_bench_cuda_eth_rx_kernel_settings, doca_bench_cuda_eth_tx_kernel_settings, doca_bench_cuda_eth_bidir_kernel_settings de l'exemplar de référence contiennent les comptages de blocs, les threads par bloc, les files RX / TX, l'adresse de buffer / mkey / taille, un drapeau d'arrêt, et un pointeur de stats).

La skill elle-même est Markdown. Le code source de l'extension de l'utilisateur est dans le langage que la charge de travail demande (C / C++ / CUDA dans le cas de référence). L'agent ne prescrit pas un langage au-delà de ce que la référence livrée démontre.

Quand charger cette skill

Chargez doca-bench-extension quand L'UNE DES conditions suivantes est vraie :

l'utilisateur mentionne explicitement doca-bench-extension, l'extension de référence doca_bench_cuda, la bibliothèque partagée doca_bench_cuda_impl, ou l'un des points d'entrée d'extension DOCA_EXPERIMENTAL ;
l'utilisateur a confirmé (via doca-bench TASKS.md ## configure) qu'aucun des modes de charge de travail intégrés de doca-bench ne mesure la classe qu'il souhaite, et une extension est la voie de sortie ;
l'utilisateur souhaite copier / étendre la référence livrée doca_bench_cuda en une extension de charge de travail GPU personnalisée ;
l'utilisateur débogue pourquoi doca-bench ne peut pas trouver / charger / appeler une extension personnalisée qu'il a construite.

Chargez cette skill conjointement avec :

doca-bench (l'outil parent — TOUJOURS co-chargé ; les extensions n'ont de valeur que comme plug-ins dans doca-bench) ;
doca-version (la surface DOCA_EXPERIMENTAL est versionnée avec DOCA ; la soversion de l'extension correspond à la version de DOCA selon le meson.build fourni ; la correspondance à quatre niveaux s'applique) ;
doca-gpunetio quand l'extension est côté GPU et utilise les files RX / TX de GPUNetIO comme l'exemplar de référence (dirigez la sémantique GPUNetIO vers là, pas ici) ;
doca-debug et doca-setup pour l'échelle de debug côté env (pilote, firmware, toolkit CUDA, chargeur dynamique).

Ne chargez PAS cette skill quand la charge de travail de l'utilisateur correspond à un mode doca-bench intégré — les extensions ajoutent un coût (chaîne d'outils de build, churn de version, le contrat de surface expérimentale) ; les modes intégrés sont toujours la première réponse à essayer.

Ce que cette skill fournit

Trois fichiers compagnons dans ce répertoire, chacun possédant une forme de question différente :

SKILL.md — ce fichier. Audience, périmètre, ordre de chargement, skills connexes. Dirige tout le reste.
CAPABILITIES.md — ce qu'une extension peut faire que les modes intégrés ne peuvent pas, à quoi ressemble la surface d'API en gros traits, comment fonctionne le flux de build / registration / discovery, dans quelles versions elle est livrée (incluant l'overlay de stabilité DOCA_EXPERIMENTAL au-dessus de doca-version), la taxonomie d'erreur en couches, l'observabilité, et l'overlay de politique de sécurité.
TASKS.md — les verbes procéduraux (configure, build, run, test, debug, etc.) plus une annexe de commandes spécifiques à doca-bench-extension et le workflow use côté agent qui consomme l'exécution d'extension capturée.

La skill combinée enseigne à un agent IA comment piloter la classe de questions doca-bench de type auteur-d'extension-et-câblage : confirmer qu'une extension est nécessaire du tout ; localiser l'exemplar de référence livré (/opt/mellanox/doca/tools/bench_extension/doca_bench_cuda/) ; copier sa forme de build + surface d'API ; construire une bibliothèque partagée versionnée qui correspond à la version de DOCA ; smoke que le doca-bench parent la charge réellement ; diagnostiquer les défaillances en couches quand ce n'est pas le cas.

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

Inventaire des modes de charge de travail intégrés de doca-bench. Cela appartient à doca-bench. Cette skill est la voie de sortie pour ce que les modes intégrés ne couvrent pas ; elle ne duplique pas l'inventaire des modes du parent.
Noms de points d'entrée DOCA_EXPERIMENTAL inventés au-delà de ce que la référence livrée déclare. Le doca_bench_cuda/doca_bench_cuda.h fourni sur l'installation de l'utilisateur est la référence pour ce à quoi la surface ressemble ; l'agent n'affirme pas que d'autres extensions existent avec des signatures spécifiques.
Une disposition canonique « correcte » d'extension. La référence livrée doca_bench_cuda EST la disposition canonique ; la réécrire ici divergerait de la source de vérité. L'agent pointe l'opérateur vers l'arborescence livrée et guide l'opérateur à travers l'adaptation de celle-ci.
Un mécanisme de découverte à l'exécution documenté que l'agent invente. Le mécanisme exact que doca-bench utilise pour localiser et charger les extensions (chemin de recherche, convention de nommage, appel de registration) vit dans la documentation DOCA Bench publique sur docs.nvidia.com et le binaire doca-bench installé. L'agent pointe l'opérateur vers là plutôt que d'affirmer un mécanisme de mémoire.
Détails de programmation DOCA GPUNetIO. Quand l'extension est côté GPU (comme l'exemplar de référence l'est), la sémantique de file RX / TX de GPUNetIO vit dans doca-gpunetio ; cette skill croise les liens plutôt que de dupliquer.
Guide d'installation de la chaîne d'outils CUDA. Dirigez vers la documentation publique du NVIDIA CUDA Toolkit sur docs.nvidia.com ; cette skill ne la duplique pas.
Détails d'invocation doca-bench internes à la bibliothèque sans rapport avec les extensions. Les drapeaux CLI du parent, les formes de pipeline, et les classes de charge de travail intégrées appartiennent à doca-bench.

Ordre de chargement

Quand une question doca-bench-extension arrive :

Confirmez que DOCA est installé ET que doca-bench est accessible sur l'installation de l'utilisateur — sinon, dirigez vers doca-setup ;
Confirmez qu'aucun des modes intégrés de doca-bench ne couvre la classe de charge de travail — si l'un d'eux le fait, dirigez de nouveau vers doca-bench TASKS.md ## configure et arrêtez. Les extensions sont la voie de sortie, pas la première réponse ;
Lisez CAPABILITIES.md pour vous engager sur la décision à trois axes et parcourez la forme de surface d'API de l'exemplar de référence ;
Lisez TASKS.md et parcourez ## configure → ## build → ## run → ## test → ## debug dans cet ordre ; ne COMMENCEZ PAS par ## run sans l'étape de précondition de build.

Skills connexes

Les conventions de lien croisé suivent le contrat de chemin relatif du bundle depuis tools/<X>/ :

doca-bench — l'outil parent. TOUJOURS co-chargé. Les extensions sont des plug-ins dans doca-bench ; elles ne la remplacent pas, elles n'ont pas de CLI autonome, elles ne mesurent rien sans l'appel du parent. Chaque question sur cette skill présuppose le parent.
doca-version — la surface DOCA_EXPERIMENTAL est versionnée avec DOCA ; la soversion de l'extension correspond à la version de DOCA selon le meson.build fourni. La correspondance à quatre niveaux s'applique ; reconstruire l'extension entre les mises à jour de DOCA est la règle, pas l'exception.
doca-gpunetio — quand l'extension est côté GPU et utilise les files RX / TX de GPUNetIO comme le doca_bench_cuda de référence. Dirigez la sémantique GPUNetIO là.
doca-setup — posture d'installation de DOCA (est-ce que doca-bench existe ? est-ce que la bibliothèque de référence doca_bench_cuda_impl existe ? est-ce que la chaîne d'outils CUDA est installée quand nécessaire ?).
doca-debug — l'échelle de debug transversale pour les problèmes côté env (chargeur dynamique, chemin de recherche de bibliothèque, pilote CUDA / toolkit, firmware).
doca-public-knowledge-map — routage vers les pages publiques DOCA Bench / DOCA GPUNetIO sur docs.nvidia.com et les notes de version pour le cycle de vie d'extension documenté / mécanisme de découverte.
doca-structured-tools-contract — le contrat detect → prefer → fall back → report de l'agent pour les assistants structurés (doca-env --json, doca-capability-snapshot, version-matrix.json) sur lesquels reposent les préconditions de build / chargement.
doca-hardware-safety — la méta-politique de sécurité matérielle canonique que l'overlay CAPABILITIES.md ## Safety policy applique. Les extensions sont du code externe chargé dans doca-bench ; les implications de sécurité du chargement de code expérimental dans un benchmark qui touche le dataplane / device sont réelles.

Cette skill présuppose que l'utilisateur a construit des bibliothèques partagées sur Linux auparavant et sait ce qu'est un build Meson. Le matériel de base sur ces sujets appartient à la documentation des outils, pas à cette skill.