Suporte a tamanhos de página de 16 KB

Android 过去仅支持 4 KB 内存页面大小， 优化了系统内存性能，以针对 Android 设备通常具备的功能。从 Android 15 开始，AOSP 支持 配置为使用 16 KB (16 KB) 页面大小的设备 设备）。如果您的应用使用任何 NDK 库，请直接使用 或者通过 SDK 间接创建，那么，您需要重新构建自己的应用 支持这些 16KB 设备。

随着设备制造商不断打造出 物理内存 (RAM)，许多此类设备都会采用 16KB（以及 页面大小以优化设备的性能。正在添加 支持 16 KB 页面大小的设备，可使您的应用在这些设备上运行 并有助于您的应用从相关的广告效果中获益 改进。如果不重新编译，应用可能无法在 16KB 设备上运行 在未来的 Android 版本中正式推出。

为帮助您为应用添加支持，我们提供了有关如何检查 如果您的应用受到影响 重新构建您的应用（如果适用），以及如何在 Google Play 中 使用模拟器（包括 Android 15）的 16 KB 环境 系统映像）。

Benefícios e ganhos de desempenho

配置为使用 16 KB 页面大小的设备平均会使用略多一些的内存，但系统和应用的性能也会得到各种提升：

• 缩短了系统内存压力时的应用启动时间：平均降低了 3.16%；对于我们测试的某些应用而言，改进幅度更大（最高可达 30%）
• 应用启动期间的功耗降低：平均降低了 4.56%
• 相机启动更快：热启动速度平均提高了 4.48%，冷启动速度平均提高了 6.60%
• 缩短了系统启动时间：平均缩短了 8%（约 950 毫秒）

这些改进基于我们的初始测试，实际设备上的结果可能会有所不同。随着测试的继续进行，我们将进一步分析应用的潜在收益。

Verificar se o app é afetado

如果您的应用使用了任何原生代码，则应重新构建应用以支持 16 KB 设备。如果您不确定自己的应用是否使用了原生代码，可以使用 APK 分析器确定是否存在任何原生代码，然后检查您找到的任何共享库的 ELF 段对齐情况。

如果您的应用仅使用以 Java 或 Kotlin 编程语言编写的代码（包括所有库或 SDK），则该应用已经支持 16 KB 设备。不过，我们建议您在 16 KB 环境中测试应用，以验证应用行为是否没有意外回归。

O app usa código nativo?

Seu app usa código nativo se uma das seguintes condições se aplicar:

• Seu app usa qualquer código C/C++ (nativo). Se o app usa o Android NDK, ele usa código nativo.
• O app se vincula a qualquer biblioteca nativa ou dependência de terceiros (como SDKs) que as use.
• O app é criado por um criador de apps de terceiros que usa bibliotecas nativas no dispositivo.

Identificar bibliotecas nativas usando o APK Analyzer

O APK Analyzer é uma ferramenta que permite avaliar vários aspectos de um APK criado. Para identificar se o app usa código nativo ou bibliotecas, siga estas etapas:

1. Abra o Android Studio, clique em File > Open e escolha qualquer projeto.

2. Na barra de menus, clique em Build > Analyze APK….

   

3. Escolha o APK que você quer analisar.

4. Procure na pasta lib, que hospeda arquivos de objeto compartilhado (.so), se houver. Se houver arquivos de objeto compartilhados, o app vai usar código nativo. Se nenhum arquivo de objeto compartilhado estiver presente ou se não houver uma pasta lib, o app não vai usar código nativo.

   

Verificar o alinhamento de segmentos ELF para bibliotecas compartilhadas

Para qualquer biblioteca compartilhada, verifique se os segmentos ELF dela estão alinhados corretamente usando o alinhamento ELF de 16 KB. Se você estiver desenvolvendo no Linux ou no macOS, use o script check_elf_alignment.sh, conforme descrito na próxima seção. Também é possível usar as ferramentas de linha de comando diretamente.

Use o script check_elf_alignment.sh (Linux ou macOS)

