# fex-emu/fex architecture

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

- Interactive diagram: https://gitdiagram.com/fex-emu/fex
- Repository: https://github.com/fex-emu/fex

## Overview

##### Project Type & Purpose
- This is FEX, a high-performance x86-on-ARM64 emulator for Linux (with Wine/Proton support).
- It combines compiler-like stages (decode → IR → JIT codegen → execute), interpreter fallback, syscall emulation, and host-API forwarding (OpenGL/Vulkan/X11/etc.).

##### Top-Level Structure
- CodeEmitter: ARM64 machine-code emitter templates and utilities.
- FEXCore: Core translation engine
– Interface/IR: internal representation & IR passes (validation, optimization, register allocation).
– Interface/Core: CPUBackend abstraction, opcode dispatchers, code cache, fallback interpreter, JIT orchestration.
– Utils: memory allocators, threading, logging, telemetry.
- Source/Tools: CLI tools (FEXServer, FEXInterpreter, FEXRootFSFetcher, FEXConfig GUI), LinuxEmulation (syscall handlers, seccomp emulator, guest context), Windows port.
- ThunkLibs: guest-side stubs and host-side shims for graphics and system libraries.
- External: third-party dependencies (Vixl, SoftFloat, Catch2, Cephes, etc.).
- Data & Scripts: configuration files (JSON), Docker/Nix setups, CI workflows, build toolchain definitions.
- unittests: exhaustive API, emitter, ASM, Linux tests, Thunk tests.

##### How the Pieces Fit & Interact
- User invokes a CLI tool (e.g. FEXServer or FEXInterpreter) or GUI (FEXConfig).
- Tool loads the target x86 ELF via the loader in Source/Common and creates a FEXCore::Context.
- Frontend reads x86 opcodes via FEXCore opcode tables → emits IR nodes (IREmitter).
- PassManager applies IR passes (validation, redundant-flag elimination, x87 optimization, register allocation).
- JIT (Interface/Core/JIT) compiles IR batches → calls CodeEmitter to emit ARM64 machine code.
- CodeCache stores generated code; CPUBackend dispatches into that code.
- At runtime, near-native ARM64 code executes. On syscalls or traps:
– Control transfers to the LinuxEmulation subsystem in Source/Tools/LinuxEmulation, which translates or emulates Linux syscalls.
- For graphics or library calls marked for forwarding:
– ThunkLibs intercept guest calls (e.g. libGL_guest) → marshal into host calls (e.g. libGL).
- Config subsystem (FEXCore/Interface/Config + Data/AppConfig) supplies per-app tuning via JSON.

