Getting started

Quick start

Boot into os8088 and explore a graphical desktop for the IBM PC/XT and later x86 PCs.

1. What you'll need

Choose an emulator or a compatible PC to get started.

ProcessorMemoryDisplay
8086 / 8088128KB minimumCGA, EGA, VGA or Hercules

The base system supports the original PC/XT. Some optional drivers need a 386 or newer. Full requirements →

2. Choose your disk image

Download the release archive and pick the images for your environment.

Real hardware & 86Box

360KB boot image

os8088-360.img

QEMU

1.44MB boot image

os8088.img

3. Boot os8088

With QEMU installed, run this from the folder containing your images:

Terminal

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

The second disk holds the apps. The serial mouse option lets QEMU control the os8088 pointer. More emulator options →

Getting started

Introduction

Built first for the IBM PC/XT, os8088 has grown into a graphical operating system for a wider range of x86 PCs. It keeps support for the 8086 and 8088 while offering applications that benefit from faster processors and more memory.

The desktop

os8088 runs on IBM PC/XT-compatible hardware and in emulators. It provides a mouse-driven desktop with windows, pull-down menus, a file manager and a dock. Multitasking lets you keep several programs running at once.

The os8088 desktop immediately after boot: a white menu bar carrying a small chip icon, the name Locator, File and Special, with the date and time at its right end; a checkerboard gray desktop below it; two floppy disk icons labelled Disk A and Disk B down the right edge; an arrow cursor near the middle; and an empty white dock strip along the bottom under a black rule.
The os8088 desktop after boot. The menu bar, checkerboard desktop, and drive icons are ready to use.

Programs and tools

Applications cover writing, spreadsheets, drawing, image editing, music, video and games. You can also browse the web, use Telnet, transfer files over FTP, run DOS programs, and explore Commodore 64, Apple II and CP/M software through the included emulators.

Save files to floppy or hard disk, add programs from The Wire, or build your own applications.

Explore os8088

Spotlight shows the applications, games and system features in action, with screenshots and guides to what each one can do.

Explore Spotlight →

Getting started

System requirements

Start with a compatible PC or emulator, then choose the devices and memory your applications need.

The base system

The minimum is an 8086 or 8088, 128KB of RAM, a supported display adapter and a boot device. The same core also runs on later x86 PCs with a compatible legacy BIOS. A keyboard and mouse provide desktop input.

The full kernel supports CGA, Hercules, EGA and VGA. A Microsoft-protocol serial mouse works on COM1 or COM2; later machines can use a PS/2 mouse. The reduced KERN_SMALL build omits planar color rendering, loadable hardware drivers and extended-memory support. The device pages below describe the full build unless stated otherwise.

Choose room for your workload

128KB is a boot minimum, rather than a promise that every application will fit. A machine with 128KB boots the 128KB system disk, made for 360KB and 720KB drives. It runs the reduced kernel and carries every program that fits in that memory, all on the one disk. More conventional RAM gives programs and their data more room; faster processors help with emulation, media and other demanding work. Extra memory above 1MB can hold bulk data for applications that use it.

On a 286 or newer with memory above 1MB, the full kernel also moves the code it keeps outside its main 64KB segment -- mostly the file, disk, driver and memory routines -- into the first 64KB above 1MB, the high memory area (HMA). That leaves about 37KB more conventional memory for programs. An IBM 5150 can get the same room from an os8088 ROM fitted in its spare ROM sockets. On a machine with neither a VGA nor an EGA card, the full kernel also gives back its VGA-only drawing code, about 2KB.

A PC with a 286 or later processor and at least 1MB of memory can instead run the 286 system, a second kernel on disks of its own. It runs in protected mode, the processor’s mode that reaches memory past the first megabyte, so programs can use all of the machine’s memory rather than only the first 640KB. Use it with the software disks made for it; see Memory expansion.

Explore the interactive memory map and the Supported Hardware pages for device-specific requirements.

Implementation: kernel build and minimum RAM, display detection, pointer input.

Getting started

Booting on real hardware

Put the desktop on an original PC or a compatible machine.

Tested on period machines

os8088 has booted from 360KB floppies on an IBM 5150, a Toshiba T1100 Plus, and a Packard Bell Victory 286. See photographs of the machines.

The IBM 5150 ran six programs at once through its Hercules display adapter. Routine testing also happens in QEMU and 86Box.

Prepare the disks

Use os8088-360.img in drive A: and apps360.img in drive B:. Write each image to a double-density 5.25" floppy, then boot from A:.

Read the instructions for writing real media →

For USB, CD or CompactFlash, the disk imager guide covers supported media and drive geometry.

Getting started

Running in an emulator

Try a PC/XT on your modern computer.

QEMU

The quick start includes the command for booting the 1.44MB disk pair with a serial mouse.

86Box

The source tree includes ready-to-run configurations for XT, 286, 386, 486 and Pentium machines. Each make target builds the images and launches the matching configuration.

Terminal

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

make deps installs the host tools; the macOS setup also fetches the 86Box ROMs. For a QEMU build, run make followed by make run.

Browse the emulator configurations →

Try it in your browser

Boot it in your browser, or download a floppy image and use an emulator. Releases include 360KB images for period hardware and 86Box, plus 1.44MB images for QEMU. The running page has the exact QEMU command.

Menus use press-drag-release: hold the mouse button, drag to an item, and release.

Supported Hardware

Processors & machines

From the original PC/XT to faster x86 PCs, with an 8086-compatible real-mode core.

Processor families

ProcessorWhat it offers
8086 / 8088The baseline kernel and native applications; conventional RAM and optional hardware EMS. On an IBM 5150, an os8088 ROM in the five spare sockets can hold the part of the kernel’s code kept outside its main 64KB segment.
80286The same desktop, plus extended memory: data transfers with the 286’s LOADALL instruction where it works, otherwise through the BIOS. The kernel’s code from outside its main 64KB segment and some drivers move into the high memory area (HMA) above 1MB.
80386 and laterThe same real-mode core and HMA use, with faster 32-bit extended-memory transfers and optional 386-specific drivers such as the virtual-machine mouse and the PCI network driver.
80286 and later, with 1MB or moreThe 286 system, a second kernel on disks of its own. It runs in protected mode, so programs can use all of the machine’s memory rather than the first 640KB, and it runs most programs unchanged. So far it has been tested on one real 286, the Packard Bell Victory 286, and on emulated 286, 386 and Pentium machines.

Machines and firmware

86Box configurations cover XT, 286, 386SX/DX, 486 and Pentium machines. Physical machines include the IBM 5150, Toshiba T1100 Plus and Packard Bell Victory 286; the Book8088 guide covers that modern XT-compatible laptop.

