DOCA Bench (`doca_bench`)

Par où commencer : Ceci est une compétence d'outil pour invoquer doca_bench, le harness de micro-benchmark cross-library. Ouvrez TASKS.md et commencez par ## configure pour la décision trois axes (bibliothèque cible × forme de charge de travail × axe de mesure), puis ## run pour le flux smoke-before-bulk. Ouvrez CAPABILITIES.md quand la question est ce que doca_bench peut mesurer, quelles bibliothèques DOCA il peut piloter, ou comment interpréter le débit / latence / op-rate sans vous tromper sur le warm-up ou l'état stable. Si DOCA n'est pas encore installé, routez d'abord vers doca-setup ; si la version installée est < 2.7.0, doca_bench n'est pas fourni sur cet hôte.

Exemples de questions que cette compétence répond bien

Les CLASSES de questions doca_bench que cette compétence est construite pour répondre, chacune avec un exemple travaillé. La classe est la pièce porteuse ; l'exemple travaillé est une instance.

"Qu'est-ce que cette bibliothèque DOCA livre vraiment sur ce dispositif ?" — exemple travaillé : "débit de DOCA Compress sur mon BlueField-3". Répondu par la configuration trois axes dans CAPABILITIES.md ## Capabilities and modes
- le flux smoke-before-bulk dans TASKS.md ## run. La même forme répond à "débit côté envoi de DOCA RDMA" — doca_bench est cross-library, non single-library.
"Quelles bibliothèques DOCA doca_bench peut-il vraiment piloter sur cette installation ?" — exemple travaillé : "doca_sha est-il énumérable sur une installation granular-build". Répondu par le système de requête intégré surfacé dans CAPABILITIES.md ## Capabilities and modes
- TASKS.md ## configure étape 2 (probe-before-bench). Énumération vide = bibliothèque non installée, non écec bench.
"Ce nombre est-il fiable, ou ai-je raté le warm-up ?" — exemple travaillé : "pourquoi mon nombre première-seconde diffère de mon nombre état-stable". Répondu par la superposition de solidité de mesure dans CAPABILITIES.md ## Error taxonomy couche 5 + TASKS.md ## test (la superposition eval-loop traite le warm-up / steady-state / outliers comme des déclencheurs de ré-itération, non des faits one-shot).
"Bench rapporte un débit zéro / se bloque au démarrage / est en désaccord avec les docs publiques." — exemple travaillé : "doca_bench affiche zéro ops pour AES-GCM mais doca_caps dit que le dispositif le supporte". Répondu par la taxonomie d'erreur en couches dans CAPABILITIES.md ## Error taxonomy (config-syntax → device-binding → library-precondition → workload-precondition → measurement-soundness → version → cross-cutting) + TASKS.md ## debug.
"Comment je capture une baseline que je peux tester en régression plus tard ?" — exemple travaillé : "snapshot débit decompress sur ce BlueField + version DOCA avant une mise à jour firmware". Répondu par la sortie CSV + la règle version-overlay dans TASKS.md ## test (capturer command line + version + device + as-deployed environment aux côtés des nombres ; citer des nombres sans le four-tuple est le mode d'échec cross-version regression-hunt).
"doca_bench retourne rien pour la bibliothèque X — que signifie cela ?" — exemple travaillé : "sortie vide pour DOCA SHA". Répondu par les règles d'interprétation empty-output dans TASKS.md ## debug + CAPABILITIES.md ## Error taxonomy. Re-routez par doca-caps pour la vérité baseline capability coarse per-device per-library, puis revenir dans bench une fois la capability confirmée présente.

Public

Cette compétence sert les opérateurs externes, développeurs, et agents IA qui ont besoin d'un moyen reproductible, soutenu par le vendeur, de mesurer la performance de la bibliothèque DOCA sur l'installation et le dispositif réels de l'utilisateur. Concrètement :

