com.github.unidbg.arm.backend

Interface Backend

All Known Implementing Classes:

AbstractBackend, UnicornBackend

public interface Backend

Method Summary

Modifier and Type	Method and Description
BreakPoint	addBreakPoint(long address, BreakPointCallback callback, boolean thumb) Adds a software breakpoint at the given address.
long	context_alloc() Allocates a new CPU context snapshot that can be used with context_save(long) and context_restore(long).
void	context_free(long context) Frees a previously allocated CPU context snapshot.
void	context_restore(long context) Restores the CPU context from a previously saved snapshot.
void	context_save(long context) Saves the current CPU context (registers and internal metadata) into the given snapshot.
void	debugger_add(DebugHook callback, long begin, long end, Object user_data) Registers a debugger hook that handles breakpoints and single-step events within the given address range.
void	destroy() Releases all resources associated with this backend, including the underlying engine, mapped memory, and registered hooks.
void	emu_start(long begin, long until, long timeout, long count) Starts emulation of machine code.
void	emu_stop() Stops the current emulation.
void	enableVFP() Enables the VFP (Vector Floating-Point) and Advanced SIMD (NEON) coprocessor.
Map<String,Integer>	getCpuFeatures() Returns the CPU feature flags supported by the backend.
long	getMemAllocatedSize() Returns the total virtual memory size allocated via mem_map(long, long, int).
long	getMemResidentSize() Returns the actual physical memory resident in RAM.
int	getPageSize() Returns the memory page size used by this backend.
void	hook_add_new(BlockHook callback, long begin, long end, Object user_data) Registers a hook that is called at the beginning of each basic block within the given address range.
void	hook_add_new(CodeHook callback, long begin, long end, Object user_data) Registers a hook that is called for every instruction executed within the given address range.
void	hook_add_new(EventMemHook callback, int type, Object user_data) Registers a hook for invalid memory access events (unmapped or protection violations).
void	hook_add_new(InterruptHook callback, Object user_data) Registers a hook for CPU interrupt/exception events (SVC, HVC, etc.).
void	hook_add_new(ReadHook callback, long begin, long end, Object user_data) Registers a hook for memory read events within the given address range.
void	hook_add_new(WriteHook callback, long begin, long end, Object user_data) Registers a hook for memory write events within the given address range.
default boolean	isHypervisor() Returns whether this backend runs on Apple's Hypervisor.framework.
void	mem_map(long address, long size, int perms) Maps a region of emulated memory.
void	mem_protect(long address, long size, int perms) Changes the access permissions of an existing memory mapping.
byte[]	mem_read(long address, long size) Reads a range of bytes from emulated memory.
void	mem_unmap(long address, long size) Unmaps a previously mapped memory region and releases the associated host memory.
void	mem_write(long address, byte[] bytes) Writes a byte array into emulated memory.
void	onInitialize() Called after the backend is constructed to perform any additional initialization, such as mapping exception vector tables (hypervisor) or setting up initial CPU state.
byte[]	reg_read_vector(int regId) Reads a 128-bit SIMD/FP vector register.
Number	reg_read(int regId) Reads the value of a CPU register.
void	reg_write_vector(int regId, byte[] vector) Writes a 128-bit SIMD/FP vector register.
void	reg_write(int regId, Number value) Writes a value to a CPU register.
void	registerEmuCountHook(long emu_count) Registers a hook that stops emulation after the specified number of instructions have been executed.
boolean	removeBreakPoint(long address) Removes a previously added breakpoint.
void	removeJitCodeCache(long begin, long end) Invalidates the JIT code cache for the specified address range.
void	setFastDebug(boolean fastDebug) Toggles fast debug mode.
void	setSingleStep(int singleStep) Configures single-step execution.
void	switchUserMode() Switches the CPU to user mode (EL0/USR).

Method Detail

onInitialize

void onInitialize()

Called after the backend is constructed to perform any additional initialization, such as mapping exception vector tables (hypervisor) or setting up initial CPU state.

switchUserMode

void switchUserMode()

