Skip to content

AndroCorn Documentation

AndroCorn is an advanced, kernel-free user-space emulation framework for Android native ARM/ARM64 libraries built on top of the Unicorn Engine.

It provides a fully simulated Android OS user-space environment, allowing you to load and execute heavily obfuscated .so files, anti-tamper protectors, and cryptors seamlessly on Windows, macOS, and Linux.


Key Highlights of Version 2.0

  • Zero God-Objects: Modular, context-driven design where interrupts and syscalls operate on pure stateless abstractions.
  • Deterministic Memory Mapping: Strict segmentation between emulator-internal storage (0x60...), process [heap] (0x70...), dynamic mmap (0x80...), and the stack (0x10...).
  • POSIX VFS with In-Memory IPC: Full object-oriented filesystem node architecture with support for character devices (/dev/null, /dev/urandom, /dev/binder, /dev/ptmx), dynamic procfs (/proc/self/maps), and non-blocking VirtualPipe.
  • Auto-Arity JNI Dispatcher: Dynamic argument extraction supporting methods with arbitrary parameter counts without hardcoded limits.
  • Modern Hooking & Forensics: Integrated InlineHook, caller-context MemoryWatchpoint, and block-level CrossModuleTracer.
  • State Rollback: Instant zero-copy memory snapshots for fuzzing and repetitive native function evaluation.

Module Index

androidemu.core.emulator.Emulator

Main class of Emulator. Store everything you need.

Parameters:

Name Type Description Default
vfs_root str

The root of the virtual file system

'vfs'
environment Dict

The configuration package

DEFAULT_PACKAGE
vfp_inst_set bool

Enable VFP instructions

True
arch int

Current architecture (32 or 64 bit). 1 (ARM32) or 2 (ARM64) (default: 1)

ARCH_ARM32
init_sys_libs bool

Initialize system libraries

True
Source code in androidemu/core/emulator.py
class Emulator:
    """
    Main class of Emulator. Store everything you need.

    :param vfs_root: The root of the virtual file system
    :param environment: The configuration package
    :param vfp_inst_set: Enable VFP instructions
    :param arch: Current architecture (32 or 64 bit). 1 (ARM32) or 2 (ARM64) (default: 1)
    :param init_sys_libs: Initialize system libraries
    """
    def __init__(
        self,
        vfs_root: str = "vfs",
        environment: Dict = DEFAULT_PACKAGE,
        vfp_inst_set: bool = True,
        arch: int = emu_const.ARCH_ARM32,
        init_sys_libs: bool = True,
        **kwargs: Any,
    ):
        self.arch = arch
        self.vfs_root = vfs_root

        # 1. State, Configuration & Properties
        self._init_core_state(environment)
        self._init_properties()

        # 2. CPU & Engine
        self._init_engine()

        # 3. Memory Subsystem
        self._init_memory_layout(vfp_inst_set)

        # 4. TLS & Linker
        self._init_linker()

        # 5. VFS Engine
        self.vfs = VFSManager(self)

        # 6. Process Context & Base Environment (PCB, app_process, vectors)
        self._init_process_and_vfs()

        # 7. Execution Subsystem (Scheduler, Syscalls, SysInit)
        self._init_execution_subsystem()

        # 8. Hooks
        self._init_hooks()

        # 9. Java Runtime
        self._init_java_runtime()

        # 10. System Libraries
        if init_sys_libs:
            self._init_syslibs()

        logging.info("[+] Emulator ready. Process PID: %d", self.pcb.pid)

    def _init_core_state(self, environment: Dict) -> None:
            set_types(self.arch)
            self.config = Config(environment)
            self.pcb = ProcessControlBlock(self.config)

    def _init_properties(self) -> None:
        prop_bin = Path(self.vfs_root) / "dev/__properties__"
        if not prop_bin.exists():
            raise FileNotFoundError(
                f"Android property file not found at '{prop_bin}'. "
                "Ensure '/dev/__properties__' exists in your VFS."
            )
        prop_txt = Path(self.vfs_root) / "system/build.prop"
        self.system_properties = (
            parse_prop_file(prop_txt) if prop_txt.exists() else {}
        )

    def _init_engine(self) -> None:
        if self.arch == emu_const.ARCH_ARM32:
            self.mu = Uc(UC_ARCH_ARM, UC_MODE_ARM)
        elif self.arch == emu_const.ARCH_ARM64:
            self.mu = Uc(UC_ARCH_ARM64, UC_MODE_ARM)
        else:
            raise ValueError(f"Unsupported arch identifier: {self.arch}")

        self.registers = RegistersMapping(self.mu, self.arch)
        self.time_manager = TimeManager(start_timestamp=self.config.pkg.start_timestamp)
        self.tls_utils = BionicTLSUtils(self.mu, self.registers)
        self._cpu_utils = CPU_Utils(self.mu)

    def _init_memory_layout(self, vfp_inst_set: bool) -> None:
        self.memory = MemoryMap(
            self.mu,
            config.EMU_HEAP_BASE,
            config.EMU_HEAP_BASE + config.EMU_HEAP_SIZE,
        )

        self.memory.map(config.ASM_CODE, config.PAGE_SIZE, UC_PROT_WRITE | UC_PROT_EXEC)
        self.memory.map(config.STACK_ADDR, config.STACK_SIZE, UC_PROT_READ | UC_PROT_WRITE)
        self.memory.map(config.STOP_MEMORY_BASE, config.STOP_MEMORY_SIZE, UC_PROT_READ | UC_PROT_EXEC)
        self.memory.map(config.BRIDGE_MEMORY_BASE, config.BRIDGE_MEMORY_SIZE, UC_PROT_READ | UC_PROT_WRITE | UC_PROT_EXEC)
        self.memory.map(config.JMETHOD_ID_BASE, 0x2000, UC_PROT_READ | UC_PROT_WRITE | UC_PROT_EXEC)

        self.memory.map(config.BRK_BASE, config.BRK_SIZE, UC_PROT_READ | UC_PROT_WRITE)

        if vfp_inst_set:
            if self.arch == emu_const.ARCH_ARM32:
                self._cpu_utils._enable_vfp32()
            elif self.arch == emu_const.ARCH_ARM64:
                self._cpu_utils._enable_vfp64()

        self.registers.v_sp = (config.STACK_ADDR + config.STACK_SIZE) - 0x4000

    def _init_linker(self) -> None:
        self.tls_state: "BionicTLSInitialization" = create_tls_backend(
            self.memory, self.mu, self.registers
        )
        self.linker = AndroidLinker(self, self.vfs_root)

    def _init_process_and_vfs(self) -> None:
        # self.pcb = ProcessControlBlock(self.mu, self.config, self.ctx)
        self._setup_env()

    def _setup_env(self) -> None:
        is_64 = (self.arch == emu_const.ARCH_ARM64)

        app_process = "/system/bin/app_process64" if is_64 else "/system/bin/app_process32"
        linker_bin = "/system/bin/linker64" if is_64 else "/system/bin/linker"

        if not is_64:
            vectors = os.path.join(self.vfs_root, "system", "lib", "vectors")
            if os.path.exists(vectors):
                node = self.vfs.get_node("/system/lib/vectors")
                if node:
                    self.memory.map(config.VECTORS_BASE, 0x1000, UC_PROT_EXEC | UC_PROT_READ, node=node, offset=0)

        node_app = self.vfs.get_node(app_process)
        if node_app:
            sz = node_app.get_size()
            self.memory.map(config.APP_PROCESS_BASE, sz, UC_PROT_EXEC | UC_PROT_READ, node=node_app, offset=0)

        node_linker = self.vfs.get_node(linker_bin)
        if node_linker:
            sz = node_linker.get_size()
            self.memory.map(config.LINKER_BASE, sz, UC_PROT_EXEC | UC_PROT_READ, node=node_linker, offset=0)
            logging.debug(f"[+] Loaded {linker_bin} into memory at 0x{config.LINKER_BASE:08X}")

    def _init_execution_subsystem(self) -> None:
        self.scheduler = Scheduler(
            self.mu, self.registers, self.memory,
            self.pcb, self.time_manager, self.vfs
        )
        self._syscall_handler = SyscallsHandler(self)
        SysInit(self, self._syscall_handler.set_handler)

    def _init_hooks(self) -> None:
        self._hooker = Hooker(
            self,
            self.mu,
            config.BRIDGE_MEMORY_BASE,
            config.BRIDGE_MEMORY_SIZE,
        )
        self.hook_manager = HookManager(self)
        HooksInitializer(self)

    def _init_java_runtime(self) -> None:
        self.java_classloader = JavaClassLoader()
        self._init_base_java_classes()
        self.java_vm = JavaVM(self, self.java_classloader, self._hooker)

    def _init_base_java_classes(self) -> None:
        from ..java.classes.java.lang.clazz import Class
        from ..java.classes.java.lang.object import Object
        from ..java.classes.java.lang.string import String
        from ..java.classes.java.lang.system import System
        from ..java.classes.java.lang.types import Boolean, Integer, Long, Float
        from ..java.classes.java.lang.array import (
            Array, ByteArray, ObjectArray, ClassArray, StringArray, IntArray
        )
        from ..java.classes.java.lang.reflect.constructor import Constructor
        from ..java.classes.java.lang.reflect.executable import Executable
        from ..java.classes.java.lang.reflect.field import Field, AccessibleObject
        from ..java.classes.java.lang.reflect.method import Method
        from ..java.classes.java.lang.reflect.proxy import Proxy
        from ..java.classes.java.io.file import File
        from ..java.classes.java.util.list import List as JavaList
        from ..java.classes.java.util.map import HashMap
        from ..java.classes.java.util.set_list import Set as JavaSet
        from ..java.classes.java.util.time_unit import TimeUnit

        base_classes = [
            Class, Object, String, System,
            Boolean, Integer, Long, Float,
            Array, ByteArray, ObjectArray, ClassArray, StringArray, IntArray,
            AccessibleObject, Executable, Constructor, Field, Method, Proxy,
            File, JavaList, HashMap, JavaSet, TimeUnit,
        ]

        for clz in base_classes:
            self.java_classloader.add_class(clz)

    def _init_syslibs(self) -> None:
        self.load_library("libc.so")

    def register_class(self, clazz: JavaClassDef) -> None:
        self.java_classloader.add_class(clazz)

    def register_classes(self, *classes: Any) -> None:
        for item in classes:
            if isinstance(item, (list, tuple, set)):
                for clz in item:
                    self.java_classloader.add_class(clz)
            else:
                self.java_classloader.add_class(item)

    def sys_reg_read(self, reg: int) -> int:
        """
        Read Non-Implement System Registers

        :type reg: int

        :param reg: The register to read

        :return: The value of the register
        """
        return self._cpu_utils._read_sys_reg(reg)

    def sys_reg_write(self, reg: int, val: int) -> None:
        """
        Write Non-Implement System Registers

        :type reg: int
        :type val: int

        :param reg: The register to write
        :param val: The value to write

        :return: None
        """
        return self._cpu_utils._write_sys_reg(reg, val)

    def load_library(
        self, filename: str, do_init: bool = True, main_lib: bool = False
    ) -> "Module":
        """
        Load a dynamic library from disk.

        :type filename: str
        :type do_init: bool
        :type main_lib: bool

        :param filename: The name of the library (e.g. libfoo.so)
        :param do_init: Whether to initialize the library with init_array
        :param main_lib: Whether this is the main executable

        :return: The loaded module
        """
        return self.linker.load_module(filename, do_init, main_lib)

    def get_library(self, filename: str) -> Optional["Module"]:
        """
        Get a loaded library.

        :type filename: str

        :param filename: The name of the library
        :return: The loaded module, or None if the library is not loaded.
        """
        if self.linker.find_module_by_name(filename) is None:
            logging.error("Library '%s' is not loaded!", filename)
            return None
        return self.load_library(filename)

    def call_symbol(
        self, module: "Module", symbol_name: str, *argv: Any
    ) -> Optional[int]:
        """
        Call a symbol in a module.

        :type module: Module
        :type symbol_name: str

        :param module: The module containing the symbol
        :param symbol_name: The name of the symbol
        :param *argv: The arguments to pass to the symbol
        :return: The return value of the symbol
        """
        symbol_addr = module.find_symbol(symbol_name)
        if symbol_addr is None:
            logging.error(
                "Unable to find symbol '%s' in module '%s'.",
                symbol_name,
                module.filename,
            )
            return None
        return self.call_native(symbol_addr, *argv)

    def call_function(
        self, module: "Module", function_name: str, *argv: Any
    ) -> Optional[int]:
        """
        Use it for non-export functions, like in libc

        :type module:        Module
        :type function_name: str

        :param module: The module containing the function
        :param function_name: The name of the function
        :param *argv: The arguments to pass to the function
        :return: The return value of the function
        """
        symbol_addr = module.find_function(function_name)
        if symbol_addr is None:
            logging.error(
                "Unable to find function '%s' in module '%s'.",
                function_name,
                module.filename,
            )
            return None
        return self.call_native(symbol_addr, *argv)

    def call_native(self, addr: int, *argv: Any) -> Optional[int]:
        """
        Call a native function with the given address and arguments.

        :type addr: int

        :param addr: The address of the native function
        :param *argv: The arguments to pass to the native function
        :return: The return value of the native function
        """
        assert addr is not None, "call addr is None!"

        saved_sp = self.mu.reg_read(self.registers.sp)

        if not self.scheduler._is_running:
            try:
                self.registers.write_args(self.java_vm, *argv)
                self.scheduler.exec(addr)
                return self.mu.reg_read(self.registers.ret)
            finally:
                self.mu.reg_write(self.registers.sp, saved_sp)
        else:
            saved_context = self.mu.context_save()
            interrupted_pc = self.mu.reg_read(self.registers.pc)

            try:
                smb = config.STOP_MEMORY_BASE
                self.registers.write_args(self.java_vm, *argv)
                self.mu.reg_write(self.registers.pc, addr)
                self.mu.reg_write(self.registers.lr, smb)

                logging.debug("Nested call to 0x%x from 0x%x", addr, interrupted_pc)
                self.mu.emu_start(addr, smb, 0, 0)

                if self.mu.reg_read(self.registers.pc) != smb:
                    logging.warning(
                        "Nested call to 0x%x was INTERRUPTED before completion!", addr
                    )

                return self.mu.reg_read(self.registers.ret)

            except UcError as e:
                logging.error("Crash in nested call to 0x%x: %s", addr, e)
                raise
            finally:
                self.mu.context_restore(saved_context)
                self.mu.reg_write(self.registers.sp, saved_sp)

    def call_native_return_2reg(self, addr: int, *argv: Any) -> Optional[int]:
        """
        The 8 (or 16) byte return value is split across two registers.
        The high (4 or 8) bytes are stored in R1 (X1) and the low (4 or 8) bytes are stored in the return value.
        This function combines the two parts of the return value into a single 8 (or 16) byte value.
        :param addr: The address of the native function
        :param *argv: The arguments to pass to the native function
        :return: The return value of the native function
        """
        res = self.call_native(addr, *argv)
        if res is None:
            return None

        off = 32 if self.arch == emu_const.ARCH_ARM32 else 64
        res_high = self.registers.v_reg_1

        return (res_high << off) | res

