# tpde2/tpde architecture

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

- Interactive diagram: https://gitdiagram.com/tpde2/tpde
- Repository: https://github.com/tpde2/tpde

## Overview

##### Project Type and Purpose
- This is a compiler back-end framework (TPDE) plus two supporting components:
- TPDE-Encodegen: generates instruction encoders from LLVM Machine IR.
- TPDE-LLVM: a drop-in LLVM back-end that compiles LLVM IR much faster than LLVM-O0.
- It targets JIT and unoptimized builds on ELF x86-64 and AArch64.

##### High-Level File Structure Analysis
- Top-level modules:
- deps/            (third-party libraries)
- docs/            (user and internals documentation)
- tpde/            (core framework: IR adaptor, analysis, assembler, ELF mapper)
- tpde-encodegen/  (template-based code generator scaffold)
- tpde-llvm/       (LLVM adaptor, JIT mapper, tools: tpde-llc, tpde-lli)
- tests/ & tpde/test/ & tpde-llvm/test/ (unit and integration tests)
- tools/           (small helper scripts, coverage, CI)
- CMakeLists.txt orchestrates multi-module build, selects targets for each subproject.

##### Key Architectural Components
A. Front-end IR Adaptor
- IRAdaptor.hpp / LLVMAdaptor.cpp in tpde and tpde-llvm
- Takes incoming SSA IR or LLVM IR and translates to TPDE’s generic IR model.
B. Analyzer & Register-Allocator
- Analyzer.hpp, util structures (liveness, RPO, etc.)
- Produces basic block order, liveness info, and allocation constraints.
C. Code Generator (Core)
- CompilerBase.hpp, Compiler.hpp and platform-specific CompilerX64/A64
- Uses templates (from tpde-encodegen) or hand-written emitter to select and emit machine instructions.
D. Assembler & ELF Mapper
- AssemblerElf*.hpp/.cpp, ElfMapper.cpp
- Converts instruction streams into binary sections, symbol tables, relocation entries.
E. TPDE-Encodegen Utility
- Reads LLVM Machine IR → emits C++ template code (EncCompilerTemplate.hpp) for each target.
- Supplies platform encoder modules (arm64, x64) to core.
F. TPDE-LLVM Adaptor & Tools
- JITMapper: links with core to JIT-compile at runtime.
- tpde-llc / tpde-lli CLI wrappers around LLVMAdaptor + Compiler – emit object code or execute IR.

##### Component Interactions and Data Flow
1. Input Stage:
- External SSA IR or LLVM IR
→ IR Adaptor (tpde/include/tpde/IRAdaptor.hpp or tpde-llvm/src/LLVMAdaptor.cpp)
2. Analysis & Allocation:
→ Analyzer (compute CFG, liveness) → Register Allocator → ValueAssignment
3. Code Generation:
→ CompilerBase + platform-specific CompilerX64/A64 (tpde/src/x64 & arm64)
→ Use templates from tpde-encodegen for instruction encoding
4. Assembly & Linking:
→ AssemblerElf (emit .text, .data, relocations)
→ ElfMapper (pack into ELF object or in-memory JIT image)
5. Tooling Integration (TPDE-LLVM):
- For LLVM IR: LLVMAdaptor calls into TPDE core pipeline
- JITMapper for in-process execution
- CLI wrappers: tpde-llc (codegen to file), tpde-lli (interpret with JIT)