Siga estas etapas para verificar o alinhamento dos segmentos ELF usando o script check_elf_alignment.sh:

1. Salve o script check_elf_alignment.sh em um arquivo.

2. Execute o script no arquivo APK do app:

   check_elf_alignment.sh APK_NAME.apk
   

   O script gera ALIGNED ou UNALIGNED para todas as bibliotecas compartilhadas arm64-v8a.

3. Se alguma biblioteca compartilhada arm64-v8a ou x86_64 estiver UNALIGNED, será necessário atualizar o pacote dessas bibliotecas, recompilar o app e fazer o teste novamente seguindo as etapas desta seção.

Usar ferramentas de linha de comando diretamente

Siga estas etapas para verificar o alinhamento de segmentos ELF usando ferramentas de linha de comando diretamente:

1. Verifique se o Android SDK Build-Tools versão 35.0.0 ou mais recente e o Android NDK estão instalados usando o SDK Manager no Android Studio ou a ferramenta de linha de comando sdkmanager.

2. Extraia o arquivo APK do app:

   Linux ou macOS

   unzip APK_NAME.apk -d /tmp/my_apk_out
   

   Windows (PowerShell)

   Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out
   

3. No diretório temporário em que você extraiu o arquivo APK, verifique o conteúdo do diretório lib para arquivos de objeto compartilhado (.so). Esses são os mesmos arquivos de objeto compartilhados que você teria encontrado ao identificar bibliotecas nativas usando o APK Analyzer. Execute o seguinte comando em cada arquivo de objeto compartilhado:

   Linux ou macOS

   SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-objdump -p SHARED_OBJECT_FILE.so | grep LOAD
   

   Windows (PowerShell)

   SDK_ROOT_LOCATION\Android\sdk\ndk\NDK_VERSION\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-objdump.exe -p SHARED_OBJECT_FILE.so | Select-String -Pattern "LOAD"
   

   Em que SDK_ROOT_LOCATION é o caminho para o diretório em que você instalou o SDK do Android, SHARED_OBJECT_FILE é o nome do arquivo de objeto compartilhado que você está verificando e NDK_VERSION é a versão do NDK do Android que você instalou (por exemplo, 28.0.12433566). A saída vai ser semelhante à seguinte para cada arquivo verificado:

   LOAD off    0x0000000000000000 vaddr 0x0000000000000000 paddr 0x0000000000000000 align 2**14
   LOAD off    0x0000000000042a90 vaddr 0x0000000000043a90 paddr 0x0000000000043a90 align 2**14
   LOAD off    0x0000000000046230 vaddr 0x0000000000048230 paddr 0x0000000000048230 align 2**14
   

4. Verifique as linhas de saída para garantir que os segmentos de carga não tenham valores menores que 2**14. Se algum segmento de carga tiver valores 2**13, 2**12 ou menores, será necessário atualizar a embalagem dessas bibliotecas, recompilar o app e fazer o teste novamente seguindo as etapas desta seção.

5. Em seguida, execute a ferramenta de linha de comando zipalign no arquivo APK do app:

   Linux ou macOS

   SDK_ROOT_LOCATION/Android/sdk/build-tools/35.0.0/zipalign -v -c -P 16 4 APK_NAME.apk
   

   Windows (PowerShell)

   SDK_ROOT_LOCATION\Android\sdk\build-tools\35.0.0\zipalign.exe -v -c -P 16 4 APK_NAME.apk
   

   Em que SDK_ROOT_LOCATION é o caminho para o diretório em que você instalou o SDK do Android e APK_NAME é o nome do arquivo APK do app. A última linha da saída vai mostrar "Verificação concluída" se todas as bibliotecas compartilhadas estiverem alinhadas corretamente.

   Se a verificação falhar, algumas bibliotecas compartilhadas precisarão ser realinhavadas. Será necessário atualizar a embalagem dessas bibliotecas, recompilar o app e fazer o teste novamente seguindo as etapas desta seção.

Criar o app com suporte a dispositivos de 16 KB