call_function(module, function_name, *argv)

Use it for non-export functions, like in libc

Parameters:

Name Type Description Default
module Module

The module containing the function

required
function_name str

The name of the function

required
*argv Any

The arguments to pass to the function

()

Returns:

Type Description
Optional[int]

The return value of the function

Source code in androidemu/core/emulator.py
def call_function(
    self, module: "Module", function_name: str, *argv: Any
) -> Optional[int]:
    """
    Use it for non-export functions, like in libc

    :type module:        Module
    :type function_name: str

    :param module: The module containing the function
    :param function_name: The name of the function
    :param *argv: The arguments to pass to the function
    :return: The return value of the function
    """
    symbol_addr = module.find_function(function_name)
    if symbol_addr is None:
        logging.error(
            "Unable to find function '%s' in module '%s'.",
            function_name,
            module.filename,
        )
        return None
    return self.call_native(symbol_addr, *argv)

call_native(addr, *argv)

Call a native function with the given address and arguments.

Parameters:

Name Type Description Default
addr int

The address of the native function

required
*argv Any

The arguments to pass to the native function

()

Returns:

Type Description
Optional[int]

The return value of the native function

Source code in androidemu/core/emulator.py
def call_native(self, addr: int, *argv: Any) -> Optional[int]:
    """
    Call a native function with the given address and arguments.

    :type addr: int

    :param addr: The address of the native function
    :param *argv: The arguments to pass to the native function
    :return: The return value of the native function
    """
    assert addr is not None, "call addr is None!"

    saved_sp = self.mu.reg_read(self.registers.sp)

    if not self.scheduler._is_running:
        try:
            self.registers.write_args(self.java_vm, *argv)
            self.scheduler.exec(addr)
            return self.mu.reg_read(self.registers.ret)
        finally:
            self.mu.reg_write(self.registers.sp, saved_sp)
    else:
        saved_context = self.mu.context_save()
        interrupted_pc = self.mu.reg_read(self.registers.pc)

        try:
            smb = config.STOP_MEMORY_BASE
            self.registers.write_args(self.java_vm, *argv)
            self.mu.reg_write(self.registers.pc, addr)
            self.mu.reg_write(self.registers.lr, smb)

            logging.debug("Nested call to 0x%x from 0x%x", addr, interrupted_pc)
            self.mu.emu_start(addr, smb, 0, 0)

            if self.mu.reg_read(self.registers.pc) != smb:
                logging.warning(
                    "Nested call to 0x%x was INTERRUPTED before completion!", addr
                )

            return self.mu.reg_read(self.registers.ret)

        except UcError as e:
            logging.error("Crash in nested call to 0x%x: %s", addr, e)
            raise
        finally:
            self.mu.context_restore(saved_context)
            self.mu.reg_write(self.registers.sp, saved_sp)

call_native_return_2reg(addr, *argv)

The 8 (or 16) byte return value is split across two registers. The high (4 or 8) bytes are stored in R1 (X1) and the low (4 or 8) bytes are stored in the return value. This function combines the two parts of the return value into a single 8 (or 16) byte value.

Parameters:

Name Type Description Default
addr int

The address of the native function

required
*argv Any

The arguments to pass to the native function

()

Returns:

Type Description
Optional[int]

The return value of the native function

Source code in androidemu/core/emulator.py
def call_native_return_2reg(self, addr: int, *argv: Any) -> Optional[int]:
    """
    The 8 (or 16) byte return value is split across two registers.
    The high (4 or 8) bytes are stored in R1 (X1) and the low (4 or 8) bytes are stored in the return value.
    This function combines the two parts of the return value into a single 8 (or 16) byte value.
    :param addr: The address of the native function
    :param *argv: The arguments to pass to the native function
    :return: The return value of the native function
    """
    res = self.call_native(addr, *argv)
    if res is None:
        return None

    off = 32 if self.arch == emu_const.ARCH_ARM32 else 64
    res_high = self.registers.v_reg_1

    return (res_high << off) | res

call_symbol(module, symbol_name, *argv)

Call a symbol in a module.

Parameters:

Name Type Description Default
module Module

The module containing the symbol

required
symbol_name str

The name of the symbol

required
*argv Any

The arguments to pass to the symbol

()

Returns:

Type Description
Optional[int]

The return value of the symbol

Source code in androidemu/core/emulator.py
def call_symbol(
    self, module: "Module", symbol_name: str, *argv: Any
) -> Optional[int]:
    """
    Call a symbol in a module.

    :type module: Module
    :type symbol_name: str

    :param module: The module containing the symbol
    :param symbol_name: The name of the symbol
    :param *argv: The arguments to pass to the symbol
    :return: The return value of the symbol
    """
    symbol_addr = module.find_symbol(symbol_name)
    if symbol_addr is None:
        logging.error(
            "Unable to find symbol '%s' in module '%s'.",
            symbol_name,
            module.filename,
        )
        return None
    return self.call_native(symbol_addr, *argv)

