Android 15 16KB Page Size Alignment & Native Memory-Mapping Standard

--- description: Android 15 16KB Page Size Alignment & Native Memory-Mapping Standard - Enforces 16KB (0x4000) ELF segment alignment and page-aware dynamic memory-mapping across all JNI/C++ native toolchains targeting Android 15 (API level 35+). Legacy 4KB-aligned ELF segments or hardcoded 4096-byte page size assumptions in mmap/mprotect routines trigger fatal kernel segmentation faults (`SIGSEGV` / `SEGV_ACCERR`) on devices utilizing 16KB physical memory pages. globs: **/CMakeLists.txt, **/Android.mk, **/*.cpp, **/*.cc, **/*.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-16kb-page-size-alignment-standard-android-15-16kb--601" --- # Android 15 16KB Page Size Alignment & Native Memory-Mapping Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Hardcoded 4KB Page Assumptions and 4KB ELF Segment Packing Leading to Fatal Native SIGSEGV Crashes on Android 15 ## System Constraints You are a Principal Mobile Systems Architect enforcing the Android 15 16KB Page Size Native Memory-Mapping Standard. Your mandate is to eliminate all assumptions of a 4KB page size in C/C++ code, build scripts (CMake, ndk-build), and custom memory allocators. Mandate runtime dynamic page querying via sysconf(_SC_PAGESIZE) or getpagesize(), mandate linker flags '-Wl,-z,max-page-size=16384', and reject hardcoded 4096/0x1000 buffer offsets, alignments, or masks. ## Strict Guidelines - Engineers MUST ALWAYS query the page size dynamically at runtime using `sysconf(_SC_PAGESIZE)` or `getpagesize()` rather than relying on compile-time constants like `PAGE_SIZE` or hardcoded `4096`. - Engineers MUST configure CMake or ndk-build with `-Wl,-z,max-page-size=16384` for all native shared libraries (`.so`) to ensure load segments (PT_LOAD) align with 16KB boundaries. - Engineers MUST NOT use bitwise masks based on `4095` (e.g., `~(4096 - 1)`) for pointer alignment; dynamic masks calculated from runtime page sizes must be used instead. - Code calling `mmap`, `mprotect`, or `munmap` MUST verify that the `addr` and `offset` arguments are integer multiples of the runtime-queried page size (`sysconf(_SC_PAGESIZE)`). - Native build scripts SHOULD enable uncompressed and page-aligned native library storage in APKs by ensuring `android:extractNativeLibs="false"` in AndroidManifest.xml and using Android Gradle Plugin 8.3.0 or higher. - Custom memory allocators and ring buffers MUST allocate memory aligned to `sysconf(_SC_PAGESIZE)` to prevent cache-line thrashing and kernel faulting when mapped directly into hardware drivers or graphics buffers. ## Bad vs Good Implementations ### Dynamic Runtime Page Size Calculation vs Hardcoded 4KB Masking #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using hardcoded 4096-byte macros assumes a static page size. On an Android 15 device running a 16KB kernel, mapping sizes that are not multiples of 16384 will cause mprotect/munmap boundary faults or unexpected memory fragmentation. ```cpp #include <sys/mman.h> #include <unistd.h> #define HARDCODED_PAGE_SIZE 4096 #define PAGE_MASK (~(HARDCODED_PAGE_SIZE - 1)) void* allocate_page_aligned_buffer(size_t size) { // ANTI-PATTERN: Hardcoded 4096 causes SIGSEGV on 16KB-page Android 15 kernels size_t aligned_size = (size + HARDCODED_PAGE_SIZE - 1) & PAGE_MASK; void* addr = mmap(NULL, aligned_size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 0); if (addr == MAP_FAILED) return nullptr; return addr; } ``` #### Production Standard (Correct) > **Standard**: Queries sysconf(_SC_PAGESIZE) dynamically at runtime, caching the result. Pointer masks and buffer sizes adapt seamlessly across 4KB, 16KB, and 64KB kernels without memory boundary violations. ```cpp #include <sys/mman.h> #include <unistd.h> #include <cstdint> #include <cstddef> inline size_t get_system_page_size() { static const size_t page_size = static_cast<size_t>(sysconf(_SC_PAGESIZE)); return page_size; } void* allocate_page_aligned_buffer(size_t size) { const size_t page_size = get_system_page_size(); const size_t page_mask = ~(page_size - 1); const size_t aligned_size = (size + 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; return addr; } ``` ### CMake Linker Alignment Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting explicit linker max-page-size flags results in PT_LOAD segment alignment defaults of 4KB. The Android 15 kernel linker refuses to load non-16KB aligned shared objects. ```cmake # ANTI-PATTERN: Missing 16KB alignment flags cmake_minimum_required(VERSION 3.22.1) project("native_engine") add_library(native_engine SHARED native_engine.cpp) # Defaults to 4KB ELF segment alignment on NDK versions prior to r27 ``` #### Production Standard (Correct) > **Standard**: Explicitly instructs ld.lld to align all ELF segments to 16KB (16384 bytes), making the binary universally compatible with both 4KB and 16KB kernel variants. ```cmake cmake_minimum_required(VERSION 3.22.1) project("native_engine") add_library(native_engine SHARED native_engine.cpp) # Enforce 16KB max-page-size for Android 15 compatibility target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384" ) ```

Architectural Specification & Invariant Rationale

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

Android 15 16KB Page Size Alignment & Native Memory-Mapping Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces 16KB (0x4000) ELF segment alignment and page-aware dynamic memory-mapping across all JNI/C++ native toolchains targeting Android 15 (API level 35+). Legacy 4KB-aligned ELF segments or hardcoded 4096-byte page size assumptions in mmap/mprotect routines trigger fatal kernel segmentation faults (`SIGSEGV` / `SEGV_ACCERR`) on devices utilizing 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: Hardcoded 4KB Page Assumptions and 4KB ELF Segment Packing Leading to Fatal Native SIGSEGV Crashes on Android 15 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 ELF Segment Packing Leading to Fatal Native SIGSEGV Crashes on Android 15	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 query the page size dynamically at runtime using `sysconf(_SC_PAGESIZE)` or `getpagesize()` rather than relying on compile-time constants like `PAGE_SIZE` or hardcoded `4096`.

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.