Later PCs need compatible legacy BIOS services. Live USB and CD boot require legacy boot or CSM support. CPU speed and available conventional RAM affect which applications are practical; an emulator running another computer benefits especially from a faster host CPU.

Implementation: CPU detection, emulator configurations, legacy boot requirements.

Supported Hardware

Video

One full kernel detects the display hardware at boot and selects the matching renderer.

Display adapters

AdapterDesktop modeVideo address
VGA640 × 480, 16 colors0xA0000 (planar)
EGA640 × 350, 16 colors0xA0000 (planar)
CGA640 × 200, monochrome0xB8000 (banked)
Hercules720 × 348, monochrome0xB0000 (banked)
VESA (VBE 1.2 or later)640 × 400 up to 1024 × 768, 16 colors0xA0000 (a 64KB window, switched by the BIOS)

VESA screens

A graphics card with a VESA BIOS of version 1.2 or later can show the desktop at a larger size through VESA.DRV. Tick VESA Display on the Drivers page of Control Panel, then choose the screen size on the Display page; Auto picks the largest the card offers. The desktop keeps its sixteen colors at any size. A program can draw a picture at the card’s own depth, up to 65,536 colors, which is how PiXEL shows a photograph. See VESA desktops.

Color, monochrome and two displays

The full build includes planar color and software monochrome rendering. The smaller KERN_SMALL build uses CGA or Hercules; an EGA or VGA card falls back to CGA mode. On a machine with neither a VGA nor an EGA card, the full build does not keep its VGA-only drawing code, which returns about 2KB to programs.

Supported dual-adapter configurations can put windows on a second display. See dual displays and the EGA walkthrough for examples. Display RAM lives in the adapter area above conventional RAM; it does not increase the application heap.

Implementation: adapter detection and mode table, monochrome rendering, VESA driver.

Supported Hardware

Sound

Use the built-in speaker, add FM synthesis or PCM audio, or send notes to a MIDI device.

Sound devices

Device / interfaceSupport
PC speakerResident tones on both builds; exclusive sample playback in the full build.
AdLib / OPL2FM synthesis through SOUND.DRV.
OPL3Two banks of nine FM channels through the sound driver. An OPL2 needs about 23 microseconds after each register write, and an OPL3 well under one. The driver waits the shorter time when it finds an OPL3, or a Sound Blaster with DSP version 4 or later.
Sound Blaster DSP8-bit DMA PCM playback and recording. The driver adapts single-cycle or auto-init operation to the DSP version; this is not a promise of every later card feature. Recording needs auto-init, so DSP version 2.00 or later: a card with an older DSP plays sound but does not record.
Covox-compatible parallel DACSample output through an available LPT port; select the port on the Sound page.
MPU-401 UARTMIDI output to compatible synthesizers, modules and daughterboards.
PicoMEMThe sound driver can initialize its emulated AdLib and Sound Blaster devices. A PicoMEM 2’s sound used to break up during long reads from the card’s own disk, so the standard kernel reads that disk at most eight sectors at a time. os8088’s firmware for the PicoMEM 2, in the tools zip, keeps the sound playing through any read, and with it the limit is lifted.
Sound Blaster mixerOn a card whose mixer can be read back, a speaker beside the clock sets the master volume. The Mixer program sets each source, with balance, and bass and treble where the card has them.

Enable the hardware you use

The PC speaker needs no loadable driver. In the full build, enable the sound driver in Control Panel, then choose the available device on its Sound page. Sound Blaster DMA uses channel 1 and needs suitable buffers; performance and available features depend on the card and application. On an XT whose hard-disk controller already uses interrupt 5, the driver refuses a Sound Blaster set to that interrupt and says so. Once loaded, the driver takes about 6KB, or 8.5KB with a card whose mixer it can set: the code that only finds the card is given back when it has run. A Sound Blaster with no usable interrupt is used for FM music only. On a 286 or newer with memory above 1MB, the driver loads into the high memory area instead of conventional RAM. Its 8KB sound buffer goes there too when the area has room left, and otherwise takes conventional RAM.

WaveRack, the sound recorder and WAV editor, records from the card's input onto disk as it goes. The card writes the sound into WaveRack's own memory, so a take keeps going while the disk is busy. See Covox audio, XTMP3, MIDI Rack and WaveRack for supported workflows.

If a card is not found or stops playing, the sound debug disk shows the probe results and a ten-second playback test.

Implementation: sound driver, Sound Blaster transport, MIDI UART, PicoMEM initialization.

Supported Hardware

Mouse

Serial and PS/2 input, plus optional drivers for specific USB and virtual-machine interfaces.

Pointer interfaces

InterfaceRequirements
Microsoft serial mouseCOM1 or COM2; the resident driver probes the serial ports and uses the Microsoft protocol at 1200 baud.
PS/2 mouseAn AT-style 8042 auxiliary port on a later machine. Included in the full kernel; the 8086/8088 path does not probe it.
CH375 / PicoMEM USB mouseUSBMOUSE.DRV supports a USB boot-protocol mouse on the WCH CH375B controller, including the Book8088 socket at ports 0x260/0x261. It also accepts USB mouse reports from a detected PicoMEM card.
Virtual-machine absolute pointerVMMOUSE.DRV uses the VMware backdoor protocol on a 386 or newer guest in a compatible emulator. This provides a pointer without capture.

Choose the matching interface

The USB mouse driver supports the CH375 controller and the PicoMEM card's separate USB-mouse interface. It is not a driver for arbitrary PC USB host controllers. It avoids taking over a USB device already configured by the BIOS, such as a boot flash drive on the same controller.

The QEMU quick start disables the virtual-machine mouse port and supplies a serial mouse. The browser demo uses the absolute-pointer path. On physical machines, a passive USB-to-PS/2 adapter works only with a mouse that itself supports PS/2 signaling.

Scroll wheel

The full kernel reads a mouse wheel on all four interfaces: a serial wheel mouse that identifies itself as an IntelliMouse, a PS/2 wheel mouse, a CH375 USB mouse that sends a wheel byte, and the virtual-machine pointer. The CH375 wheel has not yet been tried on a Book8088. The PicoMEM card reports no wheel, and the reduced kernel ignores one.

The wheel scrolls the front window, the one that receives typing, wherever the pointer is. One notch moves three lines of text. Disk windows, file dialogs and programs with a scroll bar respond to it.

Implementation: serial, PS/2 and wheel input, CH375 USB mouse, absolute pointer.

Supported Hardware

Keyboard

PC-compatible keyboard input through the machine's BIOS, with scan-code handling for held keys and desktop controls.

Keyboard interfaces

Original PC/XT keyboards and AT/PS/2 keyboards work through compatible PC BIOS keyboard services. The kernel reads BIOS key events and also tracks each key's press and release for features that need them.

