saturnus-host 0.12.1

Host-side pieces shared by the Saturnus emulator's front ends: the emulator with its key queue, command-line typing, hidden Kermit transfers, key layouts and skins, ROM identification
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
//! Pacing against the wall clock (`web/protocol.md`, "Pacing"): while the
//! CPU computes or keys are queued, passes run emulated time equal to the
//! elapsed wall time times the speed, dropping what a pass cannot fit into
//! its budget; while it sleeps in SHUTDN with nothing queued, the loop
//! asks to be woken at its next timer event, then runs all the time that
//! passed at 1x (at most [`MAX_BEHIND_MS`]), owing what does not fit the
//! wake's budget to the next passes.
//!
//! [`Loop`] holds that state; it runs a [`Core`] and reads a [`Clock`],
//! and its only output besides the machine's progress is the time it
//! wants to be called again ([`Loop::due`]).

use super::Clock;
use crate::{Emulator, Result};

/// Most emulated time a wake catches up, in ms: 12 hours. Idle time is
/// cheap (the core jumps over SHUTDN; only the ROM's timer ticks run: an
/// idle 48SX hour took 2 ms, 12 hours 9 ms), but owed time the ROM spends
/// awake (an alarm, a running program) is computed for real at the pass
/// budget; the bound keeps a computer that slept for days from paying that
/// off for minutes afterwards.
pub const MAX_BEHIND_MS: f64 = 12.0 * 3600.0 * 1000.0;

/// Longest delay a wake asks for, in ms (a browser timer's limit).
const MAX_DELAY_MS: f64 = 2_147_483_647.0;

/// How a host's pacing is tuned: the rules are the same everywhere, the
/// periods and budgets suit the host's timers. Defined here once for every
/// host ([`Pacing::WORKER`], [`Pacing::NATIVE`]).
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Pacing {
    /// Period of the passes while the CPU computes, in ms.
    pub pass_ms: f64,
    /// Wall time one pass may spend emulating at 1x, 2x and 4x.
    pub pass_budget_ms: f64,
    /// Wall time one pass may spend emulating at "Max".
    pub max_budget_ms: f64,
    /// Emulated ms one pass at "Max" may run at most.
    pub max_emulated_ms: f64,
    /// Longest stretch of wall time one pass makes up for.
    pub max_wall_ms: f64,
    /// Wall time one wake may spend catching up.
    pub wake_budget_ms: f64,
    /// The same while the page is hidden, where no frame waits for it.
    pub hidden_wake_budget_ms: f64,
    /// Shortest time between two `frame` events from passes (0: every
    /// pass may send one).
    pub frame_ms: f64,
    /// Wall time one turn of a send may take before the host serves
    /// other messages.
    pub typing_tick_ms: f64,
    /// Whether a hidden page stops the passes of a computing machine (as
    /// it stops animation frames); a native window keeps computing.
    pub pauses_when_hidden: bool,
    /// How early a host's timer may fire and still count as due, in ms (a
    /// browser truncates timer delays to whole milliseconds).
    pub timer_slack_ms: f64,
}

impl Pacing {
    /// The Web Worker's: passes on a ~60 Hz timer, as animation frames
    /// were, each its own frame.
    pub const WORKER: Pacing = Pacing {
        pass_ms: 1000.0 / 60.0,
        pass_budget_ms: 22.0,
        max_budget_ms: 11.0,
        max_emulated_ms: 1000.0,
        max_wall_ms: 100.0,
        wake_budget_ms: 22.0,
        hidden_wake_budget_ms: 200.0,
        frame_ms: 0.0,
        typing_tick_ms: 40.0,
        pauses_when_hidden: true,
        timer_slack_ms: 1.0,
    };

    /// The native machine thread's (the desktop app, `saturnus run`):
    /// passes every millisecond, so the serial bridge between them sees
    /// the UART at its pace, and frames at most every 16 ms.
    pub const NATIVE: Pacing = Pacing {
        pass_ms: 1.0,
        pass_budget_ms: 4.0,
        max_budget_ms: 11.0,
        max_emulated_ms: 1000.0,
        max_wall_ms: 100.0,
        wake_budget_ms: 22.0,
        hidden_wake_budget_ms: 22.0,
        frame_ms: 16.0,
        typing_tick_ms: 16.0,
        pauses_when_hidden: false,
        timer_slack_ms: 0.0,
    };
}

