DOCA DMA

Par où commencer : Cette skill suppose que DOCA est déjà installé et que l'utilisateur effectue un travail pratique de DMA sur un BlueField / ConnectX / hôte avec DOCA. Ouvrez TASKS.md si l'utilisateur veut faire quelque chose (configurer / compiler / modifier / exécuter / tester / déboguer) ; ouvrez CAPABILITIES.md quand la question porte sur ce que DMA peut exprimer sur cette version. Si l'utilisateur n'a pas encore installé DOCA, acheminez-le d'abord vers doca-setup. Si l'utilisateur n'est pas sûr que DMA soit la bonne bibliothèque — les données doivent traverser le réseau, ou le flux consiste en petits messages entre deux processus — lisez la règle de sélection de chemin dans CAPABILITIES.md ## Capabilities and modes avant de configurer quoi que ce soit.

Exemples de questions auxquelles cette skill répond bien

Les CLASSES de questions DMA que cette skill est conçue pour répondre, chacune avec un exemple résolu. L'agent doit traiter la classe comme la partie porteuse — l'exemple résolu est une instance unique.

« Comment démarrer un contexte DOCA DMA et copier un buffer entre l'hôte et le DPU ? » — exemple résolu : « copier un buffer de 64 KiB de la mémoire de l'hôte vers la mémoire du DPU en une seule tâche, en partant de l'application de référence DMA Copy fournie ». Répondu par le workflow de cycle de vie + memcpy-task dans TASKS.md ## configure + tableau des types de tâche dans CAPABILITIES.md ## Capabilities and modes.
« Quelle taille de buffer puis-je copier en une seule tâche sur cet appareil ? » — exemple résolu : « puis-je copier 16 MiB dans un seul doca_dma_task_memcpy ». Répondu par la règle de requête de capacité (doca_dma_cap_task_memcpy_get_max_buf_size, plus _get_max_buf_list_len pour scatter-gather) dans CAPABILITIES.md ## Capabilities and modes + l'étape de découverte dans TASKS.md ## configure.
« Quelles permissions mes mmaps source et destination doivent-ils avoir ? » — exemple résolu : « ma tâche memcpy retourne DOCA_ERROR_NOT_PERMITTED au premier submit ». Répondu par la matrice de permission source / destination dans CAPABILITIES.md ## Safety policy + la liste de contrôle des permissions dans TASKS.md ## test.
« Dois-je utiliser DOCA DMA ou DOCA RDMA / Comch / un memcpy CPU simple pour cette copie ? » — exemple résolu : « j'ai une copie de 1 MiB qui doit aller d'un processus hôte à un processus DPU ; veux-je DMA ou le fast-path Comch ». Répondu par le point « quand utiliser DMA » vs « quand ne pas utiliser » dans CAPABILITIES.md ## Capabilities and modes + les pointeurs de routage dans ## Related skills.
« DOCA DMA est-il dans ma version installée, et la tâche memcpy est-elle prise en charge sur mon appareil ? » — exemple résolu : « doca_dma_task_memcpy est-il disponible sur DOCA 2.6 contre ce ConnectX-6 ». Répondu par la surcharge de compatibilité de version dans CAPABILITIES.md ## Version compatibility, qui renvoie la chaîne de détection canonique dans doca-version, plus la règle de requête de capacité dans CAPABILITIES.md ## Capabilities and modes.
*« Que signifie ce `DOCAERRORd'un appel DMA et quelle couche l'a causé ? »** — exemple résolu : *«DOCA_ERROR_AGAINdedoca_task_submitsur undoca_dma_task_memcpy»*. Répondu par la surcharge DMA de la taxonomie inter-bibliothèques dans [CAPABILITIES.md ## Error taxonomy](CAPABILITIES.md#error-taxonomy) + l'escalade en couches dans [TASKS.md ## debug](TASKS.md#debug) qui renvoie à [doca-debug`](../../doca-debug/SKILL.md).

Audience

Cette skill sert les développeurs externes construisant des applications qui consomment la bibliothèque DOCA DMA — c'est-à-dire les utilisateurs dont le code appelle doca_dma_* (directement en C/C++, ou via FFI/bindings à partir d'un autre langage) pour copier des octets entre deux régions doca_mmap en utilisant le moteur DMA BlueField au lieu du CPU hôte. Ce n'est pas pour les développeurs NVIDIA contribuant à DOCA DMA lui-même.

Portée du langage. DOCA DMA est fourni comme une bibliothèque C avec le nom de module pkg-config doca-dma. Les exemples fournis sont écrits en C. Les consommateurs C et C++ sont le cas canonique et les exemples résolus 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 le cycle de vie, la découverte des capacités, les permissions, la taxonomie des erreurs, et les conseils de sélection de chemin indépendants du langage, et d'acheminer l'agent vers l'ABI C public comme la surface faisant autorité que tout wrapper appellera finalement.

Quand charger cette skill

Chargez cette skill quand l'utilisateur effectue un travail pratique DOCA DMA, dans n'importe quel langage. Concrètement :

