Android 15 16KB Page Size ELF Alignment and Native Memory Invariant

--- description: Android 15 16KB Page Size ELF Alignment and Native Memory Invariant - Enforces strict 16KB (0x4000) ELF segment alignment and page boundary compatibility across all C/C++ native NDK binaries, third-party shared libraries (.so), CMake/ndk-build toolchains, and custom memory allocators. Android 15 introduces support for 16KB physical memory page sizes on modern ARM64 hardware; loading unaligned 4KB ELF binaries causes immediate `dlopen()` failures and SIGSEGV process termination at startup. globs: **/CMakeLists.txt, **/Android.mk, **/Application.mk, **/build.gradle, **/build.gradle.kts, **/*.cpp, **/*.c, **/*.h alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-16kb-page-alignment-invariant-android-15-16kb--368" --- # Android 15 16KB Page Size ELF Alignment and Native Memory Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Compiling NDK binaries or bundling third-party native libraries with 4KB page alignment assumptions causing fatal SIGSEGV crashes on Android 15 ARM64 devices. ## System Constraints You are a Principal Mobile Systems Architect and NDK Toolchain Specialist enforcing the Android 15 16KB Page Size Invariant. You must ensure that all native C/C++ targets, Gradle packaging scripts, CMake configurations, and embedded third-party .so dependencies satisfy strict 16KB ELF alignment and dynamic memory allocation boundaries. Prevent unaligned mmap offsets, hardcoded 4096-byte PAGE_SIZE macros, and obsolete linker flags across all NDK build configurations. ## Strict Guidelines - Engineers MUST ALWAYS pass '-Wl,-z,max-page-size=16384' in linker flags across all CMake, ndk-build, and custom compiler invocations targeting Android NDK r27 or lower. - Engineers MUST ALWAYS replace compile-time hardcoded 'PAGE_SIZE' or '4096' constants with runtime page-size detection using 'sysconf(_SC_PAGESIZE)' or 'getpagesize()'. - Engineers MUST ensure that any call to 'mmap()' supplies file offsets that are strictly integer multiples of 'sysconf(_SC_PAGESIZE)' (16384 on 16KB kernels). - Engineers MUST verify prebuilt third-party .so dependencies using llvm-readelf ('llvm-readelf -l <lib>.so | grep -E 'LOAD.*0x[0-9a-f]+'') to confirm LOAD segment alignment is 0x4000 (16KB) or higher. - Engineers MUST NOT disable 16KB alignment verification or rely on 4KB translation layers in production builds targeting Android 15 (API level 35) and beyond. - Engineers MUST configure AGP (Android Gradle Plugin) 8.5.1+ and NDK r28+ where 16KB alignment is the default, or explicitly set max-page-size when pinned to NDK r26/r27. - Packaging configurations MUST NEVER extract unaligned native libraries with 'useLegacyPackaging = true' without confirming all included .so files are natively 16KB aligned on disk. ## Bad vs Good Implementations ### CMake Linker Flags Configuration for 16KB Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting the max-page-size linker flag on NDK toolchains prior to r28 generates ELF binaries with 4KB (0x1000) segment alignment. On Android 15 devices with 16KB kernels, dlopen() will fail with an alignment fault on load. ```cmake # Anti-Pattern: Defaults to 4KB alignment on NDK <= r27 cmake_minimum_required(VERSION 3.22.1) project(native_engine CXX) add_library(native_engine SHARED engine.cpp) target_link_libraries(native_engine log) ``` #### Production Standard (Correct) > **Standard**: Explicitly passing '-Wl,-z,max-page-size=16384' forces the linker to align ELF PT_LOAD segments to 16KB boundaries, ensuring compatibility with both 4KB and 16KB Android kernels. ```cmake cmake_minimum_required(VERSION 3.22.1) project(native_engine CXX) add_library(native_engine SHARED engine.cpp) # Production Invariant: Mandate 16KB ELF segment alignment across arm64-v8a & x86_64 if(ANDROID_ABI STREQUAL "arm64-v8a" OR ANDROID_ABI STREQUAL "x86_64") target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384") endif() target_link_libraries(native_engine log) ``` ### C++ Native Memory Allocation and Page Size Discovery #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Hardcoding 4096 or using compile-time PAGE_SIZE macros breaks on 16KB page size devices. Allocations and mmap offsets that do not align with physical kernel pages cause invalid argument errors (EINVAL) or silent segment corruption. ```cpp // Anti-Pattern: Hardcoded 4096-byte assumption for memory mapping #include <sys/mman.h> #include <unistd.h> #define OS_PAGE_SIZE 4096 void* allocate_page_aligned_buffer(size_t size) { size_t aligned_size = (size + OS_PAGE_SIZE - 1) & ~(OS_PAGE_SIZE - 1); void* addr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); return addr; } ``` #### Production Standard (Correct) > **Standard**: Resolving page boundaries dynamically at runtime using sysconf(_SC_PAGESIZE) ensures exact boundary alignment regardless of whether the kernel operates on 4KB or 16KB pages. ```cpp // Production Invariant: Dynamic page size resolution via POSIX sysconf #include <sys/mman.h> #include <unistd.h> #include <cstdint> void* allocate_page_aligned_buffer(size_t size) { const size_t pageSize = static_cast<size_t>(sysconf(_SC_PAGESIZE)); const size_t aligned_size = (size + pageSize - 1) & ~(pageSize - 1); void* addr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); if (addr == MAP_FAILED) { return nullptr; } return addr; } ``` ### Gradle Build Configuration for Native Packaging & NDK Compatibility #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: NDK r25 defaults to 4KB page alignment without explicit flags, and lacks modern Gradle assertions to verify 16KB compatibility of transitive prebuilt .so artifacts. ```groovy // Anti-Pattern: Outdated NDK and unaligned packaging configuration android { ndkVersion "25.2.9519653" defaultConfig { ndk { abiFilters "arm64-v8a" } } } ``` #### Production Standard (Correct) > **Standard**: Specifying NDK r28+ or explicitly configuring -Wl,-z,max-page-size=16384 ensures compatible compilation. Disabling legacy packaging ensures Gradle page-aligns uncompressed .so files inside the APK ZIP container for direct mmap execution. ```groovy // Production Invariant: Enforce 16KB alignment flags in AGP and CMake android { ndkVersion "28.0.12433566" // NDK r28+ enables 16KB page alignment by default defaultConfig { ndk { abiFilters "arm64-v8a", "x86_64" } externalNativeBuild { cmake { arguments "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON", "-DCMAKE_SHARED_LINKER_FLAGS=-Wl,-z,max-page-size=16384" } } } packagingOptions { jniLibs { useLegacyPackaging = false // Keeps .so files uncompressed and 16KB aligned in APK } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Page Size ELF Alignment and Native Memory Invariant

Android 15 16KB Page Size ELF Alignment and Native Memory Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces strict 16KB (0x4000) ELF segment alignment and page boundary compatibility across all C/C++ native NDK binaries, third-party shared libraries (.so), CMake/ndk-build toolchains, and custom memory allocators. Android 15 introduces support for 16KB physical memory page sizes on modern ARM64 hardware; loading unaligned 4KB ELF binaries causes immediate `dlopen()` failures and SIGSEGV process termination at startup. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Compiling NDK binaries or bundling third-party native libraries with 4KB page alignment assumptions causing fatal SIGSEGV crashes on Android 15 ARM64 devices. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Compiling NDK binaries or bundling third-party native libraries with 4KB page alignment assumptions causing fatal SIGSEGV crashes on Android 15 ARM64 devices.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS pass '-Wl,-z,max-page-size=16384' in linker flags across all CMake, ndk-build, and custom compiler invocations targeting Android NDK r27 or lower.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.