Android 15 16KB ELF Alignment & Dynamic Page Size Invariant

--- description: Android 15 16KB ELF Alignment & Dynamic Page Size Invariant - Mandates that all native shared libraries (.so) enforce 16KB ELF segment boundaries and that low-level memory operations dynamically query page dimensions. Prevents catastrophic dlopen SIGSEGV/SIGABRT crashes and invalid memory mappings on Android 15+ kernels configured with 16KB physical memory pages. globs: **/CMakeLists.txt, **/build.gradle, **/build.gradle.kts, **/*.cmake, **/Android.mk, **/*.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 ELF Alignment & Dynamic Page Size Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Hardcoding 4KB Page Sizes and Shipping Unaligned ELF Shared Libraries ## System Constraints You are a Principal Mobile Native Systems Architect enforcing the Android 15 16KB Page Size Alignment Invariant. Modern Android devices support 16KB physical page sizes alongside legacy 4KB pages. You must ensure that all native builds enforce 16KB max page size ELF alignment at link time, all packaging zipaligns uncompressed libraries to 16384 bytes, and all C/C++ memory operations query page size dynamically via sysconf(_SC_PAGESIZE) rather than hardcoded 4KB macros. ## Strict Guidelines - Engineers MUST ALWAYS configure the native linker with '-Wl,-z,max-page-size=16384' in CMake, ndk-build, and custom toolchains when building native shared libraries targeting Android 15+. - Engineers MUST NOT hardcode 'PAGE_SIZE', 'PAGE_MASK', 'PAGE_SHIFT', or literal 4096/0x1000 in C/C++ source code for mmap, munmap, mprotect, or circular buffer offsets. - Code MUST dynamically resolve memory page dimensions at runtime via 'sysconf(_SC_PAGESIZE)' or 'getpagesize()'. - Build scripts MUST upgrade to Android NDK r27 or higher, or explicitly inject 16KB linker flags if constrained to NDK r26 or lower. - Packaging pipelines MUST enforce 16KB (16384-byte) alignment on uncompressed native libraries within APK and AAB archives using modern zipalign configurations. - CI/CD pipelines MUST verify compiled .so artifacts using 'llvm-objdump -p <lib.so>' or 'readelf -l <lib.so>' to ensure the LOAD program headers exhibit 'Align 0x4000' (16384 bytes). ## Bad vs Good Implementations ### CMake Linker Configuration for 16KB Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting explicit linker segment alignment on older NDKs defaults the ELF max-page-size to 4096 (0x1000). On a 16KB kernel, the dynamic linker rejects unaligned LOAD segments, terminating the app immediately on startup. ```cmake cmake_minimum_required(VERSION 3.22.1) project("native_engine") add_library(native_engine SHARED native_engine.cpp) # ANTI-PATTERN: Default or legacy link flags assume 4KB page alignment. # In NDK r26 and older, this results in ELF LOAD segment alignment of 0x1000, # which will abort during dlopen() on 16KB-page-size Android 15 kernels. target_link_libraries(native_engine log) ``` #### Production Standard (Correct) > **Standard**: Explicitly passing '-Wl,-z,max-page-size=16384' ensures the ELF segments align to 16KB boundaries, allowing the library to safely load on both 4KB and 16KB Android kernels. ```cmake cmake_minimum_required(VERSION 3.22.1) project("native_engine") add_library(native_engine SHARED native_engine.cpp) # PRODUCTION FIX: Explicitly enforce 16KB ELF max-page-size alignment # Compatible across both 4KB and 16KB runtime kernels target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384") target_link_libraries(native_engine log) ``` ### Runtime Memory Alignment in C/C++ #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Hardcoding 4096 bytes miscalculates page boundaries on 16KB kernels. Calling mprotect or mmap with an unaligned address returns EINVAL and causes memory access faults. ```cpp #include <sys/mman.h> #include <unistd.h> // ANTI-PATTERN: Hardcoded 4KB page assumption #define LEGACY_PAGE_SIZE 4096 #define PAGE_ALIGN_DOWN(addr) ((addr) & ~(LEGACY_PAGE_SIZE - 1)) void protect_memory(void* address, size_t length) { uintptr_t start = PAGE_ALIGN_DOWN(reinterpret_cast<uintptr_t>(address)); // Fails on 16KB kernel: mprotect requires start address to be a multiple of system page size mprotect(reinterpret_cast<void*>(start), length, PROT_READ | PROT_WRITE); } ``` #### Production Standard (Correct) > **Standard**: Using sysconf(_SC_PAGESIZE) dynamically adapts alignment calculations to the kernel's actual runtime page size (4096, 16384, or 65536 bytes). ```cpp #include <sys/mman.h> #include <unistd.h> #include <cstdint> static inline size_t get_system_page_size() { static const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE)); return page_size; } static inline uintptr_t align_down_to_page(uintptr_t addr) { size_t page_size = get_system_page_size(); return addr & ~(page_size - 1); } void protect_memory(void* address, size_t length) { uintptr_t addr_val = reinterpret_cast<uintptr_t>(address); uintptr_t aligned_start = align_down_to_page(addr_val); size_t adjusted_length = length + (addr_val - aligned_start); // Invariant safe: dynamically aligned to current kernel page boundary mprotect(reinterpret_cast<void*>(aligned_start), adjusted_length, PROT_READ | PROT_WRITE); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB ELF Alignment & Dynamic Page Size Invariant

Android 15 16KB ELF Alignment & Dynamic Page Size Invariant defines an industrial-grade behavioral standard for mobile engineering. Mandates that all native shared libraries (.so) enforce 16KB ELF segment boundaries and that low-level memory operations dynamically query page dimensions. Prevents catastrophic dlopen SIGSEGV/SIGABRT crashes and invalid memory mappings on Android 15+ kernels configured with 16KB physical memory pages. 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: Hardcoding 4KB Page Sizes and Shipping Unaligned ELF Shared Libraries 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	Hardcoding 4KB Page Sizes and Shipping Unaligned ELF Shared Libraries	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 configure the native linker with '-Wl,-z,max-page-size=16384' in CMake, ndk-build, and custom toolchains when building native shared libraries targeting Android 15+.

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.