Skip to content

About

An x86 PC emulator in TypeScript that boots Windows XP in the browser and shows how the OS talks to the hardware: ports, interrupts, page tables, disk sectors, decoded live. One offline HTML file. English and Russian.

Topics

Resources

Stars

11 stars

Watchers

1 watching

Forks

Repository files navigation

x86 Lab · Windows XP through the eyes of the hardware

English · Русский

An x86 PC emulator written in TypeScript that runs Windows XP in the browser, and a lab around it that shows how the operating system talks to the hardware: which commands each device receives, which interrupts it raises, which instructions the processor executes, how memory and the disk are organised. All of it on a live Windows XP that you drive with the mouse and keyboard.

Everything runs inside the page. The disk image is not uploaded anywhere, and it is not included: you need your own Windows XP image (how to make one).

Contents

Emulated hardware

Component What is emulated Driver in XP
CPU Pentium Pro class i686, 1 core, x87 FPU, 100 MHz nominal clock; interpreter + JIT —
Memory 256 or 512 MB, 4 KB / 4 MB paging —
Chipset i440FX north bridge + PIIX3 south bridge, PCI configuration mechanism #1 pci.sys
Interrupts, timers 2× 8259A PIC, 8254 PIT, MC146818 RTC/CMOS hal.dll ("Standard PC")
Disk PIIX3 IDE, ATA disk, PIO atapi.sys
Keyboard, mouse i8042 + PS/2 keyboard + PS/2 IntelliMouse i8042prt.sys
Video Cirrus GD5446 (default) or standard VGA + Bochs VBE cirrus.sys / vga.sys
Sound Intel 82801AA AC'97 + SigmaTel STAC9700 codec ac97intc.sys
BIOS SeaBIOS + SeaVGABIOS (in bios/) —

There is no ACPI, APIC, SMP, network or USB. Windows must use the "Standard PC" HAL (see below).

Getting started

  1. Open the web app or the single HTML file.
  2. On the start screen choose the disk image (a raw .img), or drop it onto the card. Optionally choose a saved machine (.vmsave) or a snapshot (.snap.gz) to continue from. Without one the machine cold-boots with the RAM size, video adapter and sound card you pick.
  3. Click the screen to capture the mouse and keyboard. Sound starts after the first click (browser autoplay policy).

Good to know:

  • The image is only read. What Windows writes stays in memory. 💾 Save writes a .vmsave file: memory, devices and the changed sectors. A save works only with the image it was made from.
  • Write the changes into the image (the Saves tab, Chrome and Edge only) writes those changes into the .img itself, so the next cold boot starts from them. Chrome needs as much free disk space as the image for this.
  • In Chrome and Edge the page remembers the image: next time use "Open again".
  • A cold boot to the desktop takes about 2 minutes. Save the machine once it is on the desktop and start from the save later.
  • The interface is in English and Russian: the switch is in the header, or add ?lang=ru to the URL.

Creating a disk image

You need your own Windows XP Professional SP3 32-bit ISO and product key. Neither is in the repository. Do not commit them.

The image is installed in QEMU on the same hardware the emulator has. Unattended setup uses the answer file tools/xp-setup/WINNT.SIF and the first-logon script tools/xp-setup/FIRST.CMD.

1. Prepare the files. data/ is ignored by git.

mkdir -p data/floppy data/iso
cp tools/xp-setup/WINNT.SIF tools/xp-setup/FIRST.CMD data/floppy/
# put the ISO into data/iso/ and your product key into data/floppy/WINNT.SIF ([UserData] ProductKey)
qemu-img create -f raw data/xp.img 4G

WINNT.SIF sets up a Russian system locale with EN + RU keyboard layouts. For English XP, change [RegionalSettings] (for example SystemLocale=00000409, UserLocale=00000409, InputLocale=0409:00000409).

2. Run setup.