Switches the CPU to user mode (EL0/USR). On AArch32 this updates the CPSR mode bits; on AArch64 backends this is typically a no-op since only user-mode emulation is supported.

enableVFP

void enableVFP()

Enables the VFP (Vector Floating-Point) and Advanced SIMD (NEON) coprocessor. On AArch64 this sets the FPEN bits in CPACR_EL1; on AArch32 this configures C1_C0_2 and FPEXC registers.

reg_read

Number reg_read(int regId)
         throws BackendException

Reads the value of a CPU register.

Parameters:

regId - register ID, typically from unicorn.ArmConst or unicorn.Arm64Const

Returns:

the register value as a Number (Integer for 32-bit, Long for 64-bit)

Throws:

BackendException - if the register read fails

reg_read_vector

byte[] reg_read_vector(int regId)
                throws BackendException

Reads a 128-bit SIMD/FP vector register.

Parameters:

regId - vector register ID (e.g., UC_ARM64_REG_Q0..Q31 or UC_ARM_REG_D0..D15)

Returns:

16-byte array containing the vector register value

Throws:

BackendException - if the register read fails

reg_write_vector

void reg_write_vector(int regId,
                      byte[] vector)
               throws BackendException

Writes a 128-bit SIMD/FP vector register.

Parameters:

regId - vector register ID

vector - 16-byte array containing the value to write

Throws:

BackendException - if the register write fails

reg_write

void reg_write(int regId,
               Number value)
        throws BackendException

Writes a value to a CPU register.

Parameters:

regId - register ID

value - the value to write (truncated to 32-bit for AArch32)

Throws:

BackendException - if the register write fails

mem_read

byte[] mem_read(long address,
                long size)
         throws BackendException

Reads a range of bytes from emulated memory.

Parameters:

address - starting guest virtual address

size - number of bytes to read

Returns:

byte array containing the memory contents

Throws:

BackendException - if the address is unmapped or read fails

mem_write

void mem_write(long address,
               byte[] bytes)
        throws BackendException

Writes a byte array into emulated memory.

Parameters:

address - starting guest virtual address

bytes - data to write

Throws:

BackendException - if the address is unmapped or write fails

mem_map

void mem_map(long address,
             long size,
             int perms)
      throws BackendException

Maps a region of emulated memory. The address and size must be page-aligned. The backing host memory is allocated lazily via mmap(MAP_ANONYMOUS).

Parameters:

address - page-aligned starting guest virtual address

size - page-aligned size in bytes

perms - permissions bitmask (combination of UC_PROT_READ, UC_PROT_WRITE, UC_PROT_EXEC)

Throws:

BackendException - if alignment is invalid or mapping fails

mem_protect

void mem_protect(long address,
                 long size,
                 int perms)
          throws BackendException

Changes the access permissions of an existing memory mapping.

Parameters:

address - page-aligned starting guest virtual address

size - page-aligned size in bytes

perms - new permissions bitmask

Throws:

BackendException - if the region is not mapped or operation fails

mem_unmap

void mem_unmap(long address,
               long size)
        throws BackendException

Unmaps a previously mapped memory region and releases the associated host memory.

Parameters:

address - page-aligned starting guest virtual address

size - page-aligned size in bytes

Throws:

BackendException - if the region is not mapped or unmapping fails

addBreakPoint

BreakPoint addBreakPoint(long address,
                         BreakPointCallback callback,
                         boolean thumb)

Adds a software breakpoint at the given address.

Parameters:

address - guest virtual address to break on

callback - optional callback invoked when the breakpoint is hit, may be null

thumb - true if the breakpoint targets a Thumb instruction (AArch32 only)

Returns:

a BreakPoint handle that can be used to query or modify the breakpoint

removeBreakPoint

boolean removeBreakPoint(long address)

Removes a previously added breakpoint.

Parameters:

address - guest virtual address of the breakpoint to remove

Returns:

true if the breakpoint was found and removed

setSingleStep

void setSingleStep(int singleStep)

Configures single-step execution. After calling this, the emulator will break after executing the specified number of instructions.