##### Architectural Patterns and Principles
- Layered Architecture: clear separation between IR Adaptor → Analyzer → CodeGen → Assembler → ELF.
- Plug-in / Template-driven codegen: tpde-encodegen decouples instruction definitions from core logic.
- Modular targets: x64 and A64 share common core, override only necessary methods.
- CMake multi-project build: each submodule builds into its own library or tool.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Input Stage"
        IR_EXTERNAL["External SSA IR / LLVM IR"]:::external
    end

    subgraph "Adaptors"
        IR_ADAPTOR["TPDE IRAdaptor"]:::adapt
        LLVM_ADAPTOR["LLVMAdaptor"]:::adapt
    end

    subgraph "Analysis & RegAlloc"
        ANALYZER["Analyzer"]:::analysis
        REGALLOC["Register Allocator"]:::analysis
    end

    subgraph "CodeGen Core"
        COMPILER_BASE["CompilerBase"]:::codegen
        COMPILER_CORE["Compiler"]:::codegen
        subgraph "Platform Backends"
            X64_BACKEND["CompilerX64"]:::codegen
            A64_BACKEND["CompilerA64"]:::codegen
        end
    end

    subgraph "Encodegen Utility"
        ENCODEGEN_MAIN["encode_gen"]:::util
        TEMPL_X64["EncCompilerTemplate (x64)"]:::util
        TEMPL_A64["EncCompilerTemplate (arm64)"]:::util
    end

    subgraph "Assembler & ELF Mapper"
        ASSEMBLER["AssemblerElf"]:::assembler
        ELF_MAPPER["ElfMapper"]:::assembler
        subgraph "Platform Assemblers"
            ASM_X64["AssemblerElfX64"]:::assembler
            ASM_A64["AssemblerElfA64"]:::assembler
        end
    end

    subgraph "Output"
        OBJ_OUT["ELF Object"]:::external
        JIT_IMG["In-memory JIT Image"]:::external
    end

    subgraph "TPDE-LLVM Integration"
        LLVM_COMPILER["LLVMCompiler"]:::adapt
        JITMAPPER["JITMapper"]:::adapt
        CLI_LLC["tpde-llc"]:::adapt
        CLI_LLI["tpde-lli"]:::adapt
    end

    IR_EXTERNAL --> IR_ADAPTOR
    IR_EXTERNAL --> LLVM_ADAPTOR
    IR_ADAPTOR --> ANALYZER
    LLVM_ADAPTOR --> ANALYZER
    ANALYZER --> REGALLOC
    REGALLOC --> COMPILER_BASE
    COMPILER_BASE --> COMPILER_CORE
    COMPILER_CORE --> X64_BACKEND
    COMPILER_CORE --> A64_BACKEND
    ENCODEGEN_MAIN --> TEMPL_X64
    ENCODEGEN_MAIN --> TEMPL_A64
    TEMPL_X64 --> X64_BACKEND
    TEMPL_A64 --> A64_BACKEND
    X64_BACKEND --> ASM_X64
    A64_BACKEND --> ASM_A64
    ASM_X64 --> ASSEMBLER
    ASM_A64 --> ASSEMBLER
    ASSEMBLER --> ELF_MAPPER
    ELF_MAPPER --> OBJ_OUT
    ELF_MAPPER --> JITMAPPER
    JITMAPPER --> JIT_IMG
    LLVM_COMPILER --> COMPILER_BASE
    LLVM_COMPILER --> CLI_LLC
    LLVM_COMPILER --> CLI_LLI

    click IR_ADAPTOR "https://github.com/tpde2/tpde/blob/master/tpde/include/tpde/IRAdaptor.hpp"
    click LLVM_ADAPTOR "https://github.com/tpde2/tpde/blob/master/tpde-llvm/src/LLVMAdaptor.cpp"
    click ANALYZER "https://github.com/tpde2/tpde/blob/master/tpde/include/tpde/Analyzer.hpp"
    click COMPILER_BASE "https://github.com/tpde2/tpde/blob/master/tpde/include/tpde/CompilerBase.hpp"
    click COMPILER_CORE "https://github.com/tpde2/tpde/blob/master/tpde/include/tpde/Compiler.hpp"
    click X64_BACKEND "https://github.com/tpde2/tpde/blob/master/tpde/include/tpde/x64/CompilerX64.hpp"
    click A64_BACKEND "https://github.com/tpde2/tpde/blob/master/tpde/include/tpde/arm64/CompilerA64.hpp"
    click ASM_X64 "https://github.com/tpde2/tpde/blob/master/tpde/src/x64/AssemblerElfX64.cpp"
    click ASM_A64 "https://github.com/tpde2/tpde/blob/master/tpde/src/arm64/AssemblerElfA64.cpp"
    click ASSEMBLER "https://github.com/tpde2/tpde/blob/master/tpde/include/tpde/AssemblerElf.hpp"
    click ELF_MAPPER "https://github.com/tpde2/tpde/blob/master/tpde/include/tpde/ElfMapper.hpp"
    click ENCODEGEN_MAIN "https://github.com/tpde2/tpde/blob/master/tpde-encodegen/src/encode_gen.cpp"
    click TEMPL_X64 "https://github.com/tpde2/tpde/blob/master/tpde-encodegen/src/x64/EncCompilerTemplate.hpp"
    click TEMPL_A64 "https://github.com/tpde2/tpde/blob/master/tpde-encodegen/src/arm64/EncCompilerTemplate.hpp"
    click LLVM_COMPILER "https://github.com/tpde2/tpde/blob/master/tpde-llvm/include/tpde-llvm/LLVMCompiler.hpp"
    click JITMAPPER "https://github.com/tpde2/tpde/blob/master/tpde-llvm/src/JITMapper.hpp"
    click CLI_LLC "https://github.com/tpde2/tpde/blob/master/tpde-llvm/tools/tpde-llc.cpp"
    click CLI_LLI "https://github.com/tpde2/tpde/blob/master/tpde-llvm/tools/tpde-lli.cpp"

    classDef adapt fill:#acd6ff,stroke:#004080,color:#004080
    classDef analysis fill:#ccffcc,stroke:#008000,color:#006400
    classDef codegen fill:#ffe5b4,stroke:#ff8c00,color:#8b4513
    classDef assembler fill:#e0b3ff,stroke:#800080,color:#4b0082
    classDef util fill:#d3d3d3,stroke:#696969,color:#000000
    classDef external fill:#f2f2f2,stroke:#a0a0a0,color:#505050
```
