# rexglue/rexglue-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/rexglue/rexglue-sdk
- Repository: https://github.com/rexglue/rexglue-sdk

## Overview

1. **What this repository is**
   ReXGlue is a cross-platform SDK and toolchain for statically recompiling Xbox 360 PowerPC code into native C++/host code. It is not a runtime JIT/emulator in the classic sense; the central architectural idea is “analyze guest binaries once, generate host source code, then build that into a native program.”

2. **Top-level product shape**
   The repo splits into two major deliverables:
   - a **library/runtime** that provides Xbox 360-like system services and host abstractions, and
   - a **CLI tool** (`rexglue`) that drives code generation, migration, and test/recompiler workflows.
   A large `tests` tree validates both PPC translation behavior and host-side subsystems.

3. **Static recompilation pipeline**
   The core data flow is: **guest binary / manifest / symbol data → analysis → function graph and phase passes → code emission → generated C++/project files**.  
   The `src/codegen` subsystem owns this pipeline, with phases such as discovery, scan, validation, gap filling, merging, and registration. Templates under `resources/templates/codegen` and `resources/templates/init` are used to emit project scaffolding and recompilation outputs.

4. **Guest binary analysis and decoding**
   Codegen works on decoded PowerPC/XEX-like inputs via `src/codegen/ppc` and related scanners (`function_scanner`, `sig_scanner`, `vtable_scanner`). This layer identifies functions, call graphs, signatures, and data regions so the generator can produce stable native equivalents rather than interpreting instructions at runtime.

5. **Runtime system model**
   The `src/system` and `include/rex/system` layers model the guest-facing runtime environment: modules, threads, events, shared libraries, symbol resolution, guest paths, MMIO, and XEX/ELF-style module loading. This is the boundary between generated native code and “Xbox-like” services that the generated code expects to call.

6. **Kernel emulation surface**
   Guest API compatibility is organized under `src/kernel` and `include/rex/kernel`, especially the Xbox 360 kernel, XAM, and XBDM namespaces. These subsystems expose exported functions and OS services to the translated code, including threading, memory, I/O, video, audio, debug, and content-related behaviors.

7. **Graphics pipeline and translation**
   Graphics is a major standalone subsystem. The architecture is layered as:
   - **guest command processing** (`src/graphics/command_processor.cpp`, packet disassembly),
   - **register/state tracking** (`register_file`, `shared_memory`, `primitive_processor`),
   - **pipeline translation** for shaders/textures/render targets,
   - and **host backend implementations**.
   Both **D3D12** and **Vulkan** backends exist, with backend-specific caches and command processors. Shader translation includes DXBC and SPIR-V generation/interpreters, so graphics is not just a renderer—it is a translation pipeline from Xbox 360 GPU state to host GPU APIs.

8. **UI / presentation layer**
   The `src/ui` subtree is a host-facing presentation layer for windowing, immediate-mode drawing, overlays, and presenter integration. It abstracts over **Win32**, **GTK/Unix**, **D3D12**, and **Vulkan**, and includes overlays like console/debug/settings. This layer is distinct from guest graphics: it is for the host app UI and presentation of the translated runtime.

9. **Audio and input subsystems**
   Host device adapters live in separate subsystems:
   - **audio**: SDL and no-op drivers, plus XMA decoding support for Xbox 360 media audio,
   - **input**: SDL, XInput, mouse/keyboard, and no-op drivers.
   These are structured as pluggable drivers behind common interfaces, so the runtime can be built with different host input/output strategies.

10. **Filesystem and content virtualization**
   The filesystem layer provides a virtual file system abstraction with multiple device types: host path, disc image, null, and STFS container support. This is important because guest code expects Xbox-style storage/content semantics rather than direct host filesystem access. Content managers and XAM content utilities sit on top of this to map guest content operations onto host data.

11. **Cross-platform foundation**
   `src/core` and the headers in `include/rex/*` provide the portable foundation: memory, threading, fibers, sockets, logging, chrono, exceptions, dynamic libraries, filesystem primitives, string utilities, SHA/crypto, and platform-specific shims for Windows and POSIX. This layer is the portability boundary used by almost every higher-level subsystem.

