O tutorial do Advisor de Porta de Ampere – SitePoint


O Advisor de Porting de Ampere é um bifurcado do Porting Advisor for Graviton, um projeto de código aberto da AWS, que, por sua vez, é um garfo do consultor de portador do Grupo de Computação de Alto Desempenho do ARM.

Originalmente, ele era codificado como um módulo Python que analisou incompatibilidades conhecidas para o código C e Fortran. Este tutorial o leva pela construção e uso da ferramenta e como agir em questões identificadas pela ferramenta.

O AMPERE Porting Advisor é uma ferramenta de linha de comando que analisa o código -fonte para padrões de código conhecidos e bibliotecas de dependência. Em seguida, gera um relatório com qualquer incompatibilidade com os processadores da Ampere. Esta ferramenta fornece sugestões de versões mínimas necessárias e/ou recomendadas para executar em processadores amperes para as bibliotecas de tempo de execução do idioma e dependência.

Ele pode ser executado em máquinas que não são baseadas em Arm64 (como Intel e AMD) e processadores de amperes não são necessários. Esta ferramenta não funciona em binários, apenas código -fonte. Ele não faz nenhuma modificação de código, não faz recomendações no nível da API, nem envia dados de volta ao Ampere.

Observe: Embora façamos o possível para encontrar incompatibilidades conhecidas, ainda recomendamos realizar os testes apropriados ao seu aplicativo em um sistema com base em processadores de amperes antes de ir à produção.

Essa ferramenta digitaliza todos os arquivos em uma árvore de origem, independentemente de serem incluídos pelo sistema de construção ou não. Como tal, pode relatar erroneamente questões em arquivos que aparecem na árvore de origem, mas são excluídos pelo sistema de construção. Atualmente, a ferramenta suporta os seguintes idiomas/dependências:

Python 3+

  • Versão Python
  • Versão pip
  • Versões de dependência no arquivo requisitos.txt

Java 8+

  • Versão Java
  • Versões de dependência no arquivo pom.xml
  • A varredura de jar para chamadas de método nativo (exige que o Java seja instalado)

Vá 1.11+

  • Versão vá
  • Versões de dependência no arquivo go.mod

C, C ++, Fortran

  • Montagem embutida sem montagem em linha correspondente AARCH64.
  • Arquivos de origem de montagem sem arquivos de origem de montagem AARCH64 correspondentes.
  • Detecção de arquitetura AARCH64 ausente em scripts do AutoConf Config.Guess.
  • Linking contra bibliotecas que não estão disponíveis na arquitetura AARCH64.
  • Uso da arquitetura Intrínseca específica.
  • Erros de pré -processador que acionam ao compilar no AARCH64.
  • Uso do tempo de execução Visual C ++ antigo (específico do Windows).
  • Os seguintes tipos de problemas são detectados, mas não relatados por padrão:
    • Código específico do compilador guardado por macros predefinidos específicos do compilador.
  • Os seguintes tipos de problemas específicos de compilos cruzados são detectados, mas não relatados por padrão.
    • Detecção de arquitetura que depende do host e não do alvo.
    • Uso de artefatos de construção no processo de construção.

Para obter mais informações sobre como modificar os problemas relatados, use a ajuda interna da ferramenta: ./porting-advisor-linux-x86_64–help

Se você tiver algum problema, consulte nosso arquivo contribuinte em o repositório do GitHub do projeto.

Executando o Advisor de Porta de Ampere como um contêiner

Ao usar esta opção, você não precisa se preocupar com as versões Python ou Java ou qualquer outra dependência que a ferramenta precisa. Esta é a maneira mais rápida de começar.

Requisitos de Pr

  • Docker ou contêiner + nerdctl + BuildKit

Execute a imagem do contêiner

Depois de construir a imagem, podemos executar a ferramenta como um contêiner. Usamos -v para montar um volume da nossa máquina host para o recipiente.

Podemos executá -lo diretamente para console:

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

Ou gerar um relatório:

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

Exemplo do Windows:

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

Executando o Advisor de Porta de Ampere como um script Python

