Android 15 16KB Page Alignment NDK Memory Boundary Invariant

--- description: Android 15 16KB Page Alignment NDK Memory Boundary Invariant - Mandates strict 16KB (0x4000) ELF segment alignment across all compiled native C/C++ mobile shared libraries (.so) and build scripts targeting Android 15 (API level 35) and beyond. Failure to align ELF load segments to 16KB boundaries results in dynamic linker (linker64) aborts and fatal SIGSEGV/SIGBUS page fault panics when loaded into 16KB page size kernel runtimes on modern ARM64 hardware. globs: **/CMakeLists.txt, **/Android.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-ndk-memory-boundary-invariant" --- # Android 15 16KB Page Alignment NDK Memory Boundary Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Shipping 4KB-Aligned Native Binaries or Unaligned Custom Memory Mappings to 16KB Page-Size Devices ## System Constraints You are a Principal Mobile Systems Architect enforcing the Android 15 16KB Page Alignment NDK Memory Boundary Invariant. You must reject any native build configuration or low-level memory allocation logic that assumes a fixed 4KB (4096-byte) system page size. Ensure all native dynamic libraries (.so) link with -Wl,-z,max-page-size=16384, CMake toolchains target 16KB boundaries, and all POSIX memory-mapped operations (mmap, mprotect, munmap) query runtime page sizes dynamically via sysconf(_SC_PAGESIZE) or getpagesize() rather than using compile-time PAGE_SIZE macros. ## Strict Guidelines - Engineers MUST ALWAYS pass '-Wl,-z,max-page-size=16384' to linker flags (target_link_options / CMAKE_SHARED_LINKER_FLAGS / LOCAL_LDFLAGS) in NDK builds compiled with NDK r26 or earlier, and ensure NDK r27+ defaults remain uncompromised. - Engineers MUST NEVER hardcode 4096 or 4KB bitmasks (e.g., ~(4096 - 1)) for memory calculations, buffer allocations, or boundary checks; runtime page boundary logic MUST calculate masks dynamically using sysconf(_SC_PAGESIZE). - Code calling mmap() MUST ensure file offset parameters and mapped address pointers strictly align to sysconf(_SC_PAGESIZE) multiples; passing unaligned offsets causes EINVAL on 16KB kernel runtimes. - Services using zipflinger or custom APK packagers MUST set uncompressed shared library alignment to 16384 bytes (e.g., 'android:extractNativeLibs=false' with zipalign -p 16384). - Native build verification pipelines MUST run 'objdump -p <library.so> | grep LOAD' or verify that all PT_LOAD ELF segment p_align fields are >= 0x4000 (16384 bytes) before binary packaging. ## Bad vs Good Implementations ### CMake Native Linker Configuration and Dynamic Runtime mmap Boundary Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Linking without explicit 16KB max-page-size creates ELF PT_LOAD segments aligned only to 4KB (0x1000), causing the Android 15 linker64 to reject the library at runtime. Hardcoding SYSTEM_PAGE_SIZE to 4096 creates misaligned virtual memory requests when interacting with mmap/mprotect, triggering EINVAL failures or kernel segmentation faults. ```cpp // CMakeLists.txt (Anti-Pattern) // target_link_libraries(native_engine log) // Relies on legacy 4KB linker defaults prior to NDK r27 #include <sys/mman.h> #include <unistd.h> #define SYSTEM_PAGE_SIZE 4096 #define PAGE_MASK (~(SYSTEM_PAGE_SIZE - 1)) void* allocate_executable_buffer(size_t payload_size) { // Hardcoded 4096 alignment triggers SIGBUS/EINVAL on Android 15 16KB kernels size_t aligned_size = (payload_size + SYSTEM_PAGE_SIZE - 1) & PAGE_MASK; void* addr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 0); if (addr == MAP_FAILED) return nullptr; // mprotect assuming 4KB page quantum mprotect(addr, aligned_size, PROT_READ | PROT_EXEC); return addr; } ``` #### Production Standard (Correct) > **Standard**: The CMake configuration sets '-Wl,-z,max-page-size=16384', ensuring all ELF PT_LOAD segments conform to 16KB boundaries (0x4000). The C++ implementation dynamically queries sysconf(_SC_PAGESIZE), deriving a valid bitmask that guarantees safe buffer allocation and memory protection across both 4KB legacy and 16KB Android 15+ kernels. ```cpp // CMakeLists.txt (Production Invariant) // target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384") #include <sys/mman.h> #include <unistd.h> #include <cstdint> void* allocate_executable_buffer(size_t payload_size) { // Dynamically retrieve hardware page size from kernel runtime const long runtime_page_size = sysconf(_SC_PAGESIZE); if (runtime_page_size <= 0) return nullptr; const size_t page_mask = ~(static_cast<size_t>(runtime_page_size) - 1); const size_t aligned_size = (payload_size + runtime_page_size - 1) & page_mask; void* addr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 0); if (addr == MAP_FAILED) return nullptr; if (mprotect(addr, aligned_size, PROT_READ | PROT_EXEC) != 0) { munmap(addr, aligned_size); return nullptr; } return addr; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Page Alignment NDK Memory Boundary Invariant

Android 15 16KB Page Alignment NDK Memory Boundary Invariant defines an industrial-grade behavioral standard for mobile engineering. Mandates strict 16KB (0x4000) ELF segment alignment across all compiled native C/C++ mobile shared libraries (.so) and build scripts targeting Android 15 (API level 35) and beyond. Failure to align ELF load segments to 16KB boundaries results in dynamic linker (linker64) aborts and fatal SIGSEGV/SIGBUS page fault panics when loaded into 16KB page size kernel runtimes on modern ARM64 hardware. 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: Shipping 4KB-Aligned Native Binaries or Unaligned Custom Memory Mappings to 16KB Page-Size 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	Shipping 4KB-Aligned Native Binaries or Unaligned Custom Memory Mappings to 16KB Page-Size 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 linker flags (target_link_options / CMAKE_SHARED_LINKER_FLAGS / LOCAL_LDFLAGS) in NDK builds compiled with NDK r26 or earlier, and ensure NDK r27+ defaults remain uncompromised.

Engineers MUST ALWAYS pass '-Wl,-z,max-page-size=16384' to linker flags (target_link_options / CMAKE_SHARED_LINKER_FLAGS / LOCAL_LDFLAGS) in NDK builds compiled with NDK r26 or earlier, and ensure NDK r27+ defaults remain uncompromised.

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.