Guide de programmation DOCA

Par où commencer : Lisez ## Audience pour confirmer que l'utilisateur consomme DOCA, ne contribue pas à son développement. Ensuite, allez à la section H2 qui correspond au verbe (## modify pour la dérivation de première application, ## build pour le motif de construction canonical, ## test pour la boucle de test, ## debug pour l'échelle de débogage pour les classes de programme).

Exemples de questions auxquelles cette skill répond bien

Ce sont les CLASSES de questions liées aux classes de programme pour lesquelles la skill est conçue, chacune avec un exemple travaillé. Les overlays spécifiques à une bibliothèque (Flow / DMS / Caps / …) se trouvent dans la skill correspondante ; cette skill répond à la forme agnostique par rapport à la bibliothèque.

« Comment écrire mon premier programme DOCA pour <n'importe quelle bibliothèque> ? » — exemple travaillé : « Je veux écrire ma première application DOCA Flow. » Répondu par le workflow de modification d'un exemple expédié dans TASKS.md ## modify plus le motif de construction canonical dans TASKS.md ## build.
« Quelle est la bonne ligne de compilation pour n'importe quelle bibliothèque DOCA ? » — exemple travaillé : « Comment compiler un programme qui appelle `docardma? »* Répondu par le motifpkg-config doca-<library>dans [TASKS.md ## build`](TASKS.md#build) (C/C++ Piste 1) et le motif FFI/bindings en Piste 2.
« Quel est le cycle de vie que suit chaque objet DOCA ? » — exemple travaillé : « Quel est le bon ordre des appels `doca_flowpipedans mon programme ? »* Répondu par le modèle cfg-create / init / start / use / stop / destroy dans [CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes).
*« `DOCAERRORa été retourné — que cela signifie-t-il et que dois-je faire ? »** — exemple travaillé : *« Mon code a obtenuDOCA_ERROR_BAD_STATE. »* Répondu par la règledoca_error_get_descr()inter-bibliothèques dans [CAPABILITIES.md ## Error taxonomy](CAPABILITIES.md#error-taxonomy) + l'ordre de débogage pour les classes de programme dans [TASKS.md ## debug`](TASKS.md#debug).
« Mon programme s'est compilé et a démarré, mais ne fait rien sur le fil. » — exemple travaillé : « Mon programme Flow s'exécute correctement mais aucun trafic n'est appareillé. » Répondu par la règle validate-before-commit dans CAPABILITIES.md ## Safety policy et l'échelle de débogage par couches pour les classes de programme dans TASKS.md ## debug.
« À quoi ressemble un consommateur DOCA <language> (FFI / bindings) ? » — exemple travaillé : « Comment appeler DOCA Comch à partir de Rust sans écrire de C ? » Répondu par la Piste 2 de TASKS.md ## build (FFI contre l'ABI C publique) et le cycle de vie neutre en ce qui concerne le langage dans CAPABILITIES.md ## Capabilities and modes.
« Comment classifier et compiler tous les exemples et applications DOCA expédiés ? Quelle est la différence entre un exemple et une application ? » — exemple travaillé : « J'ai essayé de compiler toutes les applications DOCA et 20/159 ont échoué — lesquelles sont des régressions réelles par rapport aux piles optionnelles manquantes ? » Répondu par le modèle sample-vs-application et la taxonomie category / dependency / skip-vs-fail dans TASKS.md ## sample-and-app-categorization, qui sépare « le SDK est cassé » de « la pile GPU / RMAX / MPI optionnelle n'est pas sur ce BlueField ».

Si la question concerne la classe env (install / build env / hugepages / devices), routez vers doca-setup. Si elle est spécifique à une bibliothèque (topologie de pipe Flow, configuration de QP RDMA, déploiement de service DMS), posez la skill correspondante de la bibliothèque par-dessus.

Audience

Cette skill sert les développeurs externes construisant des applications qui consomment les bibliothèques DOCA — c'est-à-dire, les utilisateurs dont le code appelle un ou plusieurs symboles doca_<library>_* (directement en C/C++, ou via FFI / bindings dans un autre langage). C'est la programmation avec DOCA, pas la programmation de DOCA : ce n'est pas pour les développeurs NVIDIA contribuant à DOCA lui-même, et cela ne suppose pas l'accès à l'arborescence source DOCA, aux outils internes NVIDIA, ou à toute information non publique. Les seules entrées vers lesquelles elle pointe jamais l'agent sont celles que tout utilisateur externe a : la documentation publique sur docs.nvidia.com/doca/sdk/, le catalogue public sur catalog.ngc.nvidia.com, les dépôts GitHub publics sous github.com/NVIDIA / github.com/NVIDIA-DOCA, le forum de développeurs public, et l'arborescence /opt/mellanox/doca sur le disque que l'installation publique de DOCA (ou le conteneur DOCA NGC public, nvcr.io/nvidia/doca/doca) met sur la machine de l'utilisateur. Les questions Où trouver et Comment installer sont routées ailleurs — voir Related skills ci-dessous.

Périmètre du langage. DOCA lui-même est une famille de bibliothèques C ; chaque exemple expédié dans /opt/mellanox/doca/samples/ et chaque application de référence expédiée dans /opt/mellanox/doca/applications/ est en C. Les consommateurs C et C++ sont le cas canonical pour chaque workflow prescriptif de cette skill. Les consommateurs dans d'autres langages (Rust, Go, Python, …) consomment les mêmes bibliothèques *.so via FFI ou des bindings spécifiques à chaque langage contre l'ABI C publique ; la skill garde le cycle de vie, la capacité, l'erreur, l'observabilité, et les conseils de sécurité agnostiques au langage, et route le travail de construction / FFI spécifique au langage vers la chaîne d'outils du consommateur sans créer de wrappers.

Quand charger cette skill

Chargez cette skill quand l'utilisateur a DOCA installé et que les préconditions de la classe env sont déjà satisfaites (c'est-à-dire, doca-setup a produit une installation propre où pkg-config doca-<library> se résout, les hugepages sont montées, et les devices sont visibles), et pose maintenant une question sur comment programmer réellement contre DOCA de façon agnostique par rapport à la bibliothèque :