/// The speed setting (`setSpeed`).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum Speed {
    /// Real time.
    #[default]
    One,
    /// Twice real time.
    Two,
    /// Four times real time.
    Four,
    /// As fast as the host can while staying responsive.
    Max,
}

impl Speed {
    /// The protocol's name: `"1"`, `"2"`, `"4"` or `"max"`; anything else
    /// is real time.
    pub fn parse(s: &str) -> Speed {
        match s {
            "2" => Speed::Two,
            "4" => Speed::Four,
            "max" => Speed::Max,
            _ => Speed::One,
        }
    }

    /// The protocol's name.
    pub fn name(self) -> &'static str {
        match self {
            Speed::One => "1",
            Speed::Two => "2",
            Speed::Four => "4",
            Speed::Max => "max",
        }
    }

    /// Emulated time per wall time while computing (1 at "Max", whose
    /// passes are bounded by budget instead).
    fn factor(self) -> f64 {
        match self {
            Speed::One | Speed::Max => 1.0,
            Speed::Two => 2.0,
            Speed::Four => 4.0,
        }
    }
}

impl serde::Serialize for Speed {
    fn serialize<S: serde::Serializer>(&self, s: S) -> std::result::Result<S::Ok, S::Error> {
        s.serialize_str(self.name())
    }
}

/// What the loop does (the `loop` field of `status` and `stats`).
#[derive(Clone, Copy, Debug, PartialEq, Eq, serde::Serialize)]
#[serde(rename_all = "lowercase")]
pub enum LoopState {
    /// Passes run (the CPU computes or keys are queued).
    Frame,
    /// The CPU sleeps until a timer event.
    Sleep,
    /// Nothing runs (no machine, paused, halted, hidden while computing,
    /// or a send drives the machine).
    Stopped,
}

/// The machine as the loop sees it.
pub(crate) trait Core {
    /// One slice of at most `left_ms` emulated ms, feeding the key queue
    /// if `keys`; the emulated ms run (more than zero).
    fn run_slice(&mut self, left_ms: f64, keys: bool) -> Result<f64>;
    /// Emulated ms the CPU sleeps before its next event; `None` while it
    /// computes.
    fn idle_ms(&self) -> Option<f64>;
    /// Keys are down or queued.
    fn keys_busy(&self) -> bool;
    /// A key the user pressed is still down.
    fn keys_held(&self) -> bool;
    /// CPU cycles since power-on.
    fn cycles(&self) -> u64;
    /// The user memory's change counter.
    fn memory_changes(&self) -> Result<u64>;
}

impl Core for Emulator {
    fn run_slice(&mut self, left_ms: f64, keys: bool) -> Result<f64> {
        Emulator::run_slice(self, left_ms, keys)
    }
    fn idle_ms(&self) -> Option<f64> {
        Emulator::idle_ms(self)
    }
    fn keys_busy(&self) -> bool {
        Emulator::keys_busy(self)
    }
    fn keys_held(&self) -> bool {
        Emulator::keys_held(self)
    }
    fn cycles(&self) -> u64 {
        self.machine().cycles()
    }
    fn memory_changes(&self) -> Result<u64> {
        Emulator::memory_changes(self)
    }
}

/// The CPU sleeps in SHUTDN with no keys queued.
pub(crate) fn asleep(core: &impl Core) -> bool {
    core.idle_ms().is_some() && !core.keys_busy()
}

/// The timer the loop waits for.
#[derive(Clone, Copy, Debug, PartialEq)]
enum Timer {
    /// The next pass, at this time.
    Pass(f64),
    /// The wake from a sleep, at this time.
    Wake(f64),
}

/// The run loop's state.
#[derive(Clone, Debug)]
pub(crate) struct Loop {
    pub pacing: Pacing,
    /// The machine runs (a ROM is booted, not paused, not halted).
    pub running: bool,
    pub speed: Speed,
    /// The page is hidden (only if [`Pacing::pauses_when_hidden`]).
    pub hidden: bool,
    timer: Option<Timer>,
    /// Wall clock up to which the passes accounted for emulated time.
    last_pass: Option<f64>,
    /// Wall clock up to which emulated time is accounted for while asleep.
    slept_at: f64,
    /// Emulated ms owed to wall time: what a wake could not catch up
    /// within its budget. Passes and further wakes run it off first.
    behind_ms: f64,
    /// Wall ms spent emulating.
    pub work_ms: f64,
    /// Passes run.
    pub ticks: u64,
    /// Wakes from a sleep.
    pub wakes: u64,
}

