Le tutoriel Ampère Porting Advisor –

Le Conseiller de portage Ampère est une fourche du conseiller de portage pour Graviton, un projet open source d’AWS, qui, à son tour, est une fourche du conseiller de portage du groupe informatique High Performance ARM.

À l’origine, il a été codé comme un module Python qui a analysé les incompatibilités connues pour le code C et FORTRAN. Ce tutoriel vous guide à travers le bâtiment et l’utilisation de l’outil et comment agir sur les problèmes identifiés par l’outil.

L’Ampère Porting Advisor est un outil de ligne de commande qui analyse le code source pour les modèles de code connus et les bibliothèques de dépendances. Il génère ensuite un rapport avec toutes les incompatibilités avec les processeurs d’Ampère. Cet outil fournit des suggestions de versions minimales requises et / ou recommandées pour fonctionner sur des processeurs AMPERE pour les bibliothèques d’exécution et de dépendance linguistiques.

Il peut être exécuté sur des machines non ARM64 (comme Intel et AMD) et des processeurs AMPERE ne sont pas nécessaires. Cet outil ne fonctionne pas sur les binaires, seulement le code source. Il ne fait aucune modification de code, il ne fait pas de recommandations au niveau de l’API, ni ne renvoie des données à Ampère.

Veuillez noter: Même si nous faisons de notre mieux pour trouver des incompatibilités connues, nous recommandons toujours d’effectuer les tests appropriés à votre application sur un système basé sur des processeurs AMPERE avant d’aller en production.

Cet outil scanne tous les fichiers dans une arborescence source, qu’ils soient inclus ou non par le système de construction. En tant que tel, il peut signaler à tort les problèmes dans des fichiers qui apparaissent dans l’arborescence source mais sont exclus par le système de construction. Actuellement, l’outil prend en charge les langues / dépendances suivantes:

Python 3+

• Version python
• Version PIP
• Versions de dépendance dans le fichier exigences.txt

Java 8+

• Version java
• Versions de dépendance dans le fichier pom.xml
• La numérisation du pot pour les appels de la méthode native (nécessite que Java soit installée)

Aller 1.11+

• Version Go
• Versions de dépendance sur le fichier go.mod

C, C ++, FORTRAN

• Assemblage en ligne sans assemblage en ligne AARCH64 correspondant.
• Fichiers source d’assemblage sans fichiers source d’assemblage AARCH64 correspondants.
• Détection d’architecture AARCH64 manquante dans les scripts AutoConf config.GUESS.
• Liant les bibliothèques qui ne sont pas disponibles sur l’architecture AARCH64.
• Utilisation d’intrinsèques spécifiques à l’architecture.
• Erreurs de préprocesseur qui déclenchent lors de la compilation sur AARCH64.
• Utilisation de l’ancien temps d’exécution visuel C ++ (spécifique à Windows).
• Les types de problèmes suivants sont détectés, mais non signalés par défaut:
  • Code spécifique du compilateur gardé par des macros prédéfinis spécifiques du compilateur.
• Les types suivants de problèmes spécifiques transversaux sont détectés, mais non signalés par défaut.
  • Détection d’architecture qui dépend de l’hôte plutôt que de la cible.
  • Utilisation d’artefacts de construction dans le processus de construction.

Pour plus d’informations sur la façon de modifier les problèmes signalés, utilisez l’aide intégrée de l’outil: ./portun-advisor-linux-x86_64 – help

Si vous rencontrez des problèmes, consultez notre fichier contributif dans Le référentiel GitHub du projet.

Exécuter le conseiller de portage Ampère comme conteneur

En utilisant cette option, vous n’avez pas à vous soucier des versions Python ou Java, ou toute autre dépendance dont l’outil a besoin. C’est le moyen le plus rapide de commencer.

PR-requis

• Docker ou contenerd + nerdctl + buildkit

Exécuter l’image du conteneur

Après avoir construit l’image, nous pouvons exécuter l’outil en tant que conteneur. Nous utilisons -v pour monter un volume de notre machine hôte au conteneur.

