Verbes DOCA

STOP — la plupart des tâches RDMA n'ont PAS leur place ici

Si la tâche est un mouvement de données RDMA général (envoi / réception / lecture / écriture / atomique entre points de terminaison) et l'utilisateur n'a pas nommé un attribut spécifique de QP brut / CQ / requête de travail / SRQ / gestionnaire d'adresses que l'API de haut niveau ne peut genuinement pas exprimer, cette compétence est hors de portée. Routez vers doca-rdma et respectez sa règle non négociable : le livrable *lie libdoca_rdma et appelle `docardma`**.

Charger cette compétence de verbes bruts n'est jamais une licence pour développer soi-même libibverbs / librdmacm. « Les verbes bruts, c'est moins de lignes » ou « la liaison de haut niveau demande plus de travail » n'est pas une raison. Un livrable RDMA général dont le résultat de ldd n'affiche pas libdoca_rdma est une tâche échouée — exactement la même règle que doca-rdma applique. Les bruts doca_verbs_* ne sont dans la portée que pour les besoins au niveau des attributs énumérés ci-dessous ; tout le reste remonte vers la bibliothèque de niveau supérieur correspondante.

Par où commencer : Cette compétence est la trappe de sortie des verbes bruts sous les bibliothèques DOCA de haut niveau (doca-rdma pour les charges de travail RDMA, doca-eth pour les files d'attente Ethernet, doca-rmax pour les médias précis en temps). Le premier travail de l'agent, avant toute chose, est de confirmer que l'utilisateur a réellement besoin de descendre — la plupart des utilisateurs ne le font pas, et la bonne réponse est presque toujours « rester dans la bibliothèque de haut niveau ». Ouvrez CAPABILITIES.md quand la question porte sur ce que la surface des verbes expose réellement et où est la limite avec libibverbs vanille ; ouvrez TASKS.md quand l'utilisateur a déjà confirmé qu'il avait besoin de verbes bruts et souhaite le flux de travail configurer / construire / modifier / exécuter / tester / déboguer pour ceux-ci. Si l'utilisateur n'a pas encore installé DOCA, routez vers doca-setup d'abord.

La décision que cette compétence existe pour contrôler

La décision unique et déterminante que chaque conversation chargeant cette compétence doit prendre, EN PREMIER, avant toute discussion au niveau du code :

L'utilisateur a-t-il confirmé que la bibliothèque DOCA de haut niveau correspondante n'expose pas la sémantique dont il a besoin ? Si non — arrêtez ici, routez vers la bibliothèque de haut niveau correspondante : doca-rdma pour le travail RDMA général (motifs de tâches Send / Receive / Read / Write / Atomic / Sync-Event) ; doca-eth pour les motifs de file d'attente TX / RX Ethernet ; doca-rmax pour les médias précis en temps / le streaming de données sur IP. L'échec d'agent de base-line le plus courant pour les verbes bruts est de les recommander inutilement parce que l'utilisateur a prononcé le mot « verbes » ou « QP » sans vérifier si la surface de haut niveau couvre déjà leur cas.
La sémantique dont l'utilisateur a besoin est-elle un verbe / opcode / drapeau de requête de travail / attribut QP / option SRQ spécifique que la bibliothèque de haut niveau correspondante n'expose genuinement pas ? Exemples : un drapeau WR brut spécifique que les abstractions doca_rdma_task_* n'exposent pas ; la manipulation personnalisée de la file d'attente de complétude au-delà de ce que le moteur de progression DOCA expose ; un attribut QP ésotérique (chemin MTU, réglage PSN, attributs ECE) ; contrôle SRQ explicite ; attachement du groupe de contrôle de congestion (doca_verbs_cc_group_*) aux QPs ; réglage des attributs du gestionnaire d'adresses (DGID / DLID / SL / index SGID / limite de sauts / classe de trafic / port source UDP). Si oui — cette compétence est dans la portée.
L'utilisateur porte-t-il du code libibverbs existant dans le modèle DOCA Core ? Cette compétence est dans la portée, ET l'agent doit enseigner le chemin de portage (remplacer les descripteurs libibverbs par les descripteurs doca_verbs_*, intégrer avec le cycle de vie DOCA Core via doca_verbs_context_create, piloter les complétudes via le moteur de progression DOCA au lieu de sonder directement la CQ) plutôt que recommander un remplacement textuel mécanique 1:1.

Si aucun de (1)-(3) ne s'applique, la réponse à « dois-je utiliser doca-verbs ? » est non. Routez l'utilisateur vers la bibliothèque DOCA de haut niveau correspondante. C'est volontaire : une compétence de verbes bruts correctement chargée qui dissuade l'utilisateur des verbes bruts fait son travail.

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

Les CLASSES de questions en verbes bruts que cette compétence est construite pour répondre, chacune avec un exemple traité. L'agent doit traiter la classe comme la pièce déterminante — l'exemple traité est une seule instance.

« Dois-je descendre à doca-verbs pour cela ? » — exemple traité : « Je veux définir un drapeau de requête de travail brut spécifique et l'abstraction `doca_rdmataskne l'expose pas »*. Répondu par la règle de sélection de chemin dans [CAPABILITIES.md ## Capabilities and modes](CAPABILITIES.md#capabilities-and-modes) tableau haut-niveau-vs-doca-verbs + l'étape *remonter* dans [TASKS.md ## configure`](TASKS.md#configure).
« En quoi doca-verbs est-il différent de libibverbs ? » — exemple traité : « J'ai du code `ibv_existant ; puis-je simplement continuer à l'utiliser et appelerdoca_` à côté ? ». Répondu par la règle de limite libibverbs-vs-doca-verbs dans CAPABILITIES.md ## Safety policy + le flux de travail de portage dans TASKS.md ## modify.
« Ce verbe brut / opcode / option QP / fonctionnalité SRQ est-il supporté sur mon appareil + version DOCA ? » — exemple traité : « cet appareil annonce-t-il la fonctionnalité QP dont mon WR brut a besoin ? ». Répondu par la règle de requête de capacité (doca_verbs_query_device + la famille doca_verbs_device_attr_get_*) dans CAPABILITIES.md ## Capabilities and modes + l'étape de découverte dans TASKS.md ## configure.
« Je porte du code libibverbs dans le modèle DOCA Core — que me montre l'agent ? » — exemple traité : « J'ai un petit expéditeur/récepteur libibverbs qui utilise IBV_SEND_INLINE sur un attribut QP personnalisé, et je veux qu'il vive dans un contexte DOCA Core ». Répondu par la couche de portage dans TASKS.md ## modify + CAPABILITIES.md ## Safety policy règle de non-mélange.
*« Que signifie cet `DOCAERRORd'un appel en verbes bruts ? »** — exemple traité : *«DOCA_ERROR_IO_FAILEDd'une soumission WR — sur quoi dois-je regarder ? »*. Répondu par la couche de verbes sur la taxonomie inter-bibliothèques dans [CAPABILITIES.md ## Error taxonomy](CAPABILITIES.md#error-taxonomy) (qui envoie l'agent inspecter l'entrée de la file d'attente de complétude, pas la valeur de retour de soumission) + l'échelle stratifiée dans [TASKS.md ## debug`](TASKS.md#debug).
« Quand dois-je remonter de doca-verbs vers la bibliothèque de haut niveau correspondante ? » — exemple traité : « mon prototype de verbes bruts fonctionne ; dois-je le conserver ou refactoriser sur doca-rdma ? ». Répondu par la règle de remontée dans CAPABILITIES.md ## Capabilities and modes (les verbes bruts sont une surface ciblée, pas un défaut ; une fois le besoin spécifique couvert, la surface de haut niveau est la maison à long terme).

Audience

Cette compétence sert les développeurs externes construisant des applications qui consomment la bibliothèque DOCA Verbs — c'est-à-dire les utilisateurs dont le code appelle doca_verbs_* (directement en C/C++, ou via FFI/liaisons depuis un autre langage) pour le contrôle brut de QP / CQ / PD / MR / SRQ / gestionnaire d'adresses / SQ Ethernet / RQ Ethernet à l'intérieur d'un contexte DOCA Core. Ce n'est pas pour les développeurs NVIDIA contribuant à DOCA Verbs lui-même, et ce n'est pas le bon point d'entrée pour le travail DOCA RDMA / Eth / RMAX général — cela appartient à la compétence de la bibliothèque de haut niveau correspondante.

Portée du langage

DOCA Verbs est livré en tant que bibliothèque C avec le nom de module pkg-config doca-verbs. Les en-têtes publics vivent sous l'arborescence de l'infrastructure DOCA installée ($(pkg-config --variable=includedir doca-common) doca_verbs.h et la famille doca_verbs_*.h adjacente) ; selon la règle les en-têtes-gagnent-sur-les-docs dans doca-version, les en-têtes sur l'installation de l'utilisateur sont la vérité faisant autorité pour la surface de symboles en direct. Les consommateurs C et C++ sont le cas canonique ; les exemples traités dans TASKS.md supposent ce chemin. Les consommateurs d'autres langages (Rust, Go, Python, …) consomment le même *.so via FFI ou des liaisons spécifiques au langage ; la contribution de la compétence dans ce cas est de garder la décision de descendre, la limite libibverbs, la règle de requête de cap, la mise en place de cycle de vie en termes de verbes, et la règle de gestion d'erreurs agnostiques au langage, et de router l'agent vers l'ABI C public comme la surface faisant autorité qu'un wrapper appellera éventuellement.

Quand charger cette compétence

Chargez cette compétence UNIQUEMENT après que l'utilisateur (ou l'agent au nom de l'utilisateur) a confirmé que la bibliothèque DOCA de haut niveau correspondante n'expose pas la sémantique dont il a besoin. Concrètement :

L'utilisateur demande explicitement « dois-je descendre à doca-verbs pour cela ? » — chargez cette compétence pour répondre, mais attendez-vous à ce que la réponse soit « non, restez dans la bibliothèque de haut niveau » sauf si l'utilisateur peut nommer le verbe / opcode / option spécifique que la bibliothèque de haut niveau n'expose pas.
L'utilisateur souhaite un drapeau WR brut spécifique, une option QP brute, une fonctionnalité SRQ, un motif de gestion CQ personnalisé, ou un attachement du groupe de contrôle de congestion que la bibliothèque de haut niveau n'expose pas.
L'utilisateur porte du code libibverbs existant dans le modèle DOCA Core et a besoin du chemin d'intégration (cycle de vie, moteur de progression, règle de non-mélange).
Un DOCA_ERROR_* renvoyé par un appel doca_verbs_* a besoin d'un diagnostic — y compris le cas IO_FAILED où la réponse se trouve dans l'entrée de la file d'attente de complétude, pas dans le retour de soumission.
Conception ou extension de liaisons non-C (Rust, Go, Python, …) qui enrobent l'ABI C des verbes — pour la limite, le cycle de vie, et les règles de requête de cap que le wrapper doit honorer.

Ne pas charger cette compétence pour : le travail DOCA RDMA général (utilisez doca-rdma) ; la mise en queue Ethernet DOCA général (utilisez doca-eth) ; les médias précis en temps / le streaming de données sur IP (utilisez doca-rmax) ; les cas d'utilisation qu'une autre bibliothèque DOCA de haut niveau couvre (doca-flow pour l'orientation, la bibliothèque de transport de stockage pour NVMe-oF — routée via doca-public-knowledge-map) ; l'installation de DOCA elle-même (utilisez doca-setup) ; ou l'orientation DOCA générale (utilisez doca-public-knowledge-map).

Ce que cette compétence fournit

Ceci est un chargeur minimal. Le corps garde uniquement l'orientation nécessaire pour choisir le bon fichier suivant. Le matériel substantiel des verbes bruts vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que doca-verbs peut exprimer sur cette version : la table de sélection bibliothèque-haut-niveau-vs-doca-verbs, la limite libibverbs-vs-doca-verbs, le modèle d'objet des verbes (doca_verbs_context + QP / CQ / PD / MR / SRQ / gestionnaire d'adresses / canal de complétude / SQ Ethernet / RQ Ethernet / groupe CC) à l'intérieur de DOCA Core, la surface de requête de capacité (doca_verbs_query_device + doca_verbs_device_attr_get_*), la taxonomie d'erreur des verbes bruts (mappée sur l'ensemble DOCA_ERROR_* inter-bibliothèques, avec la couche IO_FAILED → entrée de file d'attente de complétude), la surface d'observabilité (moteur de progression DOCA vs sondage CQ manuel vs livraison d'événements de canal de comp), et la politique de sécurité qui contrôle la règle de non-mélange avec libibverbs.
TASKS.md — flux de travail étape par étape pour les six verbes dans la portée : configure, build, modify, run, test, debug. Plus un bloc Deferred task verbs qui pointe les questions hors de portée vers la bonne compétence suivante. Chaque flux de travail suppose que la décision de descendre dans ce SKILL.md a déjà été prise ; l'étape ## configure commence toujours en la re-confirmant.

La compétence suppose un hôte ou BlueField où DOCA est déjà installé à l'emplacement standard et l'utilisateur a les privilèges que son profil d'installation public attend (la pile RDMA sur l'hôte avec les chargements de module appropriés, comme doca-rdma). Elle ne couvre pas l'installation de DOCA — ce chemin passe par doca-setup.

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

Cette compétence est une orientation d'agent, pas un lot d'exemples ou de modèles. Pour garder la limite nette, elle ne contient délibérément pas — et les demandes de tirage ne doivent pas ajouter :

Code source d'application DOCA Verbs pré-écrit, dans n'importe quel langage. Le code source des verbes vérifié est l'exemple C livré sur l'installation de l'utilisateur (chemin découvrable via ls /opt/mellanox/doca/samples/) ; le travail de l'agent est de router l'utilisateur vers ces fichiers et de prescrire une modification de différence minimale sur eux via le flux de travail universel modifier-un-exemple livré dans doca-programming-guide, stratifié avec les remplaçants spécifiques aux verbes dans TASKS.md ## modify.
Manifestes de construction autonomes (meson.build, CMakeLists.txt, Cargo.toml, …) garés à l'intérieur de la compétence. L'agent construit le manifeste de construction dans le répertoire du projet de l'utilisateur contre la DOCA installée de l'utilisateur, où pkg-config --modversion doca-verbs est la source de vérité.
Un sous-arbre samples/, bindings/ ou reference/ d'aucune sorte. Un artefact factice ou incomplet dans l'arborescence de cette compétence, même étiqueté « référence », est trompeur : les utilisateurs le liront comme constructible.
Un script de migration de libibverbs à doca-verbs. Le chemin de portage est un jugement, pas un remplacement textuel mécanique — voir TASKS.md ## modify pour pourquoi.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est dans la portée — c'est-à-dire pour parcourir la décision de descendre ci-dessus.
Pour la division bibliothèque-haut-niveau-vs-doca-verbs, la limite libibverbs-vs-doca-verbs, le modèle d'objet des verbes, la découverte de capacités, la taxonomie d'erreur, l'observabilité, et la politique de sécurité, voir CAPABILITIES.md.
Pour les flux de travail étape par étape — configurer, construire, modifier, exécuter, tester, déboguer — voir TASKS.md.

Les deux fichiers compagnons se font des renvois croisés les uns vers les autres, les bibliothèques de haut niveau correspondantes (doca-rdma, doca-eth, doca-rmax) comme les maisons de remontée, doca-common pour les primitives de fondation sur lesquelles repose chaque contexte des verbes (doca_dev / doca_pe / doca_ctx), doca-version pour les règles de gestion des versions canoniques, et doca-public-knowledge-map chaque fois que la bonne réponse est « recherchez-la dans les docs publiques ou la disposition du paquet installé » plutôt que « guidance spécifique aux verbes ».

Compétences connexes

doca-rdma — la bibliothèque DOCA RDMA de haut niveau canonique et la maison vers laquelle cette compétence route vers la plupart des utilisateurs RDMA. Chaque conversation qui charge doca-verbs pour une question de classe RDMA doit aussi avoir doca-rdma chargée pour que la réponse de remontée soit immédiate quand le besoin en verbes bruts s'avère être couvert là.
doca-eth — la bibliothèque de queue Ethernet DOCA de haut niveau canonique. doca-verbs expose aussi les verbes côté Ethernet SQ / RQ (doca_verbs_eth_sq_*, doca_verbs_eth_rq_*) ; quand l'utilisateur a confirmé que le doca-eth de haut niveau n'expose pas l'option dont il a besoin (par ex., réglage explicite du type de source TS, épinglage d'index de plan, WQE d'envoi multi-paquets), cette compétence prend le relais.
doca-rmax — la bibliothèque DOCA Rivermax de haut niveau canonique pour les médias précis en temps. La plupart des cas Rivermax devraient rester dans doca-rmax ; les verbes bruts sont la trappe de sortie pour le rare cas d'utilisation de médias où l'utilisateur a besoin d'un verbe que l'intégration Rivermax n'expose pas.
doca-common — la bibliothèque de fondation sur laquelle repose chaque contexte DOCA (y compris doca_verbs_context). Les primitives doca_dev / doca_pe / doca_ctx, la règle de requête de capacité contre le doca_devinfo actif, et le cycle de vie y sont possédés ; cette compétence y stratifie les motifs spécifiques aux verbes.
doca-public-knowledge-map — la table de routage pour chaque source de documentation DOCA publique et la disposition sur disque d'un paquet DOCA installé. Le guide public DOCA Verbs y est listé ; cette compétence ne duplique pas l'URL.
doca-setup — préparation de l'environnement, vérification de l'installation, et le chemin je n'ai pas encore d'installation avec le conteneur NGC DOCA public. Cette compétence suppose que ses préconditions sont satisfaites.
doca-version — règles de gestion des versions DOCA canoniques. Le ## Version compatibility de cette compétence fait des renvois croisés vers la règle de correspondance quadruple (avec doca-verbs.pc rejoignant l'ensemble de correspondance) et la règle que la requête de cap est une autorité d'exécution.
doca-structured-tools-contract — la règle de précédence des outils structurés du lot (détecter / préférer / tomber en arrière / signaler). L'appendice Commande dans TASKS.md honore ce contrat.
doca-programming-guide — motifs de programmation DOCA généraux partagés par chaque bibliothèque : le motif de construction canonique pkg-config + meson, le flux de travail universel du premier-programme modifier-un-exemple-expédié, le cycle de vie universel, la taxonomie DOCA_ERROR_* inter-bibliothèques, et l'ordre de débogage côté programme. Cette compétence y stratifie les détails spécifiques aux verbes bruts.
doca-debug — l'échelle de débogage transversale (installation / version / construction / lien / exécution / programme / pilote). Débogage spécifique aux verbes bruts (inspection d'entrée de complétude, non-mélange avec libibverbs, cycle de vie en termes de verbes) y est stratifié.
doca-hardware-safety — la méta-politique de sécurité matérielle transversale sur laquelle le ## Safety policy de cette compétence est stratifié.