get_library(filename)

Get a loaded library.

Parameters:

Name Type Description Default
filename str

The name of the library

required

Returns:

Type Description
Optional[Module]

The loaded module, or None if the library is not loaded.

Source code in androidemu/core/emulator.py
def get_library(self, filename: str) -> Optional["Module"]:
    """
    Get a loaded library.

    :type filename: str

    :param filename: The name of the library
    :return: The loaded module, or None if the library is not loaded.
    """
    if self.linker.find_module_by_name(filename) is None:
        logging.error("Library '%s' is not loaded!", filename)
        return None
    return self.load_library(filename)

load_library(filename, do_init=True, main_lib=False)

Load a dynamic library from disk.

Parameters:

Name Type Description Default
filename str

The name of the library (e.g. libfoo.so)

required
do_init bool

Whether to initialize the library with init_array

True
main_lib bool

Whether this is the main executable

False

Returns:

Type Description
Module

The loaded module

Source code in androidemu/core/emulator.py
def load_library(
    self, filename: str, do_init: bool = True, main_lib: bool = False
) -> "Module":
    """
    Load a dynamic library from disk.

    :type filename: str
    :type do_init: bool
    :type main_lib: bool

    :param filename: The name of the library (e.g. libfoo.so)
    :param do_init: Whether to initialize the library with init_array
    :param main_lib: Whether this is the main executable

    :return: The loaded module
    """
    return self.linker.load_module(filename, do_init, main_lib)

sys_reg_read(reg)

Read Non-Implement System Registers

Parameters:

Name Type Description Default
reg int

The register to read

required

Returns:

Type Description
int

The value of the register

Source code in androidemu/core/emulator.py
def sys_reg_read(self, reg: int) -> int:
    """
    Read Non-Implement System Registers

    :type reg: int

    :param reg: The register to read

    :return: The value of the register
    """
    return self._cpu_utils._read_sys_reg(reg)

sys_reg_write(reg, val)

Write Non-Implement System Registers

Parameters:

Name Type Description Default
reg int

The register to write

required
val int

The value to write

required

Returns:

Type Description
None

None

Source code in androidemu/core/emulator.py
def sys_reg_write(self, reg: int, val: int) -> None:
    """
    Write Non-Implement System Registers

    :type reg: int
    :type val: int

    :param reg: The register to write
    :param val: The value to write

    :return: None
    """
    return self._cpu_utils._write_sys_reg(reg, val)

androidemu.core.registers.RegistersMapping

Source code in androidemu/core/registers.py
class RegistersMapping:
    if TYPE_CHECKING:
        v_reg_0: int;  v_reg_1: int;  v_reg_2: int;  v_reg_3: int
        v_reg_4: int;  v_reg_5: int;  v_reg_6: int;  v_reg_7: int
        v_reg_8: int;  v_reg_9: int;  v_reg_10: int; v_reg_11: int
        v_reg_12: int; v_reg_13: int; v_reg_14: int; v_reg_15: int
        v_reg_16: int; v_reg_17: int; v_reg_18: int; v_reg_19: int
        v_reg_20: int; v_reg_21: int; v_reg_22: int; v_reg_23: int
        v_reg_24: int; v_reg_25: int; v_reg_26: int; v_reg_27: int
        v_reg_28: int; v_reg_29: int; v_reg_30: int

        v_pc: int
        v_sp: int
        v_lr: int
        v_tls: int
        v_flags: int
        v_ret: int
        v_syscall: int

    def __init__(self, mu: Optional['Uc'], arch: int) -> None:
        self._arch = arch
        self._mu = mu
        self._ptr_sz = 8 if arch == emu_const.ARCH_ARM64 else 4
        self._fmt_ptr = "<Q" if arch == emu_const.ARCH_ARM64 else "<I"

        self._name_to_id = {}

        if arch == emu_const.ARCH_ARM32:
            self.reg_0   = UC_ARM_REG_R0
            self.reg_1   = UC_ARM_REG_R1
            self.reg_2   = UC_ARM_REG_R2
            self.reg_3   = UC_ARM_REG_R3
            self.reg_4   = UC_ARM_REG_R4
            self.reg_5   = UC_ARM_REG_R5
            self.reg_6   = UC_ARM_REG_R6
            self.reg_7   = UC_ARM_REG_R7
            self.reg_8   = UC_ARM_REG_R8
            self.reg_9   = UC_ARM_REG_R9
            self.reg_10  = UC_ARM_REG_R10
            self.reg_11  = UC_ARM_REG_R11
            self.reg_12  = UC_ARM_REG_R12
            self.reg_13  = UC_ARM_REG_R13
            self.reg_14  = UC_ARM_REG_R14
            self.reg_15  = UC_ARM_REG_R15

            self.pc      = UC_ARM_REG_PC
            self.sp      = UC_ARM_REG_SP
            self.lr      = UC_ARM_REG_LR
            self.tls     = UC_ARM_REG_C13_C0_3
            self.flags   = UC_ARM_REG_CPSR

            self.default = [
                UC_ARM_REG_R0, UC_ARM_REG_R1, UC_ARM_REG_R2, UC_ARM_REG_R3,
                UC_ARM_REG_R4, UC_ARM_REG_R5, UC_ARM_REG_R6, UC_ARM_REG_R7,
                UC_ARM_REG_R8, UC_ARM_REG_R9, UC_ARM_REG_R10, UC_ARM_REG_R11,
                UC_ARM_REG_R12, UC_ARM_REG_LR
            ]
            self.arguments = [
                UC_ARM_REG_R0, UC_ARM_REG_R1, UC_ARM_REG_R2, UC_ARM_REG_R3
            ]
            self.ret     = self.reg_0
            self.syscall = self.reg_7

            for i in range(16):
                self._name_to_id[f"reg_{i}"] = getattr(self, f"reg_{i}")

            self._name_to_id["pc"] = self.pc
            self._name_to_id["sp"] = self.sp
            self._name_to_id["lr"] = self.lr
            self._name_to_id["tls"] = self.tls
            self._name_to_id["flags"] = self.flags
            self._name_to_id["ret"] = self.ret
            self._name_to_id["syscall"] = self.syscall

        elif arch == emu_const.ARCH_ARM64:
            self.reg_0   = UC_ARM64_REG_X0
            self.reg_1   = UC_ARM64_REG_X1
            self.reg_2   = UC_ARM64_REG_X2
            self.reg_3   = UC_ARM64_REG_X3
            self.reg_4   = UC_ARM64_REG_X4
            self.reg_5   = UC_ARM64_REG_X5
            self.reg_6   = UC_ARM64_REG_X6
            self.reg_7   = UC_ARM64_REG_X7
            self.reg_8   = UC_ARM64_REG_X8
            self.reg_9   = UC_ARM64_REG_X9
            self.reg_10  = UC_ARM64_REG_X10
            self.reg_11  = UC_ARM64_REG_X11
            self.reg_12  = UC_ARM64_REG_X12
            self.reg_13  = UC_ARM64_REG_X13
            self.reg_14  = UC_ARM64_REG_X14
            self.reg_15  = UC_ARM64_REG_X15
            self.reg_16  = UC_ARM64_REG_X16
            self.reg_17  = UC_ARM64_REG_X17
            self.reg_18  = UC_ARM64_REG_X18
            self.reg_19  = UC_ARM64_REG_X19
            self.reg_20  = UC_ARM64_REG_X20
            self.reg_21  = UC_ARM64_REG_X21
            self.reg_22  = UC_ARM64_REG_X22
            self.reg_23  = UC_ARM64_REG_X23
            self.reg_24  = UC_ARM64_REG_X24
            self.reg_25  = UC_ARM64_REG_X25
            self.reg_26  = UC_ARM64_REG_X26
            self.reg_27  = UC_ARM64_REG_X27
            self.reg_28  = UC_ARM64_REG_X28
            self.reg_29  = UC_ARM64_REG_X29
            self.reg_30  = UC_ARM64_REG_X30

            self.pc      = UC_ARM64_REG_PC
            self.sp      = UC_ARM64_REG_SP
            self.lr      = UC_ARM64_REG_X30
            self.tls     = UC_ARM64_REG_TPIDR_EL0
            self.flags   = UC_ARM64_REG_NZCV

            self.default = [
                UC_ARM64_REG_X0,  UC_ARM64_REG_X1,  UC_ARM64_REG_X2,  UC_ARM64_REG_X3,
                UC_ARM64_REG_X4,  UC_ARM64_REG_X5,  UC_ARM64_REG_X6,  UC_ARM64_REG_X7,
                UC_ARM64_REG_X8,  UC_ARM64_REG_X9,  UC_ARM64_REG_X10, UC_ARM64_REG_X11,
                UC_ARM64_REG_X12, UC_ARM64_REG_X13, UC_ARM64_REG_X14, UC_ARM64_REG_X15,
                UC_ARM64_REG_X16, UC_ARM64_REG_X17, UC_ARM64_REG_X18, UC_ARM64_REG_X19,
                UC_ARM64_REG_X20, UC_ARM64_REG_X21, UC_ARM64_REG_X22, UC_ARM64_REG_X23,
                UC_ARM64_REG_X24, UC_ARM64_REG_X25, UC_ARM64_REG_X26, UC_ARM64_REG_X27,
                UC_ARM64_REG_X28, UC_ARM64_REG_X29, UC_ARM64_REG_X30
            ]
            self.arguments = [
                UC_ARM64_REG_X0, UC_ARM64_REG_X1, UC_ARM64_REG_X2, UC_ARM64_REG_X3,
                UC_ARM64_REG_X4, UC_ARM64_REG_X5, UC_ARM64_REG_X6, UC_ARM64_REG_X7
            ]
            self.ret     = self.reg_0
            self.syscall = self.reg_8

            for i in range(31):
                self._name_to_id[f"reg_{i}"] = getattr(self, f"reg_{i}")

            self._name_to_id["pc"] = self.pc
            self._name_to_id["sp"] = self.sp
            self._name_to_id["lr"] = self.lr
            self._name_to_id["tls"] = self.tls
            self._name_to_id["flags"] = self.flags
            self._name_to_id["ret"] = self.ret
            self._name_to_id["syscall"] = self.syscall
        else:
            raise RuntimeError("Wrong arch identifier. Expected 1 (ARM32) or 2 (ARM64)")

    def set_mu(self, mu: 'Uc') -> None:
        self._mu = mu

    def __getattr__(self, name: str):
        if name.startswith("v_"):
            lookup = name[2:].lower()
            if "_name_to_id" in self.__dict__ and lookup in self._name_to_id:
                if self._mu is None:
                    raise RuntimeError("Unicorn instance (_mu) is not set in RegistersMapping!")
                return self._mu.reg_read(self._name_to_id[lookup])
        raise AttributeError(f"'{type(self).__name__}' object has no attribute '{name}'")

    def __setattr__(self, name: str, value):
        if name.startswith("v_"):
            lookup = name[2:].lower()
            if "_name_to_id" in self.__dict__ and lookup in self._name_to_id:
                if self._mu is None:
                    raise RuntimeError("Unicorn instance (_mu) is not set in RegistersMapping!")
                self._mu.reg_write(self._name_to_id[lookup], value)
                return
            raise AttributeError(f"Unknown virtual register attribute: '{name}'")
        super().__setattr__(name, value)

    def is_thumb(self) -> bool:
        if self._arch != emu_const.ARCH_ARM32:
            return False
        return (self.v_flags & (1 << 5)) != 0

    def set_thumb(self) -> None:
        assert self._arch == emu_const.ARCH_ARM32, "Thumb mode is only supported on ARM32"
        self.v_flags = self.v_flags | (1 << 5)

    def clear_thumb(self) -> None:
        assert self._arch == emu_const.ARCH_ARM32, "Thumb mode is only supported on ARM32"
        self.v_flags = self.v_flags & ~(1 << 5)

    @staticmethod
    def _translate_val(java_vm: Optional['JavaVM'], val: Any) -> int:
        if isinstance(val, int):
            return val
        if val is None:
            return 0
        if java_vm is not None:
            if isinstance(val, (bytearray, bytes)):
                return java_vm.jni_env.add_local_reference(jobject(val))
            if hasattr(val, 'jvm_id') or hasattr(type(val), 'jvm_name') or hasattr(val, 'jvm_name'):
                return java_vm.jni_env.add_local_reference(jobject(val))
        raise NotImplementedError(f"Cannot serialize argument of type {type(val)}: {val!r}")

    def read_syscall_args(self, count: int) -> Tuple[int, ...]:
        """Reads arguments for system calls directly from registers."""
        return tuple(getattr(self, f"v_reg_{i}") for i in range(count))

    def read_args(self, count: int) -> List[int]:
        """
        Reads function call arguments according to the architecture's calling convention:
        first from registers (arguments), then falls back to reading the stack.
        """
        if self._mu is None:
            raise RuntimeError("Unicorn instance is not set!")

        max_regs = len(self.arguments)
        reg_count = min(count, max_regs)
        args = [getattr(self, f"v_reg_{i}") for i in range(reg_count)]

        if count <= max_regs:
            return args

        stack_count = count - max_regs
        total_bytes = stack_count * self._ptr_sz
        stack_raw = self._mu.mem_read(self.v_sp, total_bytes)

        fmt = f"<{stack_count}{'Q' if self._ptr_sz == 8 else 'I'}"
        args.extend(struct.unpack(fmt, stack_raw))
        return args

    def write_args(self, java_vm: Optional['JavaVM'], *argv: Any) -> None:
        """
        Writes function call arguments according to the architecture's calling convention:
        first into argument registers, then remaining onto the stack (aligned to 16 bytes).
        """
        if self._mu is None:
            raise RuntimeError("Unicorn instance is not set!")

        max_regs = len(self.arguments)
        total_args = len(argv)

        reg_count = min(total_args, max_regs)
        for i in range(reg_count):
            setattr(self, f"v_reg_{i}", self._translate_val(java_vm, argv[i]))

        if total_args > max_regs:
            stack_args = argv[max_regs:]
            stack_count = len(stack_args)

            sp_start = self.v_sp
            sp_new = (sp_start - (self._ptr_sz * stack_count)) & ~0xF

            payload = b"".join(
                struct.pack(self._fmt_ptr, self._translate_val(java_vm, arg))
                for arg in stack_args
            )

            self._mu.mem_write(sp_new, payload)
            self.v_sp = sp_new

    def set_return_val(self, val: Any, high_val: Optional[int] = None) -> None:
        """Sets return value in v_ret (and v_reg_1 if 64-bit pair on 32-bit)."""
        self.v_ret = val
        if high_val is not None:
            self.v_reg_1 = high_val

