SparkOS

A lightweight GUI operating system for the AgonLight2 retro computer (eZ80 CPU + ESP32 VDP).

SparkOS boots from the SD card into a desktop environment with a taskbar, launches applications from a file browser, and is designed to survive application crashes without taking down the OS.

Features

• Kernel at 0x040000 with a 64-entry syscall jump table, free-list memory manager (128KB heap), cooperative scheduler with watchdog, component registry with reference counting, message bus, clipboard, and crash handler
• Seven always-resident core libraries in fixed memory slots: font, coco (ESP32-C3 co-processor UART protocol), win (window chrome + PS/2 mouse + keyboard), widget, taskbar, desktop, gui (popup menus, menu bar, scrollbar, file dialog — shared system/app-wide GUI primitives)
• Window system: BeOS-inspired chrome — titlebar with minimize/maximize/close controls, menu bar, content area, footer, scrollbar sliders; apps draw content only
• Single-app model: only one app runs at a time, occupying a 64KB code/BSS/stack slot; kernel_alloc's 128KB heap is what a running app can dynamically grow into (e.g. a text buffer) beyond its own slot. Cooperative multitasking, RAM-checked app launching from .app binaries, full cleanup on exit or crash, and a pending-launch queue so an app can hand off to another app it launches
• File browser with icon/detail views, copy/paste/rename/trash operations, real filesystem root browsing
• Edit: a New/Open/Save/Save As text editor with single-step undo and a windowed/streaming buffer for files larger than available memory (see docs/project-knowledge/memory-management.md for a known unresolved kernel_alloc crash this app currently works around)
• Unified drawing layer (sys/draw.h) — every VDP operation in the system goes through one header (VDU 25 PLOT, VDU 5 text, palette)

Requirements

• Hardware: AgonLight2 (or the Fab Agon Emulator)
• Toolchain: AgDev (ez80-clang) v3.1.0
• Host: Windows (build scripts are PowerShell/make)

The project expects the toolchain and emulator under tools/ (not included in the repository):

tools/AgDev/bin/ez80-clang.exe      AgDev compiler
tools/emulator/fab-agon-emulator.exe  Fab Agon Emulator v1.2.2

Building

.\build-all.ps1            # build all libraries + kernel, verify memory layout, deploy to sdcard\
.\build-all.ps1 -Clean     # clean rebuild

or make deploy — both build in dependency order (libraries → kernel), run the memory-overlap checker (check-overlap.ps1), and copy the binaries into the emulated SD card at sdcard\SparkOS\.

Boot chain: MOS reads sdcard\autoexec.txt → loads /SparkOS/System/Kernel/kernel.bin → kernel initializes subsystems and loads the core libraries.

Memory layout

Range	Contents
0x040000-0x044FFF	Kernel code (syscall table, subsystems)
0x045000-0x049FFF	Kernel BSS
0x04A000-0x05FFFF	Core library slots (font, coco, win, widget, taskbar, desktop, gui)
0x060000-0x06FFFF	The single app slot (64KB) — whichever app is currently running
0x070000-0x08FFFF	Kernel heap (128KB, free-list allocator)
0x090000-0x09BFFF	Unused gap
0x0A0000	Stack top

Every build is gated by an overlap checker that verifies each component's code and BSS stay inside their assigned slot.

Project structure

SparkOS/
  src/            kernel sources (entry ASM, memory, scheduler, registry, msg bus, ...)
  sys/            shared headers: draw.h (VDP primitives), coord.h, colors.h
  libraries/      core libraries, each with its own makefile + fixed slot
  apps/           applications (.app binaries): filebrowser, edit, glyphtest (diagnostic)
sdcard/           emulated SD card contents (deploy target)
.planning/        roadmap, requirements, phase plans, project state
docs/             Agon platform documentation (local copies) + docs/project-knowledge (implementation notes)

Status

Under active development. Phases 1-4 of the original roadmap (kernel, core libraries, desktop, file browser, app launching, window management, crash handling) are complete and verified in the emulator. Beyond the original roadmap, the OS was pivoted from a 4-app-slot model to a single-app model (one app runs at a time, gets far more memory) and gained a second app, Edit — a text editor with streaming support for files larger than available memory. kernel_alloc (the dynamic heap allocator apps use for growable buffers) has a known, currently unresolved crash bug — see docs/project-knowledge/memory-management.md for what's been ruled out. Phase 5 (ESP32-C3 co-processor services, WiFi, ENV preferences, Settings app) has not been started. See .planning/STATE.md and .planning/ROADMAP.md for detailed progress.