Codage par effacement DOCA

Par où commencer : Cette skill suppose que DOCA est déjà installé et que l'utilisateur effectue un travail de codage par effacement pratique 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 peut exprimer le codage par effacement DOCA sur cette version. Si l'utilisateur n'a pas encore installé DOCA, routez d'abord vers doca-setup. Si l'utilisateur demande « devrais-je vraiment utiliser le codage par effacement ici, ou simplement répliquer les données ? », la règle de sélection de chemin dans CAPABILITIES.md ## Capabilities and modes est le premier arrêt — le codage par effacement est une primitive de résilience de stockage (RAID-6 / parité de système de fichiers distribué / buckets codés par effacement de stockage d'objets), pas une primitive réseau et pas un substitut de réplication.

Exemples de questions auxquelles cette skill répond bien

Les CLASSES de questions sur le codage par effacement DOCA auxquelles cette skill est conçue pour répondre, chacune avec un exemple travaillé. L'agent doit traiter la classe comme la partie portante — l'exemple travaillé est une seule instance.

« Devrais-je décharger ce codage par effacement vers DOCA, ou le faire sur le CPU — ou simplement répliquer les données à la place ? » — exemple travaillé : « J'écris un magasin d'objets distribué qui veut une résilience de type RAID-6 sur 12 disques ; est-ce que doca-erasure-coding est la bonne primitive, ou devrais-je juste conserver trois copies ? ». Répondu par le tableau de sélection de chemin dans CAPABILITIES.md ## Capabilities and modes + les puces « quand NE PAS utiliser doca-erasure-coding » dans CAPABILITIES.md ## Safety policy.
« Mon appareil supporte-t-il le type de tâche EC, la taille de bloc, la disposition N+K et le type de matrice que je veux ? » — exemple travaillé : « est-ce que doca_ec_task_create sur ce BlueField, quelle est la taille de bloc maximale, quel est le plafond sur N+K, et l'appareil annonce-t-il une matrice Reed-Solomon de Vandermonde ? ». Répondu par la règle de requête de capacité par tâche + matrice + taille (doca_ec_cap_task_create_is_supported, _task_recover_is_supported, _task_update_is_supported, _task_galois_mul_is_supported — la 4e tâche publique sur l'accélérateur EC, doca_ec_cap_get_max_block_size, doca_ec_cap_get_max_buf_list_len, et constructeur doca_ec_matrix_create() par variante — l'en-tête public N'EXPÉDIE PAS une famille doca_ec_cap_get_matrix_*) dans CAPABILITIES.md ## Capabilities and modes + l'étape de découverte dans TASKS.md ## configure.
« Un bloc source a changé — dois-je recalculer toute la parité à partir de zéro ? » — exemple travaillé : « J'ai 8 blocs de données + 4 blocs de parité sur disque ; un bloc de données vient d'être réécrit. Comment exprimer la mise à jour de parité sans relancer l'encodage complet ? ». Répondu par la ligne doca_ec_task_update dans le tableau des types de tâches dans CAPABILITIES.md ## Capabilities and modes + la règle update-vs-re-encode dans CAPABILITIES.md ## Safety policy + le slot modify-from-sample pour basculer entre les tâches create et update dans TASKS.md ## modify.
« K de mes N+K blocs ont disparu — comment les reconstruire ? » — exemple travaillé : « un disque a échoué ; les 8 blocs de données sont intacts mais 2 des 4 blocs de parité ont disparu ; est-ce que DOCA peut les récupérer ? ». Répondu par la ligne doca_ec_task_recover dans le tableau des types de tâches dans CAPABILITIES.md ## Capabilities and modes + le smoke recover (encode → drop un bloc → recover → bit-compare) dans TASKS.md ## test.
« Quelles permissions l'mmap source / destination a-t-il besoin ? » — exemple travaillé : « mon doca_ec_task_create retourne DOCA_ERROR_NOT_PERMITTED ». Répondu par la matrice de permissions dans CAPABILITIES.md ## Safety policy + la checklist mmap-set-permissions dans TASKS.md ## test.
« Cette API DOCA Erasure Coding est-elle disponible sur ma version DOCA installée ? » — exemple travaillé : « est-ce que doca_ec_task_update est dans le DOCA que j'ai installé, ou dois-je recalculer la parité à partir de zéro ? ». Répondu par le superposition de compatibilité de version dans CAPABILITIES.md ## Version compatibility, qui établit des liens croisés avec la chaîne de détection canonique dans doca-version et ajoute les puces EC-spécifiques « découvrir le support par tâche + type de matrice via requête de capacité ».
*« Que signifie ce `DOCAERRORd'un appel EC et quelle couche l'a causé ? »** — exemple travaillé : *«DOCA_ERROR_INVALID_VALUEsurdoca_ec_task_create_allocate_initavec block_size = 4 MiB »*. Répondu par la superposition EC 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 Erasure Coding — c.-à-d., les utilisateurs dont le code appelle doca_ec_* (directement en C/C++, ou via FFI/bindings d'une autre langue) pour décharger le codage par effacement Reed-Solomon sur un DPU BlueField ou un accélérateur ConnectX. Ce n'est pas pour les développeurs NVIDIA contribuant à DOCA Erasure Coding lui-même.

L'ajustement canonique est le stockage distribué : dispositions de blocs de style RAID-6, parité de système de fichiers distribué, buckets codés par effacement de stockage d'objets, et toute charge de travail de durabilité des données où le modèle de N blocs de données + K blocs de redondance permet au système de tolérer K pertes de bloc simultanées sans perte de données. La skill oriente l'agent vers ce domaine : le codage par effacement est opérationnellement distinct de la pure réplication (qui conserve M copies entières) et du RAID-6 la disposition disque (qui est une instance spécifique du cas N=k, K=2) ; les confondre produit de mauvaises recommandations.

Portée du langage. Le codage par effacement DOCA est livré en tant que bibliothèque C avec le nom de module pkg-config doca-erasure-coding. Les exemples expédiés sont écrits en C. Les consommateurs C et C++ sont le cas canonique et les exemples travaillés dans TASKS.md supposent ce chemin. Les consommateurs d'autres langues (Rust, Go, Python, …) consomment le même *.so via FFI ou bindings spécifiques au langage ; la contribution de la skill dans ce cas est de maintenir le cycle de vie, la découverte de capacité, la permission, la taxonomie d'erreur, et la guidance create-vs-recover-vs-update agnostique au langage, et de router l'agent vers l'ABI C public comme la surface faisant autorité que tout wrapper appelera finalement.

Quand charger cette skill

Chargez cette skill quand l'utilisateur effectue un travail pratique de codage par effacement DOCA, dans n'importe quelle langue. Concrètement :

Initialiser un contexte doca_ec sur un doca_dev et configurer au moins un type de tâche (doca_ec_task_create, doca_ec_task_recover, et/ou doca_ec_task_update) avant doca_ctx_start().
Choisir entre la tâche create (encoder N blocs de données en K blocs de redondance), la tâche recover (reconstruire jusqu'à K blocs manquants en fonction du sous-ensemble survivant), et la tâche update (mettre à jour progressivement les blocs de redondance quand un bloc source change — beaucoup moins cher que réencoder à partir de zéro).
Choisir les paramètres de codage : type de matrice / schéma de codage (généralement Vandermonde ou Cauchy pour Reed-Solomon), N (nombre de blocs de données), K (nombre de blocs de redondance), et taille de bloc (tous les blocs de même taille).
Définir correctement les permissions sur doca_mmap pour les buffers source — blocs de données pour create, données + parité pour recover — (DOCA_ACCESS_FLAG_LOCAL_READ_ONLY au minimum) et les buffers destination — blocs de redondance pour create, blocs récupérés pour recover, parité mise à jour pour update — (DOCA_ACCESS_FLAG_LOCAL_READ_WRITE).
Dimensionner les blocs par rapport à doca_ec_cap_get_max_block_size(devinfo) et N+K par rapport à doca_ec_cap_get_max_buf_list_len(devinfo, &max_buf_list_len).
Vérifier quels types de tâches et schémas de matrice cet accélérateur d'appareil annonce via doca_ec_cap_task_*_is_supported (y compris la 4e tâche _task_galois_mul_is_supported) et succès du constructeur doca_ec_matrix_create() par variante — l'en-tête public N'EXPÉDIE PAS des familles doca_ec_cap_get_matrix_* par rapport au doca_devinfo actif.
Valider par rapport à un smoke recover de vecteur connu (encoder une petite disposition N + K, simuler une perte de bloc, récupérer, bit-compare par rapport au bloc original) avant de pousser les données de stockage en masse via l'accélérateur.
Reconnaître quand update est la bonne tâche (un bloc source unique changé dans une disposition N + K existante — doca_ec_task_update est beaucoup moins cher que recalculer tous les K blocs de parité via un doca_ec_task_create frais).
Déboguer un DOCA_ERROR_* retourné d'un appel EC (cycle de vie vs. taille de bloc vs. N+K vs. type de matrice vs. permission vs. pression de file d'attente) et l'événement d'achèvement de tâche sur le moteur de progression.
Concevoir ou étendre des bindings non-C (Rust, Go, Python, …) qui enveloppent l'ABI C EC — pour le cycle de vie, la permission, la capacité, et les règles create-vs-recover-vs-update que le wrapper doit honorer.

Ne chargez pas cette skill pour l'orientation générale DOCA, l'installation de DOCA lui-même, les codes d'effacement non-Reed-Solomon (codes de fontaine, LDPC — ceux appartiennent à une bibliothèque CPU, pas à l'accélérateur DOCA), les conceptions de pure réplication / mirroring (le codage par effacement est la mauvaise primitive quand une copie supplémentaire est la bonne réponse), ou d'autres bibliothèques DOCA. Pour ceux-ci, utilisez doca-public-knowledge-map.

Ce que cette skill fournit

C'est un mince chargeur. Le corps garde seulement l'orientation nécessaire pour choisir le bon fichier suivant. Le matériel substantiel spécifique à EC vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que le codage par effacement DOCA peut exprimer sur cette version : les trois types de tâches (create / recover / update, chacun indépendamment limité par capacité), la surface de configuration type de matrice + N + K + taille de bloc, la famille de requête de capacité (doca_ec_cap_* pour le support de tâche, taille de bloc max, N+K max, types de matrice supportés), la taxonomie d'erreur EC (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 sécurité qui gère les décisions de permission mmap source / destination, et la règle de sélection de chemin (quand utiliser doca-erasure-coding vs. une bibliothèque EC CPU vs. pure réplication vs. RAID-6 sur disque).
TASKS.md — workflows étape par étape pour les six verbes EC dans le périmètre : configure, build, modify, run, test, debug. Plus un bloc Deferred task verbs qui pointe les questions hors du périmètre 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 publique s'attend. Elle ne couvre pas l'installation de DOCA — ce chemin passe par doca-setup.

Ce que cette skill n'expédie délibérément pas

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

Code source d'application DOCA EC pré-écrit, dans n'importe quelle langue. Le code source EC vérifié est les exemples C expédiés à /opt/mellanox/doca/samples/doca_erasure_coding/. 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, superposé avec les overrides EC-spécifiques dans TASKS.md ## modify.
Tables de parité pré-calculées pour des dispositions N + K arbitraires. La skill dit à l'agent d'utiliser un smoke de vecteur connu (encoder une petite disposition N + K à partir d'une entrée fixe, simuler la perte d'un bloc, récupérer, bit-compare par rapport à l'original) en tant que smoke avant la masse ; elle n'expédie pas sa propre banque de vecteur.
Manifestes de compilation autonomes (meson.build, CMakeLists.txt, Cargo.toml, …) garés à l'intérieur de la skill. L'agent construit le manifeste de compilation dans le répertoire du projet de l'utilisateur par rapport au DOCA installé de l'utilisateur, où pkg-config --modversion doca-erasure-coding est la source de vérité.
Un sous-arbre samples/, bindings/, ou reference/ de n'importe quel type. Un artefact factice ou incomplet dans l'arbre 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 le périmètre (résilience du domaine de stockage — N blocs de données + K blocs de redondance — et non une question de réseau ou de réplication mal classifiée en tant que codage par effacement).
Pour la matrice de capacité EC, les trois types de tâches (create / recover / update), la surface de configuration type de matrice + N + K + taille de bloc, les règles de requête de capacité, la matrice de permissions, la taxonomie d'erreur, l'observabilité, et la politique de sécurité / sélection de chemin, voir CAPABILITIES.md.
Pour les workflows étape par étape — configure, build, modify, run, test, debug — voir TASKS.md.

Les deux fichiers compagnons établissent des liens croisés avec chacun, doca-version pour les règles canoniques de gestion de version, et doca-public-knowledge-map chaque fois que la bonne réponse est « consulter la documentation publique ou la disposition du paquet installé » plutôt que « guidance EC-spécifique ».

Skills connexes

doca-public-knowledge-map — la table de routage pour chaque source de documentation publique DOCA et la disposition sur disque d'un paquet DOCA installé. La page codage par effacement DOCA vit à https://docs.nvidia.com/doca/sdk/DOCA-Erasure-Coding/index.html ; la disposition de l'arbre d'installation (répertoire d'exemples, emplacement d'en-tête) appartient à la carte de connaissances publique, pas à cette skill.
doca-setup — préparation d'env, vérification d'installation, et le chemin je n'ai pas encore d'installation avec le conteneur DOCA NGC public. Cette skill suppose que ses préconditions sont satisfaites.
doca-version — règles canoniques de gestion de version DOCA. La ## Version compatibility de cette skill établit des liens croisés avec la règle de correspondance quatre voies et ajoute seulement la superposition EC-spécifique « découvrir le support par tâche + types de matrice supportés + taille de bloc max + N+K max via requête de capacité ».
doca-structured-tools-contract — la règle de précédence des outils structurés du bundle (détecter / préférer / retour / 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 canonical de compilation pkg-config + meson, le workflow universal modify-a-shipped-sample first-app, 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 EC spécifiques par-dessus.
doca-debug — l'échelle de débogage inter-coupes (install / version / build / link / runtime / program / driver). Débogage EC-spécifique (task-not-supported, matrix-type-unsupported, block-size-over-max, N+K-over-max, recover-with-too-many-missing) se superpose par-dessus cette échelle.