Parameters:

singleStep - number of instructions to execute before breaking; 0 to disable

setFastDebug

void setFastDebug(boolean fastDebug)

Toggles fast debug mode. When enabled, the debugger hook skips per-instruction callbacks and only breaks on breakpoints or single-step events, improving performance.

Parameters:

fastDebug - true to enable fast debug mode

removeJitCodeCache

void removeJitCodeCache(long begin,
                        long end)
                 throws BackendException

Invalidates the JIT code cache for the specified address range. Should be called after modifying code in mapped memory to ensure the backend re-translates the affected region.

Parameters:

begin - start address of the range (inclusive)

end - end address of the range (exclusive)

Throws:

BackendException - if the operation fails

hook_add_new

void hook_add_new(CodeHook callback,
                  long begin,
                  long end,
                  Object user_data)
           throws BackendException

Registers a hook that is called for every instruction executed within the given address range.

Parameters:

callback - the code hook callback

begin - start address of the hook range (inclusive)

end - end address of the hook range (inclusive)

user_data - arbitrary user data passed to the callback

Throws:

BackendException - if hook registration fails

debugger_add

void debugger_add(DebugHook callback,
                  long begin,
                  long end,
                  Object user_data)
           throws BackendException

Registers a debugger hook that handles breakpoints and single-step events within the given address range.

Parameters:

callback - the debug hook callback

begin - start address of the hook range (inclusive)

end - end address of the hook range (inclusive)

user_data - arbitrary user data passed to the callback

Throws:

BackendException - if hook registration fails

hook_add_new

void hook_add_new(ReadHook callback,
                  long begin,
                  long end,
                  Object user_data)
           throws BackendException

Registers a hook for memory read events within the given address range.

Parameters:

callback - the read hook callback

begin - start address of the hook range (inclusive)

end - end address of the hook range (inclusive)

user_data - arbitrary user data passed to the callback

Throws:

BackendException - if hook registration fails

hook_add_new

void hook_add_new(WriteHook callback,
                  long begin,
                  long end,
                  Object user_data)
           throws BackendException

Registers a hook for memory write events within the given address range.

Parameters:

callback - the write hook callback

begin - start address of the hook range (inclusive)

end - end address of the hook range (inclusive)

user_data - arbitrary user data passed to the callback

Throws:

BackendException - if hook registration fails

hook_add_new

void hook_add_new(EventMemHook callback,
                  int type,
                  Object user_data)
           throws BackendException

Registers a hook for invalid memory access events (unmapped or protection violations).

Parameters:

callback - the event memory hook callback

type - bitmask of event types (e.g., UC_HOOK_MEM_READ_UNMAPPED, UC_HOOK_MEM_WRITE_UNMAPPED)

user_data - arbitrary user data passed to the callback

Throws:

BackendException - if hook registration fails

hook_add_new

void hook_add_new(InterruptHook callback,
                  Object user_data)
           throws BackendException

Registers a hook for CPU interrupt/exception events (SVC, HVC, etc.).

Parameters:

callback - the interrupt hook callback

user_data - arbitrary user data passed to the callback

Throws:

BackendException - if hook registration fails

hook_add_new

void hook_add_new(BlockHook callback,
                  long begin,
                  long end,
                  Object user_data)
           throws BackendException

Registers a hook that is called at the beginning of each basic block within the given address range.

Parameters:

callback - the block hook callback

begin - start address of the hook range (inclusive)

end - end address of the hook range (inclusive)

user_data - arbitrary user data passed to the callback

Throws:

BackendException - if hook registration fails

emu_start

void emu_start(long begin,
               long until,
               long timeout,
               long count)
        throws BackendException

Starts emulation of machine code.

Parameters:

begin - guest virtual address where emulation starts

until - guest virtual address where emulation stops (the instruction at this address is NOT executed)

timeout - maximum duration in microseconds; 0 for no limit

count - maximum number of instructions to emulate; 0 for no limit

Throws:

BackendException - if emulation fails

emu_stop

void emu_stop()
       throws BackendException

