DOCA SHA

Par où commencer : Cette compétence suppose que DOCA est déjà installé et que l'utilisateur effectue un travail pratique d'accélération SHA sur un BlueField / ConnectX / hôte avec DOCA. Ouvrez TASKS.md si l'utilisateur souhaite faire quelque chose (configurer / compiler / modifier / exécuter / tester / déboguer) ; ouvrez CAPABILITIES.md quand la question porte sur ce que DOCA SHA peut exprimer dans cette version. Si l'utilisateur n'a pas encore installé DOCA, dirigez-le d'abord vers doca-setup. Si l'utilisateur demande « dois-je même utiliser l'accélérateur pour ce hash ? », la règle de sélection du chemin dans CAPABILITIES.md ## Capabilities and modes est la première étape.

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

Les CLASSES de questions DOCA SHA que cette compétence est construite pour répondre, chacune avec un exemple travaillé. L'agent doit traiter la classe comme l'élément porteur — l'exemple travaillé est une seule instance.

« Dois-je déléguer ce hash à DOCA SHA, ou simplement le calculer sur le CPU ? » — exemple travaillé : « je vérifie l'intégrité des fichiers sur une image de 4 GiB ; vaut-il la peine de configurer doca-sha par rapport à OpenSSL sur le CPU ? ». Réponse fournie par le tableau de sélection du chemin dans CAPABILITIES.md ## Capabilities and modes + les puces « quand NE PAS utiliser doca-sha » dans CAPABILITIES.md ## Safety policy.
« Mon appareil supporte-t-il l'algorithme SHA que je veux ? » — exemple travaillé : « SHA-256 est-il dans l'accélérateur de ce BlueField, et quelle est la taille minimale du buffer de destination pour lui ? ». Réponse fournie par la règle de requête de capacité algorithme + dimensionnement du buffer (doca_sha_cap_task_hash_get_supported(devinfo, algorithm) pour le chemin one-shot ; _task_partial_hash_get_supported(devinfo, algorithm) pour le chemin partial-hash ; doca_sha_cap_get_min_dst_buf_size, doca_sha_cap_get_max_src_buf_size) dans CAPABILITIES.md ## Capabilities and modes + l'étape de découverte dans TASKS.md ## configure.
« Comment choisir entre la tâche one-shot et la tâche partial / incremental hash ? » — exemple travaillé : « mon entrée fait 1 GiB et la capacité de l'appareil indique que le buffer source max est 64 MiB ». Réponse fournie par le tableau one-shot-vs-partial dans CAPABILITIES.md ## Capabilities and modes + le flux de travail de configuration de tâche dans TASKS.md ## modify.
« Quelles permissions l'mmap source / destination doit-il avoir ? » — exemple travaillé : « mon doca_sha_task_hash renvoie DOCA_ERROR_NOT_PERMITTED ». Réponse fournie par la matrice de permissions dans CAPABILITIES.md ## Safety policy + la liste de vérification mmap-set-permissions dans TASKS.md ## test.
« Cette API DOCA SHA est-elle disponible sur ma version DOCA installée ? » — exemple travaillé : « doca_sha_task_partial_hash est-il dans le DOCA que j'ai installé ? ». Réponse fournie par la superposition de compatibilité de version dans CAPABILITIES.md ## Version compatibility, qui fait des renvois croisés à la chaîne de détection canonique dans doca-version et ajoute les puces SHA-spécifiques « découvrir, ne pas supposer ».
*« Que signifie ce `DOCAERRORprovenant d'un appel SHA et quel couche l'a causé ? »** — exemple travaillé : *«DOCA_ERROR_INVALID_VALUEsurdoca_sha_task_hash_alloc_init»*. Réponse fournie par la superposition SHA sur la taxonomie inter-bibliothèques dans [CAPABILITIES.md ## Error taxonomy](CAPABILITIES.md#error-taxonomy) + l'échelle stratifiée dans [TASKS.md ## debug](TASKS.md#debug) qui monte vers [doca-debug`](../../doca-debug/SKILL.md).

