FEX-Emu--FEX/docs/SourceOutline.md

FEX-2208

External/FEXCore

See FEXCore/Readme.md for more details

Glossary

• Splatter: a code generator backend that concaternates configurable macros instead of doing isel
• IR: Intermediate Representation, our high-level opcode representation, loosely modeling arm64
• SSA: Single Static Assignment, a form of representing IR in memory
• Basic Block: A block of instructions with no control flow, terminated by control flow
• Fragment: A Collection of basic blocks, possibly an entire guest function or a subset of it

backend

IR to host code generation

arm64

• ALUOps.cpp
• Arm64Relocations.cpp: relocation logic of the arm64 splatter backend
• AtomicOps.cpp
• BranchOps.cpp
• ConversionOps.cpp
• EncryptionOps.cpp
• FlagOps.cpp
• JIT.cpp: Main glue logic of the arm64 splatter backend
• JITClass.h
• MemoryOps.cpp
• MiscOps.cpp
• MoveOps.cpp
• VectorOps.cpp

interpreter

• ALUOps.cpp
• AtomicOps.cpp
• BranchOps.cpp
• ConversionOps.cpp
• EncryptionOps.cpp
• F80Ops.cpp
• FlagOps.cpp
• MemoryOps.cpp
• MiscOps.cpp
• MoveOps.cpp
• VectorOps.cpp

shared

• CPUBackend.h

x86-64

• ALUOps.cpp
• AtomicOps.cpp
• BranchOps.cpp
• ConversionOps.cpp
• EncryptionOps.cpp
• FlagOps.cpp
• JIT.cpp: Main glue logic of the x86-64 splatter backend
• JITClass.h
• MemoryOps.cpp
• MiscOps.cpp
• MoveOps.cpp
• VectorOps.cpp
• x64Relocations.cpp: relocation logic of the x86-64 splatter backend

frontend

x86-meta-blocks

• Frontend.cpp: Extracts instruction & block meta info, frontend multiblock logic

x86-tables

Metadata that drives the frontend x86/64 decoding

• BaseTables.cpp
• DDDTables.cpp
• EVEXTables.cpp
• H0F38Tables.cpp
• H0F3ATables.cpp
• PrimaryGroupTables.cpp
• SecondaryGroupTables.cpp
• SecondaryModRMTables.cpp
• SecondaryTables.cpp
• VEXTables.cpp
• X86Tables.h
• X87Tables.cpp
• XOPTables.cpp
• X86Tables.cpp

x86-to-ir

• Crypto.cpp: Handles x86/64 Crypto instructions to IR
• Flags.cpp: Handles x86/64 flag generation
• Vector.cpp: Handles x86/64 Vector instructions to IR
• X87.cpp: Handles x86/64 x87 to IR
• X87F64.cpp: Handles x86/64 x87 to IR
• OpcodeDispatcher.cpp: Handles x86/64 ops to IR, no-pf opt, local-flags opt

glue

Logic that binds various parts together

block-database

• LookupCache.cpp: Stores information about blocks, and provides C++ implementations to lookup the blocks

driver

Emulation mainloop related glue logic

• Core.cpp: Glues Frontend, OpDispatcher and IR Opts & Compilation, LookupCache, Dispatcher and provides the Execution loop entrypoint

gdbserver

• GdbServer.cpp: Provides a gdb interface to the guest state
• GdbServer.h

log-manager

• LogManager.cpp

thunks

FEXCore side of thunks: Registration, Lookup

• Thunks.cpp
• Thunks.h

x86-guest-code

• X86HelperGen.cpp: Guest-side assembly helpers used by the backends
• X86HelperGen.h

ir

dumper

IR -> Text

• IRDumper.cpp

emitter

C++ Functions to generate IR. See IR.json for spec.

• IREmitter.cpp

opts

IR to IR Optimization

• PassManager.cpp: Defines which passes are run, and runs them
• PassManager.h
• ConstProp.cpp: ConstProp, ZExt elim, addressgen coalesce, const pooling, fcmp reduction, const inlining
• DeadCodeElimination.cpp
• DeadContextStoreElimination.cpp: Transforms ContextLoad/Store to temporaries, similar to mem2reg
• DeadStoreElimination.cpp: Cross block store-after-store elimination
• IRCompaction.cpp: Sorts the ssa storage in memory, needed for RA and others
• IRValidation.cpp: Sanity checking pass
• LongDivideRemovalPass.cpp: Long divide elimination pass
• PhiValidation.cpp: Sanity checking pass
• RedundantFlagCalculationElimination.cpp: This is not used right now, possibly broken
• RegisterAllocationPass.cpp
• RegisterAllocationPass.h
• StaticRegisterAllocationPass.cpp: Replaces Load/StoreContext with Load/StoreReg for SRA regs
• SyscallOptimization.cpp: Removes unused arguments if known syscall number
• ValueDominanceValidation.cpp: Sanity Checking

parser

Text -> IR

• IRParser.cpp

opcodes

cpuid

• CPUID.cpp: Handles presented capability bits for guest cpu

dispatcher-implementations

• Crypto.cpp: Handles x86/64 Crypto instructions to IR
• Flags.cpp: Handles x86/64 flag generation
• Vector.cpp: Handles x86/64 Vector instructions to IR
• X87.cpp: Handles x86/64 x87 to IR
• X87F64.cpp: Handles x86/64 x87 to IR
• OpcodeDispatcher.cpp: Handles x86/64 ops to IR, no-pf opt, local-flags opt

