DOCA UROM

Par où commencer : Cette compétence suppose que DOCA est déjà installé sur l'hôte et le BlueField, que le Service DOCA UROM est déployé et exécuté du côté BlueField, et que l'utilisateur effectue un travail UROM pratique depuis le côté hôte — c'est-à-dire qu'il utilise doca-urom depuis une pile HPC / UCX / MPI sur l'hôte pour enqueuer les opérations de mémoire distante (puts, gets, atomiques, messages actifs, primitives collectives) que le DPU BlueField exécutera au nom de l'hôte. Ouvrez TASKS.md si l'utilisateur veut faire quelque chose (configurer / construire / modifier / exécuter / tester / déboguer) ; ouvrez CAPABILITIES.md quand la question porte sur ce que l'API UROM du côté hôte peut exprimer sur cette version + ce BlueField + cette version de Service UROM. Si l'utilisateur n'a pas encore installé DOCA, naviguez vers doca-setup d'abord ; si l'utilisateur pose des questions sur le Service UROM du côté DPU lui-même (déploiement, conteneur, cycle de vie d'exploitation du côté DPU), c'est un artefact DIFFÉRENT — naviguez via doca-public-knowledge-map ## DOCA services vers le guide public DOCA UROM Service. Cette compétence est la bibliothèque du côté hôte ; le Service UROM est l'exécuteur du côté DPU, et ils constituent un contrat appairé.

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

Les CLASSES de questions UROM auxquelles cette compétence est conçue pour répondre, chacune avec un exemple travaillé. L'agent doit traiter la classe comme la pièce maîtresse — l'exemple travaillé n'est qu'une instance unique.

« Comment puis-je décharger mes opérations de mémoire distante MPI / UCX du CPU hôte vers le DPU BlueField ? » — exemple travaillé : « mon all-reduce MPI consomme des cycles CPU hôte que je préférerais utiliser pour le calcul — comment pousser ce travail sur le BlueField via UROM ? ». Répondu par le modèle de contrat appairé bibliothèque-hôte + service-DPU dans CAPABILITIES.md ## Capabilities and modes + le workflow de démarrage du côté hôte dans TASKS.md ## configure.
*« Est-ce que le Service DOCA UROM s'exécute même sur mon BlueField, et pourquoi cela a-t-il de l'importance avant que j'écrive un code `docaurom? »** — exemple travaillé : *« mon premier appeldocauromretourneDOCA_ERROR_NOT_PERMITTED` sur un hôte où DOCA est par ailleurs sain ». Répondu par la matrice de précondition environnementale dans CAPABILITIES.md ## Safety policy + la vérification du service déployé et exécuté dans TASKS.md ## configure étape 1, qui navigue les questions d'env du côté service vers doca-public-knowledge-map ## DOCA services.
« Ce type d'opération UROM / atomique / collectif est-il supporté sur mon appareil + cette installation DOCA + cette version de Service UROM ? » — exemple travaillé : « mon BlueField supporte-t-il l'atomique distante Fetch-and-Add pour une fenêtre MPI ? ». Répondu par la règle de découverte de plugin (doca_urom_service_get_plugins_list sur un Service démarré — les opérations UROM sont des tâches Command définies par plugin, donc la liste des plugins supportés est la surface de capabilité) dans CAPABILITIES.md ## Capabilities and modes + l'étape de découverte dans TASKS.md ## configure.
« Comment doca-urom se rapporte-t-il à doca-rdma — le remplace-t-il, le superpose-t-il, ou autre chose ? » — exemple travaillé : « j'ai déjà raw doca-rdma qui fonctionne ; dois-je réécrire pour utiliser UROM, ou est-ce le mauvais outil ? ». Répondu par la règle de sélection de chemin dans CAPABILITIES.md ## Capabilities and modes (UROM utilise le substrat de transport RDMA en dessous mais ajoute le contrat de décharge DPU par-dessus, et n'est le bon outil que quand le CPU hôte est le goulot d'étranglement du fait de la surcharge de communication — les petits cas point-à-point simples restent sur doca-rdma).
« Cette API UROM est-elle sur ma version DOCA installée ? » — exemple travaillé : « le plugin d'opérations collectives est-il découvrable via doca_urom_service_get_plugins_list sur DOCA 3.x ». Répondu par la surcouche de compatibilité de version dans CAPABILITIES.md ## Version compatibility, qui établit des références croisées avec la chaîne de détection canonique dans doca-version et ajoute la surcouche UROM spécifique les versions de la bibliothèque hôte et du service DPU doivent correspondre.
« Que signifie ce DOCA_ERROR_* d'un appel doca_urom_* et quelle couche l'a causé ? » — exemple travaillé : « DOCA_ERROR_NOT_PERMITTED au premier enqueue `docauromaprès quedoca_ctx_start()a réussi »*. Répondu par la surcouche UROM sur la taxonomie interbiblioothèques croisées dans [CAPABILITIES.md ## Error taxonomy](CAPABILITIES.md#error-taxonomy) + l'échelle échelonnée dans [TASKS.md ## debug](TASKS.md#debug) qui escalade vers [doca-debug`](../../doca-debug/SKILL.md).

