DOCA Compress

Par où commencer : Cette skill suppose que DOCA est déjà installé et que l'utilisateur fait du travail pratique de Compression (compression ou décompression DEFLATE en masse) sur une 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 DOCA Compress peut exprimer sur cette version. Si l'utilisateur n'a pas encore installé DOCA, routez d'abord vers doca-setup. Si l'utilisateur demande « dois-je vraiment décharger cette compression sur l'accélérateur ? », la règle de sélection de chemin basée sur le seuil de taille dans CAPABILITIES.md ## Capabilities and modes est la première étape — la compression en masse est le cas canonique, une seule occurrence n'en est pas.

Exemples de questions que cette skill répond bien

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

« Dois-je décharger cette compression sur DOCA Compress, ou simplement utiliser zlib/zstd sur le CPU ? » — exemple travaillé : « Je compresse un buffer de log de 4 MiB avant de l'écrire dans le stockage ; doca-compress vaut-il le coût de configuration par rapport à zlib sur le CPU ? ». Répondu par la règle de sélection de chemin basée sur le seuil de taille dans CAPABILITIES.md ## Capabilities and modes + les points « quand NE PAS utiliser doca-compress » dans CAPABILITIES.md ## Safety policy.
« Mon device supporte-t-il la tâche de compression (ou décompression) que je veux, et quelle taille de buffer peut-il déplacer par soumission ? » — exemple travaillé : « doca_compress_task_compress_deflate est-il sur cette BlueField, et quelle est la taille maximale de source par tâche ? ». Répondu par la règle de requête de capacité par tâche (doca_compress_cap_task_compress_deflate_is_supported, _decompress_deflate_is_supported, les requêtes _get_max_buf_size correspondantes) dans CAPABILITIES.md ## Capabilities and modes + l'étape de découverte dans TASKS.md ## configure.
« J'ai juste besoin de décompresser les données réseau entrantes — est-ce une utilisation valide et autonome de doca-compress ? » — exemple travaillé : « mon client reçoit des payloads compressés en DEFLATE et ne produit jamais sa propre sortie compressée ». Répondu par la note « decompression-only » dans la table des types de tâche de CAPABILITIES.md ## Capabilities and modes + la matrice de configuration par tâche dans l'étape 5 de TASKS.md ## configure.
« Quelles permissions la mmap source / destination a-t-elle besoin ? » — exemple travaillé : « ma doca_compress_task_compress_deflate retourne DOCA_ERROR_NOT_PERMITTED ». Répondu par la matrice de permissions dans CAPABILITIES.md ## Safety policy + la checklist de définition des permissions mmap dans TASKS.md ## test.
« Cette API DOCA Compress est-elle disponible sur ma version DOCA installée ? » — exemple travaillé : « doca_compress_task_decompress_deflate est-il dans la DOCA que j'ai installée ? ». Répondu par le calque de compatibilité de version dans CAPABILITIES.md ## Version compatibility, qui relie la chaîne de détection canonique dans doca-version et ajoute les points « découvrir le support par tâche, ne pas supposer » spécifiques à Compress.
*« Que signifie ce `DOCAERRORd'un appel Compress et quelle couche l'a causé ? »** — exemple travaillé : *«DOCA_ERROR_INVALID_VALUEsurdoca_compress_task_compress_deflate_alloc_init»*. Répondu par le calque Compress 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 Compress — c'est-à-dire les utilisateurs dont le code appelle doca_compress_* (directement en C/C++, ou via FFI/bindings depuis un autre langage) pour décharger la compression ou décompression DEFLATE en masse sur une DPU BlueField ou un accélérateur ConnectX. Ce n'est pas pour les développeurs NVIDIA contribuant à DOCA Compress lui-même.

Portée du langage. DOCA Compress est livré en tant que bibliothèque C avec le nom de module pkg-config doca-compress. 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 au langage ; la contribution de cette skill dans ce cas est de garder le cycle de vie, la découverte de capacité, la permission, la taxonomie d'erreur, et le guidance de compression-vs-décompression indépendant du langage, et de router l'agent vers l'ABI C public comme la surface autoritaire que tout wrapper finira par appeler.

Quand charger cette skill

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

Initialiser un contexte doca_compress sur un doca_dev et configurer au moins un type de tâche (doca_compress_task_compress_deflate et/ou doca_compress_task_decompress_deflate) avant doca_ctx_start().
Choisir entre la tâche compress et la tâche decompress pour le flux de données de l'utilisateur. Les deux types de tâche sont indépendants : un consommateur qui ne fait que décompresser des payloads DEFLATE entrants est une forme valide et n'a pas besoin d'activer la tâche de compression.
Définir les permissions sur doca_mmap correctement pour le buffer source (DOCA_ACCESS_FLAG_LOCAL_READ_ONLY au minimum) et le buffer destination (DOCA_ACCESS_FLAG_LOCAL_READ_WRITE).
Dimensionner le buffer source selon le plafond doca_compress_cap_task_*_get_max_buf_size(devinfo) par tâche et le buffer destination selon la taille de sortie dans le pire cas que l'algorithme peut produire sur cette entrée.
Vérifier quels types de tâche l'accélérateur de ce device annonce via doca_compress_cap_task_compress_deflate_is_supported et doca_compress_cap_task_decompress_deflate_is_supported contre le doca_devinfo actif.
Valider contre un aller-retour (compression → décompression, ou décompression → comparaison avec une fixture codée en DEFLATE connue) avant de pousser l'entrée en masse via l'accélérateur.
Décider s'il faut décharger du tout — la règle de seuil de taille dans CAPABILITIES.md ## Capabilities and modes dit que doca-compress est la bonne réponse seulement pour les entrées en masse (règle empirique : ≥ quelques KiB) ; en dessous de cela, la compression CPU bate l'aller-retour DMA-vers-accélérateur.
Déboguer un DOCA_ERROR_* retourné d'un appel Compress (cycle de vie vs. dimensionnement de buffer vs. permission vs. tâche non supportée) 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 Compress — pour le cycle de vie, la permission, la capacité, et les règles de compression-vs-décompression que le wrapper doit honorer.

Ne chargez pas cette skill pour l'orientation générale de DOCA, l'installation de DOCA lui-même, les bibliothèques de compression non-DEFLATE sur CPU (utilisez zlib / zstd / similaire), ou d'autres bibliothèques DOCA. Pour celles-ci, utilisez doca-public-knowledge-map.

Ce que cette skill fournit

C'est un thin loader. Le corps ne conserve que l'orientation nécessaire pour choisir le bon fichier suivant. Le matériau substantif spécifique à Compress se trouve dans deux fichiers compagnons :

CAPABILITIES.md — ce que DOCA Compress peut exprimer sur cette version : les deux types de tâche (compress-deflate et decompress-deflate, chacun une forme valide et autonome), la surface de requête de capacité par tâche (doca_compress_cap_* pour le support de tâche et la taille maximale de buffer par soumission), la taxonomie d'erreur Compress (mappée sur l'ensemble inter-bibliothèques DOCA_ERROR_*), la surface d'observabilité (événements d'achèvement par tâche sur le moteur de progression), la politique de sécurité qui conditionne les décisions de permission mmap source / destination, et la règle de sélection de chemin basée sur le seuil de taille (quand utiliser doca-compress par rapport à la compression CPU ou doca-dma pour le cas de copie sans compression).
TASKS.md — workflows étape par étape pour les six verbes Compress en scope : configure, build, modify, run, test, debug. Plus un calque ## rollback (démontage Compress-spécifique en cinq étapes qui draine les tâches en vol avant doca_ctx_stop, désenregistre les régions mmap dans l'ordre inverse d'enregistrement, et re-vérifie le chemin de device avec le smoke aller-retour) et l'instanciation universelle de la boucle de débogage à 5 phases ajoutée à ## debug. Plus un bloc Deferred task verbs qui pointe les questions hors-scope vers la bonne skill suivante.

La skill suppose un hôte ou une 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 refuse délibérément de livrer

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

Code source d'application DOCA Compress pré-écrit, dans n'importe quel langage. Le code source Compress vérifié est les exemples C livrés à /opt/mellanox/doca/samples/doca_compress/, plus l'application de référence File Compression liée depuis le guide DOCA Compress public. La tâche de l'agent est de router l'utilisateur vers ces fichiers et de prescrire une modification minimum-diff sur eux via le workflow universel modify-a-sample dans doca-programming-guide, stratifié avec les overrides spécifiques à Compress dans TASKS.md ## modify.
Fixtures DEFLATE pré-encodés pour des entrées arbitraires. La skill dit à l'agent d'utiliser une validation aller-retour (compression → décompression et comparaison à l'original, ou décompression d'un blob DEFLATE connu produit par un encodeur CPU publié comme zlib) comme smoke connu-bon ; elle ne livre pas sa propre banque de fixtures.
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 contre la DOCA installée de l'utilisateur, où pkg-config --modversion doca-compress est la source de vérité.
Un sous-arbre samples/, bindings/, ou reference/ d'aucune sorte. Un artifact fictif ou incomplet dans l'arbre de cette skill, même un étiqueté « reference », est trompeur : les utilisateurs le liront comme compilable.

Ordre de chargement

Lire d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est en scope.
Pour la matrice de capacité Compress, la division des tâches de compression / décompression (y compris la décompression-seule comme forme autonome), les règles de requête de capacité par tâche, la matrice de permission, 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 font un lien croisé vers 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 l'agencement du package installé » plutôt que « guidance spécifique à Compress ».

Skills connexes

doca-public-knowledge-map — la table de routage pour chaque source de documentation DOCA publique et l'agencement sur disque d'un package DOCA installé. La page DOCA Compress se trouve à docs.nvidia.com/doca/sdk/DOCA-Compress/ ; l'application de référence File Compression est l'exemple travaillé canonique.
doca-setup — préparation de l'environnement, 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 relie la règle de correspondance quatre voies et ajoute uniquement le calque « découvrir le support par tâche + la taille maximale de buffer par tâche via requête de cap » spécifique à Compress.
doca-structured-tools-contract — la règle de précédence 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 de programmation DOCA généraux partagés par chaque bibliothèque : le motif de compilation pkg-config + meson canonique, le workflow universel modify-a-shipped-sample pour la première app, le cycle de vie universel, la taxonomie inter-bibliothèques DOCA_ERROR_*, et l'ordre de débogage côté programme. Cette skill stratifie les spécificités Compress par-dessus.
doca-dma — la bonne bibliothèque quand le flux de données est une copie mmap-to-mmap pure sans compression requise. La règle de sélection de chemin de cette skill route vers DMA quand Compress n'est pas la réponse (par exemple, l'utilisateur veut seulement déplacer des octets, pas les encoder).
doca-debug — l'échelle de débogage inter-couches (installation / version / compilation / liaison / runtime / programme / driver). Le débogage spécifique à Compress (tâche-non-supportée, buffer-source-trop-grand, buffer-destination-trop-petit) se stratifie par-dessus cette échelle.