Skip to main content

Crate saturnus_drive

Crate saturnus_drive 

Source
Expand description

Host-side helpers that drive a saturnus_core::Machine in emulated time, shared by the saturnus CLI and the Kermit test host: key scripts (script), the scripted session with its idle wait (session), the per-model boot and Kermit server start (autostart), ROM loading (rom) and its download from hpcalc.org (fetch), the screen as text or PNG (screen), the native hosts’ files (files) and the machine thread that drives the front-end protocol’s state machine (saturnus_host::protocol) for the desktop app and the CLI’s control API (runner) with its auto-saves’ writer thread (save_writer), and the HTTP servers on 127.0.0.1 of the control API and the desktop app’s MCP endpoint, under one set of rules (loopback).

Unlike the core crate this one does file I/O, so it is not meant for wasm32.

Modules§

autostart
Scripted boot and Kermit server start-up, shared by the CLI’s --autostart and the Kermit test host (saturnus-kermit).
fetch
Downloading a known ROM image from hpcalc.org on the user’s machine, for saturnus rom fetch and the desktop app (kb: iterations/iteration-20b-rom-download). Saturnus never hosts or proxies an image; the hosts ask the user first.
files
The native hosts’ files: ROMs and states read with a size cap, and states and settings written whole (a temporary file renamed over the old one). The page never names a file; the desktop app chooses them in dialogs and the CLI takes them on its command line, and keeps the auto-saved states in its data folder (StateDir).
loopback
HTTP servers on 127.0.0.1 under one set of rules (kb: docs/control-api-security): the CLI’s control API (saturnus run --serve) and the desktop app’s MCP endpoint. A per-user bearer token (token), the bounded HTTP/1.1 of http, and the checks and connection budgets every request passes (guard). Binding is to the IPv4 loopback address only (bind); a busy port names its listener (bind_error).
rom
Loading ROM images with a size check. ROMs are never bundled (kb: docs/clean-room-rule); saturnus rom fetch downloads them.
runner
The machine thread of the native hosts: a thin driver around the protocol’s state machine (saturnus_host::protocol::Engine, shared with the Web Worker), which owns the emulator, paces it and answers the front end’s protocol (web/protocol.md). Commands arrive on a channel, events leave through a Sink, replies through each command’s own channel; the thread blocks until the engine’s next deadline or the next command. Two hosts use it: the Tauri app (its window) and saturnus run (the HTTP control API, with the serial bridge as a Hook).
save_writer
The auto-saves of a native host, written off the machine thread (decision log, 2026-10-31). The 49G’s state is about 2.6 MB and StateDir::save writes it whole and fsynced; on the machine thread a key pressed meanwhile waited for the write.
screen
Screen dumps: the text form shared with the oracle diff script, and a 1-bit PNG, to a file or in memory.
script
Key scripts: a small line-based format that drives the keyboard in emulated time. See README.md (“Key scripts”) for the format.
session
Drives a Machine in emulated time: fixed runs, key script actions and the “wait until idle” heuristic.