Audience

Cette compétence sert les développeurs externes construisant des applications HPC / UCX / MPI qui consomment la bibliothèque DOCA UROM depuis le côté hôte — c'est-à-dire les utilisateurs dont le code appelle doca_urom_* (directement en C / C++, ou via FFI / bindings d'un autre langage, ou via une pile basée UCX telle que OpenMPI / MPICH qui a été configurée pour utiliser DOCA UROM comme transport UCX) pour pousser les opérations de mémoire distante sur le DPU BlueField au lieu de les exécuter sur le CPU hôte. Ce n'est pas pour les développeurs NVIDIA contribuant à DOCA UROM lui-même, ni le lieu pour apprendre comment déployer / exploiter le Service DOCA UROM du côté DPU — cela passe par le guide public DOCA UROM Service via doca-public-knowledge-map ## DOCA services.

Portée linguistique. DOCA UROM est livré en tant que bibliothèque C du côté hôte avec le nom de module pkg-config doca-urom. Les exemples livrés sous /opt/mellanox/doca/samples/doca_urom/ sont écrits en C (choix d'NVIDIA). Les consommateurs C et C++ — notamment les piles basées UCX qui enveloppent la bibliothèque — constituent le cas canonique et les exemples travaillés dans TASKS.md supposent ce chemin. Les consommateurs dans d'autres langages (Rust, Go, Python, …) consomment le même *.so via FFI ou des bindings spécifiques au langage ; la contribution de cette compétence dans ce cas est de garder le cycle de vie, la découverte de capabilité, la vérification du service-déployé-et-exécuté, la taxonomie des erreurs, et les conseils de substrat RDMA indépendants du langage, et d'orienter l'agent vers l'ABI C public comme la surface faisant autorité que tout wrapper finira par appeler.

Quand charger cette compétence

Chargez cette compétence quand l'utilisateur fait un travail DOCA UROM pratique depuis le côté hôte, dans n'importe quel langage. Concrètement :

Initialiser un contexte Service UROM (doca_urom_service_*) sur un doca_dev qui correspond au BlueField vers lequel l'utilisateur veut décharger, puis créer des contextes Worker (doca_urom_worker_*) attachés à ce Service, et confirmer que le Service UROM du côté DPU correspondant est accessible avant le premier enqueue.
Enqueuer les opérations de mémoire distante (puts, gets, atomiques, messages actifs, primitives collectives) via l'API doca_urom_* du côté hôte et progresser le moteur de progression DOCA pour les complétions.
Lire ou définir les propriétés de la bibliothèque via l'API UROM du côté hôte et appeler doca_urom_service_get_plugins_list sur un Service démarré pour découvrir quels plugins (et donc quels types d'opération / atomiques / collectives, puisque ceux-ci sont définis par plugin) ce appareil + cette installation DOCA + cette version de Service UROM du côté DPU supporte vraiment.
Câbler la bibliothèque doca-urom du côté hôte en dessous d'une pile HPC basée UCX (OpenMPI, MPICH, consommateur UCX personnalisé) pour que le trafic de mémoire distante de la pile se décharge sur le DPU BlueField au lieu de s'exécuter sur le CPU hôte.
Déboguer un DOCA_ERROR_* retourné d'un appel doca_urom_* — en particulier pour désambiguïser Service UROM du côté DPU non accessible de type d'opération non supporté sur cet appareil de accès standard doca_dev refusé de défaillance du transport RDMA sous-jacent.
Concevoir ou étendre des bindings non-C (Rust, Go, Python, …) qui enveloppent l'ABI UROM C — pour les règles de cycle de vie, service-déployé-et-exécuté, découverte de capabilité, et taxonomie des erreurs que le wrapper doit honorer.

