Android 15 16 KB Virtual Memory Page Alignment & Native Allocation Standard

--- description: Android 15 16 KB Virtual Memory Page Alignment & Native Allocation Standard - Enforces runtime page-size resolution and ELF 16 KB segment alignment across all Android NDK binaries, third-party C/C++ libraries, and custom virtual memory allocators. Eliminates unaligned mmap offsets and hardcoded 4096-byte assumptions that induce immediate SIGSEGV signal 11 crashes on Android 15 ARM64 hardware running 16 KB kernel pages. globs: **/*.{c,cc,cpp,cxx,h,hpp}, **/CMakeLists.txt, **/Android.mk, **/*.gradle, **/*.gradle.kts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-16kb-page-alignment-memory-standard" --- # Android 15 16 KB Virtual Memory Page Alignment & Native Allocation Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Hardcoded 4 KB Page Sizing and Unaligned Dynamic Allocations Causing Fatal SIGSEGV on Android 15 ARM64 Devices ## System Constraints You are a Principal Android Systems & Native Runtime Architect enforcing the Android 15 16 KB Page Alignment Dynamic Memory Allocation Standard. Your mandate is to prevent catastrophic SIGSEGV runtime aborts on ARM64 silicon configured with 16 KB physical/virtual page tables. Reject all code with hardcoded PAGE_SIZE macros, 4096-byte alignment assumptions, unaligned mmap offsets, or link flags lacking 16 KB ELF segment alignment. ## Strict Guidelines - Engineers MUST ALWAYS query the system page size dynamically at runtime using `sysconf(_SC_PAGESIZE)` or `getpagesize()` rather than relying on compile-time `PAGE_SIZE` macros. - Engineers MUST NOT hardcode `4096`, `0x1000`, `12` (bit shift), or any static literal to represent page size or alignment boundaries in memory management code. - Native build scripts (CMake, ndk-build) MUST pass `-Wl,-z,max-page-size=16384` to the linker for all native target shared libraries and executables. - Custom arena allocators, ring buffers, and cache-line managers MUST calculate pointer alignment and padding offsets relative to the dynamically retrieved runtime page size. - Calls to `mmap()` and `mprotect()` MUST enforce that file offsets (`offset` parameter) and base addresses are exact integer multiples of the runtime page size returned by `sysconf(_SC_PAGESIZE)`. - Components NEVER cast raw memory addresses or allocate contiguous virtual rings without checking against dynamic page-boundary boundaries. ## Bad vs Good Implementations ### Dynamic Page-Aligned Custom Arena Allocation and mmap Mapping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Uses a compile-time PAGE_SIZE macro of 4096 and passes an unaligned offset (4096) to mmap. On Android 15 running with 16 KB pages, mmap returns MAP_FAILED with EINVAL, and unaligned memory access patterns cause immediate SIGSEGV crashes. ```cpp #include <sys/mman.h> #include <unistd.h> #define PAGE_SIZE 4096 #define PAGE_MASK (~(PAGE_SIZE - 1)) void* allocate_native_ring(size_t payload_size) { // ANTI-PATTERN: Hardcoded 4 KB alignment assumption size_t aligned_size = (payload_size + PAGE_SIZE - 1) & PAGE_MASK; // Fails on Android 15 with 16 KB page size: offset must be page-aligned void* addr = mmap(NULL, aligned_size, PROT_READ | PROT_WRITE, MAP_ANONYMOUS | MAP_PRIVATE, -1, 4096); if (addr == MAP_FAILED) { return nullptr; } return addr; } ``` #### Production Standard (Correct) > **Standard**: Retrieves the dynamic page size via sysconf(_SC_PAGESIZE) once, aligns both the mapping length and any offsets to multiples of the runtime page size (16384 bytes on Android 15 16 KB targets), guaranteeing kernel-level compliance and zero SIGSEGV faults. ```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; } inline size_t align_to_page(size_t size, size_t page_size) { return (size + page_size - 1) & ~(page_size - 1); } void* allocate_native_ring(size_t payload_size) { // PRODUCTION FIX: Dynamically determine page size at runtime (4 KB, 16 KB, or 64 KB) const size_t page_size = get_system_page_size(); const size_t aligned_size = align_to_page(payload_size, page_size); // Offset must be 0 or an integer multiple of the runtime page size 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 Configuration for 16 KB ELF Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default NDK toolchains before recent revisions default to 4 KB ELF segment alignment. When installed on an Android 15 16 KB device, the OS linker rejects the shared object, causing unsatisfied link errors or runtime SIGSEGV faults during relocation. ```cmake # ANTI-PATTERN: Omitting linker alignment flags causes Android 15 package installer # or dynamic linker (linker64) to fail to load the library on 16 KB kernels. add_library(native_engine SHARED src/engine.cpp src/allocator.cpp ) ``` #### Production Standard (Correct) > **Standard**: Directs GNU ld / LLVM lld to align ELF segment boundaries to 16384-byte boundaries, ensuring backwards compatibility with 4 KB systems while providing zero-defect compatibility on Android 15 16 KB kernels. ```cmake # PRODUCTION FIX: Explicitly enforce 16 KB max page size alignment for the linker add_library(native_engine SHARED src/engine.cpp src/allocator.cpp ) target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384" ) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16 KB Virtual Memory Page Alignment & Native Allocation Standard

Android 15 16 KB Virtual Memory Page Alignment & Native Allocation Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces runtime page-size resolution and ELF 16 KB segment alignment across all Android NDK binaries, third-party C/C++ libraries, and custom virtual memory allocators. Eliminates unaligned mmap offsets and hardcoded 4096-byte assumptions that induce immediate SIGSEGV signal 11 crashes on Android 15 ARM64 hardware running 16 KB kernel 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 4 KB Page Sizing and Unaligned Dynamic Allocations Causing Fatal SIGSEGV on Android 15 ARM64 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 4 KB Page Sizing and Unaligned Dynamic Allocations Causing Fatal SIGSEGV on Android 15 ARM64 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 query the system page size dynamically at runtime using `sysconf(_SC_PAGESIZE)` or `getpagesize()` rather than relying on compile-time `PAGE_SIZE` macros.

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.