Add cross-platform AArch64 context backends

Author: YinMo19

.github/workflows/ci.yml

@@ -27,6 +27,37 @@ jobs:
       - name: Zig test
         run: zig build test
 
+      - name: Cross compile Linux AArch64 core and payload
+        run: |
+          set -euo pipefail
+          zig build-lib -dynamic -target aarch64-linux-musl -OReleaseFast \
+            -femit-bin=/tmp/libzighook_linux.so \
+            src/root.zig \
+            -lc
+          zig build-lib -dynamic -target aarch64-linux-musl -OReleaseFast \
+            -femit-bin=/tmp/prepatched_hook_linux.so \
+            --dep zighook \
+            -Mroot=examples/prepatched_inline_hook/hook.zig \
+            -Mzighook=src/root.zig \
+            -lc
+
+      - name: Cross compile iOS AArch64 core and payload
+        run: |
+          set -euo pipefail
+          IOS_SDK="$(xcrun --sdk iphoneos --show-sdk-path)"
+          zig build-lib -dynamic -target aarch64-ios -OReleaseFast \
+            -femit-bin=/tmp/libzighook_ios.dylib \
+            src/root.zig \
+            -L"$IOS_SDK/usr/lib" \
+            -lc
+          zig build-lib -dynamic -target aarch64-ios -OReleaseFast \
+            -femit-bin=/tmp/prepatched_hook_ios.dylib \
+            --dep zighook \
+            -Mroot=examples/prepatched_inline_hook/hook.zig \
+            -Mzighook=src/root.zig \
+            -L"$IOS_SDK/usr/lib" \
+            -lc
+
       - name: Example inline_hook_signal
         working-directory: examples/inline_hook_signal
         run: |

README.md

@@ -5,7 +5,10 @@
 Current scope:
 
 - macOS
-- Apple Silicon / AArch64
+- iOS
+- Linux
+- Android
+- AArch64 / ARM64
 
 Implemented APIs:
 
@@ -24,15 +27,30 @@ The current backend supports:
 - signal-based entry hooks
 - strict execute-original replay for common AArch64 PC-relative instructions
 - public callback access to AArch64 FP/SIMD state (`fpregs.v[i]`, `fpregs.named.v0..v31`, `fpsr`, `fpcr`)
-- constructor-based dylib payloads for `DYLD_INSERT_LIBRARIES` / later Mach-O insertion workflows
+- constructor-based payloads for both Mach-O (`__mod_init_func`) and ELF (`.init_array`)
 
 ## Status
 
-This repository currently targets the first backend slice only:
+Implemented AArch64 platform backends:
 
-- `aarch64-apple-darwin`
+- `aarch64-macos`
+- `aarch64-ios`
+- `aarch64-linux`
+- `aarch64-linux-android` at the code/backend level via the Linux-family signal path
 
-It is usable for local experiments on Apple Silicon macOS, but it is not yet at full feature/platform parity with the Rust crate.
+Verification status:
+
+- macOS AArch64: runtime-tested locally and in CI
+- Linux AArch64: cross-compiled core library and ELF payload locally
+- iOS AArch64: cross-compiled core dylib and Mach-O payload locally
+- Android AArch64: compiled core/payload objects against a local NDK sysroot
+
+Deployment model by platform:
+
+- macOS: runtime patching or prepatched trap sites, usually with `DYLD_INSERT_LIBRARIES`
+- Linux: runtime patching or prepatched trap sites, usually with `LD_PRELOAD` or `patchelf`
+- iOS: recommended prepatched trap sites plus inserted dylib + re-sign
+- Android: Linux-family backend plus sidecar `.so`, typically loaded via patched ELF metadata / app packaging
 
 Current execute-original replay whitelist for PC-relative AArch64 instructions:
 