To see a press or a release, the kernel never reads the keyboard controller ahead of the BIOS on a machine that offers another way. An AT-class BIOS that supports the keyboard intercept, INT 15h function 4Fh, hands the kernel each key it has read. Some keyboard controllers move on to their next byte at every read, among them QEMU's, the browser demo's and the USB keyboard emulation of many later PCs, and a second read there loses a key. An XT has no intercept, so the kernel looks at its keyboard port directly, which is safe on that hardware.

A USB keyboard on a later machine depends on firmware legacy keyboard emulation or a compatible active adapter. os8088 does not provide a general USB keyboard host driver. A passive USB-to-PS/2 adapter needs a keyboard that supports the PS/2 protocol.

The 286 system reads the keyboard with its own handler while it runs in protected mode, and stores each key the way an AT BIOS does: Ctrl with the arrow keys and the keypad, Pause, Ctrl+Break, and Ctrl+Alt with either Delete key to restart.

Desktop controls

Keyboard support includes text entry, application shortcuts and keyboard pointer controls. The full build includes keyboard settings in Control Panel; the reduced kernel leaves out some desktop configuration features. Individual applications can handle additional keys for navigation or games.

Implementation: keyboard and pointer key paths, BIOS keyboard diagnostics, keyboard settings.

Supported Hardware

Storage & controllers

Floppy disks, controller-backed hard disks, and boot media exposed by a compatible BIOS.

Storage interfaces

DevicePath and requirements
Floppy drivesBIOS disk services, with 360KB, 720KB, 1.2MB and 1.44MB FAT12 images. Match the image to the drive and media.
MFM / controller-ROM hard disksHDD.DRV first uses BIOS disk services for drives 0x80/0x81, including XT controllers with their own ROM.
IDE / ATABIOS access when available, or native CHS task-file access at 0x1F0/0x170 on a 286 or newer with a 16-bit bus.
CompactFlashThrough an IDE adapter or controller BIOS. The image geometry must match what the target machine reports.
USB boot mediaA legacy BIOS presents the live USB image as a hard disk. A generic USB mass-storage driver is not required for this path.
CD boot mediaLegacy El Torito boot support. The live CD uses a temporary RAM shadow for writes.
PicoMEM 2 disksThe card’s disks through its BIOS. The standard kernel reads them at most eight sectors a call, so the card’s sound keeps playing; os8088’s PicoMEM 2 firmware in the tools zip lifts the limit.
IDE / ATAPI CD-ROM drivesCDROM.DRV on a 286 or newer: an ISO 9660 data disc appears as a read-only drive, and an audio CD plays through the drive’s own output with CDRack. Tick CD-ROM on the Drivers page of Control Panel. See CD-ROM drives.

Filesystems and preparation

The filesystem supports FAT12 and FAT16. Controller setup, partition limits and disk geometry still apply; a large modern device does not imply that every partition layout is usable.

The standard kernel boots from a hard disk on a machine with as little as 128KB, as it does from a floppy. On a 286 or newer with memory above 1MB, HDD.DRV runs from the high memory area and takes no conventional RAM. The Hard Drive page in Control Panel provides mounting and disk tools. Its Install button starts the installer, which copies the system onto a partition from the floppies or, on a machine with a network card, from the os8088 website. System Check checks a floppy or hard disk the way DOS’s CHKDSK does, repairs what it safely can and defragments it. It is in the SYSTEM folder of the larger system disks, and on util360.img at 360KB. A folder on a web server can also appear as a read-only drive; see Networking. Use the imager guide to prepare physical media and the storage and boot media reference to choose release images.

Implementation: BIOS and native IDE paths, filesystem, CD-ROM driver, physical media, USB and CD boot.

Supported Hardware

Network adapters

Ethernet through an NE1000/NE2000-compatible ISA adapter or a Realtek RTL8139 PCI card, or a parallel cable to another computer.

Ethernet

ETHER.DRV supports the NE1000/NE2000 register family using programmed I/O. The driver polls the adapter, so it does not claim an Ethernet IRQ or DMA channel. Automatic probing checks common ISA I/O bases; the Control Panel Ports page can pin a device to a specific address.

Enable the driver, then use Control Panel's Ethernet page. DHCP is the default, with static configuration available. The stack supplies ARP, IPv4, ICMP echo, UDP, DNS and TCP for applications such as the browser, Telnet, the FTP server, The Wire, WireChat, the installer and the HTTP drive. The driver takes memory for its sockets only while a program has one open, and gives it back when the last one closes.

PCI Ethernet

PCIETHER.DRV drives a Realtek RTL8139 network card in a PCI slot, including the 8139A, B, C and C+. It finds the card through the machine’s PCI BIOS, so there is no address or jumper to set, and it looks only on a 386 or newer, since no older PC has a PCI slot. Like ETHER.DRV it polls the card and claims no IRQ. It carries the same network stack, so every program listed above works with it unchanged.

Tick PCI Ethernet on Control Panel’s Drivers page; the Ethernet page then names the card as RTL8139 and works as it does for an ISA card. The Drivers page lists it at about 39KB: the driver, an 11.5KB receive buffer in conventional memory that the card fills by itself, and the buffers of open connections.

Only one network driver is used at a time. When both are ticked, ETHER.DRV is tried first, and the PCI driver loads only if no ISA card answered. The file is on the 1.44MB, 1.2MB and 720KB system disks, the emulator disk, the 286 system disks and the live media; the 360KB disk and the small kernel’s disks leave it off. In QEMU, add -netdev user,id=n0 -device rtl8139,netdev=n0 to give the machine the card; in 86Box, choose the Realtek RTL8139C+ on a PCI machine.

Parallel link

NET.DRV uses a LapLink-style parallel cable and a matching host-side server. It can expose remote files or disk images and provide socket access through the host. This is a separate transport from Ethernet and needs the corresponding os8088 host tools. On a 286 or newer with memory above 1MB, the driver loads into the high memory area instead of conventional RAM. The HTTP drive works over this cable as well as over Ethernet.

See Networking for the distinction between direct HTTP and the host proxy used for HTTPS sites.

Implementation: Ethernet driver, adapter probe, PCI Ethernet driver, PCI probe, RTL8139 support, parallel-link driver.

Supported Hardware

Memory expansion

Conventional RAM, hardware EMS and extended RAM have different roles.

Conventional RAM

The kernel and application code live below the BIOS-reported conventional-memory ceiling, at most 640KB. Increasing conventional RAM from 128KB to 256KB, 512KB or 640KB increases the shared heap available for programs, data and loadable system components. The heap hands out memory in steps of 512 bytes, so a block is never more than 511 bytes larger than asked for.

