# zhkl0228/unidbg architecture

> Architecture diagram of the GitHub repository zhkl0228/unidbg, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhkl0228/unidbg
- Repository: https://github.com/zhkl0228/unidbg

## Overview

This project is an emulator framework—“unidbg”—designed to emulate native Android and iOS libraries. It contains multiple modules that together provide an emulation API, several backend engines (each using different techniques such as dynamic binary translation and hypervisor-based acceleration), and specialized support for both Android (JNI, syscall emulation, JavaVM/ JNIEnv simulation) and iOS (Mach-O parsing, Objective-C/ Swift runtime emulation and hooking). The project is built using Maven (notice the pom.xml files) and is split into multiple subprojects (backend components, unidbg-android, unidbg-api, and unidbg-ios), each with its own source tree and purpose.

##### Main Components
- Core Emulator API (unidbg-api): This forms the heart of the framework. It provides the abstraction for emulation, defines interfaces for emulated memory, registers, contexts, and debugging hooks.
- Backend Engines (located under “backend”):
– Dynarmic: A fast dynamic binary translation backend for ARM (both 32-bit and 64-bit).
– Hypervisor: Uses Apple M1 hypervisor technology for accelerated ARM64 emulation.
– KVM: Provides Linux KVM support (e.g., for Raspberry Pi B4).
– Unicorn2: Implements CPU emulation with support for hooks (instruction trace, memory read/write trace) and a simple debugger/gdb stub.
- Android Emulation (unidbg-android):
– Implements Android-specific features such as JNI emulation, syscall handling, hooks via xHook, and various file I/O abstractions.
- iOS Emulation (unidbg-ios):
– Provides iOS support with Mach-O parsing, support for ObjC/Swift runtime, hooking libraries (e.g., fishhook, substrate, whale) and additional utilities for handling iOS binary formats.
- Supporting Utilities and Tests:
– There are numerous tests and sample applications that exercise these capabilities. Assets (like GIFs) and test scripts are present to demonstrate functionality.

##### Relationships and Interactions
- The Core Emulator API sits at the center and is used by both the Android and iOS modules.
- The Android and iOS emulators interact with one or more backend engines to perform actual ARM code emulation.
- The backend engines are isolated modules that implement a standard “Backend” interface (as evident from the shared package names and backend factories) and are selectable based on requirements such as performance or target platform.
- Hooking subcomponents (e.g., xHook, fishhook, substrate, whale) are integrated within the Android and iOS modules to intercept and patch native calls.
- The emulator also includes support for debugging features (instruction tracing, gdb stub) in the unicorn backend and others.

##### Architectural Patterns and Principles
- Modularity – The system is split into multiple well-defined modules, each responsible for different platform emulations and backend engines.
- Abstraction – There is an abstraction layer (the API) that provides a consistent interface regardless of which backend or platform-specific implementation is running.
- Separation of Concerns – Android and iOS specific implementations are kept logically apart while sharing a common emulation core.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Platform Emulation Section
    subgraph "Platform Emulation"
        A["Android Emulation"]:::platform
        B["iOS Emulation"]:::platform
        
        subgraph "Android Emulation Modules"
            A1["JNI Emulation"]:::platformAux
            A2["Syscall Handling"]:::platformAux
            A3["File I/O & xHook"]:::platformAux
        end
        
        subgraph "iOS Emulation Modules"
            B1["Mach-O Parsing"]:::platformAux
            B2["ObjC/Swift Runtime"]:::platformAux
            B3["Hooking Libraries (fishhook,substrate,whale)"]:::platformAux
        end
    end

    %% Core Emulator API
    C["Core Emulator API"]:::core

    %% Backend Engines Section
    subgraph "Backend Engines"
        D["Dynarmic Backend"]:::backend
        E["Hypervisor Backend"]:::backend
        F["KVM Backend"]:::backend
        G["Unicorn2 Backend"]:::backend
    end

    %% Connections
    A -->|"uses"| C
    B -->|"uses"| C
    C -->|"selects"| D
    C -->|"selects"| E
    C -->|"selects"| F
    C -->|"selects"| G

    %% Click Events
    click C "https://github.com/zhkl0228/unidbg/tree/master/unidbg-api/"
    click D "https://github.com/zhkl0228/unidbg/tree/master/backend/dynarmic/"
    click E "https://github.com/zhkl0228/unidbg/tree/master/backend/hypervisor/"
    click F "https://github.com/zhkl0228/unidbg/tree/master/backend/kvm/"
    click G "https://github.com/zhkl0228/unidbg/tree/master/backend/unicorn2/"
    click A "https://github.com/zhkl0228/unidbg/tree/master/unidbg-android/"
    click B "https://github.com/zhkl0228/unidbg/tree/master/unidbg-ios/"

    %% Styles
    classDef core fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef backend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef platform fill:#cfc,stroke:#333,stroke-width:2px;
    classDef platformAux fill:#eef,stroke:#333,stroke-width:1px;
```