qemu-system-i386 -machine pc,acpi=off -cpu pentium3,-sse,-sep,-pae -m 256 \
  -vga cirrus -device AC97,addr=0x3 -nic none -rtc base=localtime \
  -drive file=data/xp.img,format=raw,if=ide \
  -cdrom data/iso/xp_sp3.iso -boot once=d \
  -drive file=fat:floppy:data/floppy,if=floppy,format=raw,readonly=on
  • Press F5 on the very first blue screen ("Press F6 if you need to install a third party SCSI or RAID driver…") and choose "Standard PC". This is required: without it setup installs the APIC HAL, and the emulator cannot boot it. The ComputerType line in WINNT.SIF is not enough: the Russian installer ignored it.
  • Setup reboots three times. After a reboot QEMU sometimes hangs on a black screen (NTLDR stalls in real mode). Then close QEMU and start the same command with -boot c instead of -boot once=d. Keep the floppy attached: FIRST.CMD runs from it at the first logon.
  • FIRST.CMD turns on autologon, removes the pagefile, turns off System Restore, Automatic Updates, Security Center and error reporting, reboots, and then shuts the machine down by itself. That is the end of the installation (about 25 minutes on Apple Silicon, where QEMU emulates the CPU in software).

3. Check the image. In XP, Device Manager → Computer must say Standard PC. The video adapter is Cirrus, 1024×768×16 (set in [Display]), and the sound card is AC'97.

The result is a raw image, 4 GB in size. Open it in the lab as is. Do not convert it to qcow2 or vmdk.

Rules that matter, if you set up an image some other way:

Requirement Why What happens otherwise
HAL "Standard PC" (acpi=off, F5 during setup) there is no ACPI or APIC BSOD 0x79 or a hang
IDE disk on PIIX3 (if=ide) the emulator's only disk controller BSOD 0x7B INACCESSIBLE_BOOT_DEVICE
CPU without SSE, SEP, PAE the emulator does not implement them BSOD 0x5D
-vga cirrus, AC'97 in slot 3 the same devices at the same PCI addresses Windows looks for new hardware
Raw image read sector by sector it does not open

What the lab shows

The interface has three parts: the VM screen, the device panel on the right, and the workspace below the screen with tabs.

Guest time. Everything is measured in guest time: 1 instruction = 1 cycle of a 100 MHz nominal clock. So "per second" means per second inside the machine, and a recording started from the same snapshot is the same every time. Counters update every 0.5 s (the "pulse").

The device panel

The machine as a tree: CPU → chipset → PCI → devices. The dot lights up when the device is accessed, the checkbox puts its accesses into the shared monitor, a click opens the device card.

Device Metric What it means
Processor busy N% share of time the CPU executes code rather than sleeping in HLT. On an idle desktop it is near 0%
Memory and MMU #PF N/s page faults: a program touched a page that is not in memory yet. Spikes when a program starts
Chipset N I/O/s all port accesses (in/out) per second
PCI bus N/s accesses to the PCI configuration ports CF8/CFC. Busy at boot, when drivers look for devices
Interrupt controller N IRQ/s all hardware interrupts per second
System timer N Hz timer interrupts (IRQ0): how often the system "ticks", the scheduler's heartbeat
Clock and CMOS IRQ8 N/s real-time clock interrupts (used for profiling); time and date reads
PS/2 keyboard IRQ1 N/s one key press is two interrupts: press and release
PS/2 mouse IRQ12 N/s one movement is a 3–4 byte packet: dx, dy, buttons, wheel
IDE disk N KB/s or quiet bytes read from and written to the disk
Video N KB/s · BLT N CPU writes to video memory, and 2D accelerator operations (BitBLT: fill, copy)
System ports N/s A20, reset, POST codes and the BIOS log
AC'97 sound playing · N buf/s sound buffers the card has played. XP plays 10 ms buffers

The device card

  • Passport: chip, place on the bus (PCI 00:01.1 or ISA), Vendor:Device ID.
  • How the OS accesses it: I/O ports with register names, and memory windows (framebuffer, MMIO, ROM) at their current PCI BAR addresses.
  • Interrupt and driver: the chain IRQ line → PIC input → vector in the IDT → handler → the Windows driver that handles it (for example IRQ1 → i8042prt.sys).
  • Registers: the device state decoded bit by bit: PIC masks, timer divisor and frequency, CMOS time, ATA task file, VGA and Cirrus registers.
  • Monitor: the accesses already decoded: who accessed the device (instruction, process, ring), what was written or read, and what it means. For example an ATA command with its LBA and the NTFS file it reads, or a scan code with the key name.
  • Flash: a recording of this device for a set amount of guest time, analysed afterwards.
  • Self-check questions.

