DOCA Ethernet

Par où commencer : Cette skill suppose que DOCA est déjà installé et que l'utilisateur fait du travail pratique sur les files d'attente de paquets sur un hôte ou BlueField 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 qu'une file d'attente DOCA Ethernet peut exprimer sur cette version. Si l'utilisateur n'a pas encore installé DOCA, routez vers doca-setup d'abord. Si l'utilisateur demande « comment faire pour que les paquets arrivent sur ma file d'attente RX ? », la réponse se trouve dans doca-flow — DOCA Ethernet est la surface de file d'attente ; DOCA Flow est la surface d'aiguillage, et ce sont des bibliothèques indépendantes.

Questions d'exemple que cette skill répond bien

Les CLASSES de questions DOCA Ethernet pour lesquelles cette skill est construite, chacune avec un exemple travaillé. L'agent doit traiter la classe comme l'élément porteur — l'exemple travaillé est une seule instance.

« Comment mettre en place une file d'attente RX et TX sur un representor ou un port physique ? » — exemple travaillé : « configurer une doca_eth_rxq plus une doca_eth_txq sur un seul representor BlueField pour un test de première exécution ». Répondu par le cycle de vie de la paire de files dans TASKS.md ## configure + le tableau des objets RX / TX dans CAPABILITIES.md ## Capabilities and modes.
« Quel type RX correspond à ma forme de données — regular, cyclic, ou managed-recv ? » — exemple travaillé : « ingestion au débit de ligne avec des trames de taille fixe dans une pré-allocation de ring de tampons ». Répondu par la taxonomie des types RX dans CAPABILITIES.md ## Capabilities and modes + la règle de requête de capacité (doca_eth_rxq_cap_is_type_supported contre un doca_devinfo) dans TASKS.md ## configure.
« Comment envoyer un paquet depuis le code utilisateur via doca_eth_txq ? » — exemple travaillé : « allouer un paquet doca_buf, attacher la charge, soumettre une tâche d'envoi, attendre l'événement d'achèvement ». Répondu par la forme de soumission TX dans CAPABILITIES.md ## Capabilities and modes + le workflow de définition de propriétés dans TASKS.md ## modify.
« Ma file est active mais aucun paquet n'arrive — pourquoi ? » — exemple travaillé : « doca_eth_rxq a démarré proprement mais le callback de réception ne se déclenche jamais ». Répondu par la règle de dépendance d'aiguillage dans CAPABILITIES.md ## Safety policy + la checklist de préparation d'env dans TASKS.md ## configure étape 1, qui route le côté aiguillage vers doca-flow et le côté mode promiscuous vers doca-setup.
« Cette capacité Ethernet est-elle disponible sur mon périphérique + mon DOCA installé ? » — exemple travaillé : « ce périphérique annonce-t-il l'offload de checksum L3 ? ». Répondu par la règle de requête de capacité (doca_eth_txq_cap_is_l3_chksum_offload_supported contre un doca_devinfo) dans CAPABILITIES.md ## Capabilities and modes + la surcouche de compatibilité de version dans CAPABILITIES.md ## Version compatibility.
*« Que signifie cet `DOCAERRORd'un appel Ethernet et quelle couche l'a provoqué ? »** — exemple travaillé : *«DOCA_ERROR_AGAINsurdoca_task_submitpour une tâche d'envoieth_txqà haut débit »*. Répondu par la surcouche Ethernet sur la taxonomie inter-bibliothèques dans [CAPABILITIES.md ## Error taxonomy](CAPABILITIES.md#error-taxonomy) + l'échelle en couches dans [TASKS.md ## debug](TASKS.md#debug) qui escalade vers [doca-debug`](../../doca-debug/SKILL.md).

Audience

Cette skill sert les développeurs externes construisant des applications qui consomment la bibliothèque DOCA Ethernet — c'est-à-dire les utilisateurs dont le code appelle doca_eth_rxq_* / doca_eth_txq_* (directement en C/C++, ou via FFI/bindings depuis un autre langage) pour faire du I/O de paquet au débit de ligne sur des ports physiques, des representors, ou des SFs d'un périphérique BlueField ou ConnectX. Ce n'est pas pour les développeurs NVIDIA contribuant à DOCA Ethernet lui-même.

Portée du langage. DOCA Ethernet est livré en tant que bibliothèque C avec le nom de module pkg-config doca-eth. Les samples livrés sont écrits en C. Les consommateurs C et C++ sont le cas canonique ; 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 division des objets de file, le cycle de vie, la découverte de capacité, la permission, la taxonomie des types RX, et la guidance de taxonomie d'erreurs neutres au langage, et de router l'agent vers l'ABI C public comme la surface autoritaire que tout wrapper appellera éventuellement.

Quand charger cette skill

Chargez cette skill quand l'utilisateur fait du travail pratique DOCA Ethernet, dans n'importe quel langage. Concrètement :

Initialiser une doca_eth_rxq sur un doca_dev ouvert contre un port physique, un representor, ou un SF — choisir parmi les types RX regular / cyclic / managed-recv en fonction de la forme des données avant doca_ctx_start().
Initialiser une doca_eth_txq sur le même doca_dev ou un différent et poster des tâches d'envoi contre les tampons de charge doca_buf des paquets.
Lire ou définir les propriétés des files Ethernet via doca_eth_rxq_set_* / doca_eth_txq_set_* et interroger la capacité du périphérique via doca_eth_rxq_cap_* / doca_eth_txq_cap_* (taille de burst max, support des types RX, longueur scatter-gather max, présence d'offload de checksum).
Confirmer que le port est actif et que le trafic est réellement acheminé vers la file RX choisie — soit via des règles DOCA Flow (le chemin canonique) soit via le mode promiscuous côté kernel (le chemin expédient de première exécution).
Câbler une file Ethernet à un plan de données de niveau supérieur : traitement de paquets GPU via DOCA GPUNetIO, agents de transfert personnalisés en user-space, ou miroirs de télémétrie qui font une copie de chaque paquet.
Déboguer un DOCA_ERROR_* retourné d'un appel Ethernet (cycle de vie vs. permission vs. capacité vs. file d'envoi pleine vs. driver en dessous) et les événements du moteur de progression par file.
Concevoir ou étendre des bindings non-C (Rust, Go, Python, …) qui enveloppent l'ABI C de DOCA Ethernet — pour les règles de cycle de vie, division de files, types RX, capacité, et permission que le wrapper doit respecter.