The full kernel can move most programs' memory blocks to gather free memory into one piece. Memory a closed program gave back then joins the rest, instead of staying stranded between other blocks. A block stays where it is only while a device is writing into it or code is running in it. The smaller kernel never moves blocks.

Expanded memory (EMS)

EMS.DRV supports boards with consecutive LIM-style page registers, including the Lo-tech 2MB board and PicoMEM EMS. Four 16KB pages map into a 64KB window below 1MB. This works on an 8088 and lets applications that use the EMS API access additional data without extending the conventional heap.

The page frame and I/O registers must not conflict with another device or option ROM. Other EMS register families are not automatically compatible.

Extended memory (286 and newer)

The full kernel loads XMEM.DRV when suitable memory above 1MB is reported. It verifies the A20 address line and manages everything above the first 64KB as a pool for data. A 286 copies with its LOADALL instruction where that works, and otherwise through BIOS services; a 386 or newer copies with 32-bit moves. The smaller kernel omits this facility and the loadable EMS driver.

The first 64KB above 1MB is the high memory area (HMA), the one part of extended memory that real-mode code can reach directly. XMEM.DRV reads COLDHMA.SYS from the system disk and moves the kernel’s code kept outside its main 64KB segment there, which returns about 37KB of conventional RAM to programs. The sound, hard disk and parallel-link drivers load into the rest of the HMA when they are enabled, and the sound driver's 8KB buffer goes there too when room is left. If the file is missing or the copy does not check out, that code simply stays in conventional RAM. The 360KB system disk carries neither XMEM.DRV nor COLDHMA.SYS, because an XT can use neither; start a 286 from one of the larger system disks to use memory above 1MB.

Applications are different: on the standard kernels, neither extended RAM nor EMS relocates application code above conventional memory. The RAM disk and applications that explicitly support these stores can use the extra capacity. Explore the memory map for each configuration.

The 286 system

The 286 system is a second kernel, on disks of its own, for a PC with a 286 or later processor and at least 1MB of memory. It runs in protected mode, the processor’s mode that reaches memory past the first megabyte. Programs and their data can then use all of the machine’s memory, not only the first 640KB, and a program built for it can keep itself above 1MB, as ARCADE does with its games. The kernel keeps no more than 68KB of itself in conventional memory.

It does not use XMEM.DRV, COLDHMA.SYS or an os8088 ROM: memory above 1MB is part of its own heap instead. A program that breaks a protected-mode rule is closed, and the rest of the desktop keeps running. A PC with 1MB and no memory above the first megabyte should use the standard disks.

The kernel in ROM (IBM 5150)

An IBM 5150 has five spare ROM sockets beside its BIOS. An os8088 ROM built for them holds that same kernel code, and the kernel runs it from there: about 37KB more conventional RAM on the full kernel and 21KB on the smaller one. The smaller kernel’s ROM also carries the file dialog, Cut, Copy and Paste, the Control Panel and the formatter, so they work without the system disk in a drive. A ROM is built for one kernel and is ignored by any other; every disk boots normally without one. See the kernel in ROM and the HMA for how both work.

Implementation: conventional allocator, EMS boards, extended-memory store, HMA design, ROM design, RAM disk storage.

Supported Hardware

Clock & timers

Keep time with the PC timer and, when present, a battery-backed real-time clock.

System timer

The PC's programmable interval timer supplies the system ticks used by scheduling and timekeeping. A battery-backed clock is optional: a machine without one can use a date and time set for the current session.

Real-time clocks

The full kernel supports AT-compatible MC146818 CMOS clocks, MM58167-based XT clock cards, RP5C01 / Toshiba TC8521 clocks, and BIOS time and date services. Detection checks the direct interfaces and uses BIOS services as a fallback; a supported interface seeds the system clock at boot. Time then advances from the PC timer.

Control Panel writes date and time changes through the detected interface. Some BIOS implementations provide clock reads without working write services, so persistence depends on that firmware. The reduced kernel leaves out the hardware RTC ladder and keeps session time instead.

Implementation: clock detection and timekeeping, setting the hardware clock, and system ticks and scheduling.

Supported Hardware

Serial & parallel ports

Standard PC ports connect pointing devices, a serial cable to a second PC, audio hardware and the parallel network link.

Serial ports

COM1 and COM2 support Microsoft-protocol serial mice. The desktop's serial mouse setup uses the corresponding PC UART interface; QEMU can emulate this with -chardev msmouse.

A desktop program can also borrow a serial port to reach another PC through a null modem cable, a serial cable with its send and receive wires crossed. The game WireFleet works this way. SERIAL.DRV, the code that runs the borrowed port, is read from the system disk when the program connects and released when it disconnects or closes. One program can hold a port at a time. The port with the serial mouse is never lent, so the mouse keeps working. Only COM1 at 0x3F8 and COM2 at 0x2F8 are used, in whichever order the BIOS lists them; a Compaq, for example, lists them in its setup's order rather than IBM's. The program chooses the speed: WireFleet uses 2400 baud. The machine cannot hibernate while a port is borrowed.

While the machine starts, the mouse driver listens on both ports. A port whose incoming bytes show line errors cannot become the mouse port, so a cable game already sending from the other PC does not take over the pointer.

Parallel ports

A compatible LPT port can serve a Covox-style DAC or the LapLink network cable. Configure the intended port and driver in Control Panel; a connector's presence alone does not identify which peripheral is attached.

Port addresses can overlap with expansion hardware. The Ports page allows supported devices to be pinned to their configured I/O address, reducing unwanted probing. Keep a port available for one active device at a time.

Implementation: serial mouse, borrowed serial port, parallel DAC, parallel network, port configuration.

Technical Details

Disk guide

What ships on each disk, and what each thing does.

Choose a disk size and an image, then select a file to read its manual. Browse programs, drivers, sample files and host tools.

Disk inventories, file sizes, free space and embedded text are read from 125 images built from source commit 0129de48 (build 317). Use boot, application and driver files from the same release. Screenshots and videos illustrate the applications; their appearance can vary between builds.

Technical Details

Storage & boot media

Choose a boot image, then keep its application and driver files from the same release.

Floppy image pairs

CapacityBoot diskApplication disk
360KBos8088-360.imgapps360.img
720KBos8088-720.imgapps720.img
1.2MBos8088-120.imgapps120.img
1.44MBos8088.imgapps.img

Programs on additional disks

In the release zip each image has a shorter name, in a folder for its size: os8088.img and apps.img are 1440K/OS88-144.IMG and 1440K/APPS-144.IMG, and the other sizes follow the same pattern. This page and the Disk guide use the names the build gives them.