read_args(count)

Reads function call arguments according to the architecture's calling convention: first from registers (arguments), then falls back to reading the stack.

Source code in androidemu/core/registers.py
def read_args(self, count: int) -> List[int]:
    """
    Reads function call arguments according to the architecture's calling convention:
    first from registers (arguments), then falls back to reading the stack.
    """
    if self._mu is None:
        raise RuntimeError("Unicorn instance is not set!")

    max_regs = len(self.arguments)
    reg_count = min(count, max_regs)
    args = [getattr(self, f"v_reg_{i}") for i in range(reg_count)]

    if count <= max_regs:
        return args

    stack_count = count - max_regs
    total_bytes = stack_count * self._ptr_sz
    stack_raw = self._mu.mem_read(self.v_sp, total_bytes)

    fmt = f"<{stack_count}{'Q' if self._ptr_sz == 8 else 'I'}"
    args.extend(struct.unpack(fmt, stack_raw))
    return args

read_syscall_args(count)

Reads arguments for system calls directly from registers.

Source code in androidemu/core/registers.py
def read_syscall_args(self, count: int) -> Tuple[int, ...]:
    """Reads arguments for system calls directly from registers."""
    return tuple(getattr(self, f"v_reg_{i}") for i in range(count))

set_return_val(val, high_val=None)

Sets return value in v_ret (and v_reg_1 if 64-bit pair on 32-bit).

Source code in androidemu/core/registers.py
def set_return_val(self, val: Any, high_val: Optional[int] = None) -> None:
    """Sets return value in v_ret (and v_reg_1 if 64-bit pair on 32-bit)."""
    self.v_ret = val
    if high_val is not None:
        self.v_reg_1 = high_val

write_args(java_vm, *argv)

Writes function call arguments according to the architecture's calling convention: first into argument registers, then remaining onto the stack (aligned to 16 bytes).

Source code in androidemu/core/registers.py
def write_args(self, java_vm: Optional['JavaVM'], *argv: Any) -> None:
    """
    Writes function call arguments according to the architecture's calling convention:
    first into argument registers, then remaining onto the stack (aligned to 16 bytes).
    """
    if self._mu is None:
        raise RuntimeError("Unicorn instance is not set!")

    max_regs = len(self.arguments)
    total_args = len(argv)

    reg_count = min(total_args, max_regs)
    for i in range(reg_count):
        setattr(self, f"v_reg_{i}", self._translate_val(java_vm, argv[i]))

    if total_args > max_regs:
        stack_args = argv[max_regs:]
        stack_count = len(stack_args)

        sp_start = self.v_sp
        sp_new = (sp_start - (self._ptr_sz * stack_count)) & ~0xF

        payload = b"".join(
            struct.pack(self._fmt_ptr, self._translate_val(java_vm, arg))
            for arg in stack_args
        )

        self._mu.mem_write(sp_new, payload)
        self.v_sp = sp_new

androidemu.kernel.fs.manager.VFSManager

