unidbg

The Apple Silicon Hypervisor backend is an ARM64 emulator backend that utilizes the macOS Hypervisor.framework. It enables the emulation of Android and iOS ARM64 native libraries on Apple Silicon (M1/M2/M3/M4) at near-native speeds.

Supported Platform:

• macOS on ARM64 (Apple Silicon)
• Output artifact: osx_arm64/libhypervisor.dylib

To build the native hypervisor component, navigate to the native source directory and execute the build script:

cd backend/hypervisor/src/main/native/hypervisor
./build.sh

Build artifacts are output to src/main/resources/natives/osx_arm64/.

Depending on your build method, you will need the following:

Docker Build (Recommended)

• Docker with ARM64 platform support.

Native Build

• A Linux ARM64 host (e.g., Raspberry Pi 4B running CentOS-7-aarch64).
• GCC.
• JDK (ensure the JAVA_HOME environment variable is set).

Because the Hypervisor.framework requires specific entitlements, you must sign your java binary using ldid before execution. Run the following command from the backend/hypervisor/assets directory:

cd backend/hypervisor/assets
sudo ./ldid -M -Shypervisor.entitlements "$JAVA_HOME"/bin/java

Builds are managed via the build.sh script located in backend/kvm/src/main/native/.

Build artifacts are output to: src/main/resources/natives/linux_arm64/.

Available build modes:

• Docker (Default): Works on any host with Docker and ARM64 support.
• Native: Requires a Linux ARM64 host.
• Clean Docker: Rebuilds using Docker without using the cache.

cd backend/kvm/src/main/native

# Build via Docker (default, works on any host)
./build.sh docker

# Build natively (requires Linux ARM64 host)
./build.sh native

# Clean Docker build (--no-cache)
./build.sh --clean docker

You can track guest-side memory allocations (such as mmap, munmap, and brk) to identify leaks in emulated native code. Using try-with-resources with emulator.traceMemoryLeaks() will automatically print a leak report containing the guest ARM backtrace and the host Java stack trace when the block closes.

To access the leaks programmatically before the tracker closes, use the getLeaks() method which returns a List<AllocationRecord>.

try (MemoryTracker tracker = emulator.traceMemoryLeaks()) {
    module.callFunction(emulator, "targetFunction", arg1, arg2);
    List<AllocationRecord> leaks = tracker.getLeaks();
    assert leaks.isEmpty() : "Memory leak detected!";
}