Some larger applications and their data ship on separate images. Use the Disk guide to browse them. A 360KB software disk cannot hold every program, so six more 360KB disks carry the rest, one subject each: music, office, network, games, emulators and utilities. At 720KB, a second software disk, more720.img, carries PiXEL, MIDIRack, RealDMG and DrMarco with their pictures, songs and demo files.

WIN16, the program that runs Windows 3.0 and 3.1 programs, has a disk of its own in every size: win16.img, win16-120.img, win16-720.img and win16-360.img. The rest of that disk is room for the Windows programs you bring. An install onto a hard disk from floppies does not copy WIN16, so copy its folder over afterwards.

ARCADE and Video Battle have disks of their own too, arcrel*.img and vbattle*.img. The 286 system for a PC with a 286 or later and 1MB or more has its own 1.44MB and 1.2MB disks: the system disks mega.img and mega120.img, the software disks megaapps.img and megaapps120.img, and builds of XTMP3, WIN16 and ARCADE for it. In the release zip they are in the 286-PLUS folders inside 1440K and 1200K. The sound debug disk, debug-sound*.img, is in the zip’s DEBUG folder.

A program’s own artwork, second code segment or ROM images are carried inside its .O88 file, so copying that one file copies the program. Data that goes with a program, such as RunCPM’s drive A folder or MIDIRack’s wavetable bank, is still kept in separate files.

The 360KB boot disk uses 512-byte clusters, which wastes less space on small files, to make room for the system, its drivers and the Sticky Apps. At that size, Paint and Minesweeper are on apps360.img, and the typefaces and Font Viewer are on office360.img. The 360KB boot disk also leaves out the CD-ROM driver, the extended-memory driver and the high-memory image, which only a 286 or later can use, and System Check, which is on util360.img at that size. The larger boot disks still carry them.

Use a boot disk and application packages from the same release. The package API changes as the system develops, so an older application disk may not work with a newer kernel. Drivers must match too: this release refuses a .DRV file from an earlier one.

A machine with 128KB

small360.img and small720.img are system disks for a machine with as little as 128KB of memory. Each boots the reduced kernel and carries every program that runs in 128KB, so a machine with one floppy drive needs no second disk. The 720KB one uses 2KB clusters instead of a standard 720KB disk's 1KB, because the reduced kernel reads only a two-sector file allocation table. For the same reason, a machine running it reads standard 360KB disks but no other 720KB disk.

A drive from a web server

The HTTP drive, HTTPFS.DRV, puts a folder published on a web server on the desktop as a read-only drive. Programs on it start and documents open as they would from a floppy. Each file is fetched when it is opened, over Ethernet or the parallel cable. Networking explains how to set one up.

Live USB and CD

os8088-usb.img is a raw hard-disk image with a FAT16 partition and applications. The live ISO boots the same system through El Torito. Both require legacy BIOS boot support.

USB media can retain changes. Writes on the live CD go to a temporary RAM shadow and disappear when the machine shuts down. See live media in action.

From source, make live builds the USB image and ISO; make usb and make iso build them separately. The imager workflow covers writing media and matching CompactFlash geometry.

Implementation: image targets, live media, disk imager, HTTP drive.

Technical Details

Bootloader

From the first 512-byte sector to a running desktop: how os8088 loads itself into memory.

Follow the boot sequence

os8088 starts through a legacy PC BIOS. The BIOS places a boot sector at 0000:7C00, linear address 0x07C00, and transfers control to it. The first code runs in 16-bit real mode with 8086-compatible instructions.

This walkthrough shows the order of work, rather than elapsed time. Stages take different amounts of time on different machines.

What the disk contains

A floppy is a FAT12 volume. Its boot sector contains both filesystem parameters (the BPB) and stage 1 code, followed on disk by the FAT copies, root directory and data area. The image builder places KERNEL.SYS first in the data area, starting at cluster 2, in one contiguous run.

A boot floppy, from its first sector onwardSchematic; block widths do not represent file sizes.
  1. Boot sector512 bytes
    BPB + stage 1
  2. FAT copiesAllocation tables
  3. Root directoryFile entries
  4. Data areaKERNEL.SYS first,
    then other files

KERNEL.SYS in a default compressed build

  1. Boot blobLoader and
    splash
  2. Plain kernel headCode needed while
    the floppy is loading
  3. LZ4-packed tailExpanded before entering the
    kernel; ends with startup code

Stage 1 calculates the data-area position from the BPB. It reads the boot blob from the beginning of KERNEL.SYS; it does not search the directory or walk the kernel's FAT chain. The build tools supply the blob size, destination and verification values when they assemble the boot sector.

Current default builds compress the kernel's tail with LZ4. The boot blob stays uncompressed because it contains the decompressor. The kernel head also stays plain so display-detection code is available while the floppy loader updates the splash. A NOKZIP=1 build keeps the body uncompressed.

Hard disks, USB and CD

A hard disk starts with a master boot record (MBR). It chooses the active partition and loads that partition's volume boot record (VBR). The VBR uses the volume's recorded geometry and partition base to read the boot blob and kernel body in two passes. It does not enter the floppy stage-2 loader; a compressed build calls the blob's expansion helper before entering the kernel.

The installer records where the contiguous kernel run starts; a fresh format places it first, while an installation that preserves existing files can use another free run. Live USB ships a prepared FAT16 hard-disk image. Live CD wraps that image with El Torito hard-disk emulation, letting the BIOS expose the same disk interface. See Storage & boot media for choosing an image.

Make room, then give it back

The kernel's destination begins at 0060:0000, linear address 0x00600. Loading it would overwrite the original boot sector at 0x07C00, so the floppy boot sector and hard-disk VBR relocate to the top of conventional RAM first. They keep a 2KB stack immediately below their 512-byte copy. The ceiling comes from BIOS INT 12h.

Conventional RAM during loading and after startupLow addresses at the top. Regions are schematic; their sizes depend on the build and machine.

While the kernel loads

  1. Low memory & BIOS dataBelow 0x00600
  2. Kernel destinationBegins at 0x00600
  3. Boot blobAbout 7KB above the future heap floor
  4. Remaining conventional RAMBetween the blob and loader stack
  5. Temporary loader stack2KB below the relocated sector
  6. Relocated sectorThe top 512 bytes

When the desktop is ready

  1. Low memory & BIOS dataBelow 0x00600
  2. Resident kernel & buffersBegins at 0x00600; task stacks are here
  3. Shared conventional heapThe boot blob, loader stack and sector no longer reserve space. Applications, drivers and system data share the heap.Ends at the BIOS conventional-memory ceiling