@@ -94,6 +112,10 @@ zig build-lib -dynamic -OReleaseFast -femit-bin=hook.dylib \
 DYLD_INSERT_LIBRARIES=$PWD/hook.dylib ./target
 ```
 
+For Linux, iOS, and Android deployment flows, see:
+
+- `docs/platform-workflows.md`
+
 Available examples:
 
 - `inline_hook_signal`: function-entry trap hook, expected output `result=42`
@@ -106,6 +128,7 @@ CI runs these exact per-directory build commands and compares exact stdout.
 
 See:
 
+- `docs/platform-workflows.md`
 - `examples/README.md`
 - each `examples/*/README.md`
 

build.zig.zon

@@ -78,5 +78,6 @@
         "src",
         "tests",
         "examples",
+        "docs",
     },
 }

docs/platform-workflows.md

@@ -0,0 +1,127 @@
+# AArch64 platform workflows
+
+This repository now implements AArch64 backends for:
+
+- macOS
+- iOS
+- Linux
+- Android
+
+The core trap/replay engine is shared across all of them. The platform-specific
+differences are mostly:
+
+- how executable pages are patched
+- how `sigaction` / `ucontext_t` machine state is remapped
+- how the sidecar payload is injected into the target process
+
+The example `hook.zig` payloads automatically pick the right constructor
+section:
+
+- Mach-O (`macOS`, `iOS`): `__DATA,__mod_init_func`
+- ELF (`Linux`, `Android`): `.init_array`
+
+## Linux AArch64
+
+Recommended workflows:
+
+- `LD_PRELOAD` for local experiments
+- `patchelf` for persistent sidecar loading
+
+Build a sidecar payload from any example directory:
+
+```bash
+cc -O3 -DNDEBUG -Wl,-export-dynamic -o target target.c
+
+zig build-lib -dynamic -target aarch64-linux-musl -OReleaseFast -femit-bin=hook.so \
+  --dep zighook \
+  -Mroot=hook.zig \
+  -Mzighook=../../src/root.zig \
+  -lc
+```
+
+Run with preload:
+
+```bash
+LD_PRELOAD=$PWD/hook.so ./target
+```
+
+Or patch the ELF loader metadata with `patchelf` / equivalent tooling and ship
+the sidecar `.so` next to the target binary.
+
+## iOS AArch64
+
+Recommended workflow:
+
+- use `prepatched.*`
+- patch `brk #0` into the app binary offline
+- ship a sidecar dylib inside `Frameworks/`
+- inject the load command with `insert-dylib`
+- re-sign the entire app bundle and install
+
+`prepatched_inline_hook` is the best template example for this deployment mode.
+
+Build the payload dylib:
+
+```bash
+IOS_SDK=$(xcrun --sdk iphoneos --show-sdk-path)
+
+zig build-lib -dynamic -target aarch64-ios -OReleaseFast -femit-bin=hook.dylib \
+  --dep zighook \
+  -Mroot=hook.zig \
+  -Mzighook=../../src/root.zig \
+  -L"$IOS_SDK/usr/lib" \
+  -lc
+```
+
+Typical packaging flow afterwards:
+
+1. Copy `hook.dylib` into `MyApp.app/Frameworks/`
+2. Use `insert-dylib` to add a load command to the app Mach-O
+3. Re-sign the full app bundle
+4. Install and run
+
+This repository's iOS support is therefore oriented around **prepatched trap
+sites plus inserted dylibs**, matching the workflow described above.
+
+## Android AArch64
+
+Recommended workflow:
+
+- use a sidecar `.so`
+- patch the target ELF / native binary with `patch-elf` or equivalent
+- let the app or native packaging flow provide the final shared-library link
+
+The Android backend shares the same Linux-family AArch64 signal/context code
+path. In local verification, the Android target successfully compiled to object
+files against an installed NDK sysroot.
+
+Example compile-to-object smoke commands:
+
+```bash
+ANDROID_NDK=$HOME/Library/Android/sdk/ndk/29.0.13113456
+ANDROID_SYSROOT=$(find "$ANDROID_NDK/toolchains/llvm/prebuilt" -maxdepth 1 -mindepth 1 -type d | head -n 1)/sysroot
+
+zig build-obj -target aarch64-linux-android -OReleaseFast \
+  --sysroot "$ANDROID_SYSROOT" \
+  src/root.zig \
+  -lc
+
+zig build-obj -target aarch64-linux-android -OReleaseFast \
+  --dep zighook \
+  -Mroot=hook.zig \
+  -Mzighook=../../src/root.zig \
+  --sysroot "$ANDROID_SYSROOT" \
+  -lc
+```
+
+On the machine used for this implementation, Zig 0.15.2 did not provide a
+fully self-contained Android libc link for the final shared library, so the
+expected final `.so` link should be driven by the NDK / app build system.
+
+## Verification status
+
+- macOS AArch64: native runtime tests and examples executed locally
+- Linux AArch64: core shared library and ELF payload cross-compiled locally
+- iOS AArch64: core dylib and Mach-O payload cross-compiled locally
+- Android AArch64: core library and payload compiled to object files against a
+  local NDK sysroot

examples/README.md

@@ -1,10 +1,10 @@
 # zighook examples
 
 These examples mirror the intent of the Rust `sighook` demos, but are currently
-implemented only for the first completed backend slice:
+implemented for the first completed AArch64 backend family:
 
-- **OS:** macOS
-- **Architecture:** Apple Silicon / AArch64
+- **OS:** macOS / iOS / Linux / Android
+- **Architecture:** AArch64 / ARM64
 
 Each example directory is intentionally a standalone mini-project with exactly:
 
@@ -15,7 +15,12 @@ Each example directory is intentionally a standalone mini-project with exactly:
 The root `build.zig` does not build examples. That is deliberate: the example
 directories are meant to show the real commands needed to compile a release C
 target, compile a release Zig hook dylib, and inject that dylib with
-`DYLD_INSERT_LIBRARIES`.
+platform-appropriate sidecar loading.
+
+The example payloads now auto-select the constructor section:
+
+- Mach-O (`macOS`, `iOS`): `__DATA,__mod_init_func`
+- ELF (`Linux`, `Android`): `.init_array`
 
 Common build pattern from inside an example directory:
 
@@ -31,6 +36,11 @@ zig build-lib -dynamic -OReleaseFast -femit-bin=hook.dylib \
 DYLD_INSERT_LIBRARIES=$PWD/hook.dylib ./target
 ```
 
+That exact command sequence is still the canonical **macOS runtime smoke**.
+For Linux / iOS / Android deployment workflows, see:
+
+- `../docs/platform-workflows.md`
+
 Available examples:
 
 - `inline_hook_signal`: function-entry trap hook, expected output `result=42`
@@ -40,4 +50,5 @@ Available examples:
 - `prepatched_inline_hook`: use `prepatched.inline_hook(...)` on a binary that already contains `brk`, expected output `result=77`
 
 Each example README contains the exact commands and expected output. CI executes
-the same commands directly and compares stdout against those documented values.
+the macOS runtime commands directly and compares stdout against those
+documented values.

examples/inline_hook_signal/hook.zig

@@ -1,17 +1,31 @@
+const builtin = @import("builtin");
 const zighook = @import("zighook");
-const c = @cImport({
-    @cInclude("dlfcn.h");
-});
+
+const init_section = switch (builtin.os.tag) {
+    .macos, .ios => "__DATA,__mod_init_func",
+    .linux => ".init_array",
+    else => @compileError("example payload constructors are only implemented for Mach-O and ELF targets."),
+};
+
+extern fn dlsym(handle: ?*anyopaque, symbol: [*:0]const u8) ?*anyopaque;
+
+fn rtldDefault() ?*anyopaque {
+    return switch (builtin.os.tag) {
+        .macos, .ios => @ptrFromInt(@as(usize, @bitCast(@as(isize, -2)))),
+        .linux => null,
+        else => @compileError("RTLD_DEFAULT is only implemented for Mach-O and ELF targets."),
+    };
+}
 
 fn onHit(_: u64, ctx: *zighook.HookContext) callconv(.c) void {
     ctx.regs.named.x0 = 42;
 }
 
 fn install() callconv(.c) void {
-    const symbol = c.dlsym(c.RTLD_DEFAULT, "target_add");
+    const symbol = dlsym(rtldDefault(), "target_add");
     if (symbol == null) return;
     _ = zighook.inline_hook(@intFromPtr(symbol.?), onHit) catch {};
 }
 
 const InitFn = *const fn () callconv(.c) void;
-pub export const example_init: InitFn linksection("__DATA,__mod_init_func") = &install;
+pub export const example_init: InitFn linksection(init_section) = &install;

examples/instrument_no_original/hook.zig

@@ -1,17 +1,31 @@
+const builtin = @import("builtin");
 const zighook = @import("zighook");
-const c = @cImport({
-    @cInclude("dlfcn.h");
-});
+
+const init_section = switch (builtin.os.tag) {
+    .macos, .ios => "__DATA,__mod_init_func",
+    .linux => ".init_array",
+    else => @compileError("example payload constructors are only implemented for Mach-O and ELF targets."),
+};
+
+extern fn dlsym(handle: ?*anyopaque, symbol: [*:0]const u8) ?*anyopaque;
+
+fn rtldDefault() ?*anyopaque {
+    return switch (builtin.os.tag) {
+        .macos, .ios => @ptrFromInt(@as(usize, @bitCast(@as(isize, -2)))),
+        .linux => null,
+        else => @compileError("RTLD_DEFAULT is only implemented for Mach-O and ELF targets."),
+    };
+}
 
 fn onHit(_: u64, ctx: *zighook.HookContext) callconv(.c) void {
     ctx.regs.named.x0 = 99;
 }
 
 fn install() callconv(.c) void {
-    const symbol = c.dlsym(c.RTLD_DEFAULT, "target_add_patchpoint");
+    const symbol = dlsym(rtldDefault(), "target_add_patchpoint");
     if (symbol == null) return;
     _ = zighook.instrument_no_original(@intFromPtr(symbol.?), onHit) catch {};
 }
 
 const InitFn = *const fn () callconv(.c) void;
-pub export const example_init: InitFn linksection("__DATA,__mod_init_func") = &install;
+pub export const example_init: InitFn linksection(init_section) = &install;

examples/instrument_unhook_restore/hook.zig

@@ -1,7 +1,21 @@
+const builtin = @import("builtin");
 const zighook = @import("zighook");
-const c = @cImport({
-    @cInclude("dlfcn.h");
-});
+
+const init_section = switch (builtin.os.tag) {
+    .macos, .ios => "__DATA,__mod_init_func",
+    .linux => ".init_array",
+    else => @compileError("example payload constructors are only implemented for Mach-O and ELF targets."),
+};
+
+extern fn dlsym(handle: ?*anyopaque, symbol: [*:0]const u8) ?*anyopaque;
+
+fn rtldDefault() ?*anyopaque {
+    return switch (builtin.os.tag) {
+        .macos, .ios => @ptrFromInt(@as(usize, @bitCast(@as(isize, -2)))),
+        .linux => null,
+        else => @compileError("RTLD_DEFAULT is only implemented for Mach-O and ELF targets."),
+    };
+}
 
 var patchpoint_addr: u64 = 0;
 
@@ -10,7 +24,7 @@ fn onHit(_: u64, ctx: *zighook.HookContext) callconv(.c) void {
 }
 
 fn install() callconv(.c) void {
-    const symbol = c.dlsym(c.RTLD_DEFAULT, "target_add_patchpoint");
+    const symbol = dlsym(rtldDefault(), "target_add_patchpoint");
     if (symbol == null) return;
 
     patchpoint_addr = @intFromPtr(symbol.?);
@@ -23,4 +37,4 @@ pub export fn zighook_example_unhook() callconv(.c) void {
 }
 
 const InitFn = *const fn () callconv(.c) void;
-pub export const example_init: InitFn linksection("__DATA,__mod_init_func") = &install;
+pub export const example_init: InitFn linksection(init_section) = &install;