Requisitos de Pr

  • Python 3.10 ou acima (com o módulo PIP3 e Venv instalado).
  • (Opcionalmente) Abra o JDK 17 (ou acima) e o Maven 3.5 (ou acima) se desejar digitalizar arquivos JAR em busca de métodos nativos.
  • O Unzip e o JQ são obrigados a executar casos de teste.

Ativar ambiente Python

Linux/Mac:

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

PowerShell:

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

Instale requisitos

  • pip3 install -r requisitos.txt

Ferramenta de execução (saída do console)

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

Executar ferramenta (relatório HTML)

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

Executando o Advisor de Porta de Ampere como um binário

Gerando o binário

Pré-requisitos

  • Python 3.10 ou acima (com o módulo PIP3 e Venv instalado).
  • (Opcionalmente) Abra o JDK 17 (ou acima) e o Maven 3.5 (ou acima) se você deseja que o binário seja capaz de digitalizar arquivos JAR em busca de métodos nativos.

O script Build.sh gerará um binário independente (para Linux/MacOS). Ele será emitido para uma pasta chamada Dist.

Por padrão, ele gerará um binário nomeado como Porting-Advisor-Linux-X86_64. Você pode personalizar o nome do arquivo gerado definindo a variável de ambiente file_name.

Para o Windows, o Build.PS1 gerará uma pasta com um EXE e todos os arquivos necessários para ser executado.

Executando o binário

Pré-requisitos

Depois de gerar o binário, ele exigirá apenas o tempo de execução do Java 11 (ou acima) se desejar digitalizar arquivos JAR em busca de métodos nativos. Caso contrário, o arquivo é independente e não precisa de Python para ser executado.

Comportamento padrão, saída do console:

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

Gerando relatório HTML:

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

Gerando um relatório de apenas dependências (isso cria um arquivo do Excel apenas com as dependências que encontramos no repositório, sem sugestões fornecidas):

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

Compreendendo um relatório de consultor de portador de amperes

Aqui está um exemplo do relatório de saída gerado com um projeto de amostra:

./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.
  • No relatório, vemos vários horários de idioma (Python, Pip, Golang, Java) e suas versões detectadas. Todas essas mensagens comunicam a versão mínima e a versão recomendada para esses idiomas. Algumas dessas linhas detectam que as versões de pré -requisito foram encontradas e são puramente informativas.
  • Também vemos algumas mensagens das dependências detectadas no Modelo de Objeto do Projeto (POM) ou em um projeto Java. São dependências que serão baixadas e usadas como parte de um processo de construção do Maven, e vemos três tipos de mensagens acionáveis:

A dependência requer uma versão mais recente

./sample-projects/java-samples/pom.xml: usando a biblioteca de dependência Snappy-java versão 1.1.3. Atualize para pelo menos a versão 1.1.4

  • As mensagens desse tipo indicam que devemos usar uma versão mais recente da dependência, que exigirá reconstrução e validação do projeto antes de continuar.

A dependência requer uma construção manual

./sample-projects/java-samples/pom.xml: usando biblioteca de dependência Hadoop-lzo. Esta biblioteca requer uma criação manual mais informações em: https://github.com/amperecomputing/ampere-porting-advisor/blob/main/doc/java.md#building-jar-libraries- Manualmente

  • Nesse caso, uma dependência suporta a arquitetura, mas por algum motivo (talvez para testar os recursos de hardware disponíveis e construir uma versão otimizada do projeto para a plataforma de destino), o projeto deve ser reconstruído manualmente, em vez de confiar em um artefato binário pré-existente

A dependência não está disponível nesta arquitetura

./sample-projects/java-samples/pom.xml: Biblioteca de dependência: Leveldbjni-all não é suportado no processador ampere.

  • Nesse caso, o projeto é especificado como uma dependência, mas não está disponível para a plataforma ampere. Um engenheiro pode ter que examinar o que está envolvido em fazer o código da compilação de dependência corretamente na plataforma de destino. Esse processo pode ser simples, mas também pode levar um tempo e esforço consideráveis. Como alternativa, você pode adaptar seu projeto para usar um pacote alternativo, fornecendo funcionalidade semelhante que suporta a arquitetura da Ampere e modifica o código do seu projeto adequadamente para usar essa alternativa.

Um exemplo de transição para C/C ++

