Skip to main content

Crate saturnus_host

Crate saturnus_host 

Source
Expand description

What every front end of Saturnus needs around the core, with no bindings, no I/O and no threads (it builds for wasm32 like the core): the browser’s wasm bindings (saturnus-web), the desktop app and the CLI’s control API (through saturnus-drive’s runner) all use it.

protocol::Engine is the front end’s protocol (web/protocol.md in the repository) with its pacing, implemented once for every host: it takes commands and the host’s clock, gives replies and events, and says when it wants to be called again. A host only feeds it messages and timer calls.

Emulator owns one Machine and runs it in emulated milliseconds (Emulator::run_ms, Emulator::run_slice); it gives the display as change-detected events (Emulator::frame_if_changed, host::Frame) and reads the user memory straight from RAM (48SX, 48GX, 49G: Emulator::memory_tree, Emulator::stack, Emulator::flags).

  • protocol: commands, replies, events, pacing, sends and the memory watch.
  • host: the key queue that times presses and types letters in emulated time, and the change-detected frame and keys events of the front end’s protocol (web/protocol.md in the repository).
  • typing: typing text into the command line (insert, run, replace) in emulated time.
  • transfer: the writes to the user memory (store, fetch, purge, rename, change directory, flags) as a hidden transaction with the ROM’s Kermit server, in emulated time.
  • layout and skins: each model’s keys in their places and its drawn calculator.
  • romid: ROM identification by SHA-256 (sha256) and size, and the assignment of ROM files to models.

Answers are typed values (serializable where a front end needs them as JSON); failures are the one Error type, shown to the user as its message. The wasm bindings and the native runner convert both to the protocol’s JSON at their own edge.

Modules§

clock
Setting the calculator’s clock (setClock in web/protocol.md) the way its owner would: by its own commands and menus, typed or pressed, never by writing the ROM’s clock in RAM. Which models have a clock, and how each sets it, from the manuals: wiki: hardware/clocks.
host
What a host needs around an Emulator to run it behind the front end’s command/event protocol (web/protocol.md): the key queue that times presses and types letters in emulated time (KeyQueue), the slice runner that feeds it, the change-detected frame and keys events, and the choice of model for a ROM file.
layout
Physical key layouts for drawing a generic keyboard.
menulabels
What the six menu keys show on the 42S, 27S, 17BII, 17B, 19BII and 28S, read from RAM and the LCD without pressing a key (the menu event; the 48SX, 48GX and 49G read theirs in saturnus_objects::softkeys).
protocol
The front end’s protocol (web/protocol.md) and its pacing, once for every host: Engine takes commands and gives replies and events, and runs the machine against a clock the host passes in. It has no clock, timer, thread or I/O of its own; a host is a thin driver around it:
romid
Which calculator a ROM image belongs to, by its content, and which remembered slots a batch of images fills: one set of rules for every host (the Worker through saturnus-web’s identify_rom and plan_roms, the desktop app natively). No I/O, so it builds for wasm32.
sha256
A small SHA-256 (FIPS 180-4) for ROM identification (crate::romid), so no host needs a crypto dependency (it also runs in the browser).
skins
Drawn calculator skins: the case, the display window and every key of a model, with its labels and colours, for the SVG keyboard in web/.
transfer
The hidden Kermit transaction: what changes the calculator’s user memory from outside (storeFile, fetchFile, purge, rename, createDir, changeDir, setFlag, storeText, copy, move, storeScreen, backup in web/protocol.md) goes through the ROM’s own Kermit server, so its memory manager stays consistent; RAM is never written. storeText (the palette’s editor) sends its text as a string variable and has the calculator compile it with a host command (Op::StoreText); storeScreen sends the screen as a GROB under a temporary name and recalls it (Op::StoreScreen).
typing
Typing text into the calculator’s command line by key presses: the engine under insert, run and replace (web/protocol.md).
wire
The emulated serial wire: the calculator’s serial port driven on emulated time only, the one implementation every in-process Kermit host uses (the hidden writes of crate::transfer, which the emulator page, the desktop app and saturnus run step in turns, and saturnus-kermit, which the reference generator and the ROM-gated Kermit tests block on). Wasm-safe: no threads, no I/O, no wall clock (the client’s clock is a fixed start plus emulated time).

Structs§

AnnunciatorFlags
The annunciators serialized as an object of booleans, {leftshift, rightshift, alpha, alert, busy, transmit, updown, battery, g, rad, suspended}: all eleven on every model, in Annunciators::list order.
Emulator
The emulated calculator.
MemoryTree
The current directory and HOME’s tree (Emulator::memory_tree).

Enums§

Error
What went wrong.

Constants§

FRAMEBUFFER_BYTES
Bytes framebuffer() returns on the 131x64 models: one per pixel.

Functions§

pack_pixels
The pixels as one byte per pixel, row-major, 1 = dark.

Type Aliases§

Result
This crate’s result type.