Activer TMA dans les applications NVSHMEM

Objectif

Préparer une application pour les transferts device-side soutenus par TMA de NVSHMEM sans modifier ses APIs put/get ni ses kernels non liés. Évaluer la cible, choisir le bon chemin de mémoire partagée, effectuer le changement le plus petit et sûr, et expliquer les exigences au lancement.

Prérequis

• Exiger la source CUDA/C++ lisible pour un patch ou une revue de code. Une évaluation statique ne nécessite ni GPU, ni runtime NVSHMEM installé, ni accès cluster.
• Exiger un environnement de développement NVSHMEM 3.7.0 ou plus récent et une toolchain CUDA uniquement lors de la compilation.
• Exiger des GPUs SM90 ou plus récents et la capacité d'accès en lecture/écriture pair-à-pair telle que NVLink uniquement lors de la validation de l'exécution TMA ou de la performance.
• CFT exige TMA.

Routage de référence

Avant de modifier le code, lisez registration-and-launch.md en intégralité, puis chaque référence sélectionnée ci-dessous. Utilisez les références comme modèles, non comme remplacements aveuglés : préservez la gestion des erreurs, l'abstraction de lancement, le contrat de complétion et la disposition de la mémoire partagée de l'application.

Pour une évaluation ou une revue en lecture seule, lisez uniquement les références nécessaires pour évaluer le chemin proposé. Ne modifiez pas le code tant que la référence d'enregistrement complète et chaque référence de chemin sélectionnée n'ont pas été lues.

Entrées

• Requis : Chemin source de l'application ou fichier source, et le résultat demandé : évaluation, patch, revue ou débogage.
• Optionnel : Dériver la version NVSHMEM, l'architecture CUDA, la topologie, les sites de lancement de kernel et la configuration de lancement du projet ou de l'environnement si possible.
• Conditionnel pour l'exécution : Obtenir la commande de compilation, la commande de lancement et l'accès au matériel cible uniquement si l'utilisateur demande de compiler ou d'exécuter la validation.
• Poser uniquement des questions sur des faits qui ne peuvent pas être inspectés et qui affectent matériellement le résultat. N'exigez pas les détails de topologie simplement pour préparer le code ; marquez le bénéfice de performance comme non vérifiés lorsque la topologie est inconnue.

Portée

• Identifier exactement une unité de traduction CUDA acceptée par l'utilisateur et un kernel NVSHMEM avant de modifier. Le code de lancement requis est la limite de changement complète.
• Dériver la cible du fichier/kernel nommé par l'utilisateur ou des métadonnées de pièce jointe, non pas des fichiers découverts par globbing. Une demande singulière n'autorise pas la modification de tous les kernels éligibles.
• Préserver tous les autres kernels, l'utilisation NVSHMEM host-only et le code de lancement non lié. Ne modifiez jamais les candidats adjacents simplement parce qu'ils contiennent des appels NVSHMEM.
• Étendre au-delà d'un kernel uniquement si l'utilisateur nomme explicitement plusieurs cibles. Appliquer cette vérification de portée indépendamment à chaque cible.

Avant de modifier, répondez à chaque question ci-dessous. Arrêtez sans modifier si une réponse requise est non ou non vérifiée.

• Portée explicite : Ceci est-il le fichier et le kernel sélectionnés ?
• Opération éligible : Le graphe d'appels device du kernel sélectionné atteint-il une opération NVSHMEM pertinente pour TMA ?
• Modification nécessaire : Chaque changement prévu est-il nécessaire pour l'enregistrement, la durée de vie, le flux de données direct-SMEM ou le dimensionnement du lancement ?
• Redondance prouvée : Si vous supprimez une copie ou un buffer de staging, est-il prouvé qu'il n'a aucun rôle de producteur, consommateur, alias, synchronisation, complétion ou durée de vie ? Si la réponse est non vérifiée parce que le buffer GMEM est un paramètre, s'échappe de l'unité de traduction sélectionnée ou a des consommateurs non inspectables, demander à l'utilisateur s'il est observable de l'extérieur avant de modifier. N'inférez pas la redondance.
• Pas de spéculation : La cible sélectionnée exige-t-elle l'enregistrement TMA côté application pour l'opération en cours de préparation ?
• Changement de lancement chirurgical : La grille, le bloc, le stream, les arguments et la gestion des erreurs existants peuvent-ils rester intacts mis à part les paramètres d'enregistrement requis et les octets de SMEM dynamique ?

Après modification, inspectez la liste des fichiers modifiés et le diff. Supprimez uniquement vos propres modifications hors de portée avant de rapporter l'achèvement ; l'ensemble de fichiers d'application modifiés doit contenir uniquement la cible acceptée.

Instructions

1. Établir la limite

• Traiter une évaluation ou une revue comme en lecture seule.
• Traiter une demande d'activation, de préparation, de mise à jour ou de correction de TMA comme une permission de modifier uniquement la configuration de kernel et de lancement sélectionnées en portée.
• Inspecter le graphe d'appels device du kernel sélectionné pour les put, get, put-with-signal point-à-point device-side et leurs variantes typées/thread/warp/block.