Source code in androidemu/kernel/fs/manager.py
class VFSManager:
    MAX_SYMLINKS = 40

    def __init__(self, emu: 'Emulator'):
        self.emu = emu
        self.vfs_root = emu.vfs_root
        self.tm = emu.time_manager
        self.ctx = emu.pcb
        self.config = emu.config

        self._tid_fds: Dict[int, Dict[int, FileHandle]] = {}
        self._next_fd = 100

        self.mount_table: MountTable = create_default_mount_table(self.config.pkg.uid)

        host_root = HostDirNode("/", self.vfs_root, self.mount_table, dev=(259 << 8) | 0)
        self.root_node = RootVfsNode(host_dir_node=host_root)

        self._init_system_mounts()
        self._init_stdio(self.ctx.pid)

    def _init_system_mounts(self):
        self.mount("/proc", ProcRootNode(self))

        self.mount("/dev/null", DevNullNode())
        self.mount("/dev/zero", DevNullNode())
        self.mount("/dev/urandom", DevUrandomNode())
        self.mount("/dev/random", DevUrandomNode())
        self.mount("/dev/binder", BinderNode())
        self.mount("/dev/ashmem", DevNullNode())
        self.mount("/dev/tty", TtyNode("/dev/tty"))

        self.mount("/dev/ptmx", PtmxNode())
        self.mount("/dev/pts", DevPtsDirNode(self))

        self.mount("/sys/devices/system/cpu/online", SysCpuOnlineNode())

    def _init_stdio(self, tid: int):
        self._tid_fds[tid] = {
            0: FileHandle(TtyNode("stdin"), O_RDONLY),
            1: FileHandle(TtyNode("stdout"), O_WRONLY),
            2: FileHandle(TtyNode("stderr"), O_WRONLY),
        }

    def mount(self, virt_path: str, node: VfsNode) -> VfsNode:
        norm = posixpath.normpath(virt_path).strip("/")
        if not norm:
            self.root_node = node  # type: ignore
            return node

        parts = norm.split("/")
        curr: VfsNode = self.root_node

        for i, part in enumerate(parts[:-1]):
            nxt = curr.lookup(part)
            if nxt is None or not nxt.is_dir:
                new_dir = VirtualDirNode(name="/" + "/".join(parts[:i + 1]))
                if isinstance(curr, VirtualDirNode):
                    curr.add_child(part, new_dir)
                curr = new_dir
            else:
                curr = nxt

        if isinstance(curr, VirtualDirNode):
            curr.add_child(parts[-1], node)
        return node

    def mount_file(self, virt_path: str, host_path: str, uid: Optional[int] = None, gid: Optional[int] = None, dev: Optional[int] = None) -> HostFileNode:
        if not os.path.exists(host_path):
            raise FileNotFoundError(f"Host file not found: {host_path}")

        norm = posixpath.normpath(virt_path)
        if not norm.startswith("/"):
            norm = "/" + norm

        mp = self.mount_table.find_mount(norm)
        node = HostFileNode(
            virt_path=norm,
            host_path=os.path.abspath(host_path),
            uid=uid if uid is not None else mp.default_uid,
            gid=gid if gid is not None else mp.default_gid,
            dev=dev if dev is not None else mp.dev,
            mode=mp.file_mode
        )
        node.setxattr("security.selinux", mp.selinux_context)
        self.mount(norm, node)
        return node

    def mount_data(self, virt_path: str, data: bytes, mode: int = 0o100644, uid: int = 0, gid: int = 0) -> MemoryFileNode:
        norm = posixpath.normpath(virt_path)
        if not norm.startswith("/"):
            norm = "/" + norm
        node = MemoryFileNode(norm, data, mode=mode, uid=uid, gid=gid)
        self.mount(norm, node)
        return node

    def resolve_node(self, dirfd: int, path: str, follow_symlinks: bool = True) -> Optional[VfsNode]:
        if not path:
            if dirfd == AT_FDCWD:
                return None
            handle = self.get_handle(dirfd)
            if not handle:
                return None
            node = handle.node
            if follow_symlinks and node.is_symlink:
                target = node.readlink()
                if target:
                    return self.get_node(target, follow_symlinks=True)
            return node

        if path.startswith("/") or dirfd == AT_FDCWD:
            start_node = self.root_node
            rel_path = path
        else:
            handle = self.get_handle(dirfd)
            if not handle or not handle.node.is_dir:
                return None
            start_node = handle.node
            rel_path = path

        norm = posixpath.normpath(rel_path)
        return self._walk_path(start_node, norm, follow_symlinks)

    def get_node(self, virt_path: str, follow_symlinks: bool = True) -> Optional[VfsNode]:
        if not virt_path:
            return None
        norm = posixpath.normpath(virt_path)
        return self._walk_path(self.root_node, norm, follow_symlinks)

    def _walk_path(self, start_node: VfsNode, path: str, follow_symlinks: bool) -> Optional[VfsNode]:
        components = [c for c in path.split("/") if c and c != "."]
        curr = start_node
        symlinks_followed = 0

        for i, comp in enumerate(components):
            is_last = (i == len(components) - 1)

            if not curr.is_dir:
                return None

            next_node = curr.lookup(comp)
            if next_node is None:
                return None

            if next_node.is_symlink and (not is_last or follow_symlinks):
                if symlinks_followed >= self.MAX_SYMLINKS:
                    return None  # -ELOOP

                target = next_node.readlink()
                if not target:
                    return None
                symlinks_followed += 1

                remaining = components[i + 1:]
                if target.startswith("/"):
                    target_path = posixpath.join(target, *remaining)
                else:
                    target_path = posixpath.join(curr.name, target, *remaining)
                return self._walk_path(self.root_node, target_path, follow_symlinks)

            curr = next_node

        return curr

    def openat(self, dirfd: int, path: str, flags: int, mode: int) -> int:
        follow = not bool(flags & O_NOFOLLOW)
        node = self.resolve_node(dirfd, path, follow_symlinks=follow)
        if not node:
            return -ENOENT

        perm_err = node.check_permission(self.ctx, flags)
        if perm_err != 0:
            return perm_err

        return self.create_fd_for_node(node, flags)

    def readlink(self, dirfd: int, path: str) -> Optional[str]:
        if not path and dirfd != AT_FDCWD:
            handle = self.get_handle(dirfd)
            if not handle:
                return None
            return handle.node.readlink()

        node = self.resolve_node(dirfd, path, follow_symlinks=False)
        if not node or not node.is_symlink:
            return None
        return node.readlink()

    def stat(self, dirfd: int, path: str, follow_symlinks: bool = True):
        node = self.resolve_node(dirfd, path, follow_symlinks=follow_symlinks)
        if not node:
            return None
        return node.stat(self.tm)

    def fstat(self, fd: int):
        handle = self.get_handle(fd)
        if not handle:
            return None
        stat = handle.node.stat(self.tm)
        return stat
    def close(self, fd: int) -> int:
        fds = self._get_current_fds()
        handle = fds.pop(fd, None)
        if not handle:
            return -EBADF
        handle.close()
        return 0

    def read(self, fd: int, count: int) -> Tuple[int, bytes]:
        handle = self.get_handle(fd)
        if not handle:
            return -EBADF, b""
        data = handle.node.read(handle.offset, count)
        handle.offset += len(data)
        return len(data), data

    def write(self, fd: int, data: bytes) -> int:
        handle = self.get_handle(fd)
        if not handle:
            return -EBADF
        written = handle.node.write(handle.offset, data)
        if written > 0:
            handle.offset += written
        return written

    def lseek(self, fd: int, offset: int, whence: int) -> int:
        handle = self.get_handle(fd)
        if not handle:
            return -EBADF

        if whence == 0:
            handle.offset = offset
        elif whence == 1:
            handle.offset += offset
        elif whence == 2:
            handle.offset = handle.node.get_size() + offset

        if handle.offset < 0:
            handle.offset = 0
        return handle.offset

    def ioctl(self, fd: int, cmd: int, arg: int, mu) -> int:
        handle = self.get_handle(fd)
        if not handle:
            return -EBADF
        return handle.node.ioctl(cmd, arg, mu)

    def mkdir(self, dirfd: int, path: str, mode: int = 0o040755) -> int:
        if not path:
            return -EINVAL

        if path.startswith("/") or dirfd == AT_FDCWD:
            start_node = self.root_node
            rel_path = path
        else:
            handle = self.get_handle(dirfd)
            if not handle or not handle.node.is_dir:
                return -EBADF
            start_node = handle.node
            rel_path = path

        norm = posixpath.normpath(rel_path).strip("/")
        if not norm:
            return -EEXIST

        parts = norm.split("/")
        curr: VfsNode = start_node

        for i, part in enumerate(parts[:-1]):
            nxt = curr.lookup(part)
            if nxt is None or not nxt.is_dir:
                new_dir = VirtualDirNode(name="/" + "/".join(parts[:i + 1]), mode=mode, uid=self.ctx.uid, gid=self.ctx.gid)
                if isinstance(curr, VirtualDirNode):
                    curr.add_child(part, new_dir)
                curr = new_dir
            else:
                curr = nxt

        target_name = parts[-1]

        existing = curr.lookup(target_name)
        if existing is not None:
            return -EEXIST

        if isinstance(curr, VirtualDirNode):
            full_path = posixpath.join(curr.name if curr.name != "/" else "", target_name)
            if not full_path.startswith("/"):
                full_path = "/" + full_path

            new_dir_node = VirtualDirNode(name=full_path, mode=mode, uid=self.ctx.uid, gid=self.ctx.gid)
            curr.add_child(target_name, new_dir_node)
            return 0

        return -EINVAL

    def getdents64(self, fd: int, count: int) -> Tuple[int, bytes]:
        handle = self.get_handle(fd)
        if not handle:
            return -EBADF, b""

        entries = handle.node.getdents()
        if not entries or handle.offset >= len(entries):
            return 0, b""

        buf = bytearray()
        cur_idx = handle.offset

        while cur_idx < len(entries):
            name, d_type, d_ino = entries[cur_idx]
            name_bytes = name.encode("utf-8") + b"\x00"

            reclen = (8 + 8 + 2 + 1 + len(name_bytes) + 7) & ~7
            if len(buf) + reclen > count:
                break

            padding = reclen - (8 + 8 + 2 + 1 + len(name_bytes))
            packed_header = struct.pack("<QqHB", d_ino, cur_idx + 1, reclen, d_type)

            buf += packed_header
            buf += name_bytes
            buf += b"\x00" * padding
            cur_idx += 1

        handle.offset = cur_idx
        return len(buf), bytes(buf)

    def clone_task(self, parent_tid: int, child_tid: int, share_table: bool = False):
        parent_table = self._tid_fds.get(parent_tid, {})
        if share_table:
            self._tid_fds[child_tid] = parent_table
            return

        new_table = {}
        for fd, handle in parent_table.items():
            new_table[fd] = handle
            handle.ref_count += 1
        self._tid_fds[child_tid] = new_table

    def remove_task(self, tid: int):
        table = self._tid_fds.get(tid)
        if not table:
            return
        is_shared = any(t != tid and self._tid_fds[t] is table for t in self._tid_fds)
        if not is_shared:
            for handle in table.values():
                handle.close()
        del self._tid_fds[tid]

    def create_fd_for_node(self, node: VfsNode, flags: int = 0, specific_fd: Optional[int] = None) -> int:
        fd = specific_fd if specific_fd is not None else self._next_fd
        if specific_fd is None:
            self._next_fd += 1
        handle = FileHandle(node, flags)
        self._get_current_fds()[fd] = handle
        return fd

    def _get_current_fds(self) -> Dict[int, FileHandle]:
        tid = self.ctx.current_tid
        if tid not in self._tid_fds:
            self._tid_fds[tid] = {}
        return self._tid_fds[tid]

    def get_handle(self, fd: int) -> Optional[FileHandle]:
        return self._get_current_fds().get(fd)

    def get_current_task_fds(self) -> List[int]:
        return list(self._get_current_fds().keys())

androidemu.native.hook.manager.HookManager

