Android 15 16KB Page-Size Boundary and Dynamic Linker Alignment Standard

--- description: Android 15 16KB Page-Size Boundary and Dynamic Linker Alignment Standard - Enforces strict 16KB ELF segment boundaries and runtime page-size agnostic memory operations across native C/C++ libraries. Prevents fatal dynamic linker loader aborts and SIGSEGV memory faults on Android 15 kernels configured with 16KB page sizes. Mandates max-page-size linker configurations and dynamic page-size resolution via sysconf instead of compile-time constants. globs: **/CMakeLists.txt, **/Android.mk, **/*.cpp, **/*.c, **/*.h, **/*.hpp, **/build.gradle*, **/app/build.gradle* alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-16kb-page-alignment-boundary" --- # Android 15 16KB Page-Size Boundary and Dynamic Linker Alignment Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Hardcoded 4KB Page Assumptions and Unaligned ELF PT_LOAD Segments Triggering Native SIGSEGV ## System Constraints You are a Principal Mobile Native Systems Architect enforcing Android 15 16KB page-alignment boundaries across all C/C++ native source and build pipelines. Mandate 16KB ELF segment alignment in linker flags (-Wl,-z,max-page-size=16384), eliminate all compile-time PAGE_SIZE macro dependencies in favor of runtime sysconf(_SC_PAGESIZE), and guarantee page-aligned offsets for dynamic memory mappings (mmap, mprotect, posix_memalign). Block any commits or code transformations that assume 4KB page granularity. ## Strict Guidelines - Engineers MUST ALWAYS configure ELF segment max-page-size to at least 16384 bytes using `-Wl,-z,max-page-size=16384` in CMake, ndk-build, or compiler flags for all shared libraries (.so). - Engineers MUST NOT rely on compile-time `PAGE_SIZE`, `PAGE_MASK`, or `PAGE_SHIFT` macros, as they are non-standard, architecture-dependent, and either undefined or inaccurate on 16KB Android kernels. - Code MUST ALWAYS obtain memory page boundaries dynamically at runtime using `sysconf(_SC_PAGESIZE)` or `getpagesize()`. - Code MUST ensure all address and file offset arguments supplied to `mmap()`, `mprotect()`, and `munmap()` are strictly aligned to the runtime page size boundary. - Components NEVER use bitwise shift literals like `>> 12` or bitwise masks like `& ~0xFFF` to calculate page alignment; bit arithmetic must derive from the runtime page size. - Build scripts SHOULD upgrade to NDK r27 or higher, which enforces 16KB alignment by default, or explicitly declare `useLegacyPackaging = false` and alignment flags on NDK r26 and lower. - Third-party prebuilt dynamic libraries (.so) MUST be audited via `llvm-objdump -p <lib>.so` or `readelf -l <lib>.so` to verify `LOAD` segment `Align` is 0x4000 (16KB) or greater. ## Bad vs Good Implementations ### Runtime Memory Mapping and Page Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code hardcodes 4096-byte page size assumptions. On an Android 15 16KB device, calling mprotect or mmap with offsets that are aligned to 4KB but unaligned to 16KB causes the kernel call to fail with EINVAL or trigger an immediate SIGSEGV memory violation. ```cpp #include <sys/mman.h> #include <unistd.h> // Anti-pattern: Hardcoded 4KB page assumptions #define FIXED_PAGE_SIZE 4096 #define PAGE_ALIGN_DOWN(addr) ((addr) & ~(FIXED_PAGE_SIZE - 1)) void* allocate_guarded_buffer(size_t size) { // Fails on Android 15 16KB kernels: mmap/mprotect requires 16KB alignment size_t aligned_size = (size + 4095) & ~4095; void* ptr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); // Hardcoded offset calculation causes SIGSEGV on 16KB pages uintptr_t guard_page = reinterpret_cast<uintptr_t>(ptr) + 4096; mprotect(reinterpret_cast<void*>(PAGE_ALIGN_DOWN(guard_page)), FIXED_PAGE_SIZE, PROT_NONE); return ptr; } ``` #### Production Standard (Correct) > **Standard**: Dynamic resolution using sysconf(_SC_PAGESIZE) ensures correct alignment calculation across both 4KB legacy and 16KB modern Android kernels, eliminating invalid parameter failures in mmap and mprotect. ```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 uintptr_t align_down(uintptr_t val, size_t page_size) { return val & ~(page_size - 1); } inline size_t align_up(size_t val, size_t page_size) { return (val + page_size - 1) & ~(page_size - 1); } void* allocate_guarded_buffer(size_t size) { const size_t page_size = get_system_page_size(); const size_t aligned_size = align_up(size, page_size); void* ptr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); if (ptr == MAP_FAILED) { return nullptr; } // Correctly aligns guard page to system boundary (16KB on Android 15) uintptr_t guard_page = reinterpret_cast<uintptr_t>(ptr) + page_size; if (mprotect(reinterpret_cast<void*>(align_down(guard_page, page_size)), page_size, PROT_NONE) != 0) { munmap(ptr, aligned_size); return nullptr; } return ptr; } ``` ### CMake Linker Flag Enforcement for 16KB ELF Segments #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting explicit max-page-size linker flags on pre-r27 NDK toolchains defaults ELF segment alignment to 4KB. Android 15's linker will reject loading the shared library via dlopen with an ELF alignment error. ```cmake # Anti-pattern: Defaulting linker settings without max-page-size alignment cmake_minimum_required(VERSION 3.22.1) project(NativeCore) add_library(native_core SHARED src/core.cpp ) # Dynamic linker in Android 15 fails to load this library if compiled # with NDK r26 or earlier due to 4KB default ELF segment boundaries ``` #### Production Standard (Correct) > **Standard**: Explicitly passing -Wl,-z,max-page-size=16384 sets the ELF PT_LOAD segment alignment to 16KB (0x4000), making the compiled shared library safe for loading under Android 15 dynamic linker memory mappings. ```cmake cmake_minimum_required(VERSION 3.22.1) project(NativeCore) add_library(native_core SHARED src/core.cpp ) # Enforce 16KB ELF alignment across all target architectures target_link_options(native_core PRIVATE "-Wl,-z,max-page-size=16384" ) # Ensure common sub-dependencies and runtime libraries adhere to alignment set_target_properties(native_core PROPERTIES LINK_FLAGS "-Wl,-z,max-page-size=16384" ) ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 16KB Page-Size Boundary and Dynamic Linker Alignment Standard

Android 15 16KB Page-Size Boundary and Dynamic Linker Alignment Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces strict 16KB ELF segment boundaries and runtime page-size agnostic memory operations across native C/C++ libraries. Prevents fatal dynamic linker loader aborts and SIGSEGV memory faults on Android 15 kernels configured with 16KB page sizes. Mandates max-page-size linker configurations and dynamic page-size resolution via sysconf instead of compile-time constants. 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 Unaligned ELF PT_LOAD Segments Triggering Native SIGSEGV 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 Unaligned ELF PT_LOAD Segments Triggering Native SIGSEGV	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 ELF segment max-page-size to at least 16384 bytes using `-Wl,-z,max-page-size=16384` in CMake, ndk-build, or compiler flags for all shared libraries (.so).

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.