PointerHook

PointerHook is an experimental pointer-slot instrumentation library for Android AArch64. It replaces a function-pointer slot with an assembly trampoline, exposes saved registers to a C++ callback, and supports returning to the caller or forwarding to the original function.

The intended use is native ABI analysis and instrumentation of owned or explicitly authorized software. Cross-architecture support is a future goal; the current implementation is AArch64 only.

Implementation and side effects

• IPointerHook.h defines the hook interface and RegContext; IPointerHook.cpp implements slot access and trampoline allocation.
• PointerHookManager.h coordinates installation and restoration. Its lock does not establish callback quiescence.
• ph_arm64_glue.s and ph_trampoline_pool.s implement the assembly boundary.
• example.cpp is compiled into libptrhook.so. Its constructor starts a SelfTest worker when the library loads; the target is not an inert core library.
• Memory-channel initialization can temporarily change process dumpability. There is no built-in target-authorization policy.

Build

Requirements: CMake 3.22.1 or newer, Ninja, Android NDK. CMake selects arm64-v8a, API 21 and C++20.

export NDK_HOME=/path/to/android-ndk
cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

Output: build/libptrhook.so. No third-party submodules are required by this target.

Known limitations

CallOrigWithContext<float> uses the double-return helper and can misinterpret the return register. Aggregate, HFA, long-double, stack-spill, x18, PAC and BTI compatibility require explicit ABI validation. The address mask is a heuristic, not pointer authentication.

Destruction of an installed hook can reach a pure virtual method. Restoration failures and calls already inside a trampoline lack a complete retirement protocol. Safe concurrent destruction and DSO unloading are not supported guarantees.

Release and Debug compilation passed with NDK r29 in the repository review. A compile-only float-return check confirms the ABI defect. SelfTest is a limited sentinel test, not a complete ABI suite. No Android runtime test was executed in that review.

Project documentation

• Research scope
• Lab guide and verification limits
• Data handling
• Dependency provenance
• Security reporting
• Contributing

First-party code is MIT licensed. Research and maintenance guidance does not amend that license. Third-party components retain their own terms.

No repository security certification or platform access approval is claimed.