12. **PowerPC/Xenon-specific support**
   The repo includes explicit PowerPC/Xenon support in `include/rex/ppc`, `include/rex/graphics/xenos.h`, and the PPC-focused tests under `tests/ppc`. This means the project is not just “cross-platform C++”; it has a substantial guest-ISA model and validation suite for Xbox 360 instruction semantics and vector behavior.

13. **Developer tooling and UX**
   The `src/rexglue` CLI bundles commands for codegen, initialization, migration scanning, legacy config handling, and recompiler testing. PowerShell helpers in `scripts/PSReX` and CMake presets/workflows support configure/build/test/install flows. The toolchain is designed around repeatable project generation and CI-friendly automation.

14. **External dependencies and generated artifacts**
   The repository vendors substantial third-party code for graphics, shader tools, crypto, logging, CLI parsing, and UI. Many shader binaries are checked in as generated headers under `src/**/bytecode` and `src/**/vulkan_spirv`, which is a strong architectural signal: runtime rendering is partially driven by precompiled host shader artifacts rather than only source-level shader compilation.

15. **How to think about the main boundaries**
   For an architecture diagram, the most important boundaries are:
   - **Guest inputs**: Xbox 360 binaries, content, and trace/state data
   - **Analysis/codegen**: static recompilation pipeline and template emission
   - **Guest-runtime services**: system/kernel/filesystem/audio/input interfaces
   - **Host backends**: Windows/POSIX, D3D12/Vulkan, SDL/XInput/GTK
   - **Developer tooling/tests**: CLI, templates, CI, PPC/unit tests  
   The overall flow is from guest artifacts through analysis and runtime service modeling to native host execution and presentation.

Main entry points: [`src/system/runtime.cpp`](https://github.com/rexglue/rexglue-sdk/blob/main/src/system/runtime.cpp) (System model), [`src/codegen/codegen.cpp`](https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/codegen.cpp) (Codegen core), [`tests/unit/CMakeLists.txt`](https://github.com/rexglue/rexglue-sdk/blob/main/tests/unit/CMakeLists.txt) (Unit tests), [`src/kernel/kernel_init.cpp`](https://github.com/rexglue/rexglue-sdk/blob/main/src/kernel/kernel_init.cpp) (Kernel APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_toolchain["Toolchain"]
  node_node_cli["rexglue CLI<br/>tooling CLI<br/>[main.cpp]"]
  node_node_codegen["Codegen core<br/>static recompilation<br/>[codegen.cpp]"]
  node_node_phases["Pipeline phases<br/>analysis passes<br/>[phase_discover.cpp]"]
  node_node_ppc_decode["PPC decode<br/>guest ISA decode<br/>[disasm.cpp]"]
  node_node_scanners["Binary scanners<br/>binary analysis"]
  node_node_graph_model(("Function graph<br/>IR graph<br/>[function_graph.h]"))
  node_node_emitter["Code emitter<br/>source emission<br/>[code_emitter.cpp]"]
  node_node_templates["Templates<br/>[register_cpp.inja]"]
end

subgraph group_group_runtime["Runtime"]
  node_node_system["System model<br/>guest runtime<br/>[runtime.cpp]"]
  node_node_kernel["Kernel APIs<br/>compatibility layer<br/>[kernel_init.cpp]"]
  node_node_xboxkrnl["xboxkrnl<br/>OS services"]
  node_node_xam["XAM<br/>shell/services<br/>[xam_content.cpp]"]
  node_node_filesystem["VFS<br/>virtual filesystem"]
  node_node_audio["Audio<br/>[audio_system.cpp]"]
  node_node_input["Input<br/>[input_system.cpp]"]
end

subgraph group_group_platform["Foundation"]
  node_node_core["Core<br/>[logging.cpp]"]
  node_node_ppc["PPC support<br/>guest ISA<br/>[ppc.h]"]
end

subgraph group_group_graphics_ui["Presentation"]
  node_node_graphics["Graphics<br/>guest GPU translation"]
  node_node_gfx_backends["GPU backends<br/>host rendering"]
  node_node_ui["Host UI<br/>presentation layer<br/>[presenter.cpp]"]
  node_node_ui_backends["UI backends<br/>host windowing<br/>[window_win.cpp]"]
end

subgraph group_group_tests["Validation"]
  node_node_ppc_tests["PPC tests<br/>ISA validation<br/>[CMakeLists.txt]"]
  node_node_unit_tests["Unit tests<br/>subsystem tests<br/>[CMakeLists.txt]"]
end

node_node_cli -->|"drives"| node_node_codegen
node_node_cli -->|"uses"| node_node_templates
node_node_codegen -->|"runs"| node_node_phases
node_node_codegen -->|"analyzes"| node_node_scanners
node_node_scanners -->|"decodes"| node_node_ppc_decode
node_node_phases -->|"builds"| node_node_graph_model
node_node_graph_model -->|"feeds"| node_node_emitter
node_node_emitter -->|"renders"| node_node_templates
node_node_codegen -->|"targets"| node_node_system
node_node_system -->|"dispatches"| node_node_kernel
node_node_kernel -->|"includes"| node_node_xboxkrnl
node_node_kernel -->|"includes"| node_node_xam
node_node_system -->|"mounts"| node_node_filesystem
node_node_system -->|"binds"| node_node_audio
node_node_system -->|"binds"| node_node_input
node_node_core -->|"supports"| node_node_system
node_node_core -->|"supports"| node_node_graphics
node_node_ppc -->|"supports"| node_node_codegen
node_node_graphics -->|"targets"| node_node_gfx_backends
node_node_graphics -->|"shares"| node_node_ui
node_node_ui -->|"abstracts"| node_node_ui_backends
node_node_ppc_tests -->|"validates"| node_node_ppc
node_node_unit_tests -->|"validates"| node_node_codegen
node_node_unit_tests -->|"validates"| node_node_system
node_node_unit_tests -->|"validates"| node_node_core

click node_node_cli "https://github.com/rexglue/rexglue-sdk/blob/main/src/rexglue/main.cpp"
click node_node_codegen "https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/codegen.cpp"
click node_node_phases "https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/phase_discover.cpp"
click node_node_ppc_decode "https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/ppc/disasm.cpp"
click node_node_scanners "https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/function_scanner.cpp"
click node_node_graph_model "https://github.com/rexglue/rexglue-sdk/blob/main/include/rex/codegen/function_graph.h"
click node_node_emitter "https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/code_emitter.cpp"
click node_node_templates "https://github.com/rexglue/rexglue-sdk/blob/main/resources/templates/codegen/register_cpp.inja"
click node_node_system "https://github.com/rexglue/rexglue-sdk/blob/main/src/system/runtime.cpp"
click node_node_kernel "https://github.com/rexglue/rexglue-sdk/blob/main/src/kernel/kernel_init.cpp"
click node_node_xboxkrnl "https://github.com/rexglue/rexglue-sdk/blob/main/src/kernel/xboxkrnl/xboxkrnl_threading.cpp"
click node_node_xam "https://github.com/rexglue/rexglue-sdk/blob/main/src/kernel/xam/xam_content.cpp"
click node_node_filesystem "https://github.com/rexglue/rexglue-sdk/blob/main/src/filesystem/virtual_file_system.cpp"
click node_node_audio "https://github.com/rexglue/rexglue-sdk/blob/main/src/audio/audio_system.cpp"
click node_node_input "https://github.com/rexglue/rexglue-sdk/blob/main/src/input/input_system.cpp"
click node_node_core "https://github.com/rexglue/rexglue-sdk/blob/main/src/core/logging.cpp"
click node_node_ppc "https://github.com/rexglue/rexglue-sdk/blob/main/include/rex/ppc.h"
click node_node_graphics "https://github.com/rexglue/rexglue-sdk/blob/main/src/graphics/graphics_system.cpp"
click node_node_gfx_backends "https://github.com/rexglue/rexglue-sdk/blob/main/src/graphics/d3d12/graphics_system.cpp"
click node_node_ui "https://github.com/rexglue/rexglue-sdk/blob/main/src/ui/presenter.cpp"
click node_node_ui_backends "https://github.com/rexglue/rexglue-sdk/blob/main/src/ui/window_win.cpp"
click node_node_ppc_tests "https://github.com/rexglue/rexglue-sdk/blob/main/tests/ppc/CMakeLists.txt"
click node_node_unit_tests "https://github.com/rexglue/rexglue-sdk/blob/main/tests/unit/CMakeLists.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_node_cli,node_node_codegen,node_node_phases,node_node_ppc_decode,node_node_scanners,node_node_graph_model,node_node_emitter,node_node_templates toneBlue
class node_node_system,node_node_kernel,node_node_xboxkrnl,node_node_xam,node_node_filesystem,node_node_audio,node_node_input toneAmber
class node_node_core,node_node_ppc toneMint
class node_node_graphics,node_node_gfx_backends,node_node_ui,node_node_ui_backends toneRose
class node_node_ppc_tests,node_node_unit_tests toneIndigo
```

## Components

### Toolchain

Static recompilation pipeline, CLI, and code generation templates.

- [rexglue CLI](https://github.com/rexglue/rexglue-sdk/blob/main/src/rexglue/main.cpp): tooling CLI · Entry point for codegen, init, migration, and test workflows. · `src/rexglue/main.cpp`
- [Codegen core](https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/codegen.cpp): static recompilation · Coordinates analysis, phase execution, emission, and project recompilation. · `src/codegen/codegen.cpp`
- [Pipeline phases](https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/phase_discover.cpp): analysis passes · Discovery, scan, validate, gap-fill, merge, and register steps. · `src/codegen/phase_discover.cpp`
- [PPC decode](https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/ppc/disasm.cpp): guest ISA decode · PowerPC disassembly and instruction modeling for translation. · `src/codegen/ppc/disasm.cpp`
- [Binary scanners](https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/function_scanner.cpp): binary analysis · Function, signature, and vtable discovery over decoded guest inputs. · `src/codegen/function_scanner.cpp`
- [Function graph](https://github.com/rexglue/rexglue-sdk/blob/main/include/rex/codegen/function_graph.h): IR graph · Represents discovered functions, calls, and code regions for generation. · `include/rex/codegen/function_graph.h`
- [Code emitter](https://github.com/rexglue/rexglue-sdk/blob/main/src/codegen/code_emitter.cpp): source emission · Writes generated C++ and project artifacts from analysis results. · `src/codegen/code_emitter.cpp`
- [Templates](https://github.com/rexglue/rexglue-sdk/blob/main/resources/templates/codegen/register_cpp.inja): inje templates · Scaffolding and codegen templates for init, project, and registration output. · `resources/templates/codegen/register_cpp.inja`

### Runtime

Guest-facing system model and Xbox compatibility layers.

- [System model](https://github.com/rexglue/rexglue-sdk/blob/main/src/system/runtime.cpp): guest runtime · Module loading, symbols, threads, paths, MMIO, and export resolution. · `src/system/runtime.cpp`
- [Kernel APIs](https://github.com/rexglue/rexglue-sdk/blob/main/src/kernel/kernel_init.cpp): compatibility layer · Xbox 360 kernel, XAM, and XBDM services exposed to translated code. · `src/kernel/kernel_init.cpp`
- [xboxkrnl](https://github.com/rexglue/rexglue-sdk/blob/main/src/kernel/xboxkrnl/xboxkrnl_threading.cpp): OS services · Core kernel exports for memory, threading, I/O, debug, and media. · `src/kernel/xboxkrnl/xboxkrnl_threading.cpp`
- [XAM](https://github.com/rexglue/rexglue-sdk/blob/main/src/kernel/xam/xam_content.cpp): shell/services · Dashboard-style application, content, user, and media services. · `src/kernel/xam/xam_content.cpp`
- [VFS](https://github.com/rexglue/rexglue-sdk/blob/main/src/filesystem/virtual_file_system.cpp): virtual filesystem · Guest storage virtualization across host paths, disc images, null devices, and STFS. · `src/filesystem/virtual_file_system.cpp`
- [Audio](https://github.com/rexglue/rexglue-sdk/blob/main/src/audio/audio_system.cpp): host audio · Audio drivers plus XMA decoding for Xbox media audio. · `src/audio/audio_system.cpp`
- [Input](https://github.com/rexglue/rexglue-sdk/blob/main/src/input/input_system.cpp): host input · Pluggable SDL, XInput, mouse/keyboard, and no-op input drivers. · `src/input/input_system.cpp`

### Foundation

Cross-platform core services and portability shims.

- [Core](https://github.com/rexglue/rexglue-sdk/blob/main/src/core/logging.cpp): portability core · Memory, threading, files, logging, chrono, sockets, dynlibs, and platform shims. · `src/core/logging.cpp`
- [PPC support](https://github.com/rexglue/rexglue-sdk/blob/main/include/rex/ppc.h): guest ISA · PowerPC/Xenon types, context, stack, and intrinsics used across the repo. · `include/rex/ppc.h`

### Presentation

Guest graphics translation plus host UI and presentation.

- [Graphics](https://github.com/rexglue/rexglue-sdk/blob/main/src/graphics/graphics_system.cpp): guest GPU translation · Guest command processing, state tracking, and shader/texture pipeline translation. · `src/graphics/graphics_system.cpp`
- [GPU backends](https://github.com/rexglue/rexglue-sdk/blob/main/src/graphics/d3d12/graphics_system.cpp): host rendering · D3D12 and Vulkan implementations of the translated graphics pipeline. · `src/graphics/d3d12/graphics_system.cpp`
- [Host UI](https://github.com/rexglue/rexglue-sdk/blob/main/src/ui/presenter.cpp): presentation layer · Windowing, overlays, immediate drawing, and presenter integration for the host app. · `src/ui/presenter.cpp`
- [UI backends](https://github.com/rexglue/rexglue-sdk/blob/main/src/ui/window_win.cpp): host windowing · Win32, GTK/Unix, D3D12, and Vulkan presentation backends. · `src/ui/window_win.cpp`

### Validation

ISA and subsystem validation, plus supporting test scaffolding.

- [PPC tests](https://github.com/rexglue/rexglue-sdk/blob/main/tests/ppc/CMakeLists.txt): ISA validation · Assembler-based instruction and vector semantics coverage for Xenon/PowerPC behavior. · `tests/ppc/CMakeLists.txt`
- [Unit tests](https://github.com/rexglue/rexglue-sdk/blob/main/tests/unit/CMakeLists.txt): subsystem tests · Focused tests for codegen, core, kernel, memory, system, and CLI behavior. · `tests/unit/CMakeLists.txt`

## Connections

- rexglue CLI → Codegen core: drives · CLI orchestrates the static recompilation workflow.
- rexglue CLI → Templates: uses · CLI init and codegen commands emit project scaffolding from templates.
- Codegen core → Pipeline phases: runs · Main codegen execution is organized as phased analysis and transformation.
- Codegen core → Binary scanners: analyzes · Codegen discovers functions, signatures, and vtables from guest binaries.
- Binary scanners → PPC decode: decodes · Scanners rely on PowerPC instruction decoding and binary inspection.
- Pipeline phases → Function graph: builds · Phase passes populate and refine the function graph.
- Function graph → Code emitter: feeds · The function graph is the main input to source emission.
- Code emitter → Templates: renders · Emitter fills project and source templates with analysis output.
- Codegen core → System model: targets · Generated code is shaped to the guest system model and module layout.
- System model → Kernel APIs: dispatches · System services route compatibility calls into kernel namespaces.
- Kernel APIs → xboxkrnl: includes · Core Xbox kernel services implement OS-level guest APIs.
- Kernel APIs → XAM: includes · XAM provides shell, content, and user-facing guest services.
- System model → VFS: mounts · Guest path and content operations are virtualized through VFS devices.
- System model → Audio: binds · Guest audio calls are mapped onto host audio and XMA decoding.
- System model → Input: binds · Guest input expectations are handled by host input drivers.
- Core → System model: supports · Portable primitives underpin runtime modules and services.
- Core → Graphics: supports · Shared memory, threading, logging, and files are used by graphics.
- PPC support → Codegen core: supports · Guest ISA types and helpers are used throughout analysis and translation.
- Graphics → GPU backends: targets · Guest GPU translation is lowered to D3D12 and Vulkan backends.
- Graphics → Host UI: shares · Graphics trace/presentation data can be surfaced through host UI.
- Host UI → UI backends: abstracts · UI presentation is implemented over Win32, GTK, D3D12, and Vulkan.
- PPC tests → PPC support: validates · Assembler tests exercise PowerPC/Xenon semantics and vector behavior.
- Unit tests → Codegen core: validates · Unit tests cover codegen configuration, manifests, templates, and scans.
- Unit tests → System model: validates · Unit tests cover function dispatch, guest paths, and runtime utilities.
- Unit tests → Core: validates · Core tests exercise memory, fibers, chrono, streams, and hashing.
