TinyEMU Data Flow Explorer

What is TinyEMU?

TinyEMU is a small, self-contained system emulator by Fabrice Bellard. It supports RISC-V (32/64/128-bit) and x86 (via KVM), and implements VirtIO console, network, block, input, and 9P filesystem devices. It can run with SDL or as a JavaScript demo (JSLinux).

This guide follows the data flow from configuration parsing through machine initialization, CPU execution, memory access, device I/O, and display output. Each page includes GitHub-style permalinks to the source.

High-Level Data Flow

graph TD A[CLI / JS Entry] --> B[Config Parsing] B --> C[Machine Init] C --> D[CPU Init] C --> E[Memory Map] C --> F[Device Init] D --> G[CPU Interpreter Loop] G --> H[TLB / MMU] H --> I[RAM or MMIO] I --> J[Device Handlers] J --> K[IRQ / PLIC] K --> G F --> L[VirtIO Queues] L --> M[Network / Block / FS] E --> N[Framebuffer] N --> O[SDL / simplefb]

Tip: On mobile, pinch to zoom the diagram. All blocks are expanded by default on detail pages.

Component Map

Entry temu.c — CLI argument parsing, config loading, main event loop (virt_machine_run).
Config machine.c + json.c — JSON config parsing, file loading, parameter defaults.
Machine riscv_machine.c / x86_machine.c — SoC integration: RAM, CLINT, PLIC, HTIF, VirtIO, framebuffer.
CPU riscv_cpu.c + riscv_cpu_template.h — RISC-V interpreter, TLB, CSR, exception handling.
Memory iomem.c + iomem.h — Physical memory map, RAM registration, MMIO dispatch, dirty bits.
Devices virtio.c + virtio.h — VirtIO MMIO/PCI transport, queues, console, net, block, 9P, input.
Platform riscv_machine.c — CLINT (timer), PLIC (irq), HTIF (console/poweroff).
Network slirp/ + block_net.c + fs_net.c — SLIRP user networking, HTTP block device, HTTP 9P filesystem.
Display sdl.c + simplefb.c + vga.c — SDL window, simple framebuffer, VGA/PCI.

Key Data Structures

VirtMachineParams — Parsed configuration (RAM size, drives, filesystems, network, display).
VirtMachine — Abstract machine handle (console, net, fb_dev).
RISCVMachine — RISC-V specific state (cpu_state, mem_map, plic_irq, htif, virtio_count).
RISCVCPUState — CPU registers, PC, TLBs, CSRs, FPU state, privilege level.
PhysMemoryMap — Array of PhysMemoryRange entries (RAM or MMIO).
VIRTIODevice — VirtIO device instance (queues, features, status).

Execution Loop

The main loop in temu.c alternates between waiting for I/O events and executing guest instructions:

Compute sleep duration (virt_machine_get_sleep_duration).
select() on console stdin, network sockets, and filesystem events.
Dispatch ready file descriptors (console input, network packets).
Refresh display (sdl_refresh).
Run the CPU interpreter for up to MAX_EXEC_CYCLE instructions (virt_machine_interp).