Para oferecer suporte a dispositivos de 16 KB, os apps que usam código nativo precisam concluir as etapas descritas nas seções a seguir. Se você atualizar para a versão 8.5.1 ou mais recente do AGP e a versão r28 ou mais recente do NDK e usar dependências pré-criadas compatíveis com 16 KB, os apps serão compatíveis com 16 KB por padrão.

Atualizar o pacote das bibliotecas compartilhadas

Recomendamos que você faça upgrade para a versão 8.5.1 ou mais recente do AGP e use bibliotecas compartilhadas descompactadas.

AGP versão 8.5.1 ou mais recente

Dispositivos de 16 KB exigem que os apps que vêm com bibliotecas compartilhadas não compactadas sejam alinhados em um limite de 16 KB compactado. Para fazer isso, é necessário fazer upgrade para a versão 8.5.1 ou mais recente do Plug-in do Android para Gradle (AGP). Consulte a seção Assistente de upgrade do Plug-in do Android para Gradle para conferir detalhes sobre o processo de upgrade.

AGP versão 8.5 ou anterior

Observação: nas versões 8.3 a 8.5 do AGP, os apps são alinhados a 16 KB por padrão. No entanto, o bundletool não alinha APKs por padrão. Assim, o app pode parecer estar funcionando, mas, quando criado a partir de um pacote no Google Play, ele não é instalado.

Se não for possível fazer upgrade do AGP para a versão 8.5.1 ou mais recente, a alternativa é mudar para o uso de bibliotecas compartilhadas compactadas. Atualize a configuração do Gradle para que ele comprima as bibliotecas compartilhadas ao empacotar o app para evitar problemas de instalação do app com bibliotecas compartilhadas não alinhadas.

Groovy

No arquivo build.gradle, adicione esta opção:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging true
      }
  }
}

Kotlin

No arquivo build.gradle.kts, adicione esta opção:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging = true
      }
  }
}

Compilar o app usando o alinhamento ELF de 16 KB

Dispositivos de 16 KB exigem que os segmentos ELF das bibliotecas compartilhadas sejam alinhados corretamente usando o alinhamento ELF de 16 KB para que o app seja executado.

Observação: se o app não extrair bibliotecas nativas para o sistema de arquivos (extractNativeLibs definido como false), provavelmente você vai notar um ligeiro aumento no tamanho binário do app após a compilação usando um alinhamento ELF de 16 KB. As otimizações no gerenciador de pacotes do Android 15 anulam os custos de execução com esse aumento.

Para compilar o app usando o alinhamento ELF de 16 KB, siga as etapas de uma das seções a seguir, dependendo da versão do Android NDK que você está usando.

Importante: se o app usar bibliotecas compartilhadas pré-criadas, também será necessário recompilá-las da mesma maneira e importar novamente as bibliotecas alinhadas a 16 KB no app.

Android NDK r28 e versões mais recentes

A versão r28 e mais recentes do NDK compilam 16 KB alinhados por padrão.

Android NDK r27

Para oferecer suporte à compilação de bibliotecas compartilhadas alinhadas a 16 KB com o Android NDK versão r27 e mais recentes, atualize as flags ndk-build, build.gradle, build.gradle.kts ou de vinculação da seguinte maneira:

ndk-build

No Application.mk:

APP_SUPPORT_FLEXIBLE_PAGE_SIZES := true

Groovy

No arquivo build.gradle, defina o argumento -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON:

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
      }
    }
  }
}

Kotlin

No arquivo build.gradle.kts, defina o argumento -DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON:

android {
  ...
  defaultConfig {
    ...
    // This block is different from the one you use to link Gradle
    // to your CMake or ndk-build script.
    externalNativeBuild {
      // For ndk-build, instead use the ndkBuild block.
      cmake {
        // Passes optional arguments to CMake.
        arguments += listOf("-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON")
      }
    }
  }
}

Outros sistemas de build

Especifique as seguintes flags do vinculador:

-Wl,-z,max-page-size=16384

Android NDK r26 e versões anteriores

