os8088

Bijdragen

Patches zijn welkom; voorkennis van 8086 assembly is niet vereist. Het bestand CONTRIBUTING.md beschrijft hoe men kan bijdragen met behulp van een coding agent (zoals Claude Code of Codex) op macOS, Linux of Windows. Dit omvat de instelling van de toolchain per platform, de regels die de assembler hanteert, het booten en aansturen van het OS in headless modus voor verificatie, en de richtlijnen voor een reviewbare pull request.

Snelstart voor ontwikkelaars

git clone https://github.com/jggonz/os8088.git && cd os8088
git config core.hooksPath .githooks     # Eenmalig: secret-scan hook
make && make run                        # Bouwen en booten in QEMU
claude                                  # ...of: codex

Dit is een experimenteel project, geschreven met AI. Vrijwel alle code en documentatie zijn geproduceerd door coding agents (Claude Code en Codex) onder menselijke regie en review. Het project is bedoeld voor hobbyisten, liefhebbers van retrocomputing en nostalgie — niet voor productiegebruik en niet als bewijs van handgeschreven vakmanschap.

Projectomschrijving

Os8088 is een grafisch besturingssysteem in de stijl van Macintosh System 1 voor de Intel 8086, geschreven in real-mode assembly en geboot vanaf een floppydisk.

Kenmerken:

• Resolutie van 640x480 met 16 kleuren.
• Overlappende, versleepbare vensters.
• Uitklapmenu's.
• Sluitbare applicaties met meerdere instanties.
• Een dock.
• Pre-emptieve multitasking (wat de originele Macintosh uit 1984 niet had; dit is via het Controlepaneel omschakelbaar naar coöperatieve multitasking).

Bouwen en Uitvoeren

De volgende make-commando's kunnen worden gebruikt:

• make: Bouwt alle zes de floppy-images.
• make run: Boot in QEMU (met een geëmuleerde seriële muis).
• make run-640: Zelfde als run, maar op een machine met 640KB RAM.
• make run-720: Zelfde als run, vanaf het 720KB paar.
• make xt: Boot de 360KB image op een geëmuleerde IBM PC/XT in 86Box.
• make xt-640: Zelfde XT met volledig 640KB RAM.
• make xt-cga: Zelfde XT met een CGA-kaart in plaats van VGA.
• make xt-hercules: Zelfde XT met een Hercules-kaart.
• make 286: 86Box: 286 @ 12.5MHz, 1MB, VGA.
• make 386sx: 86Box: 386SX @ 16MHz, 2MB, VGA.
• make 386: 86Box: 386DX @ 25MHz, 2MB, VGA.
• make 486: 86Box: 486DX2 @ 66MHz, 8MB, VGA, Sound Blaster 16.
• make pentium: 86Box: Pentium @ 133MHz, 16MB, VGA, Sound Blaster 16.
• make xt-sound: De 640KB XT met een Sound Blaster 2.0 (OPL2 + DSP).
• make 286-sound: 86Box: de 286 met een Sound Blaster 16.
• make 386-sound: 86Box: de 386 met een Sound Blaster 16.
• make test: Boot headless met een QMP socket voor gescripte tests.
• make debug: Boot met QEMU gepauzeerd, wachtend op gdb op poort :1234.
• make marty: Een cycle-accurate IBM 5150 (MartyPC) met een debugger (geheugen, registers, breakpoints, single-step, cycluscounts). Dit is het primaire hulpmiddel voor tests op een 8088 (zie docs/MARTYPC-DEBUG.md).
• make clean: Verwijdert build-bestanden.

Functionaliteiten

Interface en Gebruik

Het systeem boot direct in de GUI. Er draait in eerste instantie niets; alles wordt gelanceerd via de menu's. De klassieke Mac-interacties zijn aanwezig: vensters die kunnen worden versleept, naar voren gehaald, gesloten of geminimaliseerd; uitklapmenu's die horen bij de actieve applicatie; icoontjes van schijven op het bureaublad; een dock en een standaard dialoogvenster voor het openen en opslaan van bestanden.

Systeem

• Multitasking: Pre-emptieve multitasking gebaseerd op de 18,2Hz PIT tick, met 12 taakslots. Het Controlepaneel kan dit omschakelen naar coöperatieve modus, inclusief een watchdog zodat een taak die nooit afgeeft de machine niet volledig kan blokkeren.
• Applicaties: Tot 12 instanties kunnen gelijktijdig draaien. Meerdere kopieën van één app zijn mogelijk, elk met een eigen venster, taak en geheugen. Het dock bevat een tegel per instantie.
• Task Manager: Geeft live CPU- en RAM-gebruik weer, met één rij per instantie.
• Controlepaneel: Beheer voor Scheduler, Buffer, Display, Geluid en Datum/Tijd.
• Klok: In de menubalk; wordt bij boot gelezen van de hardware RTC (indien aanwezig) en daarna bijgehouden via de PIT.
• Systeemklembord: Gedeeld tussen applicaties.