##### Important Patterns & Principles
- Layered architecture: Frontend → IR layer → Backend → OS interface.
- Plugin-style subsystems: LinuxEmulation, ThunkLibs, Windows port separate from core.
- CodeCache & dispatcher: minimizes overhead by caching translated blocks.
- Fallback interpreter: ensures correctness for un-translated or rare paths.
- JSON-driven configuration and automated code generation (Scripts generate IR docs, syscall tables, thunks).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Front-end Clients
    subgraph "Front-end Clients"
        class FS,FI,FCG frontend
        FS["FEXServer"] 
        FI["FEXInterpreter"]
        FCG["FEXConfig GUI"]
    end

    %% Loader & Frontend
    subgraph "Loader & Frontend"
        class Loader,IRGen core
        Loader["ELF Loader\n(Source/Common)"]
        IRGen["IR Generator\n(IREmitter)"]
    end

    %% FEXCore
    subgraph "FEXCore"
        direction TB
        subgraph "IR Layer"
            class IRLayer core
            IRLayer["IR.h,\nIREmitter,\nPassManager,\nPasses"]
        end
        subgraph "JIT Engine"
            class JIT core
            JIT["JIT.cpp,\nALUOps.cpp,\nBranchOps.cpp,\nRelocations.h"]
        end
        class CodeCache,CPUBackend,Interpreter core
        CodeCache["CodeCache"]
        CPUBackend["CPUBackend"]
        Interpreter["Interpreter Fallbacks"]
    end

    %% CodeEmitter
    CodeEmitter["CodeEmitter Library"]
    class CodeEmitter emitter

    %% Emulation & Forwarding
    subgraph "Emulation & Forwarding"
        class LinuxEmu emu
        class Thunks thunk
        LinuxEmu["LinuxEmulation"]
        Thunks["ThunkLibs"]
    end

    %% Host Libraries & External
    subgraph "Host Libraries & External"
        class HostLibs,ExtDeps external
        HostLibs["Host Libraries"]
        ExtDeps["External Deps"]
    end

    %% Data & Scripts
    subgraph "Data & Scripts"
        class Config,data Scripts,data
        Config["JSON Config Files"]
        Scripts["Build & CI Scripts"]
    end

    %% Connections
    FS -->|invokes| Loader
    FI -->|invokes| Loader
    FCG -->|loads config| Config

    Loader -->|loads x86 ELF| IRGen
    IRGen -->|IR stream| IRLayer
    IRLayer -->|IR batches| JIT
    JIT -->|requests codegen| CodeEmitter
    CodeEmitter -->|ARM64 machine code| CodeCache
    CodeCache -->|dispatch| CPUBackend

    %% Fallback Interpreter
    CodeCache -->|cache miss| Interpreter
    Interpreter -->|executes fallback| CPUBackend

    %% Runtime traps and syscalls
    CPUBackend -->|syscall trap| LinuxEmu
    %% Host-API forwarding
    CPUBackend -->|guest lib call| Thunks
    Thunks -->|host call| HostLibs

    %% External and Scripts
    FCG --> Config
    Config --> JSONPool["JSONPool (shared)"]
    Scripts -->|generates docs/syscalls| IRLayer
    Scripts -->|generates thunks| Thunks

    %% Click Events
    click FS "https://github.com/fex-emu/fex/tree/main/Source/Tools/FEXServer/"
    click FI "https://github.com/fex-emu/fex/tree/main/Source/Tools/FEXInterpreter/"
    click FCG "https://github.com/fex-emu/fex/tree/main/Source/Tools/FEXConfig/"
    click Loader "https://github.com/fex-emu/fex/tree/main/Source/Common/"
    click IRLayer "https://github.com/fex-emu/fex/tree/main/FEXCore/Source/Interface/IR/"
    click JIT "https://github.com/fex-emu/fex/tree/main/FEXCore/Source/Interface/Core/JIT/"
    click CodeCache "https://github.com/fex-emu/fex/blob/main/FEXCore/Source/Interface/Core/CodeCache.cpp"
    click CPUBackend "https://github.com/fex-emu/fex/blob/main/FEXCore/Source/Interface/Core/CPUBackend.cpp"
    click Interpreter "https://github.com/fex-emu/fex/tree/main/FEXCore/Source/Interface/Core/Interpreter/Fallbacks/"
    click CodeEmitter "https://github.com/fex-emu/fex/tree/main/CodeEmitter/CodeEmitter"
    click LinuxEmu "https://github.com/fex-emu/fex/tree/main/Source/Tools/LinuxEmulation/"
    click Thunks "https://github.com/fex-emu/fex/tree/main/ThunkLibs/"
    click ExtDeps "https://github.com/fex-emu/fex/tree/main/External/"
    click Config "https://github.com/fex-emu/fex/tree/main/Data/"
    click Scripts "https://github.com/fex-emu/fex/tree/main/Scripts/"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064
    classDef core fill:#fff3e0,stroke:#ff6f00
    classDef emitter fill:#e8f5e9,stroke:#2e7d32
    classDef emu fill:#f3e5f5,stroke:#6a1b9a
    classDef thunk fill:#fce4ec,stroke:#ad1457
    classDef external fill:#eceff1,stroke:#455a64
    classDef data fill:#fff8e1,stroke:#f9a825
```
