Architecture

Architecture

Reviewed: 2026-11-01 · Source: b7140848 · Availability: current main; stable/main boundaries are stated below.

Current implementation/defaults and stable/main availability are maintained in Current status, Current register and Controls. Dated observations below retain their own source and evidence boundary.

This section documents xemu by subsystem and by data flow. The goal is to answer what owns the state, which thread performs the work, where translation occurs, and where synchronization is required.

System map

flowchart TD
    A[Guest x86 code] --> B[Single Pentium III vCPU]
    B --> C[TCG translation blocks]
    C --> D[Guest physical memory / MMIO / I/O]

    D --> E[PCI / LPC / SMBus / platform devices]
    D --> F[NV2A]

    E --> E1[IDE / USB / NVNet / APU / SMC]

    F --> G[PFIFO command processing]
    G --> H[PGRAPH guest GPU state]
    H --> I{PGRAPHRenderer backend}
    I --> J[OpenGL]
    I --> K[Vulkan]

    L[QEMU clocks and timer lists] --> B
    L --> E
    L --> F

Loading

The diagram is intentionally high level. xemu is not one large execution loop: guest CPU execution, address-space dispatch, device models, timers, GPU command processing, host rendering, networking, audio and storage each have separate ownership and synchronization rules.

Architecture pages

Subsystem	Page	Main questions answered
Whole machine	System Architecture	What hardware is modeled and how major subsystems connect
CPU	CPU & vCPU Execution	How guest x86 becomes host code, how translation blocks are dispatched, and why the vCPU exits
Memory	Memory & DMA	How RAM/ROM/MMIO mappings, DMA identity, dirty tracking and host mirrors relate
Platform / I/O	Platform & I/O	How PCI/AGP/LPC, IRQ routing, SMBus, IDE, USB, NVNet and MCPX APU fit together
Timing	Clocks & Timers	Which clocks exist, how deadlines wake xemu, and how device timers become guest-visible interrupts
Graphics	NV2A Graphics Architecture	How pushbuffer work moves through PFIFO/PGRAPH into a renderer backend
OpenGL	OpenGL Renderer	How the stateful OpenGL backend translates NV2A state and draws
Vulkan	Vulkan Renderer	How xemu records explicit Vulkan work, owns resources, caches shaders/pipelines, and synchronizes batches
Backend boundary	OpenGL vs Vulkan	What is shared and where the backend implementations differ

Ownership model

A useful way to read the code is by asking who owns each class of state.

State	Primary owner	Notes
Guest x86 architectural state	CPUState / x86 CPU model	Executed by the vCPU thread through TCG
Translation blocks	TCG execution subsystem	Generated from guest instructions and invalidated when assumptions become stale
Guest RAM / ROM / MMIO map	QEMU memory/address-space subsystem + machine/chipset devices	Defines which bytes or callbacks a guest physical access reaches
Device DMA identity	Individual device model	Guest addresses/descriptors must be resolved through the device's address-space rules
Platform PCI/LPC/SMBus state	Xbox chipset/device models	Routes MMIO/I/O, interrupts and board-management behavior
NV2A command submission	PFIFO	Consumes guest pushbuffer/channel work
Guest GPU register/state model	PGRAPH	Backend-independent Xbox GPU state
OpenGL host objects	OpenGL renderer state	Must follow GL context ownership and GL synchronization rules
Vulkan host objects	Vulkan renderer state	Device, command buffer, cache, descriptor, buffer, surface and synchronization lifetime is explicit
Scheduled emulation deadlines	QEMU clock/timer lists	Device-specific timers choose a clock domain and callback

Reading xemu by boundary

When tracing a bug or performance problem, identify which boundary is crossed:

guest instruction
    ↓
CPU memory / I/O access
    ↓
QEMU address-space dispatch
    ↓
emulated device state
    ↓
optional DMA / worker / renderer backend
    ↓
host OS / GPU / audio / network backend
    ↓
guest-visible completion / IRQ / memory update

A symptom visible in one subsystem can be caused by an earlier ownership transition. For example, stale vertex data may originate in surface-to-guest-memory coherency before Vulkan vertex upload code ever sees the range.

Fidelity is an architectural property

xemu does not use one fidelity strategy for every device. Some paths model architectural state closely, some reproduce only software-visible semantics, some reuse a generic QEMU PC device, and some are explicit compatibility workarounds or stubs.

flowchart TD
    A[Guest-visible Xbox behavior] --> B{How is it realized?}
    B --> C[Architectural emulation]
    B --> D[Functional / semantic model]
    B --> E[Host-service substitution]
    B --> F[Compatibility workaround]
    B --> G[Partial model / stub]
    C --> H[Registers / DMA / IRQ / CPU semantics]
    D --> H
    E --> H
    F --> H
    G --> H

Loading

Examples matter because they change how traces should be read: SMBus transactions currently complete as synchronous callbacks rather than timed SCL/SDA transfers; the GPIO field pin toggles on reads rather than scan timing; the APU is paced by host audio queue state; the MCPX boot overlay is intentionally writable to reproduce a CPU-cache-dependent boot observation; and the memory-controller PCI function is still a stub.

See Hardware Fidelity & Emulation Boundaries before assuming that host cost corresponds to physical hardware cost.

Architecture versus research

Architecture pages describe the implementation that a developer should understand before modifying xemu. Pull requests are referenced where they provide measurements, design history, or an active alternative, but an unmerged PR is not treated as current architecture.

For current experimental work, see Development. For measurement rules, see Performance Methodology.