impl Loop {
    pub fn new(pacing: Pacing) -> Loop {
        Loop {
            pacing,
            running: false,
            speed: Speed::One,
            hidden: false,
            timer: None,
            last_pass: None,
            slept_at: 0.0,
            behind_ms: 0.0,
            work_ms: 0.0,
            ticks: 0,
            wakes: 0,
        }
    }

    /// When the loop wants [`Loop::fire`] called, on the host's clock.
    pub fn due(&self) -> Option<f64> {
        match self.timer {
            Some(Timer::Pass(t) | Timer::Wake(t)) => Some(t),
            None => None,
        }
    }

    pub fn state(&self) -> LoopState {
        match self.timer {
            Some(Timer::Pass(_)) => LoopState::Frame,
            Some(Timer::Wake(_)) => LoopState::Sleep,
            None => LoopState::Stopped,
        }
    }

    /// Passes are due (the loop does not stop between them).
    pub fn passing(&self) -> bool {
        matches!(self.timer, Some(Timer::Pass(_)))
    }

    /// The CPU sleeps on a wake timer.
    pub fn sleeping(&self) -> bool {
        matches!(self.timer, Some(Timer::Wake(_)))
    }

    /// Passes stop while the page is hidden.
    fn held(&self) -> bool {
        self.hidden && self.pacing.pauses_when_hidden
    }

    /// Emulated ms owed to the wall clock at `now`: unpaid, plus the
    /// current sleep.
    pub fn owed_ms(&self, now: f64) -> f64 {
        self.behind_ms
            + if self.sleeping() {
                now - self.slept_at
            } else {
                0.0
            }
    }

    /// Emulated ms a wake or pass could not catch up yet.
    pub fn behind_ms(&self) -> f64 {
        self.behind_ms
    }

    /// Stop: no timer, nothing owed.
    pub fn stop(&mut self) {
        self.timer = None;
        self.last_pass = None;
        self.behind_ms = 0.0;
    }

    /// Start after [`Loop::stop`]: a pass at once, or (hidden) the sleep
    /// or nothing.
    pub fn start(&mut self, core: &impl Core, now: f64) {
        if !self.running {
            return;
        }
        if self.held() {
            self.schedule(core, now);
        } else {
            self.timer = Some(Timer::Pass(now));
        }
    }

    /// The page was hidden or shown; `idle` means the loop may start (no
    /// send drives the machine).
    pub fn set_hidden(&mut self, hidden: bool, core: Option<&impl Core>, idle: bool, now: f64) {
        if !self.pacing.pauses_when_hidden {
            return;
        }
        self.hidden = hidden;
        if let Some(core) = core
            && !hidden
            && self.running
            && self.timer.is_none()
            && idle
        {
            self.schedule(core, now);
        }
    }

    /// How fast queued keys run against the wall clock now
    /// ([`crate::clock::Pace`]): the speed, at most the pass's budget
    /// over its period of wall time; at "Max" what a pass may run per
    /// period.
    pub fn clock_pace(&self) -> crate::clock::Pace {
        let p = &self.pacing;
        let (speed, budget) = if self.speed == Speed::Max {
            (p.max_emulated_ms / p.pass_ms, p.max_budget_ms)
        } else {
            (self.speed.factor(), p.pass_budget_ms)
        };
        crate::clock::Pace {
            speed,
            share: (budget / p.pass_ms).min(1.0),
            pass_ms: if self.speed == Speed::Max {
                p.max_emulated_ms
            } else {
                p.pass_ms * speed
            },
        }
    }

    /// Run whichever timer is due at `now`; an error is a halted CPU.
    pub fn fire(&mut self, core: &mut impl Core, clock: &dyn Clock, now: f64) -> Result<()> {
        let slack = self.pacing.timer_slack_ms;
        match self.timer {
            Some(Timer::Pass(t)) if t <= now + slack => self.pass(core, clock),
            Some(Timer::Wake(t)) if t <= now + slack => self.wake(core, clock),
            _ => Ok(()),
        }
    }

    /// Run `ms` emulated ms in slices, feeding the keys if `keys`, within
    /// `budget_ms` of wall time, and only until the CPU sleeps with nothing
    /// queued if `until_sleep`; returns the emulated ms left unrun.
    fn run_slices(
        &mut self,
        core: &mut impl Core,
        clock: &dyn Clock,
        ms: f64,
        budget_ms: f64,
        keys: bool,
        until_sleep: bool,
    ) -> Result<f64> {
        let start = clock.now_ms();
        let mut left = ms;
        let result = (|| {
            // Checked before each slice: a pass that starts asleep runs
            // nothing.
            while left > 0.0 && !(until_sleep && asleep(core)) {
                left -= core.run_slice(left, keys)?;
                if clock.now_ms() - start > budget_ms {
                    break;
                }
            }
            Ok(())
        })();
        self.work_ms += clock.now_ms() - start;
        result.map(|()| left.max(0.0))
    }

