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.
- Open in the browser: https://marketkernel.github.io/html-virtual-pc/ (installable as an app, works offline)
- Single file:
x86-lab-vX.Y.Z.htmlfrom Releases. Download it and open it from disk. It needs no server and never touches the network.
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).
- Emulated hardware
- Getting started
- Creating a disk image
- What the lab shows
- Development
- Releases and deployment
- License
| 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).
- Open the web app or the single HTML file.
- 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. - 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
.vmsavefile: 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
.imgitself, 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=ruto the URL.
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 4GWINNT.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
ComputerTypeline 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 cinstead 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 |
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 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 |
- Passport: chip, place on the bus (
PCI 00:01.1or 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.
- 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.
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.pngOther 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 |
-
Every push to
maindeploys the web app to GitHub Pages (pages.yml). The page shows the version as0.1.0+<commit>. -
A
v*tag builds the single HTML file and publishes a GitHub release (release.yml). The version lives only inpackage.json, and the tag must match it:npm version minor && git push --follow-tags
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.