fix: align llama native library for Android 16 KiB pages

This commit is contained in:
Blendman974 committed 2026-11-06 00:57:10 +01:00
1 parent 40cd9eb5ba
commit 68c9dc7ae9
5 files changed
+142 -3

No files matched your search

@@ -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")
+33
View File
@@ -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.
+7 -3
View File
@@ -29,17 +29,21 @@ The build produces a debug APK for arm64 Android phones. It does not install
the APK or flash firmware. Build output and machine-local signing/SDK files
are ignored by Git.
Final artifact: `dist/faceclaw-device-preferences-debug.apk` (110,299,294 bytes),
Final artifact: `dist/faceclaw-device-preferences-debug.apk` (115,876,494 bytes),
package `com.faceclaw.app`, version 0.8.6 (806). Build completed successfully;
APK v2 signature verified with `apksigner`. The packaged JavaScript contains all
three controls, and the DEX contains the new calendar and head-up native APIs.
SHA-256 (also saved alongside the APK):
```text
589d1627df72ec84e56a85dbfe257c123ded094b6708997da6b9bd18a2d7fbaf
091ced145d499ec00aa03cbea60f5cec7a2167e459896c4b5b45211e1c9a7e8a
```
Physical validation remains pending. No phone or glasses were used. See the
The updated APK also passes ELF LOAD/RELRO and ZIP alignment checks for 16 KiB
pages; see [16 KiB validation](validation-android-16k.md).
Glasses validation remains pending. The APK was installed on a Pixel 10 Pro Fold,
which currently reports 4096-byte pages. No glasses were used. See the
manual procedures for [notifications](validation-notifications.md),
[Android calendars](validation-calendars.md) and [head-up wake](validation-head-up.md).
In particular, successful BLE encoding and simulated ACK/reconnect tests do
+57
View File
@@ -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())
+40
View File
@@ -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("<Q", data, 32, 64)
struct.pack_into("<HH", data, 54, 56, 2)
struct.pack_into("<IIQQQQQQ", data, 64, 1, 6, 0, 0, 0, writable_end, writable_end, alignment)
struct.pack_into("<IIQQQQQQ", data, 120, 0x6474E552, 4, 0, 0, 0, relro_end, relro_end, 1)
return data
class AlignmentTests(unittest.TestCase):
def test_rejects_4k_loads(self):
self.assertTrue(checker.alignment_errors(elf(alignment=4096)))
def test_accepts_16k_loads_and_relro(self):
self.assertEqual([], checker.alignment_errors(elf()))
def test_rejects_relro_protecting_writable_data(self):
self.assertTrue(checker.alignment_errors(elf(relro_end=4096)))
def test_accepts_relro_at_end_of_writable_load(self):
self.assertEqual([], checker.alignment_errors(elf(relro_end=4096, writable_end=4096)))
def test_rejects_invalid_headers(self):
self.assertTrue(checker.alignment_errors(b"not ELF"))
self.assertTrue(checker.alignment_errors(elf()[:70]))
if __name__ == "__main__":
unittest.main()