Un développeur externe choisissant entre les bibliothèques DOCA (ex. COMPRESS vs SHA vs débit DMA) avant de s'engager dans un design d'application.
Un opérateur de plateforme validant un changement de tuning (pinning NUMA, upgrade de driver, firmware burn) en relançant une baseline doca_bench capturée contre le nouvel état.
Un SRE / ingénieur de performance produisant un artefact "voici ce que le dispositif livre aujourd'hui" que les consommateurs en aval (capacity planning, regression bisection) peuvent citer.
Un agent IA répondant "quel débit / latence dois-je attendre de la bibliothèque DOCA X sur le dispositif Y ?" honnêtement — avec un nombre mesuré, la command line qui l'a produit, et la version + dispositif + environnement qui le limite — au lieu de deviner à partir des gros titres de la datasheet.

Ce n'est pas pour les utilisateurs debuggant le code source doca_bench, et pas un substitut au guide public en direct DOCA Bench sur docs.nvidia.com.

doca_bench est fourni en tant que tool (un binaire CLI unique plus une application compagne pour la moitié distante des scénarios remote-memory / RDMA / Eth), pas une bibliothèque à lier. La compétence utilise la même shape trois fichiers kind: tool que le reste du bundle donc le contrat task-verb de l'agent (configure / build / modify / run / test / debug) est uniforme entre les bibliothèques, services, et outils — même quand les verbs individuels s'effondrent en un stub de routage pour un binaire fourni.

Quand charger cette compétence

