16 KB page size

Page size is the granularity at which an OS manages memory. Most CPUs today support a 4 KB page size and so the Android OS and apps have historically been built and optimized to run with a 4 KB page size. ARM CPUs support the larger 16 KB page size, and starting in Android 15, AOSP has support for building Android with a 16 KB page size as well. This option uses additional memory but improves system performance. As of Android 15, this option isn't enabled by default, but it is available as a developer mode or a developer option for OEMs and app developers to prepare for switching to 16 KB mode everywhere in the future.

Enable 16 KB page size

16 KB pages are only supported on arm64 targets with 16 KB kernels. However, there is also an option to simulate 16 KB userspace on x86_64 for Cuttlefish.

For arm64 targets, if you use Kleaf to build your kernel, --page_size=16k builds the kernel in 16 KB mode. If you are directly using Linux kernel configuration, you can select 16 KB pages by setting CONFIG_ARM64_16K_PAGES instead of CONFIG_ARM64_4K_PAGES.

To enable 16 KB page size support in Android userspace, set the following build options on your product:

  • PRODUCT_NO_BIONIC_PAGE_SIZE_MACRO := true removes the PAGE_SIZE define, and it makes components determine page size at runtime.
  • PRODUCT_MAX_PAGE_SIZE_SUPPORTED := 16384 which ensures platform ELF files are built with 16 KB alignment. This larger-than-needed size is for future compatibility. With 16 KB ELF alignment, the kernel can support 4 KB/16 KB page sizes.

Verify build flags

After selecting the lunch target, verify that the build flags are set up correctly in the environment:

$ source build/envsetup.sh
$ lunch target

$ get_build_var TARGET_MAX_PAGE_SIZE_SUPPORTED
16384
$ get_build_var TARGET_NO_BIONIC_PAGE_SIZE_MACRO
true

If the previous two commands return 16384 and true respectively, your build flags are set up correctly.

Build shared libraries with 16 KB ELF alignment

To build shared libraries that are part of the android project, the earlier settings in Enable 16 KB page size are sufficient:

  • PRODUCT_NO_BIONIC_PAGE_SIZE_MACRO := true
  • PRODUCT_MAX_PAGE_SIZE_SUPPORTED := 16384

To build shared libraries that aren't part of android project, you need to pass this linker flag:

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

Verify binaries and prebuilts for 16 KB ELF alignment

The best way to verify alignment and runtime behavior is to test and run on a 16 KB compiled kernel. However, in order to catch some issues earlier:

  • Starting in Android W (AOSP experimental), you can set PRODUCT_CHECK_PREBUILT_MAX_PAGE_SIZE := true at build time. Use ignore_max_page_size: true in Android.bp and LOCAL_IGNORE_MAX_PAGE_SIZE := true in Android.mk to temporarily ignore them. These settings verify all prebuilts and allow you to detect when one is updated but is not 16 KB aligned.

  • You can run atest elf_alignment_test which verifies the alignment of on-device ELF files on devices launching with Android 15 and later.