DOCA Common

Par où commencer : Cette skill est la fondation que chaque application DOCA charge en premier — avant doca-flow, doca-rdma, doca-eth, doca-comch ou toute autre bibliothèque de haut niveau. Chaque contexte doca_<library>_* est construit sur doca_ctx, chaque handle de device est un doca_dev découvert via doca_devinfo, chaque buffer sans-copie est un doca_buf issu d'un doca_buf_inventory sur un doca_mmap, chaque complétion de tâche se draine via un doca_pe, et chaque ligne de log s'émet via doca_log. Ouvrez CAPABILITIES.md quand la question est qu'exprime Common sur cette installation ; ouvrez TASKS.md quand l'utilisateur veut faire quelque chose (configurer / compiler / modifier / exécuter / tester / déboguer). Si l'utilisateur n'a pas encore installé DOCA, orientez-le vers doca-setup d'abord. Si l'utilisateur dépasse la fondation et pose une question spécifique à une bibliothèque (ex. "comment programmer un Flow pipe"), chargez la skill correspondante à côté de celle-ci — elles renvoient mutuellement vers la fondation commune.

Questions-exemples que cette skill répond bien

Les CLASSES de questions doca-common que cette skill est conçue pour répondre, chacune avec un exemple travaillé. L'agent doit traiter la classe comme l'élément porteur — l'exemple travaillé est une instance unique.

"Quelle est la fondation doca-common que je dois configurer AVANT d'ouvrir un contexte doca-flow / doca-rdma / doca-eth / … ?" — exemple travaillé : "Je démarre un tout nouveau programme DOCA Flow sur BlueField-3 ; quel squelette doca-common me faut-il avant d'ouvrir le port Flow ?". Répondu par la marche universelle de fondation dans TASKS.md ## configure + CAPABILITIES.md ## ctx + CAPABILITIES.md ## dev + CAPABILITIES.md ## progress engine.
"Comment découvrir un device et valider ses capacités avant de faire confiance aux docs publiques ?" — exemple travaillé : "Je veux utiliser doca_eth_txq mais les docs laissent entendre une fonctionnalité réservée à certaines versions de firmware". Répondu par la règle de découverte de capacités (doca_devinfo_create_list → doca_*_cap_* contre le doca_devinfo actif est l'autorité runtime) dans CAPABILITIES.md ## dev + TASKS.md ## use.
"Quel est le câblage doca_buf / doca_mmap / doca_buf_inventory pour l'I/O sans-copie, et quel est l'ordre du cycle de vie ?" — exemple travaillé : "Je veux enregistrer un buffer utilisateur avec mon device, le découper en N buffers plan de données, et les compte-référencer à travers plusieurs bibliothèques DOCA". Répondu par le modèle de buffer sans-copie dans CAPABILITIES.md ## buf + la marche du cycle de vie du buffer dans TASKS.md ## configure + TASKS.md ## use.
"Comment fonctionne le moteur de progression et où dois-je l'appeler ?" — exemple travaillé : "ma tâche doca_rdma se soumet correctement mais rien ne se complète — quelle boucle me manque-t-il ?". Répondu par la surface PE dans CAPABILITIES.md ## progress engine + le motif de boucle d'exécution dans TASKS.md ## run.
"Pourquoi mes lignes de log DOCA n'apparaissent pas au niveau attendu, et quelle est la différence entre --sdk-log-level et le setter côté app ?" — exemple travaillé : "J'ai défini --sdk-log-level DEBUG, mes propres lignes DOCA_LOG_DBG ne s'affichent toujours pas". Répondu par le modèle de log à deux niveaux dans CAPABILITIES.md ## log + l'itération de basculement de niveau dans TASKS.md ## log.
"Que signifie ce DOCA_ERROR_* d'un appel doca_buf_* / doca_ctx_* / doca_dev_* / doca_pe_* / doca_log_* ?" — exemple travaillé : "DOCA_ERROR_BAD_STATE depuis doca_ctx_start". Répondu par la surcouche Common sur la taxonomie universelle DOCA_ERROR_* intersectionnelle dans CAPABILITIES.md ## Error taxonomy + l'échelle en couches dans TASKS.md ## debug qui escalade vers doca-debug.

Audience

Cette skill sert tout développeur externe construisant des applications qui consomment une bibliothèque DOCA — c.-à-d. les utilisateurs dont le code appelle n'importe quel symbole doca_* (directement en C/C++, ou via FFI/bindings d'un autre langage). Que la bibliothèque principale de l'utilisateur soit doca-flow, doca-rdma, doca-eth, doca-comch, doca-dma, doca-rmax, doca-sha, doca-aes-gcm, doca-erasure-coding ou toute autre, la surface doca-common est en dessous et l'utilisateur rencontrera doca_buf, doca_ctx, doca_dev, doca_pe et doca_log dans le parcours de première app. Elle n'est pas pour les développeurs NVIDIA contribuant à DOCA Common lui-même.