Comprendre quels sont les éléments de DOCA (bibliothèques, applications, services, outils) et de quel côté du fil ils s'exécutent.
Le motif de construction canonical pkg-config + meson que chaque application DOCA suit, indépendamment de la bibliothèque qu'elle consomme.
Le workflow universel dériver une application de première application personnalisée à partir d'un exemple expédié que chaque skill de bibliothèque étend avec des overrides spécifiques à la bibliothèque — déplacé ici de doca-setup car c'est un verbe de programmation, pas un verbe env.
Le cycle de vie DOCA universel (cfg-create → init → start → use → stop → destroy) et comment il se manifeste across les bibliothèques.
Le motif général DOCA_ERROR_*, doca_error_t, et doca_error_get_descr() — la forme inter-bibliothèques, pas les overlays spécifiques à Flow ou RDMA.
La règle validate-before-commit et la politique de sécurité côté programme que chaque skill de bibliothèque hérite.
Les motifs de programmation qui s'appliquent aux consommateurs dans n'importe quel langage (C/C++ directement, FFI / bindings pour Rust / Go / Python / …) — la skill garde les motifs agnostiques au langage et pointe l'agent vers l'ABI C publique comme la surface faisant autorité.

Ne chargez pas cette skill pour :

« Mon installation est-elle saine ? Pourquoi pkg-config ne trouve pas doca-flow ? Comment monter les hugepages ? Je n'ai pas encore DOCA installé — puis-je utiliser un conteneur ? » — les questions de classe env appartiennent à doca-setup, qui possède la vérification d'installation, la préparation env, le débogage de classe env, et le chemin no-install → NGC container pour tout utilisateur sur macOS, Windows, ou Linux sans DOCA.
« Qu'est-ce que DOCA ? Où se trouve le guide de programmation Flow ? Quel paquet dois-je installer ? » — les questions de routage / orientation appartiennent à doca-public-knowledge-map.
« Comment construire un pipe Flow / configurer une queue RDMA / utiliser Comch pour envoyer un message ? » — les questions d'API internes à une bibliothèque appartiennent à la skill correspondante de la bibliothèque (par exemple doca-flow).

Ce que cette skill fournit

C'est un loader mince. Le corps conserve uniquement l'orientation nécessaire pour choisir le bon fichier suivant. Le matériel substantiel se trouve dans deux fichiers compagnons :