Source code in androidemu/native/hook/manager.py
class HookManager:
    def __init__(self, emu: 'Emulator'):
        self._emu = emu
        self._inline_engine = InlineHook(emu)
        self._watchpoint_engine = MemoryWatchpoint(emu)

    def stub(self, symname: str, callback: Callable):
        """Replaces an exported or imported function with a Python callback."""
        func_addr = self._emu._hooker.write_function(callback)
        self._emu.linker.add_symbol_hook(symname, func_addr)
        logger.debug("Stubbed %s -> %#x", symname, func_addr)

    def inline(
        self,
        addr: int,
        num_args: int,
        cb_before: Optional[Callable] = None,
        cb_after: Optional[Callable] = None
    ):
        """Hooks execution at a specific address (function prologue/epilogue)."""
        self._inline_engine.add(addr, num_args, cb_before, cb_after)

    def inline_symbol(
        self,
        module_name: str,
        symbol_name: str,
        num_args: int,
        cb_before: Optional[Callable] = None,
        cb_after: Optional[Callable] = None
    ):
        """Finds symbol in module and inline-hooks it."""
        mod = self._emu.get_library(module_name)
        if not mod:
            raise RuntimeError(f"Module '{module_name}' is not loaded!")
        addr = mod.find_symbol(symbol_name)
        if addr is None:
            raise RuntimeError(f"Symbol '{symbol_name}' not found in '{module_name}'!")
        self.inline(addr, num_args, cb_before, cb_after)

    def watch(
        self,
        addr: int,
        size: int,
        tag: str = "WATCH",
        on_read: Optional[Callable] = None,
        on_write: Optional[Callable] = None
    ):
        """Watches memory reads/writes in a given range."""
        self._watchpoint_engine.add(addr, size, tag, on_read, on_write)

inline(addr, num_args, cb_before=None, cb_after=None)

Hooks execution at a specific address (function prologue/epilogue).

Source code in androidemu/native/hook/manager.py
def inline(
    self,
    addr: int,
    num_args: int,
    cb_before: Optional[Callable] = None,
    cb_after: Optional[Callable] = None
):
    """Hooks execution at a specific address (function prologue/epilogue)."""
    self._inline_engine.add(addr, num_args, cb_before, cb_after)

inline_symbol(module_name, symbol_name, num_args, cb_before=None, cb_after=None)

Finds symbol in module and inline-hooks it.

Source code in androidemu/native/hook/manager.py
def inline_symbol(
    self,
    module_name: str,
    symbol_name: str,
    num_args: int,
    cb_before: Optional[Callable] = None,
    cb_after: Optional[Callable] = None
):
    """Finds symbol in module and inline-hooks it."""
    mod = self._emu.get_library(module_name)
    if not mod:
        raise RuntimeError(f"Module '{module_name}' is not loaded!")
    addr = mod.find_symbol(symbol_name)
    if addr is None:
        raise RuntimeError(f"Symbol '{symbol_name}' not found in '{module_name}'!")
    self.inline(addr, num_args, cb_before, cb_after)

stub(symname, callback)

Replaces an exported or imported function with a Python callback.

Source code in androidemu/native/hook/manager.py
def stub(self, symname: str, callback: Callable):
    """Replaces an exported or imported function with a Python callback."""
    func_addr = self._emu._hooker.write_function(callback)
    self._emu.linker.add_symbol_hook(symname, func_addr)
    logger.debug("Stubbed %s -> %#x", symname, func_addr)

watch(addr, size, tag='WATCH', on_read=None, on_write=None)

Watches memory reads/writes in a given range.

Source code in androidemu/native/hook/manager.py
def watch(
    self,
    addr: int,
    size: int,
    tag: str = "WATCH",
    on_read: Optional[Callable] = None,
    on_write: Optional[Callable] = None
):
    """Watches memory reads/writes in a given range."""
    self._watchpoint_engine.add(addr, size, tag, on_read, on_write)

androidemu.internal.linker.AndroidLinker

Bionic Dynamic Linker Orchestrator Lifecycle: Load Segments -> TLS Setup -> 3-Pass Relocations -> Init Constructors -> Memory Protect.

Source code in androidemu/internal/linker.py
class AndroidLinker:
    """
    Bionic Dynamic Linker Orchestrator
    Lifecycle: Load Segments -> TLS Setup -> 3-Pass Relocations -> Init Constructors -> Memory Protect.
    """

    def __init__(self, emu: 'Emulator', vfs_root: str):
        self.emu = emu
        self.vfs_root = vfs_root

        self.modules: List[Module] = []
        self.modules_by_name: Dict[str, Module] = {}
        self.symbol_hooks: Dict[str, int] = {}

        self.resolver = SymbolResolver(self.symbol_hooks)

        self.soinfo_alloc_addr = config.SOINFO_START_BASE
        self.tls_area_size = config.TLS_SIZE
        self.tls: BionicTLSInitialization = self.emu.tls_state
        self.tls_initialized = False
        self._last_next_field_addr = 0

        try:
            emu.memory.map(config.TLS_BASE, self.tls_area_size, UC_PROT_READ | UC_PROT_WRITE)
            emu.memory.map(config.SOINFO_START_BASE, config.SOINFO_SIZE, UC_PROT_READ | UC_PROT_WRITE)
        except UcError:
            pass

    def add_symbol_hook(self, symbol_name: str, addr: int) -> None:
        self.symbol_hooks[symbol_name] = addr
        self.resolver.invalidate_cache()

    def find_symbol_globally(self, symbol_name: str) -> int:
        res = self.resolver.resolve(symbol_name, all_modules=self.modules)
        return res.address if res.found else 0

    def find_function_by_name(self, symbol_name: str) -> int:
        for mod in self.modules:
            val = mod.find_function(symbol_name)
            if val:
                return val
        return 0

    def find_module_by_name(self, filename: str) -> Optional[Module]:
        basename = os.path.basename(filename)
        return self.modules_by_name.get(basename, None)

    def find_so_on_disk(self, so_path: str) -> Optional[str]:
        if os.path.isabs(so_path):
            return misc_utils.vfs_path_to_system_path(self.emu.vfs_root, so_path)

        ld_dirs = ["/system/lib/"] if self.emu.arch == emu_const.ARCH_ARM32 else ["/system/lib64/"]
        for lib_dir in ld_dirs:
            full_path = misc_utils.vfs_path_to_system_path(self.emu.vfs_root, f"{lib_dir}{so_path}")
            if os.path.exists(full_path):
                return full_path

        return None

    def load_module(self, filename: str, do_init: bool = True, main_lib: bool = False) -> Module:
        logger.info("[Linker] Request to load: %s (do_init=%s, main=%s)", filename, do_init, main_lib)

        start_idx = len(self.modules)
        target_module = self._load_recursive(filename)
        if not target_module:
            mod = self.find_module_by_name(filename)
            if mod:
                return mod
            raise RuntimeError(f"Could not load module: {filename}")

        target_module.main_executable = main_lib
        target_module.dynamic = not main_lib

        new_modules = self.modules[start_idx:]

        if not self.tls_initialized:
            self._bootstrap_tls(target_module)
        else:
            if self.tls:
                for mod in new_modules:
                    mod.tls_offset = self.tls.setup_static_tls(mod._reader, mod.bias)

        self.resolver.invalidate_cache()
        for mod in new_modules:
            self._relocate_module(mod)

        if do_init:
            self._initialize_graph(target_module)

        for mod in new_modules:
            self._protect_module(mod)
            mod._unload_reader()

        return target_module

    def _load_recursive(self, filename: str) -> Optional[Module]:
        path = self._resolve_path(filename)
        if not path:
            return None

        basename = os.path.basename(path)
        if basename in self.modules_by_name:
            return self.modules_by_name[basename]

        logger.debug("  [Load] Parsing %s", basename)
        reader = ELFReader(path)
        self._check_arch(reader, path)

        base, bias, size = self._map_elf_segments(reader)

        module = Module(path, base, bias, size, reader.dyn_addr, reader.exported_symbols, reader)
        self.modules.append(module)
        self.modules_by_name[basename] = module

        self._setup_soinfo(module, reader)

        for dep in reader.needed_libs:
            dep_mod = self._load_recursive(dep)
            if dep_mod:
                module.needed.append(dep_mod)

        return module

    def _bootstrap_tls(self, main_module: Module) -> None:
        if self.tls_initialized or not self.tls:
            return

        libc_mod = self.modules_by_name.get("libc.so")
        if not libc_mod:
            return

        entry_point = main_module.base + main_module._reader.entry_point
        self.tls.bootstrap(
            main_module.base + main_module._reader.phoff,
            main_module._reader.phdr_num,
            entry_point
        )

        for mod in self.modules:
            mod.tls_offset = self.tls.setup_static_tls(mod._reader, mod.bias)

        self.tls_initialized = True

    def _relocate_module(self, module: Module) -> None:
        logger.debug("  [Reloc] Applying 3-pass relocations to %s", os.path.basename(module.filename))
        is_64 = (self.emu.arch == emu_const.ARCH_ARM64)

        relocator_cls = ARM64Relocator if is_64 else ARM32Relocator
        relocator = relocator_cls(self.emu, module, self.resolver)
        relocator.relocate_all(self.modules)

    def _initialize_graph(self, root_module: Module) -> None:
        visited = set()

        def visit(mod: Module):
            if mod.initialized or mod in visited:
                return
            visited.add(mod)

            for dep in mod.needed:
                visit(dep)

            mod.initialized = True
            self.call_constructors(mod)

        visit(root_module)

    def call_constructors(self, module: Module) -> None:
        bias = module.bias
        mu = self.emu.mu
        logger.info("  [Init] Initializing %s", os.path.basename(module.filename))

        # 1. DT_PREINIT_ARRAY
        if module.main_executable:
            preinit_off = module.dynamic_tags.get("DT_PREINIT_ARRAY")
            preinit_sz = module.dynamic_tags.get("DT_PREINIT_ARRAYSZ")
            if preinit_off and preinit_sz:
                for func_va in read_ptr_array(mu, bias + preinit_off, preinit_sz):
                    self.emu.call_native(func_va)

        # 2. DT_INIT
        init = module.dynamic_tags.get("DT_INIT")
        if init:
            self.emu.call_native(bias + init)

        # 3. DT_INIT_ARRAY
        arr_off = module.dynamic_tags.get("DT_INIT_ARRAY")
        arr_sz = module.dynamic_tags.get("DT_INIT_ARRAYSZ")
        if arr_off and arr_sz:
            for func_va in read_ptr_array(mu, bias + arr_off, arr_sz):
                self.emu.call_native(func_va)

    def _setup_soinfo(self, module: 'Module', reader: 'ELFReader') -> None:
        info_ptr = self.soinfo_alloc_addr
        module.soinfo_ptr = info_ptr

        writer = SoinfoWriter(self.emu)
        current_next_field_ptr = writer.write_soinfo(module, reader, info_ptr)
        self.soinfo_alloc_addr += 0x400

        if self._last_next_field_addr:
            ptr_sz = ptr_t.size
            self.emu.mu.mem_write(self._last_next_field_addr, info_ptr.to_bytes(ptr_sz, 'little'))
        else:
            self._setup_linker_symbols(info_ptr)

        self._last_next_field_addr = current_next_field_ptr

    def _setup_linker_symbols(self, soinfo_head_ptr: int) -> None:
        ptr_sz = ptr_t.size
        linker_bin = "/system/bin/linker64" if self.emu.arch == emu_const.ARCH_ARM64 else "/system/bin/linker"
        linker_path = self.find_so_on_disk(linker_bin)

        if linker_path and os.path.exists(linker_path):
            linker_reader = ELFReader(linker_path)
            for sym_name in ["__dl__ZL6solist"]:
                sym_offset = linker_reader.get_symbol_address(sym_name)
                if sym_offset is not None:
                    target_addr = config.LINKER_BASE + sym_offset
                    self.emu.mu.mem_write(target_addr, soinfo_head_ptr.to_bytes(ptr_sz, 'little'))
                    break
            linker_reader.close()

    def _protect_module(self, module: 'Module') -> None:
        bias = module.bias

        for seg in module.segments:
            if seg['p_type'] != "LOAD":
                continue

            flags = seg.get('p_flags', 7)
            prot = 0
            if flags & 4: prot |= UC_PROT_READ
            if flags & 2: prot |= UC_PROT_WRITE
            if flags & 1: prot |= UC_PROT_EXEC

            start = align_down(bias + seg['p_vaddr'])
            size = align_up(bias + seg['p_vaddr'] + seg['p_memsz']) - start
            self.emu.memory.protect(start, size, prot)

        for seg in module.segments:
            if seg['p_type'] == "GNU_RELRO":
                relro_start = align_down(bias + seg['p_vaddr'])
                relro_end = align_down(bias + seg['p_vaddr'] + seg['p_memsz'])
                if relro_end > relro_start:
                    self.emu.memory.protect(relro_start, relro_end - relro_start, UC_PROT_READ)

    def _map_elf_segments(self, reader: 'ELFReader') -> Tuple[int, int, int]:
        load_segs = [s for s in reader.segments if s['p_type'] == "LOAD"]
        if not load_segs:
            raise RuntimeError("No LOAD segments found in ELF")

        min_v = min(s['p_vaddr'] for s in load_segs)
        max_v = max(s['p_vaddr'] + s['p_memsz'] for s in load_segs)

        aligned_min = align_down(min_v)
        aligned_max = align_up(max_v)
        total_span = aligned_max - aligned_min

        addr = self.emu.memory.find_free_region(size=total_span, start_search=config.BASE_ADDR)
        base = self.emu.memory.map(addr, total_span, prot=UC_PROT_READ | UC_PROT_WRITE | UC_PROT_EXEC)
        bias = base - min_v

        for seg in load_segs:
            vaddr = seg['p_vaddr']
            memsz = seg['p_memsz']
            content = bytes(seg.get('content', b''))
            dest = bias + vaddr

            if content:
                self.emu.mu.mem_write(dest, content)

            file_sz = len(content)
            if memsz > file_sz:
                self.emu.mu.mem_write(dest + file_sz, b'\x00' * (memsz - file_sz))

        return base, bias, total_span

    def _resolve_path(self, filename: str) -> Optional[str]:
        if os.path.exists(filename):
            return filename

        is_64 = (self.emu.arch == emu_const.ARCH_ARM64)
        lib_dir = "lib64" if is_64 else "lib"
        marker = "arm64-v8a" if is_64 else "armeabi-v7a"
        base = os.path.basename(filename)

        paths = [
            f"/system/{lib_dir}/{base}",
            f"/vendor/{lib_dir}/{base}",
            f"/data/app/{self.emu.config.pkg.pkg_name}/lib/{marker}/{base}"
        ]

        for p in paths:
            real = misc_utils.vfs_path_to_system_path(self.vfs_root, p)
            if os.path.exists(real):
                return real

        return None

    def _check_arch(self, reader: 'ELFReader', path: str) -> None:
        is_32 = reader.is_32
        emu_32 = (self.emu.arch == emu_const.ARCH_ARM32)
        if is_32 != emu_32:
            raise RuntimeError(f"Arch mismatch: {path}. Expected {'ARM32' if emu_32 else 'ARM64'}")

