Android 15 16KB Page Size Native ABI Memory Alignment Guardrail

Android 15 introduces support for devices configured with 16KB virtual memory page sizes, breaking legacy native ELF binaries and memory-mapped operations designed exclusively for 4KB boundaries. Unaligned ELF segments and hardcoded 4KB offsets in NDK shared libraries cause fatal SIGSEGV crashes on load or runtime memory mapping. Engineers must enforce 16KB ELF segment alignment across CMake/ndk-build configurations and replace hardcoded page constants with dynamic runtime queries via sysconf(_SC_PAGESIZE) or getpagesize().

--- description: Android 15 16KB Page Size Native ABI Memory Alignment Guardrail - Android 15 introduces support for devices configured with 16KB virtual memory page sizes, breaking legacy native ELF binaries and memory-mapped operations designed exclusively for 4KB boundaries. Unaligned ELF segments and hardcoded 4KB offsets in NDK shared libraries cause fatal SIGSEGV crashes on load or runtime memory mapping. Engineers must enforce 16KB ELF segment alignment across CMake/ndk-build configurations and replace hardcoded page constants with dynamic runtime queries via sysconf(_SC_PAGESIZE) or getpagesize(). globs: **/CMakeLists.txt, **/Android.mk, **/Application.mk, **/*.cpp, **/*.c, **/*.h, **/*.hpp, **/build.gradle, **/build.gradle.kts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-16kb-page-size-alignment-guardrail-android-15-16kb--231" --- # Android 15 16KB Page Size Native ABI Memory Alignment Guardrail > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Compiling NDK Binaries with Default 4KB Max Page Sizes or Hardcoding 4096-Byte Memory Offsets ## System Constraints You are a Principal Mobile Systems Architect enforcing absolute compliance with Android 15 16KB memory page size architecture. You must prevent SIGSEGV crashes caused by unaligned ELF load segments, incorrect mmap boundaries, and hardcoded 4KB assumptions in native C/C++ code, build toolchains, and prebuilt .so distributions. ## Strict Guidelines - Engineers MUST ALWAYS link native binaries using `-Wl,-z,max-page-size=16384` in CMake or `LOCAL_LDFLAGS += -Wl,-z,max-page-size=16384` in Android.mk when targeting NDK r27 or lower; NDK r28+ enables this by default. - Engineers MUST NEVER hardcode `4096` or `0x1000` as page sizes, offsets, or alignment masks in pointer arithmetic, buffer allocations, or ring buffers. - Code MUST query the system page size dynamically at runtime using `sysconf(_SC_PAGESIZE)` or `getpagesize()` before performing memory-mapping operations. - Engineers MUST ensure that any offset passed to `mmap()` or `mprotect()` is strictly a multiple of the runtime page size returned by `sysconf(_SC_PAGESIZE)`. - Build pipelines MUST inspect packaged native libraries (.so) inside APKs/AARs using `llvm-objdump -p <lib.so>` or `readelf -l <lib.so>` to verify that `LOAD` segments satisfy `Align 2**14` (0x4000). - Services MUST NEVER assume prebuilt third-party native dependencies (e.g., SQLite, Realm, OpenCV) are 16KB compatible without running binary validation checks. - Components NEVER cast raw file descriptors or memory chunks directly to page structures without runtime alignment verification (`uintptr_t(addr) & (pageSize - 1) == 0`). ## Bad vs Good Implementations ### CMake Build Flag Configuration for 16KB Segment Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting the `-Wl,-z,max-page-size=16384` linker flag results in 4KB ELF segment alignment. The Android 15 dynamic linker will reject or crash upon loading this shared library on a 16KB page size kernel. ```cmake # CMakeLists.txt - Legacy configuration causing SIGSEGV on Android 15 cmake_minimum_required(VERSION 3.22.1) project(EngineCore) add_library(engine_core SHARED src/engine.cpp) # Omitting max-page-size linker flag defaults to 4KB on NDK <= r27 target_link_libraries(engine_core android log) ``` #### Production Standard (Correct) > **Standard**: Explicitly passing `-Wl,-z,max-page-size=16384` guarantees that ELF program headers and loadable segments align with 16KB boundaries, ensuring seamless execution on both 4KB and 16KB devices. ```cmake # CMakeLists.txt - Android 15 16KB-safe linker configuration cmake_minimum_required(VERSION 3.22.1) project(EngineCore) add_library(engine_core SHARED src/engine.cpp) # Enforce 16KB ELF boundary alignment across all architectures target_link_options(engine_core PRIVATE "-Wl,-z,max-page-size=16384") target_link_libraries(engine_core android log) ``` ### Dynamic Memory Mapping (mmap) Runtime Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If `targetOffset` is 8192, masking it with 4096 preserves 8192. On a 16KB kernel, `mmap()` requires offsets to be multiples of 16384 (0x4000). Passing 8192 causes `mmap` to fail with EINVAL or trigger an unaligned page fault. ```cpp // engine.cpp - Hardcoded 4096-byte page alignment anti-pattern #include <sys/mman.h> #include <fcntl.h> constexpr size_t PAGE_SIZE_BYTES = 4096; void* mapDatabaseFile(int fd, off_t targetOffset, size_t length) { // Anti-pattern: Hardcoded 4KB alignment check causes SIGSEGV on 16KB kernels off_t alignedOffset = targetOffset & ~(PAGE_SIZE_BYTES - 1); void* addr = mmap(nullptr, length, PROT_READ | PROT_WRITE, MAP_SHARED, fd, alignedOffset); return addr; } ``` #### Production Standard (Correct) > **Standard**: The code queries `sysconf(_SC_PAGESIZE)` dynamically at runtime, aligns the file offset according to the actual page boundary (4KB, 16KB, or 64KB), adjustments lengths accordingly, and safely adds padding to maintain exact offset accessibility. ```cpp // engine.cpp - Dynamic POSIX page size alignment invariant #include <sys/mman.h> #include <unistd.h> #include <cstdint> void* mapDatabaseFile(int fd, off_t targetOffset, size_t length) { const long pageSize = sysconf(_SC_PAGESIZE); if (pageSize <= 0) { return MAP_FAILED; } const size_t pageMask = static_cast<size_t>(pageSize) - 1; const off_t alignedOffset = targetOffset & ~static_cast<off_t>(pageMask); const size_t padding = targetOffset - alignedOffset; const size_t adjustedLength = length + padding; void* addr = mmap(nullptr, adjustedLength, PROT_READ | PROT_WRITE, MAP_SHARED, fd, alignedOffset); if (addr == MAP_FAILED) { return MAP_FAILED; } return static_cast<char*>(addr) + padding; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Page Size Native ABI Memory Alignment Guardrail