2. Décider si TMA est utile et disponible

Énoncer ces conclusions avant ou à côté d'un patch :

• Exiger NVSHMEM 3.7.0 ou plus récent. Arrêter une conversion demandée pour une version confirmée plus ancienne et recommander une mise à jour.
• Exiger SM90 ou plus récent pour l'exécution TMA. Avec NVSHMEM_TMA_POLICY=ENABLE, les GPUs plus anciennes préservent la correction via le chemin régulier mais ne reçoivent aucun bénéfice TMA.
• TMA aide uniquement les chemins de mémoire GPU accessibles par pair via le tissu load/store GPU, normalement NVLink. Ne pas le recommander pour IB, RoCE, EFA ou un autre transport réseau.
• C'est prometteur pour les grands transferts point-à-point, les faibles nombres de threads de communication, les kernels fusionnés ou les tuiles déjà en mémoire partagée. Ne jamais promettre une accélération sans mesure.

Quand la version, l'architecture ou la topologie est inconnue, préparer le code uniquement si demandé et marquer la conclusion correspondante comme non vérifiée.

3. Classifier chaque opération

Inspecter les espaces d'opérandes locaux, la mémoire partagée de l'application, le flux de données de copie de staging, la mémoire partagée dynamique/statique, l'alignement, les retours anticipés, le flux de contrôle uniforme CTA, les appels de fences/flushes/quiet existants et les possibles appelants staged concurrents dans un CTA.

Défaut à staging NVSHMEM-managed. Ne jamais introduire une nouvelle disposition de mémoire partagée d'application uniquement pour forcer un chemin d'opérande direct.

4. Appliquer les références sélectionnées

Suivre le protocole d'enregistrement/durée de vie complet dans la référence d'enregistrement partagée. Ensuite, appliquer la référence de chemin sélectionnée. Préserver la sémantique de complétion existante et ne pas coder en dur le nombre d'octets de mémoire partagée actuellement recommandé.

5. Valider et rapporter

Lire la référence de validation pour tous les travaux de compilation, exécution, diagnostic et rapport de validation. Précéder le rapport final avec l'un de :

• TMA est utile et l'application est préparée
• L'application est préparée, mais le bénéfice TMA est non vérifié
• TMA n'est pas utile ou non supporté pour cette cible

Utiliser ce modèle de rapport :

Résultat : <une ligne de résultat requise ci-dessus>
Portée modifiée : <le fichier sélectionné, le kernel et le site de lancement ; confirmer qu'aucun fichier adjacent n'a changé>
Chemin sélectionné : <Staging GMEM géré par NVSHMEM | put direct en SMEM explicitement accepté>
Précondition de politique : Définir NVSHMEM_TMA_POLICY=ENABLE avant nvshmem_init* ; <où la définir>
Éligibilité : NVSHMEM <version, doit être >= 3.7.0> ; <preuve SM90+> ; <preuve NVLink/pair load-store>
Contraintes d'opération : <alignement, nombre d'octets, portée/concurrence, complétion, dimensionnement de mémoire partagée>
Fallback : ENABLE préserve le chemin régulier pour les opérations inéligibles ; l'enregistrement seul ne garantit pas le routage TMA
Non vérifiés : <topologie, occupancy ou aucun>
Validation : <vérifications exécutées et commandes de test restantes exactes>

Mentionner tout candidat direct-SMEM délibérément non appliqué parce qu'il était hors de portée ou sa redondance n'était pas prouvée.

Limitations

• Ne pas convertir RMA host-side, les collectives sans un chemin TMA applicable, les opérations de transport réseau ou les cibles de mémoire partagée distante.
• Ne pas affirmer que l'enregistrement garantit le routage TMA ; la politique, l'architecture, la topologie, l'espace d'opérandes, l'alignement, la taille, la portée et les limites d'exécution déterminent chaque transfert.

Dépannage

Pour les défaillances de configuration, les résultats incorrects, les blocages près de la libération de mémoire partagée ou un chemin TMA non sélectionné, lire validation-and-troubleshooting.md. Traiter le fallback du chemin régulier sous NVSHMEM_TMA_POLICY=ENABLE comme un comportement valide ; ne pas le diagnostiquer comme une défaillance de correction.

Exemples

Utiliser $nvshmem-enable-tma pour préparer app.cu pour NVSHMEM TMA sur H100 NVLink tout en laissant les kernels non-NVSHMEM inchangés.

Utiliser $nvshmem-enable-tma pour inspecter une séquence shared-tile-vers-GMEM-vers-put et, si la copie GMEM est prouvée redondante, passer la tuile partagée existante directement.

Utiliser $nvshmem-enable-tma pour évaluer une application NVSHMEM 3.6 s'exécutant sur des pairs A100 connectés uniquement via InfiniBand.