Repository navigation
Architecture
Pablo Souza edited this page Nov 16, 2026
·
8 revisions
game.exe ──x2recomp──► games/<id>/gen/*.c ──clang──► x2gen_<id> (objects) ─┬─► x2-<id> (desktop executable)
├─► x2-<size>-<entry>.so (game pack for the Android app)
runtime/ (C): memory, threads, Win32/D3D9/DSound/DirectShow, └─► typex2_libretro (all games)
JVS I/O, GL renderer; SDL3 or libretro platform layer
-
Discovery (
discover.cpp). Recursive descent from the entry point, exports, relocated code pointers and known table patterns finds every function.- MSVC CRT
_trandispdescriptors become entry points. - Gaps between known functions are tried as candidates, once each.
- Code that discovery still misses shows up at run time as "jump to unknown
guest address". Pass
--entry 0xADDR, or teach discovery the pattern.
- MSVC CRT
-
Lifting (
lift.cpp). Each x86 function becomes one C function.- Registers and flags. General registers and EFLAGS are C locals; the compiler removes dead flag computations.
- FPU and vectors. x87 is modelled with doubles; SSE and MMX use unions.
- Calls. Direct calls are C calls; indirect calls go through the runtime's dispatcher.
-
Flag analysis (
Lifter::analyze_flag_exports):- Flag exporters are callees whose flags the caller reads, such as MSVC CRT x87 helpers.
-
Flag importers are functions that read flags their caller set, such as
MSVC
/RTC's_RTC_CheckEsp. Their callers spill flags before the call, and the callee reloads them on entry.
-
Natives and patches.
- Hot library routines, recognised by their bytes, are replaced with C
versions in
runtime/src/natives.c: zlibinflate_fast, a byte fill, and both BlazBlue sprite RLE expanders. - Byte patches fix behaviour that is wrong under the runtime, such as SSF4's frame-limiter spin.
-
--no-nativeslifts the original code instead.
- Hot library routines, recognised by their bytes, are replaced with C
versions in
-
Output goes to
games/<id>/gen/:funcs_*.c,funcs.h,table.c, andreport.txtlisting unsupported instructions. Data misread as code shows up there asoutsb/insd/aas, which is harmless.
tools/lifttest runs the lifter against Unicorn as a differential test.
| Part | Files |
|---|---|
| Guest memory: 4 GiB reserved, PE loading, import binding |
mem.c, loader.c (hle_modules[] maps DLL names to tables) |
| Threads, sync, the dispatcher for indirect calls |
thread.c, dispatch.c, hle/k32_sync.c
|
| Win32 |
hle/k32_*.c, hle/user32.c, hle/gdi32.c, ... |
| Direct3D 9, D3DX, effects |
hle/d3d9.c, hle/d3dx9.c, hle/d3dx_effect.c, gfx/fx.c
|
| Shader translation |
gfx/sm3_glsl.c (bytecode → GLSL), gfx/d3dasm.c (assembly, ps_1_x → ps_2_0), gfx/hlsl_glsl.c (HLSL source) |
| Fixed-function pipeline |
gfx/ffp.c: FVF → vertex declaration, vertex format and texture stage states → generated vs_2_0 / ps_2_0 bytecode (cached per state in hle/d3d9.c); its constants live in reserved registers (c248-c252, ps c222) that the game's own values are restored to before its next shader draw |
| Renderer |
gfx/gfx_gl*.c: commands recorded per frame by the guest, replayed on the platform thread |
| Sound, movies |
hle/dsound.c, hle/dshow.c, video_ffmpeg.c
|
| Inputs |
jvs.c (the board), padmap.c (pads, X2_PAD, X2_INPUT) |
| Front ends |
platform_sdl.c (standalone), platform_libretro.c (core), boot.c (shared start-up) |
| Profiling |
prof.c (X2_PROF), pacing / GPU timers in the platform layers |
HLE functions follow one pattern:
- signature
static void Name(X2Cpu *c); - arguments read with
ARG(n), the result returned withRET(v); - listed with their stdcall argument count in the module's
X2Hletable.
- Guest threads. Every guest thread is a host thread, and they run in parallel.
-
Frames. The game's main thread records each frame. In the standalone
app the platform thread replays it with the renderer (Metal, Vulkan or GL). In the core,
retro_runboth replays and clocks the guest, with one frame in flight: the guest computes frame N+1 while RetroArch shows frame N. -
Ending a session. Guest threads can't be torn down. On libretro unload
they park at their next import call; the guest space is remapped
inaccessible (pages freed), and so are the heap blocks of 4 KB and up on ELF
platforms (
heap.c, the core linked with--wrap=malloc,...). A parked thread that touches them faults and stays parked. -
Switching games. The runtime's state is global, so each game after the
first runs in a fresh instance of the core's library (Android:
ANDROID_DLEXT_FORCE_LOAD; elsewhere a temporary copy), and theretro_*entry points of the instance RetroArch loaded forward to it. -
Reset. The same: the game restarts in a fresh instance. RetroArch keeps
its video context across a reset, so the running instance first destroys
its Vulkan objects and frees their memory (
gfx_vk_release), the new one takes the context over instead of asking for one, and the replaced instance forwards RetroArch's context callbacks to it.
savestate.c; players' view in Save states.
-
What a state holds. Generated code spills the guest registers to the
thread's
X2Cpuaround every call, so at an import call a thread's guest state is itsX2Cpuplus guest memory. A state holds:- every allocated guest page, and the region map and heap lists;
- each thread's registers;
- the handle table: events, mutexes and semaphores with their state, and files with their path and offset;
- the COM objects' reference counts;
- the D3D9 device's state, the DirectSound buffers' playback, and the guest clock.
-
What it can't hold. Each guest function a thread is inside is a C
frame on its host stack. A state is therefore restored only into threads
whose host stacks hold the same chain of generated-code frames (return
addresses, compared module-relative). The host objects behind handles and
COM objects (textures, buffers) are not saved either: a state needs the
run that took it. Objects released after a state was taken are kept for a
while (up to 4096
keepobjects; their guest memory is freed as usual), so loading it can bring them back. -
Stopping the threads. Every thread has to stop at a reproducible point,
or no load would find them where the state has them.
- The thread that presents frames stops only in Present (
gfx_present, also inside its waits for the renderer and the front end). It may hold critical sections there. - The others keep running until it has stopped, since it may need them for its frame. Then they stop where they wait, holding no section.
- A thread blocked entering a section counts as stopped. Its chain is recorded before it blocks.
- A load waits for each thread to reach the chain and sections it has in the state. A worker elsewhere is retried at later frames.
- The thread that presents frames stops only in Present (
-
Front ends. The player saves to a file from a worker thread (F5 / F7,
X2_STATE_AT). The core serialises in memory on RetroArch's thread. It reportsSINGLE_SESSION, and refuses a state a frame (rewind, run-ahead).
-
Linking. Every game's generated code is partially linked into one
object with localised symbols. A per-game
X2GameTablesdescriptor names the game. -
Choosing the game. The core picks the game from the PE header of the
game.exeit is given.
- Save states load only in the run that took them, on the same screen, and not during movies (see above).
-
Structured exceptions (
RaiseException, C++throw) are not dispatched to the guest. -
Memory ordering. Guest threads run truly parallel. On ARM, shared
(non-stack) guest stores are release stores (and loads acquire, with
X2_TSO=1), so code relying on x86's ordering (the games' spinlocks) stays correct. - GDI text on Android uses stb_truetype: heavy weights are emboldened by one pixel only, so they look lighter than on macOS (CoreText).
-
D3DX effects:
Get*Array, parameter blocks andCloneEffectare not implemented, and stop with a named error if a game calls them.
Per-game issues are on each game's page (Game status).
Status
Games
Guides
Development