Nous pouvons l’exécuter directement à la console:

docker run --rm -v my/repo/path:/repo porting-advisor /repo

Ou générer un rapport:

docker run --rm -v my/repo/path:/repo -v my/output:/output porting-advisor /repo --output /output/report.html

Exemple Windows:

docker run --rm -v /c/Users/myuser/repo:/repo -v /c/Users/myuser/output:/output porting-advisor /repo --output /output/report.html

Exécuter le conseiller de portage Ampère en tant que script Python

PR-requis

• Python 3.10 ou supérieur (avec module PIP3 et VENV installé).
• (Éventuellement) ouvrir JDK 17 (ou supérieur) et Maven 3.5 (ou supérieur) si vous souhaitez scanner des fichiers JAR pour les méthodes natives.
• Unzip et JQ sont nécessaires pour exécuter des cas de test.

Activer l’environnement Python

Linux / Mac:

python3 -m venv .venv source .venv/bin/activate

PowerShell:

python -m venv .venv .\.venv\Scripts\Activate.ps1

Installer les exigences

• pip3 install -r exigences.txt

Outil d’exécution (sortie de la console)

• python3 src / porting-advisor.py ~ / my / path / to / my / repo

Outil d’exécution (rapport HTML)

• python3 src / portage-advisor.py ~ / my / path / to / my / repo –output report.html

Exécuter le conseiller de portage Ampère en tant que binaire

Générer le binaire

Pré-requis

• Python 3.10 ou supérieur (avec module PIP3 et VENV installé).
• (Éventuellement) ouvrir JDK 17 (ou supérieur) et Maven 3.5 (ou supérieur) si vous voulez que le binaire puisse scanner des fichiers JAR pour les méthodes natives.

Le script build.sh générera un binaire autonome (pour Linux / MacOS). Il sera sorti dans un dossier appelé dist.

Par défaut, il générera un binaire nommé comme le portage-advisor-linux-x86_64. Vous pouvez personnaliser le nom de fichier généré en définissant l’environnement variable file_name.

Pour Windows, le build.ps1 générera un dossier avec un EXE et tous les fichiers dont il a besoin pour exécuter.

Courir le binaire

Pré-requis

Une fois que le binaire généré, il ne faudra que Java 11 Runtime (ou supérieur) si vous souhaitez scanner des fichiers JAR pour les méthodes natives. Sinon, le fichier est autonome et n’a pas besoin de Python pour s’exécuter.

Comportement par défaut, sortie de la console:

$ ./porting-advisor-linux-x86_64 ~/my/path/to/my/repo

Génération du rapport HTML:

$ ./porting-advisor-linux-x86_64 ~/my/path/to/my/repo --output report.html

Génération d’un rapport de dépendances Just (cela crée un fichier Excel avec les dépendances que nous avons trouvées sur le référentiel, aucune suggestion fournie):

$ ./porting-advisor-linux-x86_64 ~/my/path/to/my/repo --output dependencies.xlsx --output-format dependencies

Comprendre un rapport de conseiller de portage d’Ampère

Voici un exemple du rapport de sortie généré avec un exemple de projet:

./dist/porting-advisor-linux-x86_64 ./sample-projects/ 
| Elapsed Time: 0:00:03 
 
Porting Advisor for Ampere Processor v1.0.0 
Report date: 2023-05-10 11:31:52 
 
