Running os8088

This page explains how you can run os8088 in 86Box, in the browser, or on real hardware.

Get the images Or boot it in your browser

Which one do I want?

QEMU -- take the 1.44MB pair: os8088.img as drive A:, apps.img as drive B:.
86Box, or a real IBM PC/XT -- take the 360KB pair: os8088-360.img and apps360.img. A 1.44MB drive postdates the 8086 by years and an XT BIOS knows nothing about that format.
Everything at once -- take apps-all.img as drive B: instead of the software disk. It is one 1.44MB floppy with all 22 programs on it, both word processors and the Frotz interpreter included. There is no 360KB version, because they do not fit on one.
Just a word processor -- word.img is Microsoft Word 1.1a, which saves Word .DOC files; cword.img is the version written in C, which saves RTF. Each goes in drive B: in place of the software disk, and each has a 360KB twin.

The two boot disks contain identical kernels. The only difference is the boot sector, which is assembled with the disk's sectors-per-track and head count baked in so it can turn a sector number into a cylinder, head and sector for the BIOS.

You need the matching software disk in the second drive to get the programs. os8088 boots and runs without one; you just get a Disk window with nothing in it, because there is no program floppy to list.

What you need to run it

Hardware requirements for os8088
CPU	Intel 8086 or 8088	Nothing newer is required and nothing newer is used. A faster x86 runs it too, in real mode.
RAM	128 KB	The kernel occupies 63,072 bytes of its own segment, plus a 4,608-byte FAT snapshot and 9,216 bytes of floppy buffers and task stacks outside it. Another 39,091 bytes of cold-start code run once and are then thrown away. Loaded programs get segments of their own out of an arena that begins at 0x1CE00, 115.5KB into the machine, so a 128KB machine has about 12KB to load packages into and a 640KB machine about 524KB.
Video	VGA, Hercules or CGA	Probed at boot, in that order. VGA gets mode 12h, 640x480 in 16 colors -- an 8-bit ISA VGA card in an XT is fine. A Hercules card gets 720x348 and a CGA 640x200, both monochrome, with the colors reduced to black, white and a dither.
Mouse	Microsoft serial mouse on COM1	Port 0x3F8, IRQ 4, 1200 baud 7N1, three bytes per report. Required: there is no keyboard route into the menus, so with no mouse nothing can be launched.
Keyboard	Any PC keyboard	Read through BIOS int 16h. Used for typing into the Note Pad and for Minesweeper's F and N keys, not for navigation.
Drives	One floppy to boot, two to be useful	A: is the boot disk, B: is the software disk. A hard disk works too -- os8088 installs onto one and boots from a partition. An NE1000 or NE2000 Ethernet card is used if one is there, but nothing boots off it and no CD is read.

Running it in QEMU

This is the command the repository's make run target issues, with the paths spelled out:

qemu-system-i386 \
  -drive file=os8088.img,format=raw,if=floppy -boot a \
  -chardev msmouse,id=m0 -serial chardev:m0 \
  -drive file=apps.img,format=raw,if=floppy,index=1

The two -chardev and -serial arguments are not optional. QEMU's msmouse backend emulates a Microsoft serial mouse on COM1, which is the only pointing device os8088 has a driver for. Leave them out and the machine boots to a desktop with no cursor and no way to open a menu, because every launch path in the system goes through the mouse.

index=1 puts the software disk in the second floppy slot. That is drive B:, which is where the Disk window looks first.

That command line gives you the PC speaker and nothing else, which is all a stock IBM PC had. To hear the other two devices the sound layer drives, hand QEMU the cards:

  -audiodev coreaudio,id=snd -machine pcspk-audiodev=snd \
  -device adlib,audiodev=snd \
  -device sb16,audiodev=snd

Substitute your host's audio backend for coreaudio -- pa on most Linux desktops, dsound on Windows. The AdLib gives the Piano and the tone route nine voices of FM; the Sound Blaster is what the Recorder needs to capture, and what lets a clip play in the background while the desktop keeps running. Without them the probes correctly find nothing and the Control Panel's Sound page refuses to route to a card that is not there.

Click into the window to give QEMU the pointer, and the arrow on the desktop starts following it. Menus are press-drag-release, the way they were on a Macintosh: hold the button down in the menu bar, drag onto the item, let go.

Running it in 86Box

86Box emulates the period machine rather than a generic PC, so it is the closer approximation of what os8088 was written for. The configuration checked into the repository at vm/xt/86box.cfg is:

The 86Box machine configuration os8088 is tested on
Machine	IBM PC/XT (`machine = ibmxt`)
CPU	Intel 8088, no dynamic recompilation
Clock	4,772,728 Hz -- 4.77MHz, the stock XT crystal divided down
RAM	256 KB
Video	Oak OTI-067, an 8-bit ISA VGA card
Keyboard	PC/XT
Mouse	Microsoft serial (`msserial`), on COM1
Floppy 1	`os8088-360.img`, mounted write-protected
Floppy 2	`apps360.img`, writable -- os8088 saves to it