Stops the current emulation. Typically called from within a hook callback.

Throws:

BackendException - if the operation fails

destroy

void destroy()
      throws BackendException

Releases all resources associated with this backend, including the underlying engine, mapped memory, and registered hooks. The backend must not be used after this call.

Throws:

BackendException - if cleanup fails

context_restore

void context_restore(long context)

Restores the CPU context from a previously saved snapshot.

Parameters:

context - handle returned by context_alloc()

See Also:

context_save(long)

context_save

void context_save(long context)

Saves the current CPU context (registers and internal metadata) into the given snapshot.

Parameters:

context - handle returned by context_alloc()

See Also:

context_restore(long)

context_alloc

long context_alloc()

Allocates a new CPU context snapshot that can be used with context_save(long) and context_restore(long).

Returns:

an opaque handle representing the allocated context

See Also:

context_free(long)

context_free

void context_free(long context)

Frees a previously allocated CPU context snapshot.

Parameters:

context - handle returned by context_alloc()

getPageSize

int getPageSize()

Returns the memory page size used by this backend. Typically 4KB (dynarmic/kvm) or 16KB (hypervisor on Apple Silicon).

Returns:

page size in bytes

registerEmuCountHook

void registerEmuCountHook(long emu_count)

Registers a hook that stops emulation after the specified number of instructions have been executed. Used for instruction counting and preemptive scheduling.

Parameters:

emu_count - maximum number of instructions before the hook fires; must be > 0

getCpuFeatures

Map<String,Integer> getCpuFeatures()

Returns the CPU feature flags supported by the backend.

arm64_features hw.optional.floatingpoint hw.optional.AdvSIMD hw.optional.arm.AdvSIMD hw.optional.arm.FEAT_AES hw.optional.arm.FEAT_PMULL hw.optional.arm.FEAT_SHA1 hw.optional.arm.FEAT_SHA256 hw.optional.armv8_crc32 hw.optional.arm.FEAT_LSE hw.optional.arm.FEAT_FP16 hw.optional.arm.AdvSIMD_HPFPCvt hw.optional.arm.FEAT_RDM hw.optional.arm.FEAT_JSCVT hw.optional.arm.FEAT_FCMA hw.optional.arm.FEAT_LRCPC hw.optional.arm.FEAT_DPB hw.optional.arm.FEAT_SHA3 hw.optional.arm.FEAT_DotProd hw.optional.arm.FEAT_SHA512 hw.optional.arm.FEAT_FHM hw.optional.arm.FEAT_DIT hw.optional.arm.FEAT_LSE2 hw.optional.arm.FEAT_FlagM hw.optional.arm.FEAT_SSBS hw.optional.arm.FEAT_SB hw.optional.arm.FEAT_FlagM2 hw.optional.arm.FEAT_FRINTTS hw.optional.arm.FEAT_I8MM hw.optional.arm.FEAT_BF16 hw.optional.arm.FEAT_BTI

Returns:

a map of feature name to value (1 if supported, 0 otherwise)

getMemAllocatedSize

long getMemAllocatedSize()

Returns the total virtual memory size allocated via mem_map(long, long, int).

This is the sum of all mapped pages tracked by the backend's native memory hash table. For unicorn2, this is computed from uc_mem_regions().

Returns:

total allocated memory in bytes

getMemResidentSize

long getMemResidentSize()

Returns the actual physical memory resident in RAM.

On macOS/Linux, this uses mincore() to check which pages are actually backed by physical memory, since mmap(MAP_ANONYMOUS) allocates lazily. Only pages that have been read from or written to will be counted.

On Windows (dynarmic) and unicorn2 (QEMU-based), host memory pointers are not accessible, so this returns the same value as getMemAllocatedSize().

Returns:

resident memory in bytes

isHypervisor

default boolean isHypervisor()

Returns whether this backend runs on Apple's Hypervisor.framework. Hypervisor backends have hardware-accelerated execution but certain limitations (e.g., only one VM instance per process, AArch64 only).

Returns:

true if this is a hypervisor backend