Ne chargez pas cette skill pour l'orientation générale de DOCA, l'installation de DOCA lui-même, la programmation de règles de flow (utilisez doca-flow), la messagerie de contrôle hôte ↔ DPU (utilisez doca-comch), ou le déplacement de données RDMA (utilisez doca-rdma). Pour l'orientation de la documentation DOCA, utilisez doca-public-knowledge-map.

Ce que cette skill fournit

Ceci est un thin loader. Le corps garde seulement l'orientation nécessaire pour choisir le bon fichier suivant. Le matériel spécifique à Ethernet substantiel se trouve dans deux fichiers compagnons :

CAPABILITIES.md — ce qu'une file d'attente DOCA Ethernet peut exprimer sur cette version : la division des objets RX / TX, la taxonomie des types RX (regular / cyclic / managed-recv), la surface de soumission de tâche d'envoi / frame, la surface de requête de capacité (doca_eth_rxq_cap_* / doca_eth_txq_cap_*), la taxonomie d'erreurs Ethernet (mappée sur l'ensemble inter-bibliothèques DOCA_ERROR_*), la surface d'observabilité (événements du moteur de progression par file, snapshots de capacité), et la politique de sécurité qui porte les conditions préalables d'aiguillage / permission / état du port.
TASKS.md — workflows étape par étape pour les six verbes Ethernet en scope : configure, build, modify, run, test, debug. Plus un bloc Deferred task verbs qui pointe les questions hors scope vers la bonne skill suivante, et un Command appendix des commandes récurrentes que l'agent utilise.

La skill suppose un hôte ou BlueField où DOCA est déjà installé à l'emplacement standard et l'utilisateur a les privileges que son profil d'installation public attend (généralement sudo ou l'appartenance au groupe mlnx pour ouvrir un doca_dev contre un port). Elle ne couvre pas l'installation de DOCA — ce chemin passe par doca-setup.

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

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

Code source d'application DOCA Ethernet pré-écrit, dans n'importe quel langage. Le code source Ethernet vérifié est les samples C livrés à /opt/mellanox/doca/samples/doca_eth/<name>/. Le travail de l'agent est de router l'utilisateur vers ces fichiers et de prescrire une modification à diff minimal sur eux via le workflow universel modify-a-sample dans doca-programming-guide, en couches avec les surcouches spécifiques à Ethernet dans TASKS.md ## modify.
Manifestes de build autonomes (meson.build, CMakeLists.txt, Cargo.toml, …) garés à l'intérieur de la skill. L'agent construit le manifeste de build dans le répertoire du projet de l'utilisateur contre le DOCA installé de l'utilisateur, où pkg-config --modversion doca-eth est la source de vérité.
Un sous-arbre samples/, bindings/, ou reference/ d'aucune sorte. Un artifact mock ou incomplet dans l'arbre de cette skill, même un libellé « 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 en scope.
Pour la matrice de capacité Ethernet, la taxonomie des types RX, la surface d'envoi, les règles de requête de capacité, la taxonomie d'erreurs, l'observabilité, et la politique de sécurité, 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, doca-flow pour le côté aiguillage dont dépend la file RX, et doca-public-knowledge-map chaque fois que la bonne réponse est « consultez la documentation publique ou la disposition du paquet installé » plutôt que « guidance spécifique à Ethernet ».

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é. Le slug URL Ethernet est DOCA-Ethernet.
doca-setup — préparation d'env, vérification d'installation, vérifications d'état du port (devlink dev show, ip link), exigences de permission et d'appartenance à un groupe pour ouvrir un doca_dev. Cette skill suppose que ses conditions préalables sont satisfaites.
doca-version — règles canoniques de gestion de version DOCA. Le ## Version compatibility de cette skill fait des renvois croisés à la règle de correspondance quatre voies et ajoute seulement la surcouche spécifique à Ethernet (fenêtres de disponibilité des types RX, support d'offload de checksum conditionnel au périphérique).
doca-structured-tools-contract — la règle de précédence des structured-tools du bundle (detect / prefer / fall back / report). Le Command appendix dans TASKS.md honore ce contrat.
doca-programming-guide — patterns de programmation DOCA généraux partagés par chaque bibliothèque : le pattern de build canonique pkg-config + meson, le workflow universel de première application modify-a-shipped-sample, le cycle de vie universel, la taxonomie inter-bibliothèques DOCA_ERROR_*, et l'ordre de debug côté programme. Cette skill ajoute des spécifiques Ethernet par-dessus.
doca-flow — la surface d'aiguillage qui décide quels paquets atterrissent sur quelle doca_eth_rxq. DOCA Ethernet ne programme pas l'aiguillage lui-même ; une file RX vide signifie presque toujours une règle Flow manquante ou incorrecte, pas un bug Ethernet.
doca-debug — l'échelle de debug transversale (install / version / build / link / runtime / program / driver). Le debug spécifique à Ethernet (désadaptations de types RX, retries de file d'envoi pleine, symptômes d'aiguillage-file-vide) se superpose à cette échelle.