ThunkLibs

See ThunkLibs/README.md for more details

thunklibs

These are generated + glue logic 1:1 thunks unless noted otherwise

EGL

• libEGL_Guest.cpp: Depends on glXGetProcAddress thunk
• libEGL_Host.cpp

GL

• libGL_Guest.cpp: Handles glXGetProcAddress
• libGL_Host.cpp: Uses glXGetProcAddress instead of dlsym

SDL2

• libSDL2_Guest.cpp: Handles sdlglproc, dload, stubs a few log fns
• libSDL2_Host.cpp

Vulkan

• Guest.cpp
• Host.cpp

X11

• libX11_Guest.cpp: Handles callbacks and varargs
• libX11_Host.cpp: Handles callbacks and varargs
• libXext_Guest.cpp
• libXext_Host.cpp
• libXfixes_Guest.cpp
• libXfixes_Host.cpp
• libXrender_Guest.cpp
• libXrender_Host.cpp

asound

• libasound_Guest.cpp
• libasound_Host.cpp

drm

• Guest.cpp
• Host.cpp

fex_malloc

• Guest.cpp: Handles allocations between guest and host thunks
• Host.cpp: Handles allocations between guest and host thunks

fex_malloc_loader

• Guest.cpp: Delays malloc symbol replacement until it is safe to run constructors

fex_malloc_symbols

• Host.cpp: Allows FEX to export allocation symbols

xcb

• libxcb_Guest.cpp
• libxcb_Host.cpp

xcb-dri2

• libxcb-dri2_Guest.cpp
• libxcb-dri2_Host.cpp

xcb-dri3

• libxcb-dri3_Guest.cpp
• libxcb-dri3_Host.cpp

xcb-glx

• Guest.cpp
• Host.cpp

xcb-present

• Guest.cpp
• Host.cpp

xcb-randr

• Guest.cpp
• Host.cpp

xcb-shm

• libxcb-shm_Guest.cpp
• libxcb-shm_Host.cpp

xcb-sync

• Guest.cpp
• Host.cpp

xcb-xfixes

• libxcb-xfixes_Guest.cpp
• libxcb-xfixes_Host.cpp

xshmfence

• Guest.cpp
• Host.cpp

Source/Tests

Bin

FEXBash

• FEXBash.cpp: Launches bash under FEX and passes arguments via -c to it

FEXLoader

• FEXLoader.cpp: Glues the ELF loader, FEXCore and LinuxSyscalls to launch an elf under fex

IRLoader

• IRLoader.cpp: Used to run IR Tests

TestHarnessRunner

• TestHarnessRunner.cpp: Used to run Assembly tests

UnitTestGenerator

• UnitTestGenerator.cpp: Brute forces generation of tests for x86/64, incomplete, unused right now

LinuxSyscalls

Linux syscall emulation, marshaling and passthrough

android-syscalls-shared

• Memory.cpp

common

• EmulatedFiles.cpp: Emulated /proc/cpuinfo, version, osrelease, etc
• EmulatedFiles.h
• FileManagement.cpp: Rootfs overlay logic
• FileManagement.h
• SignalDelegator.cpp: Handles host -> host and host -> guest signal routing, emulates procmask & co
• SignalDelegator.h
• Syscalls.cpp: Glue logic, brk allocations
• Syscalls.h: Glue logic, STRACE magic
• SyscallsSMCTracking.cpp: SMC/MMan Tracking
• SyscallsVMATracking.cpp: VMA Tracking

syscalls-arm64

• SyscallsEnum.h

syscalls-shared

Syscall implementations shared between x86 and x86-64

• EPoll.cpp
• FD.cpp
• FS.cpp
• IO.cpp
• IOUring.cpp
• Info.cpp
• Key.cpp
• Memory.cpp
• Msg.cpp
• Namespace.cpp
• NotImplemented.cpp
• SHM.cpp
• Sched.cpp
• Semaphore.cpp
• Signals.cpp
• Socket.cpp
• Stubs.cpp
• Thread.cpp
• Thread.h
• Time.cpp
• Timer.cpp

syscalls-x86-32

x86-32 specific syscall implementations

• EPoll.cpp
• FD.cpp
• FS.cpp
• IO.cpp
• Info.cpp
• Memory.cpp
• Msg.cpp
• NotImplemented.cpp
• Sched.cpp
• Semaphore.cpp
• Signals.cpp
• Socket.cpp
• Stubs.cpp
• Syscalls.cpp
• Syscalls.h
• SyscallsEnum.h
• Thread.cpp
• Thread.h
• Time.cpp
• Timer.cpp
• Types.h

syscalls-x86-64

x86-64 specific syscall implementations

• EPoll.cpp
• FD.cpp
• IO.cpp
• Info.cpp
• Ioctl.cpp
• Memory.cpp
• Msg.cpp
• NotImplemented.cpp
• Sched.cpp
• Semaphore.cpp
• Signals.cpp
• Socket.cpp
• Syscalls.cpp
• Syscalls.h
• SyscallsEnum.h
• Thread.cpp
• Thread.h
• Time.cpp
• Types.h

unittests

See unittests/Readme.md for more details