Megahit é uma ferramenta de montagem NGS disponível como um binário para x86_64. Um cliente queria executar o Megahit no ARM64 como parte de uma transição de arquitetura. Mas a compilação falhou no ARM64 no primeiro arquivo:

O desenvolvedor queria saber o que precisava ser alterado para tornar o MegaHit compilar corretamente no ARM64.

Nesse caso, o AMPERE PORTING Advisor (APA) pode desempenhar um papel fundamental. Depois de digitalizar o repositório de origem do projeto Megahit com a APA, temos uma lista de questões que precisam ser verificadas antes de reconstruir o Megahit no ARM64:

Vamos investigar cada tipo de erro na lista e corrigi -los para o ARM64, se necessário.

Opções de construção específicas da arquitetura

Esses erros serão acionados assim que as opções de construção detectadas da APA não são válidas no ARM64.

O cmakelist.txt original está usando sinalizadores x86_64 por padrão sem verificar as arquiteturas da CPU. Para corrigir isso, podemos testar uma condição cmake_system_processor para garantir que os sinalizadores relatados pelo APA sejam aplicados apenas às arquiteturas x86_64.

Instruções específicas da arquitetura

O erro de instruções específicas da arquitetura será acionado assim que a APA detectar funções no estilo C não-ARM64 sendo usadas no código. As instruções intrínsecas são compiladas pelo compilador diretamente no código de montagem específico da plataforma e, normalmente, cada plataforma terá seu próprio conjunto de instruções intrínsecas e do código de montagem otimizadas para essa plataforma.

Nesse caso, podemos fazer o uso de condicionais de pré-processador para compilar apenas as instruções _pdep_u32/64 e __cpuid/ex quando #if definido (x86_64) é verdadeiro para as funções Haspopcnt () e Hasbmi2 (). Para VEC_VSX_LD, ele já está envolvido em um pré-processador condicional e só será compilado na arquitetura do Power PC, para que possamos deixá-lo como está.

Montagem em linha específica da arquitetura

O erro de instruções específicas da arquitetura será acionado quando o código de montagem detectado da APA sendo usado no código. Precisamos verificar se o trecho do código de montagem é para o ARM64 ou não.

O projeto Megahit usa apenas o código de montagem do BSWAP em phmap_bits.h quando está sendo compilado na arquitetura x86_64. Ao ser compilado em outras arquiteturas, ele compila uma implementação de devolução do Glibc. Portanto, nenhuma alteração é necessária em phmap_bits.h.

Em CPU_DISPATCH.H, duas funções embutidas HASPOPCNT () e HASBMI2 () incluem incondicionalmente o CPUID de instrução de montagem x86_64 para testar os recursos da CPU em x86_64. Podemos adicionar um sinalizador condicional pré -compilador #if definido (x86_64) para garantir que esse código não seja chamado no ARM64 e sempre retornaremos falsos.

Arquitetura específica SIMD intrínseca

O erro de instruções específicas da arquitetura será acionado quando a APA detectar instruções X86_64 SIMD como AVX256 ou AVX512 sendo usadas no código. Essas instruções SIMD são embrulhadas por sinalizadores condicionais pré -compiladores e geralmente não causam nenhum problema de funcionalidade no ARM64.

Se não houvesse implementação SIMD do algoritmo para o ARM64, poderia haver uma lacuna de desempenho em comparação com x86_64. Nesse caso, existe uma implementação de neon SIMD para o ARM64 em xxh3.h e essa implementação será escolhida pelo compilador com base na arquitetura da CPU. Nenhuma ação adicional precisa ser tomada.

Erro de pré -processador no AARCH64

O erro do pré-processador será acionado pela APA para indicar que a arquitetura ARM64 não pode ser incluída em um estágio pré-compilador. Nesse caso, podemos ver que o condicional pré-compile é apenas para x86_64 e não diz respeito à arquitetura ARM64.

Reconstruir e testar

Depois que todos esses ajustes forem feitos, poderíamos reconstruir o projeto:

O projeto compilou com sucesso. Em seguida, verificamos se ele passou no conjunto de testes do projeto:

Depois de verificar e corrigirmos manualmente todas as armadilhas em potencial relatadas pela APA, o Megahit agora pode construir e executar processadores de amperes.



Source link