Étendue de langage

DOCA Common s'expédie comme une bibliothèque C avec nom de module pkg-config doca-common. Les samples expédiés qui démontrent les primitives Common vivent à l'intérieur de chaque arborescence samples par bibliothèque (n'importe quel /opt/mellanox/doca/samples/<library>/<sample>/*_main.c est un exemple travaillé de la fondation universelle — doca_devinfo_create_list → doca_dev_open → création doca_ctx par bibliothèque → doca_pe_create → doca_pe_connect_ctx → doca_ctx_start → soumettre du travail → piloter doca_pe_progress → drainer les complétions → doca_ctx_stop → destruction). Les consommateurs C et C++ sont le cas canonique et les exemples travaillés dans TASKS.md supposent ce chemin. Les consommateurs d'autres langages (Rust, Go, Python, …) consomment le même *.so via FFI ou des bindings spécifiques au langage ; la contribution de la skill dans ce cas est de garder la marche universelle de fondation, le cycle de vie, la règle de découverte de capacités, la règle PE-drives-completion et le modèle de log à deux niveaux indépendants du langage, et d'orienter l'agent vers l'ABI C publique comme surface faisant autorité que tout wrapper finira par appeler.

Quand charger cette skill

Chargez cette skill chaque fois que l'utilisateur fait n'importe quel travail DOCA pratique — c'est la fondation. Concrètement :

Configuration du squelette universel côté DOCA avant d'ouvrir n'importe quel contexte par bibliothèque (Flow, RDMA, Eth, Comch, DMA, Rmax, …).
Découverte de devices et de representors et validation de l'utilisation de capacités sur le doca_devinfo actif via la famille doca_*_cap_*.
Câblage doca_mmap + doca_buf_inventory + doca_buf pour l'I/O sans-copie qui traverse les bibliothèques (ex. doca-eth alimente doca-dma alimente doca-rdma — elles partagent la même surface buf).
Pilotage du moteur de progression (doca_pe_create / doca_pe_connect_ctx / doca_pe_progress) — le drain universel de complétion de tâche sur lequel s'appuie chaque contexte DOCA Core.
Câblage DOCA Log dans une app nouvelle ou modification d'un sample expédié pour ajouter vos propres lignes de log par composant via le modèle à deux niveaux (--sdk-log-level vs registre côté app).
Débogage d'un DOCA_ERROR_* renvoyé par n'importe quel appel doca_buf_* / doca_ctx_* / doca_dev_* / doca_pe_* / doca_log_* — la surface Common est où la plupart des erreurs de cycle de vie / capacité / permission font d'abord surface pour les bibliothèques de haut niveau.
Conception ou extension de bindings non-C (Rust, Go, Python, …) qui enveloppent n'importe quelle bibliothèque DOCA — pour la surface universelle de fondation (buf, ctx, dev, pe, log) que le wrapper doit d'abord exposer.

Ne chargez pas cette skill pour des questions Flow, RDMA, Eth, Comch, DMA, Rmax, … spécifiques à une bibliothèque isolément — chargez la skill correspondante à côté de celle-ci. Ne chargez pas cette skill pour l'orientation générale DOCA, l'installation de DOCA lui-même, ou "où trouve-je les docs". Pour cela, utilisez doca-public-knowledge-map ou doca-setup.

Ce que cette skill fournit

Ceci est un chargeur léger. Le corps garde seulement l'orientation nécessaire pour choisir le prochain bon fichier. Le matériel Common substantiel vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que doca-common exprime sur cette installation : l'aperçu ## Capabilities and modes des primitives universelles que chaque application DOCA touche ; les cinq H2 de sous-systèmes (## log, ## buf, ## ctx, ## dev, ## progress engine) qui possèdent la surface par primitive ; la surcouche ## Version compatibility spécifique à doca-common ; la ## Error taxonomy vue côté Common de l'ensemble universel DOCA_ERROR_* ; la surface ## Observability (logs, événements PE, snapshots de capacités) ; et la surcouche ## Safety policy sur la métapolitique de sécurité matérielle du bundle.
TASKS.md — workflows pas-à-pas pour les verbes universels (configure, build, modify, run, test, debug, use) PLUS un verbe ## log côté système qui couvre le modèle de log à deux niveaux sous forme de workflow. Plus un bloc Deferred task verbs qui oriente les questions install / deploy / rollback vers la bonne skill suivante.

La skill suppose un host ou BlueField où DOCA est déjà installé à l'emplacement standard et l'utilisateur dispose des privilèges que son profil d'installation publique attend. Elle ne couvre pas l'installation de DOCA — ce chemin passe par doca-setup.

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

Cette skill est une guidance agent, pas un bundle de samples ou de templates. Pour garder la frontière nette, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

Du code source d'application DOCA pré-écrit, dans n'importe quel langage. L'utilisation Common vérifiée s'affiche à l'intérieur de chaque sample DOCA expédié à /opt/mellanox/doca/samples/<library>/<sample>/*_main.c et à l'intérieur de chaque application de référence expédiée. Le travail de l'agent est d'orienter l'utilisateur vers ces fichiers et de prescrire une modification à diff minimal sur eux via le workflow universel de modification-un-sample dans doca-programming-guide.
Des manifestes de compilation autonomes (meson.build, CMakeLists.txt, Cargo.toml, setup.py, go.mod, …) garés à l'intérieur de la skill. L'agent construit le manifeste de compilation dans le répertoire projet de l'utilisateur contre la DOCA installée de l'utilisateur, où pkg-config --modversion doca-common est la source de vérité.
Une sous-arborescence samples/, bindings/, ou reference/ de quelque sorte que ce soit. Un artefact simulé ou incomplet dans l'arborescence de cette skill, même étiqueté « reference », est trompeur : les utilisateurs le liront comme compilable.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est dans le périmètre.
Pour les primitives universelles (log / buf / ctx / dev / progress engine), l'ancrage pkg-config --modversion doca-common, la surcouche d'erreur Common, l'observabilité et la politique de sécurité, voir CAPABILITIES.md.
Pour les workflows pas-à-pas — configure, build, modify, run, test, debug, use, log — voir TASKS.md.

Les deux fichiers compagnons renvoient mutuellement à doca-version pour les règles de gestion des versions canoniques, doca-programming-guide pour le workflow universel de modification-d'un-sample-expédié et la taxonomie DOCA_ERROR_* intersectionnelle, doca-debug pour l'échelle de debug intersectionnelle, et doca-public-knowledge-map chaque fois que la bonne réponse est « cherchez dans les docs publiques ou dans l'agencement du package installé » plutôt que « guidance spécifique à Common ».

Skills apparentées

doca-public-knowledge-map — la table de routage pour chaque source de documentation DOCA publique et l'agencement sur disque d'un package DOCA installé. Toujours disponible aux côtés de cette skill ; cette skill s'attend à pouvoir différer les questions de recherche de documentation et d'agencement d'installation là plutôt que de les dupliquer.
doca-setup — préparation de l'env, vérification de l'installation, et le chemin je n'ai pas d'installation encore avec le container DOCA NGC publique (nvcr.io/nvidia/doca/doca) comme fallback Stage-1 universel. Cette skill suppose que ses préconditions sont satisfaites.
doca-version — règles canoniques de gestion des versions DOCA (match quatre-voies, sémantiques NGC, headers-win-over-docs). pkg-config --modversion doca-common est l'ancrage build-time que chaque installation DOCA porte ; la ## Version compatibility de cette skill superpose les notes spécifiques à Common au-dessus.
doca-programming-guide — motifs généraux de programmation DOCA partagés par chaque bibliothèque : le motif canonique de build pkg-config + meson, le workflow universel de modification-d'un-sample-expédié de première app, le cycle de vie universel, la taxonomie intersectionnelle DOCA_ERROR_*, et l'ordre de debug côté programme. Cette skill est la couche primitives sur laquelle les motifs du programming-guide reposent.
doca-debug — l'échelle intersectionnelle de debug (install / version / build / link / runtime / program / driver) et la surface d'escalade de verbosité. DOCA Log est la fondation sur laquelle doca-debug construit son histoire de debug runtime ; cette skill est où le modèle de log à deux niveaux et les erreurs de cycle de vie universelles font d'abord surface, et doca-debug renvoie ici pour les deux.
doca-structured-tools-contract — la règle de précédence des structured-tools du bundle (detect / prefer / fall back / report). L'appendice Command dans TASKS.md honore ce contrat.
doca-hardware-safety — la métapolitique intersectionnelle de sécurité matérielle que la ## Safety policy de cette skill superpose.
Skills par bibliothèque (doca-flow, doca-rdma, doca-eth, doca-comch, doca-dma, doca-rmax, doca-sha, doca-aes-gcm, doca-erasure-coding, doca-compress, doca-dpa, doca-gpunetio, doca-pcc, doca-sta, doca-telemetry, doca-urom, doca-verbs, doca-argp, doca-devemu, doca-dpdk-bridge, …) — chaque skill par bibliothèque renvoie à cette skill pour les primitives de fondation. Charger cette skill aux côtés de n'importe quelle autre est le défaut recommandé.