The boot blob remains available after the disk read, because the splash in it runs until the desktop is ready. The kernel’s one-time startup code is not in the blob: it is the last part of KERNEL.SYS, packed with the tail and expanded with it, so it is read after the loading screen is up. The kernel switches to its own task stack, runs that startup code, finishes the splash, then lowers the heap floor to reclaim the blob and the startup code together. The full build also compacts claims to join the recovered space with the rest of the heap. Stage 1 loads the blob about 7KB above the future heap floor on the standard kernel, so that neither the end of the kernel’s compressed tail nor the expanded startup code can reach it, and that gap is reclaimed with the blob.

The kernel keeps the code that lives outside its main 64KB segment at the top of its resident area, just under the heap. When that code runs from somewhere else, the heap floor drops by that much more: about 37KB on the full kernel. On a machine with neither a VGA nor an EGA card, the full kernel also gives up its VGA-only drawing code, about 2KB; when the code above it stays in RAM, the kernel moves that code down over the space. The first step of initialization looks for an os8088 ROM in an IBM 5150’s spare sockets and uses its copy if the ROM was built for this kernel. On a 286 or newer with memory above 1MB, the extended-memory overlay copies the code into the high memory area instead, from COLDHMA.SYS. Just before the first desktop paint, the kernel opens every link in the boot disk’s AUTOSTRT folder, unless Shift is held.

The top-of-RAM loader copy and stack are temporary too; the running kernel does not reserve them. On the hard-disk path, the MBR briefly uses 0x00600 while it chain-loads the VBR; the later kernel load replaces that scratch copy. Explore Memory model for exact resident boundaries and different RAM configurations.

Read checks and boot failures

The floppy loader splits BIOS reads at track or cylinder boundaries, while limiting each request to the sectors still needed. The PC’s DMA controller cannot transfer across a 64KB boundary in memory, so stage 1 stops a read there. Stage 2 instead reads such a run whole, just above the boundary, and copies it down, which saves a disk call at each boundary. It resets the controller between failed attempts and stops after repeated failures.

Some floppy BIOSes report success after returning the wrong sectors across a head boundary. When the faster cylinder-read path is used, stage 2 adds up one 512-byte sector of the kernel that lies past a head boundary, and compares the total with the value recorded when the kernel was built. A mismatch, or a failed crossing read, makes it retry with track-bounded reads. A wrong sector passes this check about one time in 65,536. It is a simple sum, not a cryptographic signature.

MessageWhat it means
RAMThe floppy loader cannot fit the kernel's startup layout below its temporary stack.
Loader checksumThe boot blob's word-sum check failed before stage 2 could run. Diagnostic builds may print a shorter message and a value.
Disk errorA BIOS disk read failed after retries. This can occur in the floppy loader or MBR.
No active partitionThe MBR found no partition marked active.
R / G / DThe hard-disk VBR reports insufficient RAM, invalid recorded geometry, or a failed disk read, respectively.

For setup, start with Booting on real hardware or Running in an emulator. When reporting a boot failure, include the medium, image version, RAM size, controller or emulator, and the exact screen message.

Checked against source commit 0129de48. Implementation: floppy stage 1, stage 2 and expansion, MBR, volume loader, kernel startup, kernel packing, and live media.

Technical Details

Networking

Connect through Ethernet or a parallel link, and choose direct access or a host-side web proxy.

Direct Ethernet

With a supported adapter, enable ETHER.DRV for an NE1000/NE2000 ISA card or PCIETHER.DRV for a Realtek RTL8139 PCI card, and configure the Ethernet page in Control Panel. Both drivers carry the same network stack, and only one is used at a time. DHCP supplies the address by default. Applications share the driver's socket interface for TCP and UDP connections.

The native browser can use HTTP directly. Telnet logs in to other computers, and the FTP server lets another computer copy files to and from this one. The operating system does not terminate TLS for HTTPS sites.

Services on os8088.com

Three programs talk to the os8088.com website over plain HTTP, so they need an Ethernet card and a route to the internet but no proxy. The installer can copy a new release of the system and all its programs straight from the website, onto a hard disk, with no floppies to write first. It can also check for a newer release each time the machine starts. The Wire downloads programs from the online software library. WireChat joins chat rooms: four public rooms and private messages, with a member list and friends. The chat server holds each request until there is something new, so a message arrives in about a second while an idle machine sends one request every 50 seconds. The server screens every message for abuse, and removes a message flagged from two addresses other than its author’s.

WireChat can reserve your nickname with Chat > Claim Nick.... It gives you a code to use the same name on another machine. Signing in there ends the first machine's connection, whose status bar says Signed in elsewhere. The WireChat guide explains how to replace the code or release the name.

HTTP drive

HTTPFS.DRV mounts a folder published on a web server as a read-only drive with its own letter. Tick HTTP Drive on the Drivers page of Control Panel, then type the folder's address on the Web Drive page and click Mount. Only http:// addresses work, and redirects are not followed.

The folder needs an index file, OS88.IDX, that lists every file and folder with its size. The drive reads it once, so browsing the folders costs nothing on the network, and each file is fetched when it is opened. In the source, tools/os88httpdrv.py writes the index and can serve the folder. The drive works over Ethernet or the parallel cable, and the installer reads a network release through it.

Web proxy

The source includes tools/os88proxy.py, a host-side Python web proxy that fetches HTTPS pages and simplifies content for the native browser. Run it on another computer, then open that computer's address and proxy port in the os8088 browser. In QEMU's user network, the host is normally 10.0.2.2; on a physical LAN, use the host's LAN address.

The proxy handles the upstream encryption. It does not add TLS support to every os8088 network application. See the browser walkthrough and The Wire.

Parallel connection

NET.DRV uses a LapLink cable with the project's matching server tools on the other end. It can serve remote files and disk images as well as bridge socket requests. Enable only the driver and LPT port intended for that connection.

Implementation: Ethernet stack, PCI Ethernet driver, parallel transport, web proxy, chat client, HTTP drive, HTTP drive publisher, installer.

Technical Details

Memory model

See how the kernel, applications, video hardware and extra memory share the PC address space.

Choose a RAM configuration to explore the layout. Conventional RAM holds the desktop and program code; expanded and extended memory provide separate stores for applications that use them.

One heap, two allocation directions

The interrupt vectors and BIOS data occupy the first 1.5KB. The kernel starts at 0x00600. Its image, resident cold code, FAT window, disk buffers, task stacks and optional planar-decoder buffers determine where the conventional heap begins.

Data claims search upward from the heap's low end; application regions search downward from the BIOS-reported conventional-memory ceiling. Both use the same allocator. Drivers, fonts, overlays and other system features also claim space here. There is no fixed application pool, and the heap span shown above is not all free after boot.

Like Task Manager's RAM view, the diagram follows address order. Task Manager additionally draws live claims and package locations; this documentation cannot know which programs or drivers your machine has loaded.

640KB, the adapter area and 1MB