Two more configurations sit beside it, vm/xt-cga and vm/xt-hercules, identical except for the card. They are the only way to exercise the monochrome paths and the boot-time probe: QEMU emulates neither of those cards.

VGA arrived in 1987, nine years after the 8086, but 8-bit ISA VGA cards did work in XTs. It is a period-plausible configuration and it is the one most of the testing happens on. It is no longer the only one: the kernel probes the card at boot, so the same image also boots on a Hercules or a CGA machine, in monochrome.

Repaints at 4.77MHz are slow, and that is the hardware. A window opening, a menu closing or the Task Manager redrawing its list takes long enough that you watch it happen row by row. Nothing is wrong. There is no back buffer -- an off-screen copy of a 640x480 16-color screen is 153,600 bytes, more than half a 256K machine's memory -- so every pixel is composited live on the visible display, at the speed an 8088 can push bytes at an ISA card. In QEMU the same code is instant. The optional back buffer that a machine with 500K or more could once switch on from the Control Panel was removed in v1.0.20260815, along with the kernel code that drove it; drawing now always goes straight to the visible screen.

Every change is tested in QEMU. The 360KB images boot in 86Box on the configuration above; real XT hardware is what the system targets, not what it is regression-tested on.

Writing to real media

The 360KB image is 720 sectors of 512 bytes, laid out as 40 cylinders, 2 heads and 9 sectors per track. It goes on a double-density 5.25" disk, written by a drive that can write that format, and it is a sector-for-sector copy -- no filesystem tool is involved because there is no DOS filesystem on it.

dd if=os8088-360.img of=/dev/fd0 bs=512

Check the device name before you press Return. dd writes to whatever you name in of= and asks no questions. Name the wrong device and you overwrite that disk, including the one you booted from. List the devices first -- lsblk on Linux, diskutil list on macOS -- confirm the size matches a floppy, and unmount it before writing.

Two things that do not work:

You cannot write the 360KB image to a 1.44MB disk and have an XT read it. An XT's drive is a 5.25" 360KB unit and its BIOS has no notion of 1.44MB media; on top of that, the boot sector in that image asks the BIOS for 9 sectors per track, which is not the geometry a 1.44MB disk is formatted with.
A 1.2MB high-density 5.25" drive can write 360KB-format disks, but it writes narrower tracks than a real 360KB drive does. Disks made that way are frequently unreadable in period hardware. If the XT will not boot a disk that looks fine on your modern machine, this is usually why -- write it in a genuine 360KB drive.

Put the boot disk in A: and the software disk in B:. With one drive, os8088 still boots; the desktop just shows a single floppy icon and there is no program disk to load from.

Building from source

git clone https://github.com/jggonz/os8088.git
cd os8088
make

That writes the four core images into build/, along with the intermediate kernel.bin (105,740 bytes) and boot.bin, which the Makefile checks is exactly 512 bytes and fails the build if it is not.

The dependencies are nasm, qemu-system-i386 and python3. NASM assembles the kernel, the boot sector and the packages, one assembly each; Python validates and stamps the package headers and builds the FAT12 software disk; QEMU is only needed to run the result. There is no linker in the build -- every binary is nasm -f bin flat output, deliberately, because a linker on a modern Mac only emits Mach-O. 86Box is optional, and only for make xt.

Makefile targets
`make`	Build the four core floppy images into `build/`.
`make worddisk`	Build the Microsoft Word disk, in all three geometries.
`make cworddisk`	Build the CWORD disk. Needs a C compiler, which `tools/setup-cc.sh` fetches and builds.
`make allapps`	Build `apps-all.img`, the one floppy with every program on it. Needs the C compiler too.
`make run`	Boot the 1.44MB pair in QEMU with the emulated serial mouse attached.
`make test`	Boot headless with a QMP control socket at `build/qmp.sock`, for scripted clicks and screendumps.
`make debug`	Boot with QEMU halted, waiting for gdb on port 1234.
`make xt`	Boot the 360KB pair in 86Box using `vm/xt/86box.cfg`.
`make clean`	Remove `build/`.

The kernel is assembled with cpu 8086 and -w+error, so any instruction newer than 1978 is a build failure rather than a surprise on real hardware. If your build succeeds, it runs on an 8088.

The source is at github.com/jggonz/os8088, under the MIT license.

Then what

Pull down the File menu and open a Clock and a couple of Bounce windows, then open Disk and double-click NOTEPAD to load the Note Pad off the software floppy, and drag one of them around by its title bar. The clocks keep time and the balls keep moving underneath the drag.

Boot it in your browser See it working How it works