androidemu.utils.memory.map.MemoryMap

Source code in androidemu/utils/memory/map.py
class MemoryMap:
    def __init__(self, mu: 'Uc', alloc_min_addr: int, alloc_max_addr: int):
        self._mu: 'Uc' = mu
        self._ptr_sz = ptr_t.size

        self._alloc_min_addr = alloc_min_addr
        self._alloc_max_addr = alloc_max_addr

        self._brk_ptr = alloc_min_addr

        self._file_map_addr: Dict[int, Tuple[int, int, 'VfsNode']] = {}
        self._allocations: Dict[int, int] = {}

        self.map_generation = 0

    def _is_mapped(self, addr: int, size: int) -> bool:
        """Check if the given range is already mapped in Unicorn."""
        try:
            for r_start, r_end, _ in self._mu.mem_regions():
                if max(addr, r_start) < min(addr + size, r_end + 1):
                    return True
            return False
        except:
            return False

    def static_alloc(self, size: int, addr: int = None, align: int = 0x10) -> int:
        """
        Allocate memory.
        If addr is provided, it acts as a fixed-base mapping (for TLS/Soinfo zones).
        If addr is None, it acts as a linear allocator (for general heap).
        """
        if addr is not None:
            target_addr = align_up(addr, align)
        else:
            target_addr = align_up(self._brk_ptr, align)

        end = target_addr + size
        map_start = page_start(target_addr)
        map_end = page_end(end)

        if map_end > self._alloc_max_addr:
            raise RuntimeError(f"MemoryMap: Out of address space. Requested end: {map_end:#x}, Max: {self._alloc_max_addr:#x}")

        cur_page = map_start
        while cur_page < map_end:
            if not self._is_mapped(cur_page, PAGE_SIZE):
                try:
                    self._mu.mem_map(cur_page, PAGE_SIZE, UC_PROT_READ | UC_PROT_WRITE)
                except unicorn.UcError as e:
                    if e.errno != UC_ERR_MAP:
                        raise e
            cur_page += PAGE_SIZE

        if addr is None:
            self._brk_ptr = end
        elif end > self._brk_ptr and target_addr < self._alloc_max_addr:
            if target_addr < self._brk_ptr + STACK_ADDR:
                self._brk_ptr = end

        self._allocations[target_addr] = size
        return target_addr

    def dynamic_alloc(self, n_units: int, is_ptr_array: bool = False) -> int:
        """
        Fast allocation for dynamic data or arrays of pointers.

        :param n_units: Number of bytes or number of pointers.
        :param is_ptr_array: If True, n_units is treated as count of pointers (size * ptr_sz).
        :return: Allocated address.
        """
        size = n_units * self._ptr_sz if is_ptr_array else n_units
        return self.static_alloc(size)

    def map(self, address: int, size: int, prot: int = UC_PROT_READ | UC_PROT_WRITE,
            node: Optional['VfsNode'] = None, offset: int = 0) -> int:
        """
        Standard memory mapping (page-aligned).
        If address is 0, finds a free region automatically.

        :param address: Target address (must be page aligned if not 0).
        :param size: Size in bytes.
        :param prot: Protection flags (UC_PROT_...).
        :param node: Optional VfsNode to load data from.
        :param offset: File offset.
        :return: Base address of the mapped region.
        """
        if size <= 0:
            raise ValueError("Size must be > 0")

        aligned_size = page_end(size)
        target_addr = self.find_free_region(aligned_size) if address == 0 else address

        try:
            self._mu.mem_map(target_addr, aligned_size, prot)
        except unicorn.UcError as e:
            if e.errno == UC_ERR_MAP:
                self._mu.mem_protect(target_addr, aligned_size, prot)
            else:
                raise e

        if node is not None:
            data = node.read(offset, size)
            if data:
                self._mu.mem_write(target_addr, data)

            self._file_map_addr[target_addr] = (target_addr + aligned_size, offset, node)

        self._allocations[target_addr] = aligned_size
        self.map_generation += 1

        return target_addr

    def find_free_region(self, size: int, start_search: int = 0) -> int:
        """
        Finds a continuous unmapped memory region.
        """
        regions = sorted(self._mu.mem_regions())

        if start_search > 0:
            search_base = page_end(start_search)
        else:
            search_base = MMAP_BASE

        candidate = page_end(search_base)

        for r_start, r_end, _ in regions:
            r_limit = r_end + 1
            if r_start > candidate:
                if (r_start - candidate) >= size:
                    return candidate
            if r_limit > candidate:
                candidate = page_end(r_limit)

        if candidate + size > 0xFFFFFFFF:
            raise RuntimeError(f"MemoryMap: Out of address space. Cannot find {size:#x} bytes.")

        return candidate

    def unmap(self, addr: int, size: int) -> int:
        """Unmap a memory region and clean up tracking."""
        start = page_start(addr)
        aligned_size = page_end(size)

        try:
            self._mu.mem_unmap(start, aligned_size)
            self._allocations.pop(start, None)
            self._file_map_addr.pop(start, None)
            self.map_generation += 1
            return 0
        except unicorn.UcError:
            return -1

    def protect(self, addr: int, size: int, prot: int) -> int:
        """Change memory protection."""
        try:
            self._mu.mem_protect(page_start(addr), page_end(size), prot)
            return 0
        except unicorn.UcError:
            return -1

    def _read_fully(self, fd: int, size: int) -> bytes:
        data = b""
        while size > 0:
            chunk = os.read(fd, size)
            if not chunk:
                break
            data += chunk
            size -= len(chunk)
        return data

    def get_regions(self) -> List[Tuple[int, int, int]]:
        """Return list of all mapped regions (start, end, prot)."""
        return self._mu.mem_regions()

    def dump_maps(self, stream: 'io.StringIO') -> None:
        """Write current memory map to a stream."""
        regions = sorted(self._mu.mem_regions())
        stream.write(f"{'Start':<10} {'End':<10} {'Prot':<5}\n")
        for start, end, prot in regions:
            stream.write(f"{start:08x}-{end+1:08x} {prot:<5}\n")

    def create_snapshot(self) -> 'Snapshot':
        """
        Takes a full snapshot of CPU registers and writable (RW) memory regions.
        Ignores Read-Only/Execute code segments to save memory and time.
        """
        cpu_ctx = self._mu.context_save()

        pages = {}
        for start, end, prot in self._mu.mem_regions():
            if prot & UC_PROT_WRITE:
                size = end - start + 1
                pages[start] = self._mu.mem_read(start, size)

        return Snapshot(
            cpu_context=cpu_ctx,
            memory_pages=pages,
            brk_ptr=self._brk_ptr,
            generation=self.map_generation
        )

    def restore_snapshot(self, snapshot: 'Snapshot') -> None:
        """
        Restores CPU state and rolls back all writable memory pages to the snapshot.
        """
        self._mu.context_restore(snapshot.cpu_context)

        for addr, data in snapshot.memory_pages.items():
            self._mu.mem_write(addr, data)

        self._brk_ptr = snapshot.brk_ptr
        self.map_generation = snapshot.generation

    @property
    def current_brk(self) -> int:
        """Get the current counter-allocation pointer."""
        return self._brk_ptr