Chargez cette compétence quand l'utilisateur est — ou l'agent a besoin de — invoquer doca_bench sur un vrai host avec DOCA ≥ 2.7.0 installé (ou à l'intérieur du conteneur public NGC DOCA avec la version équivalente) pour mesurer la performance d'une bibliothèque DOCA. Concrètement :

Choisir quelle bibliothèque DOCA benchmarker pour une charge de travail candidate (RDMA vs COMPRESS vs DMA, etc.).
Choisir quel axe de mesure demander (débit vs latence bulk vs latence precision vs max-bandwidth) — les quatre modes définis dans tools/bench/doca_bench/configuration.hpp ne sont pas interchangeables.
Sonder l'état granular-build de l'installation afin que l'agent puisse rapporter honnêtement "cette bibliothèque n'est pas exposée sur cette installation" au lieu d'inventer une charge de travail.
Capturer une baseline documentée (command line + version + dispositif
- as-deployed environment + nombres) pour les chasses en régression ultérieures.
Diagnostiquer pourquoi une exécution bench a rapporté zéro / instable / inattendu résultats (la marche error-taxonomy dans TASKS.md ## debug).

Ne pas charger cette compétence pour l'orientation générale DOCA, le travail API de bibliothèque, ou l'installation. Pour ceux-ci, utilisez doca-public-knowledge-map, la compétence libs/<library> correspondante, ou doca-setup. Ne la chargez pas non plus pour le benchmarking end-to-end niveau application — doca_bench mesure la surface de la bibliothèque DOCA, pas l'application de l'utilisateur au-dessus.

Ce que cette compétence fournit

Ceci est un thin loader. Le matériel substantif vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que doca_bench peut mesurer (la portée cross-library, le modèle de configuration trois axes, les modes de fonctionnement documentés, les concepts warm-up / pipeline / multi-core qui contraignent la solidité de mesure), la version overlay (doca-bench-faits spécifiques au-dessus des règles canoniques doca-version), la taxonomie d'erreur en couches (config-syntax / device-binding / library-precondition / workload-precondition / measurement-soundness / version / cross-cutting), la surface observabilité (écran + sortie CSV, stats en temps réel, système de requête), et la posture de sécurité (l'avertissement "not for production" du guide public, la règle d'exécution host vs BlueField, la surface d'attaque de l'application compagne).
TASKS.md — workflows étape-par-étape pour les verbs task in-scope : configure (la décision trois axes + l'étape probe-before-bench), build (routez vers install — le binaire est fourni, l'application compagne est fournie), modify (refusez — ne patchlez pas le binaire bench ; modifiez l'invocation bench à la place), run (le flux smoke-before-bulk), test (la boucle eval — warm-up, steady-state, outliers, cross-version), debug (marchez la taxonomie d'erreur couche par couche), plus un bloc Deferred task verbs routant les questions out-of-scope et un Command appendix des classes d'invocation spécifiques à doca_bench.

La compétence suppose un host où DOCA ≥ 2.7.0 est déjà installé (ou le conteneur public NGC DOCA s'exécute à une version équivalente) et l'opérateur a les permissions que le guide public requiert pour que doca_bench lie des dispositifs et alloue des ressources sur leur plateforme.

Ce que cette compétence ne fournit délibérément pas

Cette compétence est agent guidance, pas un bundle samples ou scripts. Pour garder la limite nette, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

Chaînes de flag ou noms de scénario / métrique / attribut au-delà de ce que le guide public DOCA Bench documente. La surface flag évolue et est install-spécifique ; les invocations documentées + --help sur la version installée sont la réponse authoritative. Inventer un flag est le mode d'échec hallucination le plus commun pour cette compétence.
Sortie d'exemple pre-baked ou nombres throughput attendus. La sortie Bench est device-, version-, firmware-, NUMA-, et tuning-spécifique. Un nombre capturé épinglé à une plateforme et une version DOCA induit en erreur les opérateurs sur une plateforme / version différente.
Wrappers, parsers, ou scripts dans n'importe quel langage qui consomment doca_bench CSV ou stdout. Les formats de sortie sont documentés ; si un utilisateur veut scripter contre eux, la bonne réponse est "lisez le guide en direct, écrivez le parser contre votre version installée".
Un subtree samples/ ou reference/. Ceci est un thin loader pour un CLI documenté ; le matériel substantif 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 in-scope (l'utilisateur veut vraiment invoquer doca_bench pour la mesure, pas apprendre une bibliothèque DOCA en général).
Pour ce que doca_bench mesure, le modèle trois axes, la version overlay, la taxonomie d'erreur, la surface 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 — voir TASKS.md.

Compétences associées

doca-public-knowledge-map — routage vers la page publique DOCA Bench sur docs.nvidia.com et le reste de l'ensemble de documentation DOCA publique.
doca-version — la chaîne de détection de version canonique, la règle de match quatre voies, la sémantique du conteneur NGC, et la règle headers-win-over-docs. La section ## Version compatibility dans cette compétence est une thin overlay au-dessus de doca-version ; le corps vit là.
doca-structured-tools-contract — le contrat bundle-wide pour les outils helper structured-output. Les exécutables bench-runner / bench-snapshot qui satisfont la boucle detect-prefer-fallback-report sont déférés à PR2 ; le contrat est consommé ici en avance donc le ## Command appendix dans TASKS.md est infra-aware dès PR1.
doca-setup — préparation env, vérification install, hugepages, conscience NUMA, et le chemin I have no install yet avec le conteneur public NGC DOCA.
doca-debug — la ladder debug cross-cutting. Bench surface sa propre own taxonomie d'erreur dans CAPABILITIES.md ## Error taxonomy ; quand la cause s'avère être below DOCA (driver, firmware, NUMA), la taxonomie bench transfère à doca-debug.
doca-caps — l'outil DOCA sibling pour le snapshot capability coarse per-device per-library. Bench sonde la capability à grain plus fin via son propre système de requête ; doca_caps est la première étape moins chère pour confirmer que le dispositif est même visible à DOCA.
La compétence libs/<library> correspondante — ex. doca-comch, doca-compress — pour les préconditions côté charge de travail, les règles capability-query, et les overlays error-taxonomy de la bibliothèque sous test. Bench pilote la bibliothèque ; la compétence de bibliothèque explique ce que "healthy" signifie pour elle.

DOCA Bench (doca_bench)