13 files scanned. 
detected go code. min version 1.16 is required. version 1.18 or above is recommended. we detected that you have version 1.19. see https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/golang.md for more details. 
detected python code. if you need pip, version 19.3 or above is recommended. we detected that you have version 22.3.1 
detected python code. min version 3.7.5 is required. we detected that you have version 3.10.9. see https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/python.md for more details. 
./sample-projects/java-samples/pom.xml: dependency library: leveldbjni-all is not supported on Ampere processor. 
./sample-projects/java-samples/pom.xml: using dependency library snappy-java version 1.1.3. upgrade to at least version 1.1.4 
./sample-projects/java-samples/pom.xml: using dependency library zstd-jni version 1.1.0. upgrade to at least version 1.2.0 
./sample-projects/python-samples/incompatible/requirements.txt:3: using dependency library OpenBLAS version 0.3.16. upgrade to at least version 0.3.17 
detected go code. min version 1.16 is required. version 1.18 or above is recommended. we detected that you have version 1.19. see https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/golang.md for more details. 
./sample-projects/java-samples/pom.xml: using dependency library hadoop-lzo. this library requires a manual build  more info at: https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/java.md#building-jar-libraries-manually 
./sample-projects/python-samples/incompatible/requirements.txt:5: dependency library NumPy is present. min version 1.19.0 is required. 
detected java code. min version 8 is required. version 17 or above is recommended. see https://github.com/AmpereComputing/ampere-porting-advisor/blob/main/doc/java.md for more details. 
 
Use --output FILENAME.html to generate an HTML report. 

• Dans le rapport, nous voyons plusieurs runtimes linguistiques (Python, PIP, Golang, Java) et leurs versions détectées. Tous ces messages communiquent la version minimale et la version recommandée pour ces langues. Certaines de ces lignes détectent que des versions préalables ont été trouvées et sont purement informatives.
• Nous voyons également certains messages des dépendances détectées dans le modèle d’objet Project (POM) ou un projet Java. Ce sont des dépendances qui seront téléchargées et utilisées dans le cadre d’un processus de construction Maven, et nous voyons trois types de messages exploitables:

La dépendance nécessite une version plus récente

./sample-projects/java-seless/pom.xml: Utilisation de la bibliothèque de dépendances Snappy-Java version 1.1.3. passer à au moins la version 1.1.4

• Les messages de ce type indiquent que nous devons utiliser une version plus récente de la dépendance, qui nécessitera la reconstruction et la validation du projet avant de continuer.

La dépendance nécessite une construction manuelle

./sample-projects/java-seless/pom.xml: Utilisation de la bibliothèque de dépendances Hadoop-LZO. Cette bibliothèque nécessite une création manuelle plus d’informations sur: https://github.com/amperecomputing/ampere-portting-advisor/blob/main/doc/java.md#building-jar-librares-manalal

• Dans ce cas, une dépendance prend en charge l’architecture, mais pour une raison quelconque (peut-être tester les fonctionnalités matérielles disponibles et créer une version optimisée du projet pour la plate-forme cible), le projet doit être reconstruit manuellement plutôt que de compter sur un artefact binaire préexistant

La dépendance n’est pas disponible sur cette architecture

./sample-projects/java-seless/pom.xml: Bibliothèque de dépendances: le niveaudbjni-all n’est pas pris en charge sur le processeur AMPERE.

• Dans ce cas, le projet est spécifié comme dépendance mais n’est pas disponible pour la plate-forme AMPERE. Un ingénieur peut avoir à examiner ce qui est impliqué dans la fabrication correcte du code de la compilation de dépendance à la plate-forme cible. Ce processus peut être simple mais peut également prendre beaucoup de temps et d’efforts. Alternativement, vous pouvez adapter votre projet pour utiliser un package alternatif fournissant des fonctionnalités similaires qui prennent en charge l’architecture AMPERE et modifier le code de votre projet de manière appropriée pour utiliser cette alternative.

Un exemple de transition pour C / C ++

Mégahit est un outil d’assembleur NGS disponible en binaire pour x86_64. Un client voulait exécuter Megahit sur ARM64 dans le cadre d’une transition d’architecture. Mais la compilation a échoué sur ARM64 dans le premier fichier:

Le développeur voulait savoir ce qui devait être changé pour faire correctement la compilation Megahit sur ARM64.

Dans ce cas, Ampère Porting Advisor (APA) peut jouer un rôle clé. Après avoir scanné le référentiel source du projet Megahit avec APA, nous obtenons une liste de problèmes qui doivent être vérifiés avant de reconstruire Megahit sur ARM64:

Étudions chaque type d’erreur dans la liste et corrigeons-les pour ARM64 si nécessaire.