Public

Cette compétence sert les développeurs externes construisant des applications qui consomment la bibliothèque DOCA SHA — c'est-à-dire les utilisateurs dont le code appelle doca_sha_* (directement en C/C++, ou via FFI/bindings depuis un autre langage) pour déléguer le hachage SHA vers un DPU BlueField ou un accélérateur ConnectX. Elle n'est pas destinée aux développeurs NVIDIA contribuant à DOCA SHA lui-même.

Portée linguistique. DOCA SHA est livré comme une bibliothèque C avec le nom du module pkg-config doca-sha. Les exemples livré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 langages (Rust, Go, Python, …) consomment le même *.so via FFI ou des bindings spécifiques à la langue ; la contribution de cette compétence dans ce cas est de conserver le cycle de vie, la découverte de capacité, les permissions, la taxonomie d'erreurs et la guidance one-shot-vs-partial indépendantes du langage, et de diriger l'agent vers l'ABI C public en tant que surface autoritaire que tout wrapper appellera finalement.

Quand charger cette compétence

Chargez cette compétence quand l'utilisateur effectue un travail pratique DOCA SHA, dans n'importe quel langage. Concrètement :

Initialisation d'un contexte doca_sha sur un doca_dev et configuration d'au moins un type de tâche (doca_sha_task_hash et/ou doca_sha_task_partial_hash) avant doca_ctx_start().
Choix entre la tâche one-shot (doca_sha_task_hash — l'entrée tient dans un seul buffer source, le digest de sortie se termine dans un seul buffer destination) et la tâche partial / incremental (doca_sha_task_partial_hash — entrée diffusée par chunks, finalisée séparément) pour la forme de données de l'utilisateur.
Définition correcte des permissions sur doca_mmap pour le buffer source (DOCA_ACCESS_FLAG_LOCAL_READ_ONLY au minimum) et le buffer destination (DOCA_ACCESS_FLAG_LOCAL_READ_WRITE).
Dimensionnement du buffer destination par rapport à doca_sha_cap_get_min_dst_buf_size(devinfo, algorithm) et du buffer source par rapport à doca_sha_cap_get_max_src_buf_size(devinfo).
Vérification des énums d'algorithme SHA (DOCA_SHA_ALGORITHM_SHA1, DOCA_SHA_ALGORITHM_SHA256, DOCA_SHA_ALGORITHM_SHA512) que l'accélérateur de l'appareil actif annonce, via doca_sha_cap_task_hash_get_supported(devinfo, algorithm) et doca_sha_cap_task_partial_hash_get_supported(devinfo, algorithm) — les deux fusionnent le support de tâche et le support d'algorithme en un seul appel.
Validation d'un digest par rapport à un vecteur de test publié avant de pousser l'entrée en vrac via l'accélérateur.
Débogage d'un DOCA_ERROR_* renvoyé par un appel SHA (cycle de vie vs. dimensionnement de buffer vs. permission vs. algorithme non supporté) et l'événement d'accomplissement de tâche sur le moteur de progression.
Conception ou extension de bindings non-C (Rust, Go, Python, …) qui enrobent l'ABI SHA C — pour le cycle de vie, les permissions, les capacités et les règles one-shot-vs-partial que l'enrobage doit respecter.

Ne chargez pas cette compétence pour l'orientation générale de DOCA, l'installation de DOCA lui-même, les bibliothèques de hachage non-SHA sur CPU (utilisez OpenSSL ou similaire), ou d'autres bibliothèques DOCA. Pour cela, utilisez doca-public-knowledge-map.

Ce que cette compétence fournit

Ceci est un chargeur mince. Le corps ne conserve que l'orientation nécessaire pour choisir le bon fichier suivant. Le matériau spécifique SHA substantiel vit dans deux fichiers complémentaires :

CAPABILITIES.md — ce que DOCA SHA peut exprimer dans cette version : les deux types de tâche (one-shot hash et partial / incremental hash), les trois énums d'algorithme, la surface de requête de capacité (doca_sha_cap_* pour le support d'algorithme et le dimensionnement de buffer), la taxonomie d'erreurs SHA (mappée à l'ensemble DOCA_ERROR_* inter-bibliothèques), la surface d'observabilité (événements d'accomplissement par tâche sur le moteur de progression), la politique de sécurité qui gère les décisions de permissions mmap source / destination, et la règle de sélection du chemin (quand utiliser doca-sha par rapport à un hash CPU ou une autre bibliothèque de cryptographie DOCA).
TASKS.md — flux de travail étape par étape pour les six verbes SHA in-scope : configure, build, modify, run, test, debug. Plus un bloc Deferred task verbs qui dirige les questions hors-scope vers la compétence suivante appropriée.

