# mirage2032/qemu-wasm architecture

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

- Interactive diagram: https://gitdiagram.com/mirage2032/qemu-wasm
- Repository: https://github.com/mirage2032/qemu-wasm

## Overview

QEMU Wasm is an experimental browser-hosted system emulator. The documented workflow starts QEMU in a browser, loads a guest image, and executes guest code through either the TCI interpreter or TCG translation; frequently executed translation blocks (TBs) can become Wasm modules instantiated through browser APIs. The README also documents x86_64, AArch64 and RISC-V system guests, plus multi-threaded TCG. The available source excerpts do not show the browser interface or the modified backend wiring, so those connections are documented at README level rather than inferred from imports.

Main entry points: [`hw/core/machine.c`](https://github.com/mirage2032/qemu-wasm/blob/master/hw/core/machine.c) (Machine setup), [`accel/tcg/cpu-exec.c`](https://github.com/mirage2032/qemu-wasm/blob/master/accel/tcg/cpu-exec.c) (CPU execution), [`system/main.c`](https://github.com/mirage2032/qemu-wasm/blob/master/system/main.c) (System entry), [`tcg/tcg.c`](https://github.com/mirage2032/qemu-wasm/blob/master/tcg/tcg.c) (TCG engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_launch["Launch and guests"]
  node_guest_image["Guest image"]
  node_qemu_entry["System entry<br/>[main.c]"]
end

subgraph group_execution["CPU execution"]
  node_tcg_engine["TCG engine<br/>[tcg.c]"]
  node_tcg_dispatch["CPU execution<br/>[cpu-exec.c]"]
  node_translator["Instruction translation<br/>[translator.c]"]
  node_tci["TCI interpreter"]
  node_mt_tcg["Multi-threaded TCG"]
end

subgraph group_wasm["Wasm translation"]
  node_wasm_backend["Wasm backend<br/>[tcg.c]"]
  node_tb_modules["TB Wasm modules<br/>[tcg.c]"]
  node_wasm_api["WebAssembly APIs"]
end

subgraph group_machine["Virtual machine"]
  node_machine_setup["Machine setup<br/>[machine.c]"]
  node_guest_cpu["Guest CPU models<br/>[cpu.c]"]
  node_device_models["Device models"]
end

node_user(("Browser user"))
node_browser["Browser runtime"]

node_user -->|"starts emulator"| node_browser
node_browser -->|"runs QEMU"| node_qemu_entry
node_guest_image -->|"supplies guest"| node_machine_setup
node_qemu_entry -.->|"starts system"| node_machine_setup
node_machine_setup -.->|"configures CPU"| node_guest_cpu
node_machine_setup -.->|"provides devices"| node_device_models
node_tcg_dispatch -.->|"executes translated code"| node_tcg_engine
node_tcg_engine -->|"translates IR"| node_translator
node_tcg_dispatch -->|"interprets TBs"| node_tci
node_translator -->|"translates IR"| node_wasm_backend
node_wasm_backend -->|"generates modules"| node_tb_modules
node_tb_modules -->|"instantiated by"| node_wasm_api
node_wasm_api -->|"uses browser APIs"| node_browser
node_tcg_dispatch -->|"runs with threads"| node_mt_tcg

click node_qemu_entry "https://github.com/mirage2032/qemu-wasm/blob/master/system/main.c"
click node_machine_setup "https://github.com/mirage2032/qemu-wasm/blob/master/hw/core/machine.c"
click node_guest_cpu "https://github.com/mirage2032/qemu-wasm/blob/master/target/i386/cpu.c"
click node_device_models "https://github.com/mirage2032/qemu-wasm/tree/master/hw"
click node_tcg_engine "https://github.com/mirage2032/qemu-wasm/blob/master/tcg/tcg.c"
click node_tcg_dispatch "https://github.com/mirage2032/qemu-wasm/blob/master/accel/tcg/cpu-exec.c"
click node_translator "https://github.com/mirage2032/qemu-wasm/blob/master/accel/tcg/translator.c"
click node_tci "https://github.com/mirage2032/qemu-wasm/tree/master/accel/tcg"
click node_wasm_backend "https://github.com/mirage2032/qemu-wasm/blob/master/tcg/tcg.c"
click node_tb_modules "https://github.com/mirage2032/qemu-wasm/blob/master/tcg/tcg.c"
click node_mt_tcg "https://github.com/mirage2032/qemu-wasm/blob/master/accel/tcg/tcg-accel-ops-mttcg.c"

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_guest_image,node_qemu_entry,node_user,node_browser toneBlue
class node_tcg_engine,node_tcg_dispatch,node_translator,node_tci,node_mt_tcg toneAmber
class node_wasm_backend,node_tb_modules,node_wasm_api toneMint
class node_machine_setup,node_guest_cpu,node_device_models toneRose
```

## Components

### Launch and guests

- **Guest image**
- [System entry](https://github.com/mirage2032/qemu-wasm/blob/master/system/main.c): `system/main.c`

### CPU execution

- [TCG engine](https://github.com/mirage2032/qemu-wasm/blob/master/tcg/tcg.c): `tcg/tcg.c`
- [CPU execution](https://github.com/mirage2032/qemu-wasm/blob/master/accel/tcg/cpu-exec.c): `accel/tcg/cpu-exec.c`
- [Instruction translation](https://github.com/mirage2032/qemu-wasm/blob/master/accel/tcg/translator.c): `accel/tcg/translator.c`
- [TCI interpreter](https://github.com/mirage2032/qemu-wasm/tree/master/accel/tcg): `accel/tcg`
- [Multi-threaded TCG](https://github.com/mirage2032/qemu-wasm/blob/master/accel/tcg/tcg-accel-ops-mttcg.c): `accel/tcg/tcg-accel-ops-mttcg.c`

### Wasm translation

- [Wasm backend](https://github.com/mirage2032/qemu-wasm/blob/master/tcg/tcg.c): `tcg/tcg.c`
- [TB Wasm modules](https://github.com/mirage2032/qemu-wasm/blob/master/tcg/tcg.c): `tcg/tcg.c`
- **WebAssembly APIs**

### Virtual machine

- [Machine setup](https://github.com/mirage2032/qemu-wasm/blob/master/hw/core/machine.c): `hw/core/machine.c`
- [Guest CPU models](https://github.com/mirage2032/qemu-wasm/blob/master/target/i386/cpu.c): `target/i386/cpu.c`
- [Device models](https://github.com/mirage2032/qemu-wasm/tree/master/hw): `hw`

### Other components

- **Browser user**
- **Browser runtime**

## Connections

- Browser user → Browser runtime: starts emulator
- Browser runtime → System entry: runs QEMU
- Guest image → Machine setup: supplies guest
- System entry → Machine setup: starts system
- Machine setup → Guest CPU models: configures CPU
- Machine setup → Device models: provides devices
- CPU execution → TCG engine: executes translated code
- TCG engine → Instruction translation: translates IR
- CPU execution → TCI interpreter: interprets TBs
- Instruction translation → Wasm backend: translates IR
- Wasm backend → TB Wasm modules: generates modules
- TB Wasm modules → WebAssembly APIs: instantiated by
- WebAssembly APIs → Browser runtime: uses browser APIs
- CPU execution → Multi-threaded TCG: runs with threads
