com.github.unidbg.arm.backend

Class UnicornBackend

java.lang.Object

com.github.unidbg.arm.backend.AbstractBackend

com.github.unidbg.arm.backend.UnicornBackend

All Implemented Interfaces:

Backend

public class UnicornBackend
extends AbstractBackend
implements Backend

Nested Class Summary

Nested classes/interfaces inherited from class com.github.unidbg.arm.backend.AbstractBackend

AbstractBackend.BreakPointImpl

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 Backend.context_save(long) and Backend.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.
long	getMemAllocatedSize() Returns the total virtual memory size allocated via Backend.mem_map(long, long, int).
long	getMemResidentSize() Returns the actual physical memory resident in RAM.
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.
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.
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.
boolean	removeBreakPoint(long address) Removes a previously added breakpoint.
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).

Methods inherited from class com.github.unidbg.arm.backend.AbstractBackend

checkVectorRegId, decodeSWI, enableVFP, getCpuFeatures, getPageSize, onInitialize, registerEmuCountHook, removeJitCodeCache, switchUserMode

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.github.unidbg.arm.backend.Backend

getCpuFeatures, getPageSize, isHypervisor, onInitialize, registerEmuCountHook, removeJitCodeCache

Method Detail

switchUserMode

public void switchUserMode()

Description copied from interface: Backend

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.

Specified by:

switchUserMode in interface Backend

enableVFP

public void enableVFP()

Description copied from interface: Backend

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.

Specified by:

enableVFP in interface Backend

reg_read_vector

public byte[] reg_read_vector(int regId)
                       throws BackendException

Description copied from interface: Backend

Reads a 128-bit SIMD/FP vector register.

Specified by:

reg_read_vector in interface Backend

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

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

Description copied from interface: Backend

Writes a 128-bit SIMD/FP vector register.

Specified by:

reg_write_vector in interface Backend

Parameters:

regId - vector register ID

vector - 16-byte array containing the value to write

Throws:

BackendException - if the register write fails

reg_read

public Number reg_read(int regId)
                throws BackendException

Description copied from interface: Backend

Reads the value of a CPU register.

Specified by:

reg_read in interface Backend

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_write

public void reg_write(int regId,
                      Number value)
               throws BackendException

Description copied from interface: Backend

Writes a value to a CPU register.

Specified by:

reg_write in interface Backend

Parameters:

regId - register ID

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

Throws:

BackendException - if the register write fails

mem_read

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

Description copied from interface: Backend

Reads a range of bytes from emulated memory.

Specified by:

mem_read in interface Backend

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

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

Description copied from interface: Backend

Writes a byte array into emulated memory.

Specified by:

mem_write in interface Backend

Parameters:

address - starting guest virtual address

bytes - data to write

Throws:

BackendException - if the address is unmapped or write fails

mem_map

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

Description copied from interface: Backend

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).

Specified by:

mem_map in interface Backend

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

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

Description copied from interface: Backend

Changes the access permissions of an existing memory mapping.

Specified by:

mem_protect in interface Backend

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

public void mem_unmap(long address,
                      long size)
               throws BackendException

Description copied from interface: Backend

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

Specified by:

mem_unmap in interface Backend

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

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

Description copied from interface: Backend

Adds a software breakpoint at the given address.

Specified by:

addBreakPoint in interface Backend

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

public boolean removeBreakPoint(long address)

Description copied from interface: Backend

Removes a previously added breakpoint.

Specified by:

removeBreakPoint in interface Backend

Parameters:

address - guest virtual address of the breakpoint to remove

Returns:

true if the breakpoint was found and removed

setSingleStep

public void setSingleStep(int singleStep)

Description copied from interface: Backend

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

Specified by:

setSingleStep in interface Backend

Parameters:

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

setFastDebug

public void setFastDebug(boolean fastDebug)

Description copied from interface: Backend

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

Specified by:

setFastDebug in interface Backend

Parameters:

fastDebug - true to enable fast debug mode

hook_add_new

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

Description copied from interface: Backend

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

Specified by:

hook_add_new in interface Backend

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

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

Description copied from interface: Backend

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

Specified by:

debugger_add in interface Backend

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

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

Description copied from interface: Backend

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

Specified by:

hook_add_new in interface Backend

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

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

Description copied from interface: Backend

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

Specified by:

hook_add_new in interface Backend

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

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

Description copied from interface: Backend

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

Specified by:

hook_add_new in interface Backend

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

public void hook_add_new(InterruptHook callback,
                         Object user_data)
                  throws BackendException

Description copied from interface: Backend

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

Specified by:

hook_add_new in interface Backend

Parameters:

callback - the interrupt hook callback

user_data - arbitrary user data passed to the callback

Throws:

BackendException - if hook registration fails

hook_add_new

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

Description copied from interface: Backend

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

Specified by:

hook_add_new in interface Backend

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

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

Description copied from interface: Backend

Starts emulation of machine code.

Specified by:

emu_start in interface Backend

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

public void emu_stop()
              throws BackendException

Description copied from interface: Backend

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

Specified by:

emu_stop in interface Backend

Throws:

BackendException - if the operation fails

destroy

public void destroy()
             throws BackendException

Description copied from interface: Backend

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.

Specified by:

destroy in interface Backend

Throws:

BackendException - if cleanup fails

context_restore

public void context_restore(long context)

Description copied from interface: Backend

Restores the CPU context from a previously saved snapshot.

Specified by:

context_restore in interface Backend

Parameters:

context - handle returned by Backend.context_alloc()

See Also:

Backend.context_save(long)

context_save

public void context_save(long context)

Description copied from interface: Backend

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

Specified by:

context_save in interface Backend

Parameters:

context - handle returned by Backend.context_alloc()

See Also:

Backend.context_restore(long)

context_alloc

public long context_alloc()

Description copied from interface: Backend

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

Specified by:

context_alloc in interface Backend

Returns:

an opaque handle representing the allocated context

See Also:

Backend.context_free(long)

context_free

public void context_free(long context)

Description copied from interface: Backend

Frees a previously allocated CPU context snapshot.

Specified by:

context_free in interface Backend

Parameters:

context - handle returned by Backend.context_alloc()

getMemAllocatedSize

public long getMemAllocatedSize()

Description copied from interface: Backend

Returns the total virtual memory size allocated via Backend.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().

Specified by:

getMemAllocatedSize in interface Backend

Overrides:

getMemAllocatedSize in class AbstractBackend

Returns:

total allocated memory in bytes

getMemResidentSize

public long getMemResidentSize()

Description copied from interface: Backend

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 Backend.getMemAllocatedSize().

Specified by:

getMemResidentSize in interface Backend

Overrides:

getMemResidentSize in class AbstractBackend

Returns:

resident memory in bytes