CAPABILITIES.md — à quoi ressemble chaque programme DOCA en abstrait : la forme de DOCA (host / DPU / switch, bibliothèques / applications / services / outils, rationnelle de sélection de saveur de construction), le cycle de vie universel du programme, la règle de compatibilité de version unifiée qui s'applique à chaque programme liant DOCA, la taxonomie inter-bibliothèques DOCA_ERROR_*, la surface d'observabilité côté programme (journalisation DOCA, snapshots de capacité), et la politique de sécurité côté programme que chaque skill de bibliothèque hérite.
TASKS.md — workflows étape par étape pour les six verbes de programmation dans le périmètre : configure, build, modify, run, test, debug. Le verbe ## modify possède le motif universel dériver une application de première application personnalisée à partir d'un exemple que chaque skill de bibliothèque DOCA étend avec des overrides spécifiques à la bibliothèque ; le verbe ## build possède le motif de construction canonical pkg-config doca-<library> en deux pistes de langage (C/C++ direct, non-C via FFI).

Cette skill suppose que doca-setup a déjà produit une installation propre. Elle ne couvre pas la préparation env ; c'est le travail de doca-setup, y compris le fallback no-install → NGC container (nvcr.io/nvidia/doca/doca) pour les utilisateurs sur macOS, Windows, ou Linux sans DOCA.

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

Cette skill est un guide d'agent, pas un bundle d'exemples ou de templates. Elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

Code source d'application DOCA pré-écrit, dans n'importe quel langage. Cela inclut les fichiers C / C++, les crates Rust, les packages Go, les modules Python, et le code wrapper pour n'importe quel autre langage. La surface d'API DOCA évolue entre les versions et le code écrit à partir de prose de documentation ne peut pas être vérifié sans compiler / lier / charger FFI contre la bibliothèque en direct sur une installation réelle. Le code source d'application DOCA vérifié est les exemples C expédiés sur le système installé de l'utilisateur ; le travail de l'agent est de router l'utilisateur vers ce fichier et de prescrire une modification de différence minimale sur lui (TASKS.md ## modify) — pour les utilisateurs C/C++ — ou de router les utilisateurs non-C vers la surface ABI C publique que leurs bindings appelleront (TASKS.md ## build Piste 2), pas de créer le wrapper.
Des manifestes de construction 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 construction dans le répertoire de projet de l'utilisateur contre le DOCA installé de l'utilisateur, où pkg-config --modversion doca-<library> est la source de vérité.
Une sous-arborescence samples/, bindings/, ou reference/ d'aucune sorte. Un artifact fictif ou incomplet dans l'arborescence de cette skill, même un é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 une question de classe de programmation (pas env, pas routage, pas API de bibliothèque).
Pour la forme DOCA, le cycle de vie universel, la taxonomie d'erreur inter-bibliothèques, la surface d'observabilité côté programme, et la politique de sécurité que chaque skill de bibliothèque hérite, voir CAPABILITIES.md.
Pour les workflows de programmation étape par étape — configure, build, modify, run, test, debug — voir TASKS.md.

Si l'utilisateur demande une première application dans une bibliothèque spécifique, parcourez TASKS.md ## modify pour le motif universel de copie et édition, puis confiez au skill de la bibliothèque (par exemple doca-flow) les valeurs spécifiques à la bibliothèque à échanger.

Skills connexes

doca-public-knowledge-map — routage de la documentation DOCA publique et la disposition sur le disque d'un paquet DOCA installé. Cette skill reporte toutes les questions « où X est documenté », « où sur le disque Y », et « comment vérifier la version installée » vers la knowledge-map.
doca-setup — préparation env, vérification d'installation, débogage de classe env, et la procédure Je n'ai pas encore d'installation avec le conteneur NGC (nvcr.io/nvidia/doca/doca) comme le fallback Stage-1 universel pour tout utilisateur sur macOS, Windows, ou Linux sans DOCA. Cette skill suppose que les préconditions de doca-setup sont déjà satisfaites.
doca-flow — DOCA Flow sur BlueField. Étend le ## modify de cette skill (dérivation universelle de première application) avec la liste des champs spécifiques à Flow à échanger.

doca-programming-guide