Android 15 16KB Page-Size Native ABI & Memory-Mapping Invariant

--- description: Android 15 16KB Page-Size Native ABI & Memory-Mapping Invariant - Enforces 16KB ELF alignment for all native C/C++ shared libraries and dynamic runtimes to ensure compatibility with Android 15 page-agnostic kernels. Mandates dynamic page size querying via sysconf(_SC_PAGESIZE) or getpagesize() rather than hardcoded 4096-byte constants during native memory allocations (mmap/posix_memalign) and JNI transfers to prevent silent memory corruption and fatal SIGSEGV faults. globs: **/CMakeLists.txt, **/*.cmake, **/Android.mk, **/*.cpp, **/*.cc, **/*.h, **/*.c, **/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-standard" --- # Android 15 16KB Page-Size Native ABI & Memory-Mapping Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Hardcoded 4KB Page Assumptions and 4KB-Aligned ELF Segments Causing SIGSEGV Crashes on Android 15 Devices ## System Constraints You are a Principal Mobile Systems Architect and NDK Security Engineer enforcing strict compliance with Android 15 16KB page-size execution standards. You must ensure all ELF binaries, C++ memory primitives, JNI mappings, and Kotlin Multiplatform Native link steps adhere to max-page-size=16384 linker boundaries and dynamically query kernel page sizes instead of assuming 4KB. ## Strict Guidelines - Engineers MUST ALWAYS pass '-Wl,-z,max-page-size=16384' to native linker flags in CMakeLists.txt and Android.mk across all target ABIs (arm64-v8a, x86_64). - Engineers MUST NEVER hardcode 4096, 0x1000, 12-bit shift operations (PAGE_SHIFT = 12), or PAGE_SIZE macros for memory allocation, buffer offsets, or custom memory allocators. - Engineers MUST dynamically query page sizes at runtime using 'sysconf(_SC_PAGESIZE)' or 'getpagesize()' before invoking 'mmap', 'mprotect', 'madvise', or 'posix_memalign'. - Components NEVER bundle pre-built third-party shared libraries (.so) without verifying ELF segment alignment using 'readelf -lW <library.so> | grep LOAD' showing 0x4000 (16KB) or 0x10000 (64KB) alignments. - Build scripts MUST update NDK to revision r27 or higher, or explicitly configure 16KB page-size support in Gradle packagingOptions and cmake arguments. ## Bad vs Good Implementations ### CMake Native Linker Configuration for 16KB Page Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default linker settings in NDK r26 and older align ELF segments to 4KB (0x1000) boundaries, causing Android 15 dynamic linkers to reject execution with fatal ELF alignment SIGSEGV errors. ```cmake cmake_minimum_required(VERSION 3.22.1) project(native_engine) add_library(native_engine SHARED engine.cpp) # Flaw: Relies on default NDK 4KB max-page-size linker alignment target_link_libraries(native_engine log) ``` #### Production Standard (Correct) > **Standard**: Configuring -Wl,-z,max-page-size=16384 ensures that ELF program headers (LOAD segments) align with 16KB memory virtual addresses without breaking 4KB backwards compatibility. ```cmake cmake_minimum_required(VERSION 3.22.1) project(native_engine) add_library(native_engine SHARED engine.cpp) # Enforce 16KB ELF segment alignment across 64-bit architectures if(ANDROID_ABI MATCHES "arm64-v8a|x86_64") target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384") endif() target_link_libraries(native_engine log) ``` ### Dynamic Page Size Native Allocation via sysconf #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Hardcoding PAGE_SIZE to 4096 causes misaligned mmap/mprotect boundaries when executed on a 16KB-paged device, yielding EINVAL or memory corruption. ```cpp #include <sys/mman.h> #include <unistd.h> #define PAGE_SIZE 4096 void* allocate_page_aligned_buffer(size_t size) { // Flaw: Hardcoded 4096 bytes page alignment assumption size_t aligned_size = (size + PAGE_SIZE - 1) & ~(PAGE_SIZE - 1); void* ptr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 0); return ptr; } ``` #### Production Standard (Correct) > **Standard**: sysconf(_SC_PAGESIZE) dynamically adapts to runtime hardware page sizes (4KB or 16KB), ensuring correct mmap offset alignment and memory boundary protection. ```cpp #include <sys/mman.h> #include <unistd.h> #include <cstdint> void* allocate_page_aligned_buffer(size_t size) { // Dynamically retrieve system page size via POSIX runtime call const size_t pageSize = static_cast<size_t>(sysconf(_SC_PAGESIZE)); size_t aligned_size = (size + pageSize - 1) & ~(pageSize - 1); void* ptr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 0); if (ptr == MAP_FAILED) { return nullptr; } return ptr; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Page-Size Native ABI & Memory-Mapping Invariant

Android 15 16KB Page-Size Native ABI & Memory-Mapping Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces 16KB ELF alignment for all native C/C++ shared libraries and dynamic runtimes to ensure compatibility with Android 15 page-agnostic kernels. Mandates dynamic page size querying via sysconf(_SC_PAGESIZE) or getpagesize() rather than hardcoded 4096-byte constants during native memory allocations (mmap/posix_memalign) and JNI transfers to prevent silent memory corruption and fatal SIGSEGV faults. 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: Hardcoded 4KB Page Assumptions and 4KB-Aligned ELF Segments Causing SIGSEGV Crashes on Android 15 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	Hardcoded 4KB Page Assumptions and 4KB-Aligned ELF Segments Causing SIGSEGV Crashes on Android 15 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' to native linker flags in CMakeLists.txt and Android.mk across all target ABIs (arm64-v8a, x86_64).

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.