BIOS INT 12h supplies the conventional-memory ceiling, normally at most 640KB in the standard PC map shown here. Firmware may reserve some of that RAM, including an Extended BIOS Data Area. A machine with 1MB installed therefore does not offer a 1MB application heap.

0xA0000–0xBFFFF contains video-memory windows. The rest of the first megabyte holds adapter ROMs, firmware and optional mapped hardware. The diagram shows standard address windows, not a claim that every byte in those windows is populated. Machine-specific remapping of RAM around this area is not modeled.

EMS, HMA and extended memory

Hardware EMS switches 16KB pages into a 64KB frame below 1MB. The optional example uses 0xE0000 and appears in the map when the selected span reaches that address; the driver probes frames at E000, D000 and C000 segments, avoids detected option ROMs, and uses whichever supported board answers. The frame is a window into the board's memory, not another 64KB of conventional heap.

On a 286 or newer with the full kernel and usable RAM above 1MB, XMEM.DRV keeps the first 64KB for the HMA. Real-mode addresses reach 65,520 bytes of it, through 0x10FFEF; the last 16 bytes are outside the HMA. The kernel’s code from outside its main 64KB segment moves there from COLDHMA.SYS, so on those machines it leaves conventional RAM and the heap starts that much lower, as the map shows. The sound, hard disk and parallel-link drivers, when enabled, load into the space under it. The extended data pool starts at 0x110000.

An IBM 5150 can run the same code from an os8088 ROM in its spare sockets, at 0xF4000, with the same effect on the heap. The map does not model a ROM.

A 286 copies with its LOADALL instruction where that works, and otherwise with BIOS INT 15h/AH=87h; neither reaches addresses at or above 16MB. A 386 or newer copies with 32-bit moves. Sizing still depends on the older BIOS AH=88h report; the 1MB+ preset illustrates a 2MB machine. Extra RAM is a data store for explicit users such as a RAM disk, media buffers or the disk cloner. It does not increase the address range for application code.

Build and hardware differences

The full and reduced builds have different resident sizes. The reduced build omits planar color rendering, loadable hardware drivers and extended-memory support. An EMS board can still occupy address space, but this build cannot load its driver. In the full build, the VGA-only drawing code, about 2KB, and 336 bytes of planar-decoder buffers return to the heap when neither a VGA nor an EGA is detected. This decision follows the detected hardware, even if a VGA machine is currently displaying a monochrome mode.

Application primary images plus zero-initialized data are limited to 63.5KB each, with additional heap claims and overlays available. All code shares an unprotected real-mode address space; allocations express ownership, not hardware isolation.

Layout measured from source commit 0129de48 using tools/kernsize.py --json --strict for both builds. These figures describe that source snapshot and can change between releases. Implementation: kernel layout, allocator, Task Manager, extended memory, and EMS.

Developer guide

Your first application

Write a program or bring an existing one to os8088.

Start building

Start with the Hello application. It creates a window, draws text, registers menus and supplies an About dialog. Its assembly source uses the shared os88api.inc interface.

In a source checkout with the build dependencies installed, build the package, put it on a separate application disk, then boot it in QEMU:

Terminal

make build/hello.o88
python3 tools/os88disk.py --size 1440 -o build/hello-apps.img build/hello.o88
make run RUNAPPS=build/hello-apps.img

Open disk B: and launch HELLO.O88. For an interactive C example, see chello.c; make chello builds its disk, and make run RUNAPPS=build/chello.img boots it.

Two loaded programs open at once on the checkerboard desktop: a Minesweeper window with an untouched 9 by 9 grid of raised cells and a counter reading 10, and beside it a Calculator window showing 0. Three small tiles sit in the dock at the bottom left, the first of them inverted to black.
Two programs running together. Each program has its own memory segment.

The developer guide covers the workflow and tools for contributing.

Developer guide

Language & toolchain

Build real-mode applications in NASM assembly or C through SmallerC.

Assembly and C

The boot code and kernel are NASM assembly. Native applications use assembly, C or a mix of the two. SmallerC emits NASM source; the project's checking and runtime tools adapt it to the os8088 calling convention, then NASM produces the program image.

C programs call the same window, drawing, file and memory services as assembly programs. There is no general C standard library. The C toolchain guide explains the supported subset and build setup.

C constraints

Use static storage when an object's address must be passed to the OS. Avoid taking the address of automatic variables, copying structures by value, or using unsupported wide and floating-point types. The checking tool enforces these rules and the small stack-frame budget; consult the C guide before porting library code.

Package size and memory

A primary application image plus its zero-initialized data must fit within 0xFE00 bytes (63.5KB). Memory is handed out in steps of 512 bytes, so a program takes its image and data rounded up to the next 512 bytes. That limit does not describe the total package file or all memory an application can use. Applications can claim heap memory, load overlays and carry additional embedded parts. An overlay can itself be carried inside the program’s file, so a program that needs a second code segment still ships as one file.

On the standard kernels, programs share a real-mode address space without memory protection. The 286 system runs most of the same programs unchanged in protected mode. A few, such as the Video Player, are built a second time for it, and its software disk carries those builds. Use the OS allocation and lifecycle APIs to own and release memory. On the full kernel, a program can let the system move a block it owns, to gather free memory into one piece; it gives the system a routine to call after each move, so it can update the addresses it keeps. A block stays put while a device is writing into it or code is running in it. The C runtime does this for a C program's own memory. The memory map shows where primary images and data claims fit.

API and other ways to build

The API index groups services by task, os88api.inc defines assembly calls, and os88.h exposes the C interface. The specification defines the contracts.

Weave and Loom also support authoring applications with markup, scripts and effects. See the Weave specification.

Debug disks

Debug disks

Boot a disk that shows what a driver found on your machine, photograph the screen, and send the pictures with your report.

What a debug disk is

A debug disk is a system disk that boots straight into a report on one part of the system: what its driver probed, what it found, and what happened when the disk exercised it. It is for problems that occur on your hardware and not in an emulator, where the only instrument available is a camera.

The driver on a debug disk is built from the same source as the shipped one, with one assembler define that adds a record of its probes and a package verb that returns the record. Without the define, the hooks assemble to nothing; the build checks that the shipped driver is byte-identical to one with the hooks removed. The report therefore shows the probes the shipped driver runs, not a separate diagnostic implementation.

Every page is 17 rows of 78 columns in the 8x8 font, so it fits CGA's 640x200 screen and reads the same on EGA, VGA and Hercules. The disk starts the report from \AUTOSTRT, so it needs no keyboard or mouse input to produce the first two pages.

The machine still has to boot os8088. A machine that stops at Disk error or never reaches the desktop is a boot problem; report it with what the screen shows.