Options de construction spécifiques à l’architecture

Ces erreurs seront déclenchées une fois que les options de construction détectées APA ne sont pas valides sur ARM64.

Le CMakelist.txt d’origine utilise des indicateurs de compilation x86_64 par défaut sans vérifier les architectures de CPU. Pour résoudre ce problème, nous pouvons tester une condition CMake_System_processor pour nous assurer que les drapeaux rapportés par APA ne seront appliqués qu’aux architectures x86_64.

Instructions spécifiques à l’architecture

L’erreur d’instructions spécifiques à l’architecture sera déclenchée une fois que les fonctions de style C APA ont détecté ARM64 utilisée dans le code. Les instructions intrinsèques sont compilées par le compilateur directement dans le code d’assemblage spécifique à la plate-forme, et généralement chaque plate-forme aura son propre ensemble d’instructions d’intrinsèques et de code d’assemblage optimisées pour cette plate-forme.

Dans ce cas, nous pouvons faire l’utilisation de conditions de pré-processeur pour ne compiler que les instructions _pdep_u32 / 64 et __cpuid / ex lorsque #if défini (x86_64) est vrai pour les fonctions haspopcnt () et hasbmi2 (). Pour VEC_VSX_LD, il est déjà enveloppé dans un pré-processeur conditionnel et ne sera compilé que sur l’architecture Power PC, nous pouvons donc le laisser tel quel.

Assemblage en ligne spécifique à l’architecture

L’erreur d’instructions spécifiques à l’architecture sera déclenchée une fois qu’APA détecté le code d’assemblage utilisé dans le code. Nous devons vérifier si l’extrait du code d’assemblage est pour ARM64 ou non.

Le projet Megahit utilise uniquement le code d’assemblage BSWAP dans phmap_bits.h lorsqu’il est compilé sur l’architecture x86_64. Lorsqu’il est compilé sur d’autres architectures, il compile une implémentation de retour de GLIBC. Donc, aucune modification n’est requise dans phmap_bits.h.

Dans cpu_dispatch.h, deux fonctions en ligne HaspOpcnt () et hasbmi2 () incluent inconditionnellement l’instruction d’assemblage x86_64 cpuid pour tester les fonctionnalités du CPU sur x86_64. Nous pouvons ajouter un drapeau conditionnel du précompilateur # si défini (x86_64) Pour s’assurer que ce code n’est pas appelé sur ARM64, et nous retournerons toujours faux.

Intrinsèque SIMD spécifique à l’architecture

L’erreur d’instructions spécifiques à l’architecture sera déclenchée une fois qu’APA a détecté les instructions SIMD X86_64 comme AVX256 ou AVX512 utilisées dans le code. Ces instructions SIMD sont enveloppées par les drapeaux conditionnels du précompilateur et ne provoqueront généralement aucun problème de fonctionnalité sur ARM64.

S’il n’y avait pas de mise en œuvre SIMD de l’algorithme pour ARM64, il pourrait y avoir un écart de performance par rapport à x86_64. Dans ce cas, il y a une implémentation SIMD Neon pour ARM64 dans XXH3.h et cette implémentation sera choisie par cerise par le compilateur en fonction de l’architecture CPU. Aucune autre action ne doit être prise.

Erreur de préprocesseur sur AARCH64

L’erreur du préprocesseur sera déclenchée par APA pour indiquer que l’architecture ARM64 peut ne pas être incluse dans une étape pré-compile. Dans ce cas, nous pouvons voir que le conditionnel pré-compile est pour x86_64 uniquement et ne concerne pas l’architecture ARM64.

Reconstruire et tester

Une fois tous ces ajustements apportés, nous pourrions reconstruire le projet:

Le projet a compilé avec succès. Nous avons ensuite vérifié s’il a réussi la suite de tests du projet:

Après avoir vérifié et corrigé manuellement tous les pièges potentiels rapportés par l’APA, Megahit est désormais en mesure de construire et d’exécuter sur des processeurs Ampère.