Initialiser un contexte doca_dma sur un doca_dev et configurer le type de tâche memcpy via doca_dma_task_memcpy_set_conf avant doca_ctx_start().
Configurer les régions doca_mmap source et destination pour un memcpy, y compris les drapeaux de permission par côté (DOCA_ACCESS_FLAG_LOCAL_READ_ONLY sur la source, DOCA_ACCESS_FLAG_LOCAL_READ_WRITE sur la destination) et, pour les copies entre pairs, l'étape doca_mmap_export_*.
Lire la surface de capacité d'appareil pour DMA via la famille de requête doca_dma_cap_task_memcpy_* (_is_supported, _get_max_buf_size, _get_max_buf_list_len) avant de dimensionner n'importe quel buffer ou supposer que scatter-gather est disponible.
Soumettre des tâches doca_dma_task_memcpy contre un moteur de progression DOCA et réagir aux événements d'achèvement par tâche.
Choisir entre DOCA DMA et une option adjacente (DOCA RDMA quand les données doivent traverser le réseau, fast-path DOCA Comch pour les flux de producteur/consommateur orientés message, memcpy CPU simple quand la copie est minuscule et ponctuelle).
Déboguer un DOCA_ERROR_* retourné par un appel DMA (cycle de vie vs. permission vs. capacité vs. would-block) et le statut d'achèvement par tâche signalé sur le moteur de progression.
Concevoir ou étendre des bindings non-C (Rust, Go, Python, …) qui enveloppent l'ABI C DMA — pour les règles de cycle de vie, permission et capacité que le wrapper doit respecter.

Ne chargez pas cette skill pour l'orientation générale DOCA, l'installation de DOCA lui-même, ou les questions sur les bibliothèques non-DMA. Pour ceux-ci, utilisez doca-public-knowledge-map.

Ce que cette skill fournit

Ceci est un thin loader. Le corps ne conserve que l'orientation nécessaire pour choisir le bon fichier suivant. La matière substantielle spécifique à DMA vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que DMA peut exprimer sur cette version : le type de tâche unique doca_dma_task_memcpy et sa forme de liste de buffers scatter-gather, la surface de requête de capacité (doca_dma_cap_task_memcpy_*), la taxonomie d'erreur DMA (mappée sur l'ensemble DOCA_ERROR_* inter-bibliothèques), la surface d'observabilité (événements d'achèvement par tâche sur le moteur de progression), la politique de permission mmap source / destination, et la règle de sélection de chemin contre les bibliothèques adjacentes (RDMA / Comch / memcpy CPU).
TASKS.md — workflows étape par étape pour les six verbes DMA 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 skill suivante.

La skill 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. Elle ne couvre pas l'installation de DOCA — ce chemin passe par doca-setup.

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

Cette skill est un guide agent, pas un bundle d'exemples ou de modèles. Pour garder la limite claire, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

Code source d'application DOCA DMA pré-écrit, dans n'importe quel langage. Le code source DMA vérifié est les exemples C fournis à /opt/mellanox/doca/samples/doca_dma/<name>/ et l'application de référence DMA Copy accessible via doca-public-knowledge-map. Le travail de l'agent est d'acheminer l'utilisateur vers ces fichiers et de prescrire une modification de différence minimale via le workflow universel modify-a-sample dans doca-programming-guide, superposé avec les surcharges spécifiques à DMA dans TASKS.md ## modify.
Manifestes de compilation autonomes (meson.build, CMakeLists.txt, Cargo.toml, …) garés dans la skill. L'agent construit le manifeste de compilation dans le répertoire du projet de l'utilisateur contre le DOCA installé de l'utilisateur, où pkg-config --modversion doca-dma est la source de vérité.
Un sous-arbre samples/, bindings/ ou reference/ de quelque sorte. 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 la portée.
Pour la surface de capacité DMA, le type de tâche memcpy, la règle de requête de capacité, la matrice de permission source / destination, la taxonomie d'erreur, l'observabilité, et la règle de sélection de chemin contre RDMA / Comch / memcpy CPU, voir CAPABILITIES.md.
Pour les workflows étape par étape — configure, build, modify, run, test, debug — voir TASKS.md.

Les deux fichiers compagnons font des renvois croisés l'un vers l'autre, doca-version pour les règles de gestion de version canoniques, et doca-public-knowledge-map chaque fois que la bonne réponse est « cherchez-le dans la documentation publique ou la disposition du paquet installé » plutôt que « guide spécifique à DMA ».

Skills connexes

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é. L'URL DMA est https://docs.nvidia.com/doca/sdk/DOCA-DMA/index.html ; l'application de référence canonique est DMA Copy.
doca-setup — préparation d'env, vérification d'installation, et le chemin je n'ai pas d'installation encore avec le conteneur DOCA NGC public. Cette skill suppose que ses préconditions sont satisfaites.
doca-version — règles de gestion de version DOCA canoniques. La ## Version compatibility de cette skill renvoie la règle de correspondance quadruple + la chaîne de détection et ajoute au plus une règle de surcharge spécifique à DMA.
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-programming-guide — motifs de programmation DOCA généraux partagés par chaque bibliothèque : le motif de compilation pkg-config + meson canonique, le workflow de première application modify-a-shipped-sample universel, le cycle de vie universel, la taxonomie DOCA_ERROR_* inter-bibliothèques, et l'ordre de débogage côté programme. Cette skill superpose les spécificités DMA par-dessus.
doca-rdma — la bonne bibliothèque quand la copie doit traverser le réseau. La règle de sélection de chemin de cette skill renvoie à RDMA quand DMA n'est pas la réponse.
doca-comch — la bonne bibliothèque quand le flux est une messagerie producteur / consommateur entre une paire de processus hôte et DPU, plutôt qu'une copie mmap-à-mmap brute.
doca-debug — l'escalade de débogage transversale (install / version / build / link / runtime / program / driver). Le débogage spécifique à DMA (violations de cycle de vie, incompatibilités de permission, rejets de buffers surdimensionnés) se superpose à cette escalade.