Ne pas charger cette compétence pour une orientation DOCA générale, l'installation de DOCA lui-même, le déploiement / l'exploitation du Service DOCA UROM du côté DPU (un artefact séparé, avec son propre guide public accessible via doca-public-knowledge-map ## DOCA services), ou les questions de bibliothèque autres qu'UROM. Pour cela, utilisez doca-public-knowledge-map.

Ce que cette compétence fournit

Ceci est un chargeur fin. Le corps garde uniquement l'orientation nécessaire pour choisir le bon fichier suivant. Le matériau substantiel spécifique à UROM réside dans deux fichiers compagnons :

CAPABILITIES.md — ce que l'API UROM du côté hôte peut exprimer sur cette version + ce BlueField + cette version de Service UROM : le modèle de contrat appairé (la bibliothèque hôte enquete ; le service DPU exécute) ; les deux types de contexte du côté hôte — les contextes doca_urom_service (un par BlueField, lié à son doca_dev) et doca_urom_worker qui y sont attachés ; la surface d'opération du côté enqueue (puts, gets, atomiques, messages actifs, primitives collectives) livrées en tant que tâches Command définies par plugin et nommées génériquement car les formes exactes des symboles sont liées à l'installation et au plugin ; la surface de découverte de plugin (doca_urom_service_get_plugins_list) ; la taxonomie des erreurs UROM mappée sur l'ensemble DOCA_ERROR_* interbiblioothèques ; la surface d'observabilité (événements de complétude sur le moteur de progression DOCA, snapshots de capabilité, compteurs RDMA du côté infrastructure) ; et la politique de sécurité qui valide les préconditions d'env (Service DOCA UROM déployé et exécuté du côté DPU ; accord de version entre la bibliothèque hôte et le service DPU ; un BlueField compatible RDMA + installation DOCA).
TASKS.md — les workflows étape par étape pour les six verbes UROM in-scope : configure, build, modify, run, test, debug. Plus un bloc Deferred task verbs qui pointe les questions hors-scope vers la prochaine compétence appropriée.

La compétence suppose une paire hôte + BlueField où DOCA est déjà installé à l'emplacement standard, le Service DOCA UROM est déjà déployé et exécuté sur le BlueField, le transport RDMA sous-jacent entre hôte et BlueField est sain, et l'utilisateur a déjà au moins une esquisse de la pile HPC / UCX / MPI qu'il veut décharger. Elle ne couvre pas l'installation de DOCA, le déploiement du conteneur Service UROM sur le BlueField, ou la mise en place du transport RDMA / RoCE / IB entre hôte et BlueField — ces chemins passent par doca-setup, le guide public DOCA UROM Service, et doca-rdma respectivement.

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

Cette compétence est une guidance d'agent, pas un bundle d'exemples ou de templates. Pour garder la limite claire, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

Du code source d'application DOCA UROM pré-écrit, dans n'importe quel langage. Le code source UROM vérifié est les exemples C livrés à /opt/mellanox/doca/samples/doca_urom/. Le travail de l'agent est d'orienter l'utilisateur vers ces fichiers et de prescrire une modification diff-minimum sur eux via le workflow universel modify-a-sample dans doca-programming-guide, superposé avec les remplacements spécifiques à UROM dans TASKS.md ## modify.
Une implémentation d'algorithme ou de primitive collective MPI / UCX. Cette bibliothèque décharge les opérations de mémoire distante ; l'algorithme qui sélectionne quels puts / gets / atomiques / collectives émettre pour une primitive MPI donnée est votre pile HPC (OpenMPI, MPICH, consommateur UCX personnalisé) ou votre expertise de domaine. L'agent doit refuser d'inventer des algorithmes collectifs et doit orienter toute question « quel algorithme mon all-reduce doit-il utiliser » vers la documentation upstream MPI / UCX — c'est une question de recherche / conception de pile, pas une question d'API UROM.
Des manifestes de construction autonomes (meson.build, CMakeLists.txt, Cargo.toml, …) garés à l'intérieur de la compétence. L'agent construit le manifest de construction dans le répertoire du projet de l'utilisateur contre le DOCA installé de l'utilisateur, où pkg-config --modversion doca-urom est la source de vérité.
Un sous-arbre samples/, bindings/, ou reference/ de toute sorte. Un artefact simulé ou incomplet dans l'arbre de cette compétence, même un étiqueté « reference », est trompeur : les utilisateurs le liront comme constructible.
La surface du Service DOCA UROM. Ce service est un artefact séparé avec son propre guide public ; le routage pour son déploiement / exploitation réside dans doca-public-knowledge-map ## DOCA services. Confondre la bibliothèque (cette compétence, enqueue du côté hôte) avec le service (exécuteur du côté DPU) est l'erreur de conception de première app UROM la plus commune.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est in-scope (travail de la bibliothèque du côté hôte ; pas le déploiement du service du côté DPU, ni la conception d'algorithme MPI / UCX).
Pour la matrice de capabilité UROM, le modèle de contrat appairé (bibliothèque hôte + service DPU), le modèle de contexte Service + Worker, la surface d'opération du côté enqueue, la règle de découverte de plugin, la politique de précondition d'env, la taxonomie des erreurs, la surface d'observabilité, et la politique de sécurité, consultez CAPABILITIES.md.
Pour les workflows étape par étape — configure, build, modify, run, test, debug — consultez TASKS.md.

Les deux fichiers compagnons se font des références croisées mutuellement, doca-version pour les règles canoniques de traitement de version DOCA (avec la surcouche UROM que la version de la bibliothèque hôte et la version du service DPU doivent correspondre), doca-rdma pour le substrat de transport RDMA sous-jacent sur lequel la décharge UROM s'appuie, et doca-public-knowledge-map chaque fois que la bonne réponse est « consulte-la dans le guide public de la bibliothèque DOCA UROM, le guide public du Service DOCA UROM, ou dans la mise en page d'installation sur disque » plutôt que « guidance spécifique au côté hôte UROM ».

Compétences connexes

doca-public-knowledge-map — la table de routage pour chaque source de documentation DOCA publique et la mise en page sur disque d'un package DOCA installé. Le guide public de la bibliothèque DOCA UROM se trouve à https://docs.nvidia.com/doca/sdk/DOCA-UROM/index.html ; le Service DOCA UROM est un artefact différent documenté séparément sous la section DOCA services de cette carte.
doca-rdma — le substrat de transport RDMA sous-jacent que le BlueField utilise pour déplacer les octets entre nœuds une fois qu'UROM a déchargé une opération de mémoire distante. UROM ne remplace PAS RDMA ; il ajoute le contrat de décharge DPU par-dessus pour que le CPU hôte n'ait pas à poster les verbes lui-même. Quand l'intention de l'utilisateur est du RDMA simple point-à-point et que le CPU hôte n'est pas le goulot d'étranglement, le bon outil est doca-rdma directement — UROM ajoute le contrat du côté service qui ne vaut pas sa surcharge pour ce cas.
doca-setup — la préparation d'env, la vérification d'installation, la configuration BlueField, et le chemin je n'ai pas encore d'installation avec le conteneur DOCA NGC public. Cette compétence suppose que ses préconditions sont satisfaites ET que le Service UROM du côté DPU est déployé et exécuté sur le BlueField.
doca-version — les règles canoniques de gestion de version DOCA. La ## Version compatibility de cette compétence établit des références croisées avec la règle de correspondance à quatre voies et ajoute la surcouche spécifique à UROM la bibliothèque hôte et le service DPU doivent avoir la même version.
doca-structured-tools-contract — la règle de préséance des structured-tools du bundle (détecter / préférer / revenir / rapporter). L'appendice Command dans TASKS.md honore ce contrat.
doca-programming-guide — les motifs généraux de programmation DOCA partagés par chaque bibliothèque : le motif de construction canonique pkg-config + meson, le workflow universel modify-a-shipped-sample de première app, le cycle de vie universel du contexte Core, la taxonomie interbiblioothèques DOCA_ERROR_*, et l'ordre de debug du côté programme. Cette compétence superpose les spécificités UROM par-dessus.
doca-debug — l'échelle de debug transversale (install / version / build / link / runtime / program / driver). Le debug spécifique à UROM (Service UROM du côté DPU non exécuté / non accessible, décalage de version entre la bibliothèque hôte et le service DPU, défaillance du transport RDMA en dessous de la décharge UROM, type d'opération ne figurant pas dans ce appareil + firmware + version de service) se superpose par-dessus cette échelle.

Le Service DOCA UROM qui s'exécute du côté DPU est délibérément hors scope pour cette compétence — c'est un artefact séparé avec son propre guide public, accessible via doca-public-knowledge-map ## DOCA services. Confondre la bibliothèque et le service est l'erreur de conception de première app UROM la plus commune : l'agent doit faire surface du fractionnement bibliothèque / service explicitement chaque fois que la question traverse les deux.