    /// One pass while the CPU computes: time owed from a sleep first (wall
    /// time, at 1x), kept until paid; then the pass's own share at the
    /// speed until the CPU sleeps. What does not fit the budget is
    /// dropped; the wall time a sleep left over is the sleep's, at 1x.
    fn pass(&mut self, core: &mut impl Core, clock: &dyn Clock) -> Result<()> {
        self.timer = None;
        let t = clock.now_ms();
        let wall = self
            .last_pass
            .map_or(0.0, |l| (t - l).clamp(0.0, self.pacing.max_wall_ms));
        self.last_pass = Some(t);
        if !self.running {
            return Ok(());
        }
        self.ticks += 1;
        // A key held by the user runs at 1x whatever the speed, so a tap
        // is as short as on the calculator.
        let speed = if core.keys_held() {
            Speed::One
        } else {
            self.speed
        };
        let max = speed == Speed::Max;
        let budget = if max {
            self.pacing.max_budget_ms
        } else {
            self.pacing.pass_budget_ms
        };
        self.behind_ms = self.run_slices(core, clock, self.behind_ms, budget, true, false)?;
        if self.behind_ms == 0.0 {
            let factor = speed.factor();
            let own = if max {
                self.pacing.max_emulated_ms
            } else {
                wall * factor
            };
            let rest = (budget - (clock.now_ms() - t)).max(0.0);
            let left = self.run_slices(core, clock, own, rest, true, true)?;
            if !max && asleep(core) {
                self.last_pass = Some(t - left / factor);
            }
        }
        self.schedule(core, clock.now_ms());
        Ok(())
    }

    /// Keep passing while the CPU computes or keys are queued; once it
    /// sleeps with nothing to do, set the wake timer for its next timer
    /// event instead, so an idle machine costs nothing. Time still owed
    /// brings the wake forward to now.
    pub fn schedule(&mut self, core: &impl Core, now: f64) {
        if !self.running {
            return;
        }
        match core.idle_ms() {
            Some(idle) if !core.keys_busy() => {
                // The last pass or wake accounted for wall time up to
                // `last_pass`. Scheduled again while already asleep (a
                // poke), the sleep keeps its start, or its time is lost.
                if !(self.sleeping() && self.last_pass.is_none()) {
                    self.slept_at = self.last_pass.unwrap_or(now);
                }
                self.last_pass = None;
                // Asleep, emulated time runs at 1x at any speed.
                let delay = if self.behind_ms > 0.0 {
                    0.0
                } else {
                    idle.min(MAX_DELAY_MS) + 1.0
                };
                self.timer = Some(Timer::Wake(now + delay));
            }
            _ => {
                if !self.passing() && !self.held() {
                    let due = self
                        .last_pass
                        .map_or(now, |l| (l + self.pacing.pass_ms).max(now));
                    self.timer = Some(Timer::Pass(due));
                }
            }
        }
    }

    /// Leave the sleep: run all the emulated time that passed meanwhile
    /// (cheap while the CPU sleeps), however late the timer fired. What
    /// does not fit the budget, as when the ROM wakes up and computes,
    /// stays owed for the next pass or wake. Nothing if not asleep.
    pub fn wake(&mut self, core: &mut impl Core, clock: &dyn Clock) -> Result<()> {
        if !self.running || !self.sleeping() {
            return Ok(());
        }
        self.timer = None;
        self.wakes += 1;
        let now = clock.now_ms();
        self.behind_ms = (self.behind_ms + (now - self.slept_at)).min(MAX_BEHIND_MS);
        let budget = if self.hidden {
            self.pacing.hidden_wake_budget_ms
        } else {
            self.pacing.wake_budget_ms
        };
        // A key that woke the machine goes down after the time that passed.
        self.behind_ms = self.run_slices(core, clock, self.behind_ms, budget, false, false)?;
        self.last_pass = Some(now);
        // The ROM may have woken for a timer event and redrawn (the
        // clock), then gone back to sleep: sleep on without a pass.
        self.schedule(core, clock.now_ms());
        Ok(())
    }
}