diff --git a/App_Resources/Android/src/main/native/llama/CMakeLists.txt b/App_Resources/Android/src/main/native/llama/CMakeLists.txt index 7ab3677e..7ee5de52 100644 --- a/App_Resources/Android/src/main/native/llama/CMakeLists.txt +++ b/App_Resources/Android/src/main/native/llama/CMakeLists.txt @@ -29,3 +29,8 @@ add_subdirectory(${LLAMA_CPP_SOURCE_DIR} llama.cpp-build EXCLUDE_FROM_ALL) add_library(faceclaw_llama SHARED faceclaw_llama.cpp) target_link_libraries(faceclaw_llama PRIVATE llama android log) +# NDK r27 defaults to 4 KiB. Align both LOAD segments and RELRO boundaries +# for Android devices using 16 KiB pages, including debug APKs. +target_link_options(faceclaw_llama PRIVATE + "-Wl,-z,max-page-size=16384" + "-Wl,-z,common-page-size=16384") diff --git a/docs/validation-android-16k.md b/docs/validation-android-16k.md new file mode 100644 index 00000000..359f102d --- /dev/null +++ b/docs/validation-android-16k.md @@ -0,0 +1,33 @@ +# Android 16 KiB page compatibility + +The initial debug APK triggered Android's page-size compatibility warning. +Its `libfaceclaw_llama.so` LOAD segments were aligned to 4096 bytes. The other +six packaged arm64 libraries were aligned to 16384 bytes, and APK ZIP alignment +already passed `zipalign -c -P 16 4`. + +The llama JNI shared library now links with both `max-page-size=16384` and +`common-page-size=16384`, matching the LC3 JNI library. This changes the native +binary layout rather than hiding the compatibility warning or disabling debug. +Gradle already tracks CMakeLists.txt as an input, and Ninja reconfigures and +relinks existing builds after this change. + +Reproduce the regression and artifact checks inside `devenv shell`: + +```sh +python3 -m unittest discover -s tests -p test_apk_pages.py +bash build.sh +python3 scripts/check-apk-pages.py platforms/android/app/build/outputs/apk/debug/app-debug.apk +"$ANDROID_HOME/build-tools/35.0.1/zipalign" -c -P 16 4 platforms/android/app/build/outputs/apk/debug/app-debug.apk +``` + +The checker rejects the initial APK and reports its misaligned llama library. +Five unit tests cover 4 KiB rejection, 16 KiB acceptance, RELRO boundaries and +invalid ELF program headers. APK checks inspect all arm64/x86_64 shared libraries. + +Reference: [Android's 16 KiB guidance](https://developer.android.com/guide/practices/page-sizes). +Static alignment and successful installation do not prove every native code +path works on-device; voice/LLM features still require functional testing. + +The rebuilt APK passes all seven native-library checks, ZIP alignment and APK +signature verification. The connected Pixel 10 Pro Fold reports `getconf +PAGE_SIZE` = 4096; actual execution with 16 KiB pages remains untested. diff --git a/scripts/check-apk-pages.py b/scripts/check-apk-pages.py new file mode 100644 index 00000000..dd0594e9 --- /dev/null +++ b/scripts/check-apk-pages.py @@ -0,0 +1,57 @@ +#!/usr/bin/env python3 +"""Check ELF64 LOAD/RELRO alignment in an APK; pair with zipalign -c -P 16 4.""" +import argparse +import struct +import zipfile + +PAGE = 16384 + + +def alignment_errors(data): + if len(data) < 64 or data[:4] != b"\x7fELF" or data[4] != 2 or data[5] not in (1, 2): + return ["expected an ELF64 library"] + endian = "<" if data[5] == 1 else ">" + offset = struct.unpack_from(endian + "Q", data, 32)[0] + size, count = struct.unpack_from(endian + "HH", data, 54) + if size < 56 or offset + size * count > len(data): + return ["invalid program headers"] + headers = [struct.unpack_from(endian + "IIQQQQQQ", data, offset + i * size) for i in range(count)] + errors = [] + loads = [h for h in headers if h[0] == 1] + if not loads: + errors.append("no LOAD segments") + for h in loads: + if h[7] < PAGE or h[7] % PAGE or (h[3] - h[2]) % PAGE: + errors.append(f"LOAD alignment {h[7]} is incompatible with 16 KiB pages") + for h in headers: + if h[0] != 0x6474E552: + continue + end = h[3] + h[6] + # A RELRO ending within a writable LOAD may protect unrelated writable + # data on a 16 KiB device. A separate LOAD after RELRO is also safe. + if end % PAGE and any(p[1] & 2 and p[3] <= h[3] and end < p[3] + p[6] for p in loads): + errors.append("RELRO ends inside writable LOAD without 16 KiB alignment") + return errors + + +def main(): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument("apk") + args = parser.parse_args() + checked = 0 + failed = False + with zipfile.ZipFile(args.apk) as archive: + for name in archive.namelist(): + if not name.startswith(("lib/arm64-v8a/", "lib/x86_64/")) or not name.endswith(".so"): + continue + checked += 1 + errors = alignment_errors(archive.read(name)) + failed |= bool(errors) + print(f"{'FAIL' if errors else 'OK'} {name}" + (": " + "; ".join(errors) if errors else "")) + if not checked: + parser.error("no 64-bit native libraries found") + return int(failed) + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_apk_pages.py b/tests/test_apk_pages.py new file mode 100644 index 00000000..1424f5a4 --- /dev/null +++ b/tests/test_apk_pages.py @@ -0,0 +1,40 @@ +import importlib.util +from pathlib import Path +import struct +import unittest + +spec = importlib.util.spec_from_file_location("apk_pages", Path(__file__).parents[1] / "scripts/check-apk-pages.py") +checker = importlib.util.module_from_spec(spec) +spec.loader.exec_module(checker) + + +def elf(alignment=16384, relro_end=16384, writable_end=32768): + data = bytearray(64 + 2 * 56) + data[:6] = b"\x7fELF\x02\x01" + struct.pack_into("