Para oferecer suporte à compilação de bibliotecas compartilhadas alinhadas a 16 KB com a versão r26 ou mais recente do Android NDK, atualize a configuração ndk-build ou cmake da seguinte maneira:

ndk-build

Atualize o Android.mk para ativar o alinhamento ELF de 16 KB:

LOCAL_LDFLAGS += "-Wl,-z,max-page-size=16384"

CMake

Atualize o CMakeLists.txt para ativar o alinhamento ELF de 16 KB:

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE "-Wl,-z,max-page-size=16384")

Importante: mesmo que o app se conecte dinamicamente à biblioteca padrão C++ (libc++_shared.so) do NDK r26 e versões anteriores, algumas das quais não estão alinhadas a 16 KB, é necessário atualizar o alinhamento de todas as outras bibliotecas aqui e atualizar o código para evitar a dependência de PAGE_SIZE. Para testar essas versões mais antigas do NDK em dispositivos de 16 KB, as versões canário das versões LTS do NDK r23 e r25 estão disponíveis no Android CI com bibliotecas libc++_shared.so alinhadas de 16 KB. De qualquer forma, é recomendável mudar para o Android NDK r27 ou mais recente para atualizar para a versão alinhada ELF de 16 KB da biblioteca padrão C++. Caso contrário, o app não será instalado em dispositivos de 16 KB.

Se não for possível migrar para o NDK do Android mais recente, você poderá atualizar o app para compilar estaticamente a biblioteca padrão C++ na biblioteca compartilhada. Consulte a seção Suporte para a biblioteca C++ para saber mais sobre o vínculo estático com a biblioteca C++ padrão e leia a seção Considerações importantes.

Verificar instâncias de código que fazem referência a tamanhos de página específicos

Mesmo que o app esteja alinhado a 16 KB, ele pode encontrar erros se lugares no código presumirem que um dispositivo está usando um tamanho de página específico. Para evitar isso, siga estas etapas:

1. Remova todas as dependências codificadas que fazem referência à constante PAGE_SIZE ou instâncias na lógica do código que presumem que o tamanho da página de um dispositivo é de 4 KB (4096).

   Use getpagesize() ou sysconf(_SC_PAGESIZE).

2. Procure usos de mmap() e outras APIs que exigem argumentos alinhados à página e substitua por alternativas quando necessário.

Em alguns casos, se o app usar PAGE_SIZE como um valor conveniente que não esteja vinculado ao tamanho da página, ele não será interrompido quando usado no modo de 16 KB. No entanto, se esse valor for transmitido ao kernel com mmap sem MAP_FIXED, o kernel ainda usará uma página inteira, o que desperdiça parte da memória. Por esses motivos, PAGE_SIZE é indefinido quando o modo de 16 KB é ativado no NDK r27 e versões mais recentes.

Se o app usar PAGE_SIZE dessa maneira e nunca transmitir esse valor diretamente ao kernel, em vez de usar PAGE_SIZE, crie uma nova variável com um novo nome para refletir que ela é usada para outros fins e não reflete uma página de memória real.

Verificar o suporte a 16 KB nos SDKs

Muitos SDKs são compatíveis com tamanhos de página de 16 KB, principalmente se você os criou ou recebeu pré-criações recentes. No entanto, como alguns SDKs pré-criados ou versões de SDK não são compatíveis com 16 KB, verifique o site de cada provedor de SDK para determinar qual versão usar com 16 KB.

Testar o app em um ambiente de 16 KB

Depois de criar o app com suporte a dispositivos de 16 KB, teste o app em um ambiente de 16 KB para saber se ele tem algumas regressões. Para isso, siga estas etapas:

1. Configure o SDK do Android 15.

2. Configure um dos seguintes ambientes de teste:

   • Configurar o Android Emulator com uma imagem do sistema Android 15 baseada em 16 KB
   • Ativar o modo de 16 KB em um dispositivo usando as opções do desenvolvedor
   • Usar o Cuttlefish com tamanho de página de 16 KB no ARM64
   • Simulação do Cuttlefish com tamanho de página de 16 KB no x86-64