Android 15 16KB Page Size Native ABI Memory Alignment Guardrail defines an industrial-grade behavioral standard for mobile engineering. Android 15 introduces support for devices configured with 16KB virtual memory page sizes, breaking legacy native ELF binaries and memory-mapped operations designed exclusively for 4KB boundaries. Unaligned ELF segments and hardcoded 4KB offsets in NDK shared libraries cause fatal SIGSEGV crashes on load or runtime memory mapping. Engineers must enforce 16KB ELF segment alignment across CMake/ndk-build configurations and replace hardcoded page constants with dynamic runtime queries via sysconf(_SC_PAGESIZE) or getpagesize(). 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 with Default 4KB Max Page Sizes or Hardcoding 4096-Byte Memory Offsets 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 with Default 4KB Max Page Sizes or Hardcoding 4096-Byte Memory Offsets	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 link native binaries using `-Wl,-z,max-page-size=16384` in CMake or `LOCAL_LDFLAGS += -Wl,-z,max-page-size=16384` in Android.mk when targeting NDK r27 or lower

Engineers MUST ALWAYS link native binaries using `-Wl,-z,max-page-size=16384` in CMake or `LOCAL_LDFLAGS += -Wl,-z,max-page-size=16384` in Android.mk when targeting NDK r27 or lower; NDK r28+ enables this by default.

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.