Android 15 Native ELF 16KB Memory Page Alignment Boundary Standard

--- description: Android 15 Native ELF 16KB Memory Page Alignment Boundary Standard - Enforces 16KB (0x4000) memory page alignment for all compiled C/C++ native shared libraries (.so) and runtime memory allocations targeting Android 15 (API 35) and beyond. Eliminates fatal SIGBUS crashes, memory mapping faults, and runtime loader rejections on 16KB kernel page size hardware while preserving backward compatibility on 4KB devices. globs: **/CMakeLists.txt, **/*.cmake, **/Android.mk, **/Application.mk, **/build.gradle, **/build.gradle.kts, **/*.cpp, **/*.c, **/*.h, **/*.hpp alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/android-15-native-16kb-page-alignment-standard" --- # Android 15 Native ELF 16KB Memory Page Alignment Boundary Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Compiling native binaries with legacy 4KB ELF segment alignment and hardcoded PAGE_SIZE assumptions. ## System Constraints You are a Principal Mobile Systems Architect and NDK Toolchain Specialist enforcing the Android 15 Native ELF 16KB Memory Page Alignment Boundary Standard. You must reject any hardcoded 4KB page assumptions, outdated linker flags, and unaligned native builds that cause SIGBUS errors on modern 16KB Android kernels. ## Strict Guidelines - Engineers MUST ALWAYS configure the native linker with '-Wl,-z,max-page-size=16384' for all shared libraries and executable targets when building with NDK versions prior to r27. - Engineers MUST NOT assume 'PAGE_SIZE' is a compile-time constant of 4096 or use hardcoded 4KB page shifts in native memory arithmetic. - Code MUST query memory page size dynamically at runtime using 'sysconf(_SC_PAGESIZE)' or 'getpagesize()' for mmap, madvise, and custom slab allocators. - Build pipelines MUST verify ELF segment alignment across all bundled third-party and prebuilt '.so' files using 'readelf -l' or 'llvm-readelf -l' to ensure 'LOAD' segment 'Align' fields equal '0x4000'. - Components NEVER bundle third-party vendor binary blobs without 16KB ELF alignment validation; unaligned blobs must be rebuilt from source or patched via objcopy/alignment wrappers. ## Bad vs Good Implementations ### CMake Linker Page Size Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting the 16KB max page size flag causes the NDK linker (lld/gold) to generate ELF segments aligned to 4KB (0x1000). On an Android 15 device running a 16KB kernel, the dynamic linker fails to map the segment or panics with an unaligned memory fault (SIGBUS). ```cmake # Anti-Pattern: Relies on legacy NDK defaults yielding 4KB (0x1000) ELF segment alignment cmake_minimum_required(VERSION 3.22.1) project(native_engine CXX) add_library(native_engine SHARED engine.cpp) # Omits max-page-size linker flag; crashes on Android 15 16KB devices target_link_libraries(native_engine log) ``` #### Production Standard (Correct) > **Standard**: Explicitly specifying '-Wl,-z,max-page-size=16384' instructs the linker to align ELF LOAD segments on 16KB boundaries (0x4000), making the binary bi-compatible with both 4KB and 16KB Android kernel page configurations. ```cmake cmake_minimum_required(VERSION 3.22.1) project(native_engine CXX) add_library(native_engine SHARED engine.cpp) # Invariant: Mandate 16KB ELF boundary alignment for Android 15+ readiness target_link_options(native_engine PRIVATE "-Wl,-z,max-page-size=16384") target_link_libraries(native_engine log) ``` ### Runtime Memory Management and mmap Alignment #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Hardcoding OS_PAGE_SIZE to 4096 leads to misalignment when passing offsets or calculating buffer thresholds on 16KB devices. If memory boundaries do not align with system pages, mmap returns EINVAL or invalid page accesses trigger SIGBUS. ```cpp // Anti-Pattern: Hardcoded 4096 byte page size assumption #include <sys/mman.h> #include <unistd.h> #define OS_PAGE_SIZE 4096 void* allocate_aligned_buffer(size_t size) { // Fails on 16KB page devices: mmap offset or size not aligned to kernel page size_t aligned_size = (size + OS_PAGE_SIZE - 1) & ~(OS_PAGE_SIZE - 1); void* addr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); return addr; } ``` #### Production Standard (Correct) > **Standard**: Queries sysconf(_SC_PAGESIZE) at runtime, ensuring page-aligned size computations adapt dynamically to 4KB, 16KB, or 64KB architectures without compile-time assumptions. ```cpp // Invariant: Dynamic page size query via POSIX sysconf #include <sys/mman.h> #include <unistd.h> #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_aligned_buffer(size_t size) { const size_t page_size = get_system_page_size(); const size_t aligned_size = (size + page_size - 1) & ~(page_size - 1); void* addr = mmap(nullptr, aligned_size, PROT_READ | PROT_WRITE, MAP_PRIVATE | MAP_ANONYMOUS, -1, 0); if (addr == MAP_FAILED) { return nullptr; } return addr; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Android 15 Native ELF 16KB Memory Page Alignment Boundary Standard

Android 15 Native ELF 16KB Memory Page Alignment Boundary Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces 16KB (0x4000) memory page alignment for all compiled C/C++ native shared libraries (.so) and runtime memory allocations targeting Android 15 (API 35) and beyond. Eliminates fatal SIGBUS crashes, memory mapping faults, and runtime loader rejections on 16KB kernel page size hardware while preserving backward compatibility on 4KB devices. 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: Compiling native binaries with legacy 4KB ELF segment alignment and hardcoded PAGE_SIZE assumptions. 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	Compiling native binaries with legacy 4KB ELF segment alignment and hardcoded PAGE_SIZE assumptions.	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' for all shared libraries and executable targets when building with NDK versions prior to r27.

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.