One disk exists so far, the sound debug disk. Disks for other drivers will use the same design when a field report needs one, and each will get a page in this section.

Get the disks

Releases after v1.0.20261106 include a DEBUG folder in the release archive. Each disk comes in four sizes with the same contents; use the image that matches your A: drive.

File in the archiveDiskDrive
DEBUG/SOUND144.IMGSound3.5" 1.44MB
DEBUG/SOUND720.IMGSound3.5" 720KB
DEBUG/SOUND120.IMGSound5.25" 1.2MB
DEBUG/SOUND360.IMGSound5.25" 360KB, for a PC or XT

Write the image to a floppy in the same way as a system disk; see Booting on real hardware. The disk carries its own system files and Note Pad, so drive B: can stay empty.

To build the images from the source tree, run make debugdisks. The images are written to build/debug-sound.img, -120, -720 and -360. A plain make builds them as well.

What to send

Open an issue on GitHub and attach:

  • a photograph of every page the disk shows (three on the sound disk);
  • what you saw or heard while it ran (on the sound disk: whether the tone played for all ten seconds, and if not, when it stopped);
  • the name and chip of the device, and the machine it is in.

The design record is DEBUG-DISKS-PLAN.md; the record layout and package verb are specified in section 127 of SPEC.md.

Debug disks

Sound debug disk

Probe results for Sound Blaster, AdLib, MPU-401 and Covox hardware, and a ten-second playback test that reports each second.

Run it

Write DEBUG/SOUND144.IMG, SOUND720, SOUND120 or SOUND360 to a floppy for your A: drive (Get the disks). Use it when a sound card is not found, has the wrong settings, or plays briefly and then goes silent. Its SYSTEM.CFG requests SOUND.DRV, so the driver probes for a card even if the kernel's boot check did not find one.

  1. Turn the speakers up and boot the disk in drive A:. Sound Debug opens on page 1.
  2. After two seconds the play test starts on page 2: a square-wave tone for ten seconds through the stream path that the music players use. Listen for a steady tone for the full ten seconds, and note when it stops if it stops early.
  3. When row 1 reads Done., photograph the screen. Press 1 and photograph page 1, then press 3 and photograph page 3.
KeyAction
1 2 3Show Detect, Play test or Registers
PRun the play test again
RChange the test rate: 22,050, 11,025, 8,000 or 44,100 Hz
VTurn the DSP D8h voice-switch reading off or on
EscClose Sound Debug

Read the pages

Page 1: Detect

This page shows the CPU tier and adapter; whether the loaded SOUND.DRV is the debug build; and the capability word. The DSP line shows the base port, version, IRQ, 8-bit and 16-bit DMA channels, and whether auto-init is used. The page also shows the result for each base port the reset probe tried, how the IRQ was found (PicoMEM, mixer register 80h or the F2h interrupt probe), and the interrupt controller's current registers. It identifies the mixer, OPL, MPU-401, Covox and PicoMEM, and ends with a BLASTER= line and a verdict.

For an ESS chip, the page also shows mixer register 40h read four times. That read returns the part number and configuration port; Linux's es18xx driver uses it to identify ESS chips. The page also shows the reply to DSP command E7h.

Sound Debug page 1 on VGA. Rows read: Machine CPU 386 or better, video VGA; Driver SOUND.DRV loaded, debug build; DSP base 220h version 3.01 IRQ 5 DMA 1; Scan 220:AA=ok; IRQ F2h probe, IRQ 5 fired; Mixer CT1345 (SB Pro, ESS compatible); ESS mixer 40h x4 = 18 68 08 00 = ES1868 cfg 0800h, DSP E7h 68 8B; FM OPL3, MPU-401 330h; BLASTER=A220 I5 D1 P330 T4; Verdict: Sound Blaster tier attached.
Page 1 on 86Box's ES1868, in a Pentium. The chip identifies itself as an ES1868 with its configuration port at 0800h.

Page 2: Play test

Each one-second row shows what the card did in that second:

ColumnMeaning
bytes/sBytes the card consumed, read from the DMA position. It should stay near the rate, about 22,000 at 22,050 Hz.
IRQsBlock interrupts taken. With a 2,048-byte block at 22,050 Hz, about 11 per second.
D8hThe DSP's voice (speaker) switch: FF on, 00 off. na means the DSP did not answer; -- means the reading was off.
mix22 mix04Sound Blaster Pro master and voice volume registers.
60h 62h 64hAn ESS chip's master volume registers; -- on other cards.
streamThe driver's stream state.

The verdict names the first thing that stopped, checked in this order: DMA, block interrupts, the DSP voice switch, and then a mixer register. If none stopped, the verdict says so and asks when the tone stopped. Those registers cannot show a fault after the DSP, so your note about when the sound stopped is part of the result.

Sound Debug page 2 on VGA: a 22050 Hz 8-bit mono tone, ring 16384, 10 seconds, Done. Ten rows each show about 21970 bytes, 10 or 11 IRQs, D8h FF, mix22 FF, mix04 99 and ESS registers 3F 3F 20, stream playing. Totals: 222132 bytes, 108 IRQs, no underruns, no watchdog stops. Verdict: DMA, IRQs, voice and mixer steady 10 s.
A complete play test on the same ES1868. Every column stays steady, so the verdict asks when the tone stopped.

Page 3: Registers

Page 3 shows mixer registers 01h–7Fh (it skips 00h, the reset register), the last 32 bytes sent to the DSP from oldest to newest, the driver's stream record, and the interrupt controller. A ! after a DSP byte means that the write timed out.

Sound Debug page 3 on VGA: an 8-row hex dump of mixer registers 01h to 7Fh, two rows of DSP write log bytes including E1, F2, E7, 40, D3, D1, 48 and repeated D8, then the stream record and ISR counters.
Page 3 after the play test. The DSP log shows the identify commands followed by a D8h reading once a second.
The same play-test page on a 640 by 200 CGA screen, shown at double height. All 17 rows fit. D8h reads na and the ESS columns read dashes, because this is QEMU's Sound Blaster 16.
The play test on CGA, under QEMU's Sound Blaster 16. All 17 rows fit at 640x200. This card does not answer D8h, and its columns read na.

What to send

Open an issue on GitHub with photographs of pages 1, 2 and 3; whether the tone played for all ten seconds and, if not, when it stopped; and the card's name, its chip and the machine it is in.

Troubleshooting

Reporting a bug

Help reproduce a problem and get it fixed.

What to include

Open an issue on GitHub. Include a screenshot, your display adapter, emulator and version, image size, and what you clicked before the problem.

If the problem involves sound hardware and occurs only on a real machine, boot the sound debug disk first and attach photographs of its three pages. Debug disks describes how these disks work.

For architecture and implementation details, explore the source on GitHub.