Schijven en Bestanden

• Bestandssystemen: Ondersteuning voor FAT12 en FAT16 (lezen en schrijven). De schijven zijn standaard volumes, waardoor ze kunnen worden gemount door PC, Mac of Linux. Alle data die van een schijf wordt gelezen, wordt als potentieel onbetrouwbaar behandeld.
• Harde schijven: Mount elke gevonden FAT-partitie, installeert os8088 op een schijf en boot vanaf die partitie.
• Bestandsbeheer: Per volume beschikbaar; functies zijn onder meer openen, hernoemen, verwijderen, mappen maken en knippen/kopiëren/plakken via drag-and-drop. Kopiëren gebeurt via streams om geheugentekorten te voorkomen.
• Bestandsassociaties: Dubbelklikken op een document opent dit in het bijbehorende programma.

Software

Er worden vijftien laadbare pakketten meegeleverd op de softwaredisk:

• Apps: Note Pad (word wrap, DOS-leesbare tekstbestanden), Paint, ArtfulType, Fractal, Piano, Recorder, Tracker en ModPlug Player (beide spelen Amiga MOD-bestanden).
• Games: Minesweeper, Solitaire, Arkanoid, Missile Command en TameGram.
• Overig: Task Manager en HELLO (een minimaal pakket voor SDK-tests).

Timer en Bounce zijn ingebouwd in de kernel. Drivers worden op dezelfde manier geladen als pakketten (harde schijf, geluid en een seriële debugmonitor).

Frotz: Wordt apart geleverd op een eigen story-floppy (make zdisk). Dit is een onafhankelijke implementatie van de Z-Machine Standard 1.1 in 8086 assembly voor Infocom-games (v1–v8), voorzien van vensters, scrollback, geluid en afbeeldingen. Omdat floppy-opvragingen traag zijn (~400ms), blijft het hele verhaal resident in het geheugen; daarom vereist Frotz een machine met 640KB RAM.

Hardwareondersteuning

Eén binair bestand ondersteunt drie adapters, die bij boot worden geselecteerd: VGA (640x480, 16 kleuren), CGA en de Hercules mono-kaart.

• Muis: Microsoft seriële muis op COM1 of COM2. Beide poorten worden gescand; de eerste die correcte pakketten levert, wordt gebruikt, zodat de andere poort vrij blijft voor bijvoorbeeld een modem.
• Geluid: PC speaker, AdLib/OPL2 en Sound Blaster.
• CPU: Doorgaans 8086 real mode, waardoor het image draait op alles van een 4.77MHz IBM PC/XT tot een Pentium.

Technische Implementatie

Grafische weergave

Gebruikt VGA modus 12h (640x480x16 planar), standaard direct getekend. Voor vullingen worden Set/Reset + Bit Mask gebruikt, en XOR voor sleep-omlijningen en menu-highlights. Een backbuffer van 150KB is optioneel beschikbaar op machines met voldoende heap. CGA en Hercules maken gebruik van dezelfde binary; een 1bpp renderer neemt het over na detectie bij boot.

Multitasking

Round-robin via int 08h (PIT, 18.2Hz). De registerframe wordt op de taakstack opgeslagen, de SP wordt gewisseld en er volgt een iret naar de volgende klaarstaande taak. Er zijn 12 slots met stacks van 512 bytes. In coöperatieve modus switcht de tick niet; een taak draait tot deze afgeeft, slaapt of afsluit, met een watchdog van ~1s tegen runaway-processen.

Muis en Toetsenbord

• Muis: Microsoft seriële muis (IRQ4 / IRQ3), 1200 baud 7N1, pakketten van 3 bytes. De cursor is een pijl met 'save-under', getekend door de muis ISR zelf.
• Toetsenbord: BIOS int 16h, gepolld door de UI-taak.

Lettertype

Maakt gebruik van het eigen 8x8 lettertype uit de VGA ROM, gekopieerd bij boot via int 10h AX=1130h.

Schijven en Bestanden

Gebruikt BIOS int 13h met retries. Contigue clusters worden samengevoegd tot één transfer om overhead te beperken. Taak-switching wordt gepauzeerd tijdens een transfer. Ondersteunt FAT12 en FAT16 op floppies en harde schijfpartities.

Softwarepakketten

Pakketten (.o88) staan op gewone FAT-volumes. Een pakket is een flat binary geassembleerd op org 0 en geladen in een paragraaf-uitgelijnde claim van de heap (eigen adresruimte, één segment per pakket). Er zijn geen relocaties nodig.

• De kernel wordt aangeroepen via een vaste tabel met far-call cells op 0060:0010.
• De kernel roept het pakket terug via een three-byte dispatcher in de header van het pakket.
• Maximale grootte per pakket is 60KB.

Concurrency en Kernel

