lr-virtualxt/docs/SPEC.md

VirtualXT -- Specification

Philosophy

VirtualXT shall be a Turbo PC/XT emulator. Its design shall be governed by three principles:

• Simplicity. Every component shall have one job and one interface. The peripheral system shall have one vtable. The bus shall have one dispatch mechanism. The CPU shall have one decode-execute loop. When a simpler design can do the job, it wins.

• Minimalism. No external dependencies beyond the libretro API header. No threading. No dynamic plugin loading. No abstraction layers that don't map directly to hardware concepts.

• Transparency. A developer familiar with PC/XT hardware should be able to read any module and recognize the hardware it models. The emulator's structure shall mirror the machine it emulates.

The implementation language shall be C11. The core emulator shall compile in a freestanding environment (-ffreestanding) with no standard library dependency, ensuring portability to bare-metal targets. Optional modules (networking, debugging) and unit tests may use hosted facilities such as threads and sockets, but these shall never be required for the core to build and run.

Design Characteristics

Several choices shall be applied consistently across the codebase:

1. Freestanding-first core design
2. Flat lookup-table dispatch instead of dynamic discovery chains
3. Statically allocated singleton-style system state
4. Small, explicit interfaces between layers
5. Minimal dependencies and minimal hidden control flow

The intended result is a codebase where major behavior is easy to trace from the frontend entry points down to CPU, bus, and peripheral interactions.

System Overview

The emulator shall be organized as four layers:

┌──────────────────────────────────────────┐
│              Frontend                    │
│     (libretro callbacks, frame loop)     │
├──────────────────────────────────────────┤
│              Machine                     │
│    (step loop, timer dispatch, reset)    │
├────────┬────────────────────────┬────────┤
│  CPU   │          Bus           │ Timers │
│8088/V20│  memory map · I/O map  │        │
├────────┴────────────────────────┴────────┤
│           Peripheral Modules             │
│  PIT · PIC · PPI · DMA · ROM · CGA · …   │
└──────────────────────────────────────────┘

Frontend

The frontend shall be the boundary between the emulator and the host environment. In normal use this shall be the libretro integration layer.

Its responsibilities shall be:

1. Accept host callbacks for video, audio, input, timing, and file access
2. Create and initialize the emulated machine
3. Apply runtime configuration and machine setup
4. Drive frame-by-frame execution
5. Present audio/video output back to the host

At a high level, the frontend shall own host integration while the emulator core shall own emulation behavior.

Machine

The machine shall be the central coordinator for the emulated system.

Its responsibilities shall be:

1. Own global emulator lifecycle operations such as create, init, reset, and destroy
2. Register and initialize peripherals
3. Step the CPU forward by a requested cycle budget
4. Advance timers alongside CPU execution
5. Route configuration requests to the appropriate layer

The machine shall be the point where the frontend's frame-level view meets the core's cycle-level execution model. The machine shall be a singleton: all state shall be module-scoped. There shall be exactly one machine per process.

Core Services

Core services shall be the internal mechanisms shared by the whole emulator:

1. CPU instruction execution
2. Bus dispatch for memory and I/O
3. Timer scheduling and updates
4. Interrupt routing

These services shall form the runtime backbone of the emulator. They shall not model a single external device; instead, they shall provide the execution environment in which peripherals and the CPU interact.

Peripheral Modules

Peripheral modules shall represent hardware devices attached to the machine. Examples include memory-mapped devices, I/O devices, video, storage, and support chips.

A module may instantiate multiple peripherals. For example, a VGA module could register both a video peripheral (for the CRTC and attribute controller I/O) and a ROM peripheral (for the VGA BIOS). Each peripheral still implements the same vtable interface independently.

Each peripheral shall follow the same broad model:

1. It exposes a common interface to the machine and bus
2. It shall register the address ranges or ports it owns
3. It shall maintain its own device state
4. It shall react to reads, writes, resets, timers, and configuration as needed
5. It may read frontend-provided resources via the Frontend API during install()

This shall keep the system modular without introducing deep abstraction layers.

Runtime Flow

The emulator shall run in a simple top-down flow:

1. The frontend shall receive a frame callback from the host
2. It shall gather input and determine how many emulated CPU cycles to run
3. It shall ask the machine to execute that cycle budget
4. The machine shall repeatedly step the CPU and update timers
5. CPU memory and I/O operations shall be dispatched through the bus to peripherals
6. Peripherals shall update internal state and may raise interrupts or produce output
7. The frontend shall submit the resulting audio and video to the host

This structure shall keep host concerns separated from core emulation while still allowing the whole system to advance in a predictable loop.