3. Inicie o dispositivo de teste e execute o comando abaixo para verificar se ele está usando um ambiente de 16 KB:

   adb shell getconf PAGE_SIZE
   

   O comando precisa retornar um valor de 16384.

4. Execute o comando zipalign abaixo para verificar se o app está alinhado a 16 KB, em que APK_NAME é o nome do arquivo APK do app:

   zipalign -c -P 16 -v 4 APK_NAME.apk
   

5. Teste seu app de forma abrangente, focando nas áreas que podem ser afetadas por mudanças nas instâncias de código que fazem referência a tamanhos de página específicos.

Configurar o Android Emulator com uma imagem do sistema Android 15 baseada em 16 KB

Importante: há um problema conhecido que impede a depuração com o LLDB com imagens do sistema do emulador de 16 KB. Uma correção para esse problema está incluída no NDK r27 RC 1 e na atualização de recursos do Android Studio Koala | 2024.1.2 Canary 5.

Para configurar um ambiente de 16 KB usando o emulador do Android, siga estas etapas:

1. As imagens de sistema do emulador do Android 15 com base em 16 KB são compatíveis com o Android Studio Jellyfish | 2023.3.1 ou mais recente. No entanto, para ter a melhor experiência ao trabalhar com o Android 15 Beta, faça o download da versão de pré-lançamento mais recente do Android Studio.

   Lembre-se de que você pode manter a versão atual do Android Studio instalada, já que é possível instalar diversas versões lado a lado.

2. No Android Studio, clique em Tools > SDK Manager.

3. Na guia SDK Platforms, marque Show Package Details, expanda a seção Android VanillaIceCream Preview e selecione uma ou ambas as seguintes imagens do sistema do emulador, dependendo dos dispositivos virtuais que você quer criar:

   • Imagem do sistema experimental de 16 KB de tamanho de página das APIs do Google ARM 64 v8a
   • Google APIs Experimental 16k Page Size Intel x86_64 Atom System Image
   Observação: se você planeja emular um dispositivo Google Pixel compatível, você só vai precisar da imagem do sistema ARM 64 v8a.

   

4. Clique em Aplicar > OK para fazer o download das imagens do sistema selecionadas.

5. Siga as etapas para configurar um dispositivo virtual para o Android 15 e, quando solicitado, selecione a imagem do sistema de 16 KB que você fez o download. Se ela não for recomendada automaticamente, você pode encontrar a imagem do sistema de 16 KB na guia Outras imagens.

   

Aviso: para simular um ambiente de 16 KB em sistemas x86_64, também é necessário concluir as etapas a seguir. Essas etapas são temporárias e serão removidas no futuro.

1. No Gerenciador de dispositivos, clique nos três pontos ao lado da imagem de 16 KB e em Mostrar no disco.
2. Nessa pasta, encontre o arquivo config.ini.

3. Adicione a seguinte linha ao arquivo config.ini e salve as alterações:

   kernel.parameters = androidboot.page_shift=14
   

4. Para verificar as mudanças, execute o comando a seguir, que deve retornar 16384:

   adb shell getconf PAGE_SIZE
   

Ativar o modo de 16 KB em um dispositivo usando as opções do desenvolvedor

Ative ou desative a opção de desenvolvedor Inicialização com tamanho de página de 16 KB a opção de inicializar um dispositivo no modo de 16 KB.

A partir do QPR1 do Android 15, é possível usar a opção do desenvolvedor que está disponível em determinados inicialize o dispositivo no modo de 16 KB e faça testes no dispositivo.

Essa opção para desenvolvedores está disponível nos seguintes dispositivos:

• Pixel 8 e 8 Pro (com o QPR1 Beta 1 ou mais recente do Android 15)

Observação: o Android 15 QPR1 está na versão Beta. Para mais informações sobre como instalar o QPR1 em um dispositivo qualificado, consulte Instalar os builds Beta do QPR do Android 15 .