Er is één tekenmutex (gfx_lock). Background-taken controleren hun zichtbaarheid onder deze lock voordat ze een clip-regio instellen. ISR's draaien met IF=0 en tekenen nooit over een gehouden lock.

De kernel is ongeveer 54KB aan code en data, en in totaal 89.5KB (inclusief buffers, stacks en FAT snapshots). De kernelcode gebruikt het near-model (CS = DS = KERNEL_SEG (0x0060)). Alleen 8086-instructies worden gebruikt; NASM dwingt dit af met cpu 8086.

Geheugenkaart (Memory Map)

Lineair	Segment	Inhoud
0x00600	0060	Kernel: code, data, .bss
Afgeleid	—	Mount-time FAT snapshot
Afgeleid	—	Taakstacks en diskbuffers, gevolgd door stack van taak 0
Afgeleid	—	De claim heap: alles overig, on demand toegewezen
0xA0000	A000	VGA planar framebuffer (80 bytes per rij)

De heap is simpelweg wat int 12h rapporteert minus 91.0KB.

Projectstructuur (Layout)

• SPEC.md: Bindende module-contracten, interfaces en concurrency-regels.
• PERFORMANCE.md: Informatie over de doelmachine (4.77MHz 8088) en kalibratie.
• docs/TESTING.md: Richtlijnen over welk testinstrument te gebruiken.
• docs/MARTYPC-DEBUG.md: Details over de cycle-accurate 5150 debugger.
• docs/KERNEL-MEMORY.md: Specificaties van het geheugenbudget van de kernel.
• docs/HERCULES-TESTING.md: Informatie over testen op Hercules-kaarten.
• boot/boot.asm: Bootsector (512 bytes), LBA → CHS conversie.
• kernel/kernel.asm: Constanten, geheugenladder, bootsequentie en API jump table.
• kernel/*.inc: 34 modules, waaronder vga12 (primitieven), vgabb (renderer), sched (scheduler) en wm (window manager).
• apps/os88api.inc: SDK voor pakketten (API offsets, macros).
• apps/<name>/: De vijftien meegeleverde pakketten.
• drivers/<name>/: Laadbare drivers (.DRV) voor harde schijf, geluid en seriële debugmonitor.
• tests/: Benchmarks en capability gates (niet meegeleverd in standaard build).
• tools/os88pkg.py: Validator/stamper voor pakketten (.bin → .o88).
• tools/os88disk.py: FAT12 image builder.
• tools/kernsize.py: Analyseert het geheugengebruik per module.

Emulatie en Hardwareconfiguraties

Overzicht hardware-targets

Target	Machine	CPU	RAM	Video	Geluid
xt	IBM PC/XT	8088 @ 4.77MHz	256KB	OTI-067 VGA	—
xt-640	XT, 1986 board	8088 @ 4.77MHz	640KB	OTI-067 VGA	—
xt-cga	IBM PC/XT	8088 @ 4.77MHz	256KB	CGA	—
xt-hercules	IBM PC/XT	8088 @ 4.77MHz	256KB	Hercules	—
xt-sound	XT, 1986 board	8088 @ 4.77MHz	640KB	OTI-067 VGA	Sound Blaster 2.0
286	AMI 286 clone	286 @ 12.5MHz	1MB	OTI-067 VGA	—
286-sound	AMI 286 clone	286 @ 12.5MHz	1MB	OTI-067 VGA	Sound Blaster 16
386sx	Shuttle HOT-304	386SX @ 16MHz	2MB	OTI-067 VGA	—
386	Micronics 386	386DX @ 25MHz	2MB	OTI-067 VGA	—
386-sound	Micronics 386	386DX @ 25MHz	2MB	OTI-067 VGA	Sound Blaster 16
486	AMI SiS 471	486DX2 @ 66MHz	8MB	OTI-067 VGA	Sound Blaster 16
pentium	ASUS P/I-P55TP4XE	Pentium P54C @ 133MHz	16MB	OTI-067 VGA	Sound Blaster 16

Schijfgeometrieën

• 1.44MB (18 spt, 2 heads): Voor QEMU boot floppy (A:) en software floppy (B:).
• 720KB (9 spt, 2 heads): Voor 3.5" DD / USB floppy / Gotek.
• 360KB (9 spt, 2 heads): Voor 86Box en echte IBM PC/XT hardware.

Gescripte Tests

Het systeem kan headless worden geboot met een QMP socket op build/qmp.sock. Hiermee kunnen muisbewegingen en toetsaanslagen worden gesimuleerd via Python-scripts (tools/mouse.py en tools/qmp.py).

Beveiliging en Licentie

• Secret Scanning: Om te voorkomen dat credentials in de repository terechtkomen, is er een pre-commit hook (.githooks/pre-commit) die gitleaks uitvoert op staged diffs.
• Licentie: Het project is gelicentieerd onder de MIT-licentie. Er is geen externe code opgenomen in het OS. Gezien het experimentele karakter en het gebruik van AI, wordt de software geleverd zonder enige vorm van garantie.