Bus

The bus shall be two flat arrays that map addresses to peripheral indices.

Memory map. The 8088 has a 20-bit address space (1 MB). The memory map shall divide this into 16-byte pages, yielding 65,536 entries. Each entry shall hold the index of the peripheral responsible for that page. A memory access shall mask the address to 20 bits, shift right by 4 to find the page, look up the peripheral index, and call that peripheral's read or write callback.

I/O map. The 8088 has a 16-bit I/O port space (65,536 ports). The I/O map shall have one entry per port, each holding a peripheral index. Port access shall look up the index directly and call the peripheral's I/O callback.

Default peripheral. Peripheral index 0 shall be special. It shall be created first and claim the entire memory and I/O space. It shall provide 1 MB of RAM and return open-bus values (0xFF) for all I/O reads. Every other peripheral shall overlay its ranges on top by writing its own index into the map entries. This means unregistered regions shall always fall through to sensible defaults without any conditional logic in the dispatch path.

The lookup tables shall be the only dispatch mechanism. There shall be no linked lists, priority chains, or fallback searches.

Peripheral Interface

Every hardware device -- RAM, ROM, timers, interrupt controller, video adapter, disk controller -- shall implement the same interface. This shall be a struct of function pointers (a vtable) with the following callbacks:

Lifecycle:

• install -- called once; the peripheral shall register its memory and I/O ranges by writing its index into the bus lookup tables.
• reset -- shall restore the peripheral to power-on state.
• destroy -- shall free resources.
• config -- shall accept a section/key/value triple for runtime configuration. The section corresponds to an INI section name during data-driven setup.
• name -- shall return a human-readable identifier.

Memory bus:

• read(address) -- shall return a byte from the peripheral's address space.
• write(address, byte) -- shall store a byte.

I/O bus:

• io_in(port) -- shall return a byte from an I/O port.
• io_out(port, byte) -- shall write a byte to an I/O port.

Timer:

• timer(id, cycles) -- shall be called when a registered timer fires.

Interrupt controller (PIC only):

• pic_irq(line) -- shall assert an interrupt request line.
• pic_next -- shall return the highest-priority pending interrupt vector, or -1.

DMA controller (DMA only):

• dma_read(channel) / dma_write(channel, byte) -- DMA transfer callbacks.

All callbacks shall be nullable. The bus shall check for null and substitute safe defaults: 0xFF for reads, no-op for writes.

Device state shall be attached by embedding the vtable struct as the first field of a larger device-specific struct. Because the vtable is at offset zero, a pointer to either type shall be interchangeable. This gives each device private state with zero indirection cost and no separate allocation.

Class tags. Each peripheral shall carry a bitmask of class flags (generic, PIC, DMA, PPI, PIT, video, audio, etc.). The machine shall use these to discover specific peripherals -- for example, locating the PIC for interrupt routing. Peripherals may also read frontend-provided configuration via the Frontend API during install().

The system shall support up to 64 peripherals. This is more than sufficient for a PC/XT and shall allow the index to fit in a single byte in the lookup tables.

Frontend API

Modules may occasionally need configuration or resources that cannot be expressed through the peripheral vtable alone. The Frontend API shall be a set of global configuration functions that sit alongside the peripheral manager. Modules shall read these values during install(); the frontend shall set them before vxt_machine_init().

This shall be intentionally separate from the vtable because it represents module ↔ frontend communication, not module ↔ machine communication. The peripheral vtable shall handle runtime interaction; the Frontend API shall handle setup-time resource binding such as framebuffers, file loaders, and logging.

Global setters shall be called once by the frontend before machine init. Global getters shall be used by modules during install() to discover frontend-provided resources. This eliminates the need for type-specific setup functions or module-specific global pointers in the frontend.

CPU

The CPU shall model an Intel 8088 processor implementing the 8086 instruction set, with optional NEC V20 emulation. It shall follow the decode-dispatch pattern:

1. Prepare -- shall clear per-instruction state and set default segment bases.
2. Prefix -- shall consume prefix bytes: segment overrides, LOCK, REP/REPNE.
3. Decode -- shall read the opcode byte, decode operands (ModR/M, immediates, displacements), and resolve a function pointer for execution.
4. Execute -- shall call the resolved function.
5. REP -- for string instructions, shall decrement CX and repeat if nonzero (with flag checks for REPE/REPNE variants).
6. Interrupt check -- if interrupts are enabled, shall poll the PIC for a pending vector and service it.
7. Prefetch -- shall use any remaining bus cycles to speculatively fill the prefetch queue from ahead of IP.

Cycle accounting shall model the 8088's split architecture. The execution unit (EU) and bus interface unit (BIU) shall operate in parallel. Memory and port accesses shall charge bus cycles; arithmetic shall charge execution cycles. The true cost of an instruction shall be the greater of the two.

Cycle lookup tables. Static cycle costs shall be stored in per-CPU-type tables indexed by opcode. A zero entry shall mean dynamic cost computed by the handler.

Prefetch queue. A 4-byte circular buffer shall model the 8088's instruction prefetch. Instruction bytes shall be fetched from the queue when available, falling back to direct memory reads. After execution, idle bus cycles shall fill the queue ahead of the instruction pointer.

Register file. The 8086 registers (AX/BX/CX/DX with 8-bit halves, SP, BP, SI, DI, segment registers, IP, FLAGS) shall be stored in a struct with overlapping 8-bit and 16-bit fields. Flag manipulation shall use a 256-entry parity lookup table and bitmask operations.

ALU. Each arithmetic and logic operation (ADD, SUB, AND, OR, XOR, shifts, rotates, MUL, DIV, BCD adjustments) shall be a standalone function that computes the result and updates the relevant flags. Operations shall be generic over byte and word widths.

Timers

Peripherals shall register timers during installation, specifying an interval in microseconds. The peripheral manager shall maintain a flat list of timers, each tracking accumulated CPU cycles. After every instruction, the machine shall advance all timers by the instruction's cycle count. When a timer's accumulated cycles reach its interval threshold (converted from microseconds using the CPU frequency), the owning peripheral's timer callback shall fire. For non-zero intervals, the accumulator subtracts the threshold, carrying the remainder forward for timing accuracy. For zero intervals (fire every update), the accumulator resets to zero.

An interval of zero shall mean the timer fires on every update, which the PIT shall use for sub-instruction-granularity counting.

Interrupts

Peripherals shall never interrupt the CPU directly. All hardware interrupts shall route through the PIC (Intel 8259):

1. A peripheral shall call interrupt(irq_line) on the bus.
2. The bus shall forward this to the PIC, which sets the corresponding request bit.
3. After each CPU instruction, the CPU shall poll the PIC via next().
4. If the PIC returns a valid vector and interrupts are enabled in FLAGS, the CPU shall push FLAGS, CS, and IP onto the stack, clear the interrupt flag, and jump to the address in the interrupt vector table.

This shall mirror real hardware: the PIC shall arbitrate priority, masks, and end-of-interrupt signaling. The CPU shall be unaware of individual IRQ lines.

Disk Emulation

Unlike most PC/XT peripherals, the disk controller shall not be a hardware-level device model. Instead, it shall emulate the BIOS INT 0x13/0x19 interface directly through two I/O ports. This avoids the need to model a real floppy controller (Intel 8272/NEC 765) while still providing full disk support for DOS and DOS applications.

Architecture. The disk peripheral shall register I/O ports 0xB0 and 0xB1. The VXTX extension ROM (see below) shall hook INT 0x13 and INT 0x19 and translate them into port I/O that the disk peripheral shall handle. The disk controller shall read CPU registers directly from the machine to get the INT 0x13 parameters (drive number, CHS address, sector count, buffer address) and write results back the same way.

I/O ports:

• Port 0xB0 out -- bootstrap. Shall load the first sector of the boot drive into memory at 0x7C00.
• Port 0xB0 in -- shall return 0x00 if the boot drive is a hard disk, 0xFF if it is a floppy.
• Port 0xB1 out -- shall dispatch the INT 0x13 function in AH. Supported functions: reset (0x00), status (0x01), read sectors (0x02), write sectors (0x03), verify/format (0x04-0x07), drive geometry (0x08).
• Port 0xB1 in -- shall return 0x00 if drive DL has a disk mounted, 0xFF otherwise.

Asynchronous completion protocol. Because the libretro VFS interface does not define an asynchronous I/O mechanism, the disk controller shall support an optional guest-visible polling path for frontends where physical device I/O may block:

1. When file_api.read() or file_api.write() returns VXT_DISK_NOT_READY (-2), the controller shall record the pending operation and return AH = 0x80 with carry clear.
2. The VXTX BIOS shall poll port 0xB1: 0x80 means busy, 0x00 means complete, 0xFF means error. On completion it shall read final AL/AH from ports 0xB2/0xB3.
3. The frontend shall complete the blocking call outside the emulation thread and make the result available on the next read()/write() call for the same drive.
4. Frontends that never return VXT_DISK_NOT_READY shall see no behavioral difference.

Drive management. The controller shall support up to 256 drives (indices 0x00-0xFF). Floppy drives shall use indices 0x00-0x7F; hard disks shall use 0x80-0xFF. On mount, the controller shall auto-detect floppy geometry from well-known image sizes (160K, 360K, 720K, 1.2M, 1.44M) or compute hard disk geometry (63 sectors, 16 heads, cylinders derived from image size). All addressing shall use LBA, computed from the CHS values passed by the BIOS.

File access. The controller shall not access files directly. Instead, it shall receive a vxt_disk_file_api_t struct of function pointers (open, read, write, seek, tell, close, size, flush, set_led) from the frontend. The frontend shall bridge these to the libretro VFS interface.

Configuration. The disk controller shall accept INI configuration keys under the [disk] section: boot (set boot drive number), auto (mount with auto-detect), A (mount as floppy 0), C (mount as hard disk 0x80), and umount (unmount a floppy drive).

VXTX Extension ROM

VXTX shall be a 2 KB extension ROM mapped at address 0xFD800. It shall be the glue between the system BIOS and the emulated disk controller.

Purpose. A real PC/XT uses a hardware floppy controller with its own BIOS extension ROM that hooks INT 0x13. VirtualXT skips the hardware controller entirely. VXTX shall fill the same role in software: it installs INT 0x13 and INT 0x19 handlers that forward disk requests to the emulated disk peripheral via I/O ports.

Initialization. During POST, the system BIOS shall scan the ROM space for expansion ROMs (signature 0x55AA). When it finds VXTX at 0xFD800, it shall call the ROM's init entry point. VXTX shall install its interrupt handlers and update the BIOS Data Area equipment word at 0x40:0x10 to report one floppy drive present.

INT 0x13 handler. Shall perform OUT 0xB1, AL to dispatch the disk request to the disk peripheral. The peripheral shall read the function number and parameters directly from CPU registers. After the I/O completes, the handler shall copy the CPU flags to the interrupt stack frame so the caller sees the correct carry flag result, then returns via IRET.

INT 0x19 handler. Shall perform OUT 0xB0, AL to trigger the bootstrap sequence (loading sector 1 to 0x7C00). Before the OUT, it patches the return address on the stack to 0x0000:0x7C00, so the IRET transfers control directly to the loaded boot sector.

Build Modes

VirtualXT shall be organized around a freestanding emulator core, with hosted code used only where it is clearly needed.

At a high level:

1. The core emulator and normal frontend build shall be freestanding-oriented
2. Tests shall run in a hosted environment
3. Some development-only tooling shall be enabled only in develop builds

This shall keep the main emulator architecture portable while still allowing richer debugging and test support during development.

Testing

Tests shall be hosted (they may use libc for stdio, malloc, etc.) and shall run against the same libvxt.a core library that ships in the emulator.

CPU opcode tests. The 8088 Machine Opcode Operation (MOO) test suite covers the full instruction set. A binary parser shall read .MOO files, apply initial CPU/memory state, execute to completion, and validate final state against expected results. It shall be run with make test-cpu (requires make testdata to fetch the test files).

Module tests. A lightweight test framework (module.h) shall provide peripheral-level unit tests that instantiate individual modules, wire them to the bus, and exercise their behavior in isolation. Each test file (e.g. test_pic.c, test_pit.c) shall compile into a single module-runner binary. It shall be run with make test-modules.

Both suites shall run together via make test.

Optional Debug Server

Develop builds may include an optional debug server layer.

This shall not be part of the normal emulation path, but an auxiliary development feature that can observe machine-visible events and support debugging without changing the core architectural split between frontend, machine, core services, and peripherals.

Frontend Effects

The frontend may apply optional visual and audio effects during presentation, such as a CRT filter and simulated hardware sounds. These are purely cosmetic and do not affect emulation state.

Bare-Metal Multicore Frontends

On bare-metal targets such as the Raspberry Pi, the frontend may utilize multiple CPU cores. The design shall maintain a strict separation: the emulator core shall remain single-threaded, and host-integration concerns shall be offloaded to dedicated cores.

• Core 0 shall handle initialization, USB input polling, and device hot-plug.
• Core 1 shall run the emulation frame loop.
• Core 2 shall handle video presentation, including optional CRT filtering and scaling.
• Core 3 shall drive audio output from a shared ring buffer.

Synchronization shall be achieved through spinlocks, atomic flags with memory barriers, and trampoline callbacks. The emulation core shall call standard libretro video and audio callbacks; the frontend's callback implementations shall act as trampolines that queue work to the appropriate core via lockless atomics. The emulation core shall be unaware of threading; it shall be driven by a single caller exactly as in any other frontend.