La compétence suppose un hôte ou BlueField où DOCA est déjà installé à l'emplacement standard et l'utilisateur dispose des 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 compétence ne livre volontairement pas

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

Code source d'application DOCA SHA pré-écrit, dans n'importe quel langage. Le code source SHA vérifié est les exemples C livrés à /opt/mellanox/doca/samples/doca_sha/, plus l'application de référence File Integrity liée depuis le guide public DOCA SHA. Le travail de l'agent est de diriger l'utilisateur vers ces fichiers et de prescrire une modification diff-minimale sur eux via le flux de travail universel modify-a-sample dans doca-programming-guide, stratifié avec les surcharges SHA-spécifiques dans TASKS.md ## modify.
Tables de digest pré-calculées pour des entrées arbitraires. La compétence dit à l'agent d'utiliser un vecteur de test publié (p. ex. les vecteurs de test NIST SHA pour la chaîne vide, « abc » et l'entrée million-a) comme le contrôle de fum connu-vecteur ; elle ne livre pas sa propre banque de vecteurs.
Manifestes de compilation autonomes (meson.build, CMakeLists.txt, Cargo.toml, …) stationnés à l'intérieur de la compétence. 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-sha est la source de vérité.
Un sous-arbre samples/, bindings/, ou reference/ d'aucune sorte. Un artefact simulé ou incomplet dans l'arbre de cette compétence, 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 in-scope.
Pour la matrice de capacité SHA, les énums d'algorithme, la division tâche one-shot vs partial, les règles de requête de capacité, la matrice de permissions, la taxonomie d'erreurs, l'observabilité et la politique de sécurité / sélection du chemin, voir CAPABILITIES.md.
Pour les flux de travail étape par étape — configure, build, modify, run, test, debug — voir TASKS.md.

Les deux fichiers complémentaires 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-la dans la documentation publique ou la mise en page du paquet installé » plutôt que « guidance SHA-spécifique ».

Compétences associées

doca-public-knowledge-map — la table de routage pour chaque source de documentation DOCA publique et la mise en page sur disque d'un paquet DOCA installé. La page DOCA SHA vit à docs.nvidia.com/doca/sdk/DOCA-SHA/ ; l'application de référence File Integrity est l'exemple travaillé canonique.
doca-setup — préparation de l'env, vérification de l'installation, 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.
doca-version — règles de gestion de version DOCA canoniques. La ## Version compatibility de cette compétence fait des renvois croisés à la règle de correspondance quatre voies et n'ajoute que la superposition SHA-spécifique « découvrir les algorithmes + tailles de buffer via cap query ».
doca-structured-tools-contract — la règle de préséance 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 flux de travail first-app universel modify-a-shipped-sample, le cycle de vie universel, la taxonomie DOCA_ERROR_* inter-bibliothèques, et l'ordre de débogage côté programme. Cette compétence stratifie les spécificités SHA par-dessus.
doca-debug — l'échelle de débogage transversale (install / version / build / link / runtime / program / driver). Le débogage SHA-spécifique (algorithm-not-supported, destination-buffer-too-small, partial-hash-out-of-order) se superpose à cette échelle.