# momo5502/emulator architecture

> Architecture diagram of the GitHub repository momo5502/emulator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/momo5502/emulator
- Repository: https://github.com/momo5502/emulator

## Overview

Main Components to Include:

##### Core Emulation Layer
- X64 emulation layer (src/unicorn-emulator)
- It to the memory management system (src/emulator/memory_manager)

##### Windows Emulation Layer
- Syscall Dispatcher (central component)
- Process Context Management
- Module Management System
- Registry Emulation
- Device Emulation (AFD, KUSD)

##### Debugging Infrastructure
- GDB Stub Implementation
- Debugging Protocol Handlers

##### Support Systems
- Memory Management
- Threading System
- State Serialization
- Exception Handling

**[User Applications]**
- ↓
**[Debugging Interface] ← → [GDB/IDE Integration]**
- ↓
**[Windows Emulator]**
- ↙     ↓     ↘
**[Syscalls] [Memory] [Modules]**
- ↓        ↓        ↓
**[Unicorn Engine Core]**

Key Elements to Emphasize:

##### Component Relationships
- Bidirectional flows between the debugging interface and emulator
- Memory management spanning across layers
- Syscall interception points

##### Subsystem Details
- Memory Management:
- Reserved/committed memory handling
- PE loading paths
- Thread Management:
- Round-robin scheduling
- Exception handling paths

##### Integration Points
- External tool connections (IDA Pro, GDB, etc.)
- State serialization boundaries
- Hooking interface points

Special Considerations:

##### Layering
- Maintain clear separation between the Unicorn core and Windows-specific components
- How syscall interception bridges these layers

##### State Management
- Snapshot points
- Serialization boundaries

##### Performance Aspects
- Direct syscall paths
- Memory optimization points

- Double lines for primary data flows
- Rectangles: Core components
- Rounded rectangles: Interfaces
- Hexagons: External integration points

Remember to maintain a balance between detail and clarity, focusing on the architectural decisions that make this emulator unique, such as its syscall-level operation and comprehensive Windows integration.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph User_Layer
        UserApp[User Applications]:::user
    end

    subgraph Debug_Layer
        DebugInterface[Debugging Interface]:::debug
        GDBIntegration[GDB/IDE Integration]:::debug
        GDBStub[GDB Stub]:::debug
        DebugProtocol[Debug Protocol Handlers]:::debug
    end

    subgraph Windows_Layer
        WinEmulator[Windows Emulator Core]:::windows
        SyscallDisp[Syscall Dispatcher]:::windows
        ProcContext[Process Context Management]:::windows
        ModuleManager[Module Management]:::windows
        RegEmulation[Registry Emulation]:::windows
        DeviceEmulation[Device Emulation]:::windows
    end

    subgraph Support_Layer
        MemoryMgmt[Memory Management]:::support
        ThreadMgmt[Threading System]:::support
        StateSerial[State Serialization]:::support
        ExceptionHandler[Exception Handling]:::support
        MemPermissions[Memory Permissions]:::support
        ContextFrame[Context Frame]:::support
    end

    subgraph Core_Layer
        UnicornCore[Unicorn Engine Core]:::core
        X64Emulator[X64 Emulation Layer]:::core
    end

    %% Connections
    UserApp --> DebugInterface
    DebugInterface <--> GDBIntegration
    DebugInterface <--> GDBStub
    GDBStub <--> DebugProtocol
    DebugInterface --> WinEmulator
    
    WinEmulator --> SyscallDisp
    WinEmulator --> ProcContext
    WinEmulator --> ModuleManager
    WinEmulator --> RegEmulation
    WinEmulator --> DeviceEmulation
    
    SyscallDisp --> X64Emulator
    ModuleManager --> MemoryMgmt
    ProcContext --> ThreadMgmt
    WinEmulator --> StateSerial
    ProcContext --> ExceptionHandler
    MemoryMgmt --> MemPermissions
    ProcContext --> ContextFrame
    
    X64Emulator --> UnicornCore
    MemoryMgmt --> UnicornCore

    %% Click Events
    click X64Emulator "https://github.com/momo5502/emulator/blob/main/src/unicorn-emulator/unicorn_x64_emulator.hpp"
    click MemoryMgmt "https://github.com/momo5502/emulator/blob/main/src/emulator/memory_manager.hpp"
    click SyscallDisp "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/syscall_dispatcher.hpp"
    click ProcContext "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/process_context.hpp"
    click ModuleManager "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/module/module_manager.hpp"
    click RegEmulation "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/registry/registry_manager.hpp"
    click DeviceEmulation "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/devices/afd_endpoint.hpp"
    click GDBStub "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/debugging/gdb_stub.hpp"
    click DebugProtocol "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/debugging/win_x64_gdb_stub_handler.hpp"
    click StateSerial "https://github.com/momo5502/emulator/blob/main/src/emulator/serialization.hpp"
    click MemPermissions "https://github.com/momo5502/emulator/blob/main/src/emulator/memory_permission.hpp"
    click ContextFrame "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/context_frame.hpp"
    click WinEmulator "https://github.com/momo5502/emulator/blob/main/src/windows-emulator/windows_emulator.hpp"

    %% Styles
    classDef core fill:#2b5797,color:#fff
    classDef windows fill:#00a300,color:#fff
    classDef debug fill:#ffc40d,color:#000
    classDef support fill:#777777,color:#fff
    classDef user fill:#fff,stroke:#000

    %% Legend
    subgraph Legend
        CoreL[Core Components]:::core
        WindowsL[Windows Components]:::windows
        DebugL[Debug Components]:::debug
        SupportL[Support Systems]:::support
        UserL[User Layer]:::user
    end
```