Workspace tabs

  • Overview: charts of the pulse. What the CPU does (ring 3 = programs, ring 0 = kernel and drivers, real mode, idle in HLT), interrupts, system calls (int 2Eh) and page faults per second, disk and video traffic, processes and kernel modules by CPU time.
  • Monitor: a shared stream of accesses for all watched devices.
  • CPU: registers, EFLAGS, CR0 and CR4 bit by bit, segments, GDT, IDT. ⏸ Pause and Step (one instruction). An instruction flash: share of idle time, top instructions, hot addresses as module+offset, and a listing with interleaved interrupts and port accesses.
  • Memory: a process → its CR3 → page directory → page table → page; how a virtual address becomes a physical one; the physical memory map.
  • Windows: processes (from the kernel's EPROCESS), loaded drivers, a process's DLLs, the system call table, and a CPU profile by process built from CPU registers alone, to compare with Task Manager.
  • Disk: the MBR and partitions, the NTFS boot sector, a map of reads and writes, sector → file, a hex view.
  • Video: a heat map of CPU writes to the framebuffer over the screen: who draws, the CPU or the 2D accelerator.
  • Labs: 13 step-by-step exercises with questions, from "The system's heartbeat: the timer" to "Sound: DMA and buffers".
  • Saves: saved machines.

Names of functions come from export tables, without debug symbols. A name marked ≈ is the nearest export and may be wrong.

Development

Requirements: Node.js 24 (the tools/*.ts scripts run on Node's own TypeScript type stripping), Chrome for the browser tests, macOS or Linux.

npm install
npm run typecheck        # tsc
npm run i18n             # every text has a Russian translation
npm run build:file       # build/x86-lab.html and build/pages/ (the PWA)
npm run test:pages       # the PWA in headless Chrome
npm run test:file        # the single file in headless Chrome (needs data/xp.img and data/xp.snap.gz)

Dev server. Put the image at data/xp.img and run:

./build_and_start.sh            # build, serve at http://localhost:8080 and open the browser
./build_and_start.sh --cold     # cold boot even if data/xp.snap.gz exists
./build_and_start.sh --512      # 512 MB RAM (snapshot data/xp-512.snap.gz)

URL parameters of the dev page: disk=/data/xp.img, snapshot=/data/xp.snap.gz, ram=256, video=std (standard VGA instead of Cirrus), audio=none, lang=en|ru.

Headless runner (Node, no browser):

npm run build
node dist/run.js --seconds 160 --save data/xp.snap.gz   # boot and save a snapshot of the desktop
node dist/run.js --load data/xp.snap.gz --seconds 10   # continue from it, screenshot to dist/shot.png

Other options: --disk, --ram, --video cirrus|std, --audio ac97|none, --nojit. A snapshot only fits the image, video adapter, sound card and RAM size it was made with.

Run one emulator in Node at a time: each instance takes 256 MB of guest RAM plus a snapshot and a disk cache.

Project layout

Path What is there
src/cpu/ CPU: decoder and instructions, x87 FPU, JIT
src/devices/ PIC, PIT, RTC, PCI, PS/2, IDE, VGA, Cirrus, AC'97
src/pc.ts, src/bus.ts, src/snapshot.ts the machine, memory and port buses, state snapshots
src/lab/ the lab: counters and flashes, device passports, reading XP kernel structures, NTFS
src/web/ the page and the Web Worker that runs the emulator; disk, saves, sound
src/locales/ru.json Russian translation
web/index.html page template
build.mjs builds the single file and the PWA
tools/ tests, benchmarks, trace and debugging scripts, XP setup files
bios/ SeaBIOS and SeaVGABIOS binaries
vendor/html-disasm/ x86 disassembler and instruction reference

Releases and deployment

  • Every push to main deploys the web app to GitHub Pages (pages.yml). The page shows the version as 0.1.0+<commit>.

  • A v* tag builds the single HTML file and publishes a GitHub release (release.yml). The version lives only in package.json, and the tag must match it:

    npm version minor && git push --follow-tags

License

The code is under the MIT License. bios/ contains SeaBIOS and SeaVGABIOS binaries (LGPLv3). vendor/html-disasm/ is under its own MIT License. Windows XP is not included. Use your own licensed copy.

About

An x86 PC emulator in TypeScript that boots Windows XP in the browser and shows how the OS talks to the hardware: ports, interrupts, page tables, disk sectors, decoded live. One offline HTML file. English and Russian.

Topics

Resources

Stars

11 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages