How rexglue/rexglue-sdk works
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: runtime.cpp System model · codegen.cpp Codegen core · CMakeLists.txt Unit tests · kernel_init.cpp Kernel APIs
Components 23
Toolchain
Static recompilation pipeline, CLI, and code generation templates.
- rexglue CLI · Entry point for codegen, init, migration, and test workflows.
src/rexglue/main.cpp - Codegen core · Coordinates analysis, phase execution, emission, and project recompilation.
src/codegen/codegen.cpp - Pipeline phases · Discovery, scan, validate, gap-fill, merge, and register steps.
src/codegen/phase_discover.cpp - PPC decode · PowerPC disassembly and instruction modeling for translation.
src/codegen/ppc/disasm.cpp - Binary scanners · Function, signature, and vtable discovery over decoded guest inputs.
src/codegen/function_scanner.cpp - Function graph · Represents discovered functions, calls, and code regions for generation.
include/rex/codegen/function_graph.h - Code emitter · Writes generated C++ and project artifacts from analysis results.
src/codegen/code_emitter.cpp - 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 · Module loading, symbols, threads, paths, MMIO, and export resolution.
src/system/runtime.cpp - Kernel APIs · Xbox 360 kernel, XAM, and XBDM services exposed to translated code.
src/kernel/kernel_init.cpp - xboxkrnl · Core kernel exports for memory, threading, I/O, debug, and media.
src/kernel/xboxkrnl/xboxkrnl_threading.cpp - XAM · Dashboard-style application, content, user, and media services.
src/kernel/xam/xam_content.cpp - VFS · Guest storage virtualization across host paths, disc images, null devices, and STFS.
src/filesystem/virtual_file_system.cpp - Audio · Audio drivers plus XMA decoding for Xbox media audio.
src/audio/audio_system.cpp - 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 · Memory, threading, files, logging, chrono, sockets, dynlibs, and platform shims.
src/core/logging.cpp - PPC support · 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 · Guest command processing, state tracking, and shader/texture pipeline translation.
src/graphics/graphics_system.cpp - GPU backends · D3D12 and Vulkan implementations of the translated graphics pipeline.
src/graphics/d3d12/graphics_system.cpp - Host UI · Windowing, overlays, immediate drawing, and presenter integration for the host app.
src/ui/presenter.cpp - UI backends · Win32, GTK/Unix, D3D12, and Vulkan presentation backends.
src/ui/window_win.cpp
Validation
ISA and subsystem validation, plus supporting test scaffolding.
- PPC tests · Assembler-based instruction and vector semantics coverage for Xenon/PowerPC behavior.
tests/ppc/CMakeLists.txt - Unit tests · Focused tests for codegen, core, kernel, memory, system, and CLI behavior.
tests/unit/CMakeLists.txt
Connections 25
- 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.