current_brk property

Get the current counter-allocation pointer.

create_snapshot()

Takes a full snapshot of CPU registers and writable (RW) memory regions. Ignores Read-Only/Execute code segments to save memory and time.

Source code in androidemu/utils/memory/map.py
def create_snapshot(self) -> 'Snapshot':
    """
    Takes a full snapshot of CPU registers and writable (RW) memory regions.
    Ignores Read-Only/Execute code segments to save memory and time.
    """
    cpu_ctx = self._mu.context_save()

    pages = {}
    for start, end, prot in self._mu.mem_regions():
        if prot & UC_PROT_WRITE:
            size = end - start + 1
            pages[start] = self._mu.mem_read(start, size)

    return Snapshot(
        cpu_context=cpu_ctx,
        memory_pages=pages,
        brk_ptr=self._brk_ptr,
        generation=self.map_generation
    )

dump_maps(stream)

Write current memory map to a stream.

Source code in androidemu/utils/memory/map.py
def dump_maps(self, stream: 'io.StringIO') -> None:
    """Write current memory map to a stream."""
    regions = sorted(self._mu.mem_regions())
    stream.write(f"{'Start':<10} {'End':<10} {'Prot':<5}\n")
    for start, end, prot in regions:
        stream.write(f"{start:08x}-{end+1:08x} {prot:<5}\n")

dynamic_alloc(n_units, is_ptr_array=False)

Fast allocation for dynamic data or arrays of pointers.

Parameters:

Name Type Description Default
n_units int

Number of bytes or number of pointers.

required
is_ptr_array bool

If True, n_units is treated as count of pointers (size * ptr_sz).

False

Returns:

Type Description
int

Allocated address.

Source code in androidemu/utils/memory/map.py
def dynamic_alloc(self, n_units: int, is_ptr_array: bool = False) -> int:
    """
    Fast allocation for dynamic data or arrays of pointers.

    :param n_units: Number of bytes or number of pointers.
    :param is_ptr_array: If True, n_units is treated as count of pointers (size * ptr_sz).
    :return: Allocated address.
    """
    size = n_units * self._ptr_sz if is_ptr_array else n_units
    return self.static_alloc(size)

find_free_region(size, start_search=0)

Finds a continuous unmapped memory region.

Source code in androidemu/utils/memory/map.py
def find_free_region(self, size: int, start_search: int = 0) -> int:
    """
    Finds a continuous unmapped memory region.
    """
    regions = sorted(self._mu.mem_regions())

    if start_search > 0:
        search_base = page_end(start_search)
    else:
        search_base = MMAP_BASE

    candidate = page_end(search_base)

    for r_start, r_end, _ in regions:
        r_limit = r_end + 1
        if r_start > candidate:
            if (r_start - candidate) >= size:
                return candidate
        if r_limit > candidate:
            candidate = page_end(r_limit)

    if candidate + size > 0xFFFFFFFF:
        raise RuntimeError(f"MemoryMap: Out of address space. Cannot find {size:#x} bytes.")

    return candidate

get_regions()

Return list of all mapped regions (start, end, prot).

Source code in androidemu/utils/memory/map.py
def get_regions(self) -> List[Tuple[int, int, int]]:
    """Return list of all mapped regions (start, end, prot)."""
    return self._mu.mem_regions()

map(address, size, prot=UC_PROT_READ | UC_PROT_WRITE, node=None, offset=0)

Standard memory mapping (page-aligned). If address is 0, finds a free region automatically.

Parameters:

Name Type Description Default
address int

Target address (must be page aligned if not 0).

required
size int

Size in bytes.

required
prot int

Protection flags (UC_PROT_...).

UC_PROT_READ | UC_PROT_WRITE
node Optional[VfsNode]

Optional VfsNode to load data from.

None
offset int

File offset.

0

Returns:

Type Description
int

Base address of the mapped region.

Source code in androidemu/utils/memory/map.py
def map(self, address: int, size: int, prot: int = UC_PROT_READ | UC_PROT_WRITE,
        node: Optional['VfsNode'] = None, offset: int = 0) -> int:
    """
    Standard memory mapping (page-aligned).
    If address is 0, finds a free region automatically.

    :param address: Target address (must be page aligned if not 0).
    :param size: Size in bytes.
    :param prot: Protection flags (UC_PROT_...).
    :param node: Optional VfsNode to load data from.
    :param offset: File offset.
    :return: Base address of the mapped region.
    """
    if size <= 0:
        raise ValueError("Size must be > 0")

    aligned_size = page_end(size)
    target_addr = self.find_free_region(aligned_size) if address == 0 else address

    try:
        self._mu.mem_map(target_addr, aligned_size, prot)
    except unicorn.UcError as e:
        if e.errno == UC_ERR_MAP:
            self._mu.mem_protect(target_addr, aligned_size, prot)
        else:
            raise e

    if node is not None:
        data = node.read(offset, size)
        if data:
            self._mu.mem_write(target_addr, data)

        self._file_map_addr[target_addr] = (target_addr + aligned_size, offset, node)

    self._allocations[target_addr] = aligned_size
    self.map_generation += 1

    return target_addr

protect(addr, size, prot)

Change memory protection.

Source code in androidemu/utils/memory/map.py
def protect(self, addr: int, size: int, prot: int) -> int:
    """Change memory protection."""
    try:
        self._mu.mem_protect(page_start(addr), page_end(size), prot)
        return 0
    except unicorn.UcError:
        return -1

restore_snapshot(snapshot)

Restores CPU state and rolls back all writable memory pages to the snapshot.

Source code in androidemu/utils/memory/map.py
def restore_snapshot(self, snapshot: 'Snapshot') -> None:
    """
    Restores CPU state and rolls back all writable memory pages to the snapshot.
    """
    self._mu.context_restore(snapshot.cpu_context)

    for addr, data in snapshot.memory_pages.items():
        self._mu.mem_write(addr, data)

    self._brk_ptr = snapshot.brk_ptr
    self.map_generation = snapshot.generation

static_alloc(size, addr=None, align=16)

Allocate memory. If addr is provided, it acts as a fixed-base mapping (for TLS/Soinfo zones). If addr is None, it acts as a linear allocator (for general heap).

Source code in androidemu/utils/memory/map.py
def static_alloc(self, size: int, addr: int = None, align: int = 0x10) -> int:
    """
    Allocate memory.
    If addr is provided, it acts as a fixed-base mapping (for TLS/Soinfo zones).
    If addr is None, it acts as a linear allocator (for general heap).
    """
    if addr is not None:
        target_addr = align_up(addr, align)
    else:
        target_addr = align_up(self._brk_ptr, align)

    end = target_addr + size
    map_start = page_start(target_addr)
    map_end = page_end(end)

    if map_end > self._alloc_max_addr:
        raise RuntimeError(f"MemoryMap: Out of address space. Requested end: {map_end:#x}, Max: {self._alloc_max_addr:#x}")

    cur_page = map_start
    while cur_page < map_end:
        if not self._is_mapped(cur_page, PAGE_SIZE):
            try:
                self._mu.mem_map(cur_page, PAGE_SIZE, UC_PROT_READ | UC_PROT_WRITE)
            except unicorn.UcError as e:
                if e.errno != UC_ERR_MAP:
                    raise e
        cur_page += PAGE_SIZE

    if addr is None:
        self._brk_ptr = end
    elif end > self._brk_ptr and target_addr < self._alloc_max_addr:
        if target_addr < self._brk_ptr + STACK_ADDR:
            self._brk_ptr = end

    self._allocations[target_addr] = size
    return target_addr

unmap(addr, size)

Unmap a memory region and clean up tracking.

Source code in androidemu/utils/memory/map.py
def unmap(self, addr: int, size: int) -> int:
    """Unmap a memory region and clean up tracking."""
    start = page_start(addr)
    aligned_size = page_end(size)

    try:
        self._mu.mem_unmap(start, aligned_size)
        self._allocations.pop(start, None)
        self._file_map_addr.pop(start, None)
        self.map_generation += 1
        return 0
    except unicorn.UcError:
        return -1