mod autosave;
mod command;
mod pacing;
mod recover;
mod watch;
#[cfg(test)]
mod tests;
pub use autosave::DELAY_MS as AUTO_SAVE_MS;
pub use command::{CommandKind, HttpEndpoint, Policy};
pub use pacing::{LoopState, MAX_BEHIND_MS, Pacing, Speed};
pub use watch::{EVENT_MS as MEMORY_EVENT_MS, LOOK_MS as MEMORY_LOOK_MS};
use saturnus_core::{Machine, Model};
use serde::Serialize;
use serde_json::{Value, json};
use crate::host::{Frame, KeysDown, base64_decode, model_for_rom};
use crate::transfer::{MAX_FILE_BYTES, Op, Target};
use crate::{Emulator, Error, Result};
use autosave::AutoSave;
use pacing::Loop;
use recover::{Recover, Step};
use watch::Watch;
pub const VERSION: u64 = 1;
pub const MAX_STATE_BYTES: usize = 4 * 1024 * 1024;
pub const TYPING_STEP_MS: f64 = 20.0;
pub const WALL_LIMIT_MS: f64 = 30_000.0;
const WAIT_END_STEPS: usize = 64;
pub const MAX_SERIAL_PENDING: usize = 16 * 1024;
pub const SERIAL_IN_USE: &str = "the serial port is in use (serialClose frees it)";
pub const SERIAL_EVENT_MS: f64 = 10.0;
pub trait Clock {
fn now_ms(&self) -> f64;
}
#[derive(Clone, Debug, PartialEq, Serialize)]
#[serde(tag = "type", rename = "status", rename_all = "camelCase")]
pub struct Status {
pub model: Option<&'static str>,
pub rom_name: String,
pub running: bool,
pub halted: Option<String>,
pub speed: Speed,
#[serde(rename = "loop")]
pub loop_state: LoopState,
pub busy: bool,
pub starting: bool,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
#[serde(tag = "type", rename = "error")]
pub struct ErrorEvent {
pub message: String,
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
#[serde(tag = "type", rename = "memoryChanged")]
pub struct MemoryChanged {}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
#[serde(tag = "type", rename = "serial")]
pub struct SerialEvent {
#[serde(serialize_with = "crate::host::as_base64")]
pub bytes: Vec<u8>,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
#[serde(untagged)]
pub enum Event {
Serial(SerialEvent),
Frame(Frame),
Keys(KeysDown),
Status(Status),
Error(ErrorEvent),
MemoryChanged(MemoryChanged),
Menu(crate::host::MenuKeys),
}
#[derive(Clone, Debug, PartialEq)]
pub struct Reply {
pub tag: u64,
pub result: std::result::Result<Value, String>,
pub bytes: Option<(&'static str, Vec<u8>)>,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Saved {
pub model: &'static str,
pub rom_name: String,
pub cycles: u64,
pub state: Vec<u8>,
}
#[derive(Clone, Debug, PartialEq)]
pub enum Output {
Event(Event),
Reply(Reply),
Save(Saved),
}
#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Booted {
pub model: &'static str,
pub rom_name: String,
#[serde(skip_serializing_if = "std::ops::Not::not")]
pub restored: bool,
#[serde(skip_serializing_if = "Option::is_none")]
pub restore_error: Option<String>,
}
#[derive(Clone, Debug, PartialEq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct Stats {
pub cycles: u64,
pub emulated_ms: f64,
pub work_ms: f64,
pub ticks: u64,
pub wakes: u64,
pub memory_looks: u64,
pub memory_ms: f64,
#[serde(rename = "loop")]
pub loop_state: LoopState,
pub owed_ms: f64,
pub now_ms: f64,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct RunError {
pub message: String,
pub halted: bool,
}
#[derive(Clone, Debug, Default)]
struct SerialOut {
held: Vec<u8>,
last: Option<f64>,
}
impl SerialOut {
fn take(&mut self, t: f64, slack: f64, now: bool) -> Option<Vec<u8>> {
if self.held.is_empty()
|| (!now && self.last.is_some_and(|l| t + slack < l + SERIAL_EVENT_MS))
{
return None;
}
self.last = Some(t);
Some(std::mem::take(&mut self.held))
}
fn due(&self) -> Option<f64> {
(!self.held.is_empty()).then(|| self.last.map_or(0.0, |l| l + SERIAL_EVENT_MS))
}
}
#[derive(Clone, Debug)]
struct Send {
tag: Option<u64>,
freezes: bool,
transfer: bool,
started: f64,
due: f64,
stopping: Option<Error>,
waiting: Option<Waiting>,
}
#[derive(Clone, Debug)]
enum Waiting {
Typing(String, String),
Transfer(Op),
}
#[derive(Debug)]
pub struct Engine {
host: &'static str,
emu: Option<Emulator>,
model: Option<Model>,
rom_name: String,
halted: Option<String>,
lp: Loop,
watch: Watch,
send: Option<Send>,
out: Vec<Output>,
last_status: Option<Status>,
last_frame: Option<f64>,
autosave: AutoSave,
answer_recover: bool,
recover: Option<Recover>,
serial: bool,
serial_out: SerialOut,
}
enum Look {
Wait,
GiveUp,
Answer(Option<Recover>),
}
fn look(e: &Emulator, r: Recover) -> Look {
if e.emulated_ms() > r.until_ms {
return Look::GiveUp;
}
let rows = &e.machine().framebuffer().pixels.pixels;
match r.step {
Step::Prompt if recover::is_prompt(rows) => {
Look::Answer((e.model() == Model::Hp49g).then(|| Recover {
step: Step::Dismiss,
until_ms: e.emulated_ms() + recover::DISMISS_WAIT_MS,
}))
}
Step::Dismiss if recover::is_memory_clear(rows) => Look::Answer(None),
_ => Look::Wait,
}
}
fn answer_boot(e: &mut Emulator, recover: &mut Option<Recover>) -> Result<bool> {
if pacing::asleep(e) {
match recover.map(|r| look(e, r)) {
None => return Ok(true),
Some(Look::Wait) => {}
Some(Look::GiveUp) => *recover = None,
Some(Look::Answer(next)) => {
e.type_keys("f");
*recover = next;
}
}
}
e.run_slice(TYPING_STEP_MS, true)?;
Ok(false)
}
fn str_field<'a>(msg: &'a Value, name: &str) -> Result<&'a str> {
msg.get(name)
.and_then(Value::as_str)
.ok_or_else(|| format!("missing string field {name:?}").into())
}
fn text_field(msg: &Value) -> Result<String> {
let text = str_field(msg, "text")?;
Ok(if msg.get("codes").and_then(Value::as_bool) == Some(true) {
saturnus_objects::charset::from_trigraphs(text)
} else {
text.to_string()
})
}
fn value_of<T: Serialize>(v: &T) -> Result<Value> {
serde_json::to_value(v).map_err(|e| e.to_string().into())
}
fn unknown_key(e: &Emulator, key: &str) -> Error {
format!("no key {key:?} on the {}", e.model().name()).into()
}
enum Answer {
Now(Value, Option<(&'static str, Vec<u8>)>),
Later,
}
impl From<Value> for Answer {
fn from(v: Value) -> Self {
Answer::Now(v, None)
}
}
impl Engine {
pub fn new(host: &'static str, pacing: Pacing) -> Engine {
Engine {
host,
emu: None,
model: None,
rom_name: String::new(),
halted: None,
lp: Loop::new(pacing),
watch: Watch::default(),
send: None,
out: Vec::new(),
last_status: None,
last_frame: None,
autosave: AutoSave::default(),
answer_recover: false,
recover: None,
serial: false,
serial_out: SerialOut::default(),
}
}
pub fn set_answer_recover(&mut self, on: bool) {
self.answer_recover = on;
if !on {
self.recover = None;
}
}
pub fn answering_recover(&self) -> bool {
self.recover.is_some()
}
pub fn set_auto_save(&mut self, on: bool) {
self.autosave.on = on;
if !on {
self.autosave.clear();
}
}
pub fn auto_saves(&self) -> u64 {
self.autosave.saves
}
pub fn save_owed(&self) -> bool {
self.autosave.owed()
}
pub fn save_now(&mut self) {
if self.autosave.owed() && self.settled() {
self.emit_save();
}
}
pub fn admit<'a>(&self, msg: &'a Value) -> Result<&'a str> {
match msg.get("v") {
Some(v) if v.as_u64() == Some(VERSION) => {}
Some(v) => {
return Err(format!(
"protocol version {v} not supported (this host speaks {VERSION})"
)
.into());
}
None => {
return Err(
format!("protocol version missing (this host speaks {VERSION})").into(),
);
}
}
let cmd = str_field(msg, "cmd")?;
match self.refusal(cmd) {
Some(e) => Err(e),
None => Ok(cmd),
}
}
pub fn refusal(&self, cmd: &str) -> Option<Error> {
let policy = cmd.parse::<CommandKind>().ok()?.policy();
if self.serial && (policy.write || policy.server) {
return Some(SERIAL_IN_USE.into());
}
let send = self.send.as_ref()?;
let refused = policy.refused_while_typing || (send.transfer && policy.serial);
refused.then(|| {
if send.transfer {
"a transfer is in progress (releaseAll stops it)".into()
} else {
"typing is in progress (releaseAll stops it)".into()
}
})
}
pub fn command(
&mut self,
clock: &dyn Clock,
msg: &Value,
bytes: Option<Vec<u8>>,
reply: Option<u64>,
) {
let answer = self
.admit(msg)
.and_then(|cmd| self.handle(clock, cmd, msg, bytes, reply));
match answer {
Ok(Answer::Later) => self.flush(clock, true),
Ok(Answer::Now(v, b)) => self.respond(clock, reply, Ok(v), b),
Err(e) => self.respond(clock, reply, Err(e), None),
}
}
pub fn answer(&mut self, clock: &dyn Clock, reply: Option<u64>, result: Result<Value>) {
self.respond(clock, reply, result, None);
}
fn respond(
&mut self,
clock: &dyn Clock,
reply: Option<u64>,
result: Result<Value>,
bytes: Option<(&'static str, Vec<u8>)>,
) {
self.flush(clock, true);
self.reply_to(reply, result, bytes);
}
fn reply_to(
&mut self,
reply: Option<u64>,
result: Result<Value>,
bytes: Option<(&'static str, Vec<u8>)>,
) {
match (reply, result) {
(Some(tag), result) => self.out.push(Output::Reply(Reply {
tag,
result: result.map_err(|e| e.to_string()),
bytes,
})),
(None, Err(e)) => self.event(Event::Error(ErrorEvent {
message: e.to_string(),
})),
(None, Ok(_)) => {}
}
}
fn event(&mut self, e: Event) {
self.out.push(Output::Event(e));
}
pub fn take_output(&mut self) -> Vec<Output> {
std::mem::take(&mut self.out)
}
pub fn deadline(&self) -> Option<f64> {
[
self.send.as_ref().map(|s| s.due),
self.lp.due(),
self.watch.due,
self.serial_out.due(),
self.settled().then(|| self.autosave.due()).flatten(),
]
.into_iter()
.flatten()
.reduce(f64::min)
}
pub fn timer(&mut self, clock: &dyn Clock) {
let now = clock.now_ms();
let slack = self.lp.pacing.timer_slack_ms;
if self.send.as_ref().is_some_and(|s| s.due <= now + slack) {
self.typing_turn(clock);
}
if let Some(e) = self.emu.as_mut()
&& let Err(err) = self.lp.fire(e, clock, now)
{
self.halt(clock, err);
}
if self.watch.due.is_some_and(|d| d <= now + slack) {
self.watch.due = None;
}
self.flush(clock, !self.lp.passing());
self.poll_recover(clock);
}
fn poll_recover(&mut self, clock: &dyn Clock) {
let Some(r) = self.recover else {
return;
};
if !self.settled() {
return;
}
let Some(e) = self.emu.as_mut() else {
self.recover = None;
return;
};
match look(e, r) {
Look::Wait => {}
Look::GiveUp => self.recover = None,
Look::Answer(next) => {
e.type_keys("f");
self.recover = next;
self.after_keys(clock);
}
}
}
pub fn input(&mut self, clock: &dyn Clock) {
self.autosave.touch(clock.now_ms());
if self.lp.sleeping() {
self.wake(clock);
self.flush(clock, !self.lp.passing());
}
}
pub fn serial_open(&self) -> bool {
self.serial
}
fn close_serial(&mut self) {
self.serial_out = SerialOut::default();
if std::mem::take(&mut self.serial)
&& let Some(e) = self.emu.as_mut()
{
let m = e.machine_mut();
m.serial_clear_inbound();
m.serial_drain();
}
}
pub fn transferring(&self) -> bool {
self.send.as_ref().is_some_and(|s| s.transfer)
}
pub fn sending(&self) -> Option<u64> {
self.send.as_ref().and_then(|s| s.tag)
}
pub fn cancel_send(&mut self, clock: &dyn Clock, why: &str) {
if self.send.is_some() {
self.end_typing(clock, Some(why.into()));
}
}
pub fn status(&self) -> Status {
Status {
model: self.model.map(Model::name),
rom_name: self.rom_name.clone(),
running: self.lp.running,
halted: self.halted.clone(),
speed: self.lp.speed,
loop_state: self.lp.state(),
busy: self.send.as_ref().is_some_and(|s| s.freezes),
starting: self.recover.is_some() && self.lp.running && self.halted.is_none(),
}
}
pub fn emulator_mut(&mut self) -> Option<&mut Emulator> {
self.emu.as_mut()
}
pub fn emulator(&self) -> Result<&Emulator> {
self.emu.as_ref().ok_or_else(|| "no ROM loaded".into())
}
pub fn into_emulator(self) -> Option<Emulator> {
self.emu
}
pub fn start(&mut self, clock: &dyn Clock, emu: Emulator, rom_name: &str) {
self.serial = false;
self.serial_out = SerialOut::default();
self.model = Some(emu.model());
self.emu = Some(emu);
self.rom_name = rom_name.to_string();
self.recover = None;
self.halted = None;
self.watch.force = true;
self.autosave.clear();
self.set_running(clock, true);
self.flush(clock, true);
}
pub fn poke(&mut self, clock: &dyn Clock, address: u32, nibbles: &[u8]) -> Result<()> {
if let Some(e) = self.refusal("poke") {
return Err(e);
}
let e = self.emu.as_mut().ok_or("no ROM loaded")?;
self.recover = None;
for (a, &n) in (address..).zip(nibbles) {
e.machine_mut().poke(a, n);
}
e.reshow();
self.watch.force = true;
if self.send.is_none() {
self.lp.schedule(&*e, clock.now_ms());
}
self.autosave.touch(clock.now_ms());
Ok(())
}
pub fn exclusive<T>(
&mut self,
clock: &dyn Clock,
f: impl FnOnce(Machine) -> (Machine, std::result::Result<T, RunError>),
) -> Result<T> {
if let Some(e) = self.refusal("keyScript") {
return Err(e);
}
self.wake_running(clock)?;
let mut emu = self.emu.take().ok_or("no ROM loaded")?;
emu.release_keys();
self.recover = None;
let start = clock.now_ms();
let (machine, result) = f(emu.into_machine());
self.lp.work_ms += clock.now_ms() - start;
self.emu = Some(Emulator::from_machine(machine));
self.autosave.touch(clock.now_ms());
match result {
Ok(t) => {
self.set_running(clock, self.lp.running);
Ok(t)
}
Err(e) => {
if e.halted {
self.halted = Some(e.message.clone());
self.set_running(clock, false);
} else {
self.set_running(clock, self.lp.running);
}
Err(e.message.into())
}
}
}
pub fn boot(
&mut self,
clock: &dyn Clock,
model: &str,
rom: &[u8],
rom_name: &str,
) -> Result<Booted> {
self.boot_restoring(clock, model, rom, rom_name, None)
}
pub fn boot_restoring(
&mut self,
clock: &dyn Clock,
model: &str,
rom: &[u8],
rom_name: &str,
kept: Option<&[u8]>,
) -> Result<Booted> {
if let Some(e) = self.refusal("boot") {
return Err(e);
}
let model = model_for_rom(rom, model.parse()?);
let mut emu = Emulator::new(model, rom)?;
let mut restored = false;
let mut restore_error = None;
if let Some(state) = kept {
if state.len() > MAX_STATE_BYTES {
restore_error = Some(format!("state is larger than {MAX_STATE_BYTES} bytes"));
} else {
match emu.load_state(state) {
Ok(()) => restored = true,
Err(e) => restore_error = Some(e.to_string()),
}
}
}
self.recover =
(self.answer_recover && !restored && recover::asks(model)).then(|| Recover {
step: Step::Prompt,
until_ms: emu.emulated_ms() + recover::PROMPT_WAIT_MS,
});
self.serial = false;
self.serial_out = SerialOut::default();
self.emu = Some(emu);
self.model = Some(model);
self.rom_name = rom_name.to_string();
self.halted = None;
self.watch.force = true;
self.autosave.clear();
self.set_running(clock, true);
self.flush(clock, true);
Ok(Booted {
model: model.name(),
rom_name: self.rom_name.clone(),
restored,
restore_error,
})
}
pub fn save_state(&self) -> Result<Vec<u8>> {
if let Some(e) = self.refusal("saveState") {
return Err(e);
}
Ok(self.emulator()?.save_state())
}
pub fn load_state(&mut self, clock: &dyn Clock, state: &[u8]) -> Result<()> {
if let Some(e) = self.refusal("loadState") {
return Err(e);
}
if state.len() > MAX_STATE_BYTES {
return Err(format!("state is larger than {MAX_STATE_BYTES} bytes").into());
}
let e = self.emu.as_mut().ok_or("no ROM loaded")?;
e.load_state(state)?;
e.reshow();
self.recover = None;
self.halted = None;
self.watch.force = true;
self.autosave.touch(clock.now_ms());
self.set_running(clock, self.lp.running);
self.flush(clock, true);
Ok(())
}
pub fn stats(&self, clock: &dyn Clock) -> Stats {
let now = clock.now_ms();
Stats {
cycles: self.emu.as_ref().map_or(0, |e| e.machine().cycles()),
emulated_ms: self.emu.as_ref().map_or(0.0, Emulator::emulated_ms),
work_ms: self.lp.work_ms,
ticks: self.lp.ticks,
wakes: self.lp.wakes,
memory_looks: self.watch.looks,
memory_ms: self.watch.spent_ms,
loop_state: self.lp.state(),
owed_ms: self.lp.owed_ms(now),
now_ms: now,
}
}
fn emu(&mut self) -> Result<&mut Emulator> {
self.emu.as_mut().ok_or_else(|| "no ROM loaded".into())
}
fn handle(
&mut self,
clock: &dyn Clock,
cmd: &str,
msg: &Value,
bytes: Option<Vec<u8>>,
reply: Option<u64>,
) -> Result<Answer> {
let kind: CommandKind = cmd.parse()?;
use CommandKind as C;
if matches!(kind, C::KeyDown | C::TypeLetter | C::TypeKeys) {
self.recover = None;
}
Ok(match kind {
C::Hello => {
self.last_status = None;
self.watch.on = false;
self.close_serial();
if let Some(e) = self.emu.as_mut() {
e.reshow();
}
let models: Vec<&str> = crate::skins::hosted_models().map(|m| m.name()).collect();
json!({
"protocol": VERSION,
"host": self.host,
"models": models,
"version": env!("CARGO_PKG_VERSION"),
})
.into()
}
C::Skin => {
let m: Model = str_field(msg, "model")?.parse()?;
let view = crate::skins::skin_view(m)
.ok_or_else(|| format!("no drawn keyboard for the {} yet", m.name()))?;
value_of(&view)?.into()
}
C::Layout => {
let m: Model = str_field(msg, "model")?.parse()?;
value_of(&crate::layout::grid(m))?.into()
}
C::Boot => {
let model = str_field(msg, "model")?;
let rom = bytes.ok_or("missing bytes field \"rom\"")?;
let name = msg.get("romName").and_then(Value::as_str).unwrap_or("");
value_of(&self.boot(clock, model, &rom, name)?)?.into()
}
C::KeyDown => {
let key = str_field(msg, "key")?;
let shift = msg.get("shift").and_then(Value::as_str);
let e = self.emu()?;
let queued = match shift {
None => e.press(key),
Some(shift) => {
if !e.has_key(shift) {
return Err(unknown_key(e, shift));
}
e.press_shifted(key, shift)
}
};
if !queued {
if let Some(shift) = shift.filter(|_| e.has_key(key)) {
return Err(format!("{shift:?} is not a shift key").into());
}
return Err(unknown_key(e, key));
}
self.autosave.touch(clock.now_ms());
self.after_keys(clock);
Value::Null.into()
}
C::KeyUp => {
let key = str_field(msg, "key")?;
let e = self.emu()?;
if !e.has_key(key) {
return Err(unknown_key(e, key));
}
e.release(key);
e.pump();
self.autosave.touch(clock.now_ms());
Value::Null.into()
}
C::KeyUpAll => {
if self.send.is_none()
&& let Some(e) = self.emu.as_mut()
{
e.release_held();
e.pump();
}
Value::Null.into()
}
C::TypeLetter => {
let letter = str_field(msg, "letter")?;
let Some(e) = self.emu.as_mut() else {
return Ok(Value::Bool(false).into());
};
let ok = e.type_letter(letter);
self.autosave.touch(clock.now_ms());
self.after_keys(clock);
Value::Bool(ok).into()
}
C::TypeKeys => {
let keys = msg
.get("keys")
.and_then(Value::as_array)
.ok_or("missing array field \"keys\"")?;
if keys.len() > crate::typing::MAX_CHARS {
return Err(format!(
"\"keys\" holds more than {} keys",
crate::typing::MAX_CHARS
)
.into());
}
let keys: Vec<&str> = keys
.iter()
.map(Value::as_str)
.collect::<Option<_>>()
.ok_or("\"keys\" must hold key names (strings)")?;
let e = self.emu()?;
if let Some(k) = keys.iter().find(|k| !e.has_key(k)) {
return Err(unknown_key(e, k));
}
e.queue().type_keys(&keys);
self.autosave.touch(clock.now_ms());
self.after_keys(clock);
Value::Null.into()
}
C::ReleaseAll => {
self.cancel_send(clock, "cancelled");
if let Some(e) = self.emu.as_mut() {
e.release_keys();
}
Value::Null.into()
}
C::SetSpeed => {
self.lp.speed = Speed::parse(str_field(msg, "speed")?);
Value::Null.into()
}
C::Pause => {
let paused = msg.get("paused").and_then(Value::as_bool).unwrap_or(true);
self.set_running(clock, !paused);
Value::Null.into()
}
C::Unload => {
if self.autosave.owed() {
self.emit_save();
}
self.serial = false;
self.serial_out = SerialOut::default();
self.emu = None;
self.model = None;
self.rom_name.clear();
self.halted = None;
self.recover = None;
self.watch.on = false;
self.autosave.clear();
self.set_running(clock, false);
self.send_status();
Value::Null.into()
}
C::Reset => {
self.recover = None;
let e = self.emu()?;
e.release_keys();
e.reset();
self.halted = None;
self.autosave.touch(clock.now_ms());
self.set_running(clock, true);
Value::Null.into()
}
C::SaveState => {
let state = self.save_state()?;
let cycles = self.emulator()?.machine().cycles();
Answer::Now(json!({"cycles": cycles}), Some(("state", state)))
}
C::LoadState => {
let state = match bytes {
Some(b) => b,
None => {
let b64 = str_field(msg, "state")?;
if b64.len() > MAX_STATE_BYTES.div_ceil(3) * 4 {
return Err(
format!("state is larger than {MAX_STATE_BYTES} bytes").into()
);
}
base64_decode(b64).map_err(|e| format!("state: {e}"))?
}
};
self.load_state(clock, &state)?;
json!({}).into()
}
C::Visibility => {
let hidden = msg.get("hidden").and_then(Value::as_bool).unwrap_or(false);
if hidden {
self.autosave.hide();
}
let idle = self.send.is_none();
self.lp
.set_hidden(hidden, self.emu.as_ref(), idle, clock.now_ms());
Value::Null.into()
}
C::Stats => value_of(&self.stats(clock))?.into(),
C::WatchMemory => {
let on = msg.get("on").and_then(Value::as_bool).unwrap_or(false);
self.watch.subscribe(on, self.emu.as_ref());
let Some(e) = &self.emu else {
return Ok(json!({"supported": null, "reason": null}).into());
};
let reason = e.memory_refusal();
json!({"supported": reason.is_none(), "reason": reason}).into()
}
C::MemoryTree => value_of(&self.emu()?.memory_tree()?)?.into(),
C::Stack => Value::Array(self.emu()?.stack()?).into(),
C::StackTop => self.emu()?.stack_top()?.into(),
C::Flags => value_of(&self.emu()?.flags()?)?.into(),
C::ObjectAt => {
let address = msg
.get("address")
.and_then(Value::as_u64)
.ok_or("missing number field \"address\"")?;
let address = u32::try_from(address)
.ok()
.filter(|&a| a <= 0xF_FFFF)
.ok_or("address is outside the address space")?;
self.emu()?.object_at(address)?.into()
}
C::CommandLine => value_of(&self.emu()?.command_line()?)?.into(),
C::EntryModes => value_of(&crate::typing::entry_modes(self.emu()?.machine())?)?.into(),
C::UiState => value_of(&self.emu()?.ui_state()?)?.into(),
C::SerialOpen => {
let serial = self.serial;
let e = self.emu()?;
if !e.machine().has_serial() {
return Err(format!(
"the {} has no serial port",
e.model().name().to_uppercase()
)
.into());
}
if !serial {
e.machine_mut().serial_drain();
self.serial = true;
}
Value::Null.into()
}
C::SerialWrite => {
self.emu()?;
if !self.serial {
return Err("the serial port is not open (serialOpen first)".into());
}
let too_many =
|| format!("more than {MAX_SERIAL_PENDING} bytes for the serial port");
let data = match bytes {
Some(b) => b,
None => {
let b64 = str_field(msg, "bytes")?;
if b64.len() > MAX_SERIAL_PENDING.div_ceil(3) * 4 {
return Err(too_many().into());
}
base64_decode(b64).map_err(|e| format!("bytes: {e}"))?
}
};
if data.len() > MAX_SERIAL_PENDING {
return Err(too_many().into());
}
let m = self.emu()?.machine_mut();
let waiting = m.serial_pending();
if waiting + data.len() > MAX_SERIAL_PENDING {
return Err(format!(
"the serial port's input is full ({waiting} bytes still waiting)"
)
.into());
}
m.serial_push(&data);
self.input(clock);
Value::Null.into()
}
C::SerialClose => {
self.close_serial();
Value::Null.into()
}
C::EditText => {
let (dir, target) = self.text_target(msg)?;
let (text, was) = self.emu()?.edit_text(&dir, &target)?;
json!({"text": text, "was": was}).into()
}
C::Insert | C::TypeText => self.start_typing(clock, "insert", msg, reply)?,
C::Run => self.start_typing(clock, "run", msg, reply)?,
C::ProbeServer | C::EndServer => {
let m = self.emu()?.machine();
if !crate::transfer::may_serve(m) && m.has_serial() {
return Ok(json!({"server": false, "emulatedMs": 0.0, "keys": false}).into());
}
let op = Op::Server {
end: kind == C::EndServer,
};
self.start_transfer(clock, op, reply)?
}
C::StoreFile
| C::FetchFile
| C::Purge
| C::Rename
| C::CreateDir
| C::ChangeDir
| C::SetFlag
| C::Copy
| C::Move
| C::StoreScreen
| C::StoreText
| C::Backup => {
let op = self.write_op(kind, msg, bytes)?;
self.start_transfer(clock, op, reply)?
}
C::Replace => self.start_typing(clock, "replace", msg, reply)?,
C::SetClock => self.set_clock(clock, msg, reply)?,
C::Screen
| C::Info
| C::Model
| C::Peek
| C::Poke
| C::KeyScript
| C::StateSlot
| C::OpenState
| C::SaveFile
| C::RomSlots
| C::BootModel
| C::ChooseRom
| C::DownloadRom
| C::ForgetRom
| C::RomSettings
| C::Join
| C::Ping
| C::Attach
| C::Leave => return Err(format!("unknown command {cmd:?}").into()),
})
}
fn after_keys(&mut self, clock: &dyn Clock) {
self.wake(clock);
if let Some(e) = self.emu.as_mut() {
e.pump();
}
}
fn wake(&mut self, clock: &dyn Clock) {
if let Some(e) = self.emu.as_mut()
&& let Err(err) = self.lp.wake(e, clock)
{
self.halt(clock, err);
}
}
fn wake_running(&mut self, clock: &dyn Clock) -> Result<()> {
if self.halted.is_none() {
self.wake(clock);
}
match &self.halted {
Some(h) => Err(format!("the CPU is halted: {h}").into()),
None => Ok(()),
}
}
fn halt(&mut self, clock: &dyn Clock, err: Error) {
self.halted = Some(err.to_string());
self.set_running(clock, false);
}
fn set_running(&mut self, clock: &dyn Clock, on: bool) {
self.lp.running = on && self.emu.is_some() && self.halted.is_none();
self.lp.stop();
if self.send.is_some() {
return;
}
if let Some(e) = &self.emu {
self.lp.start(e, clock.now_ms());
}
}
fn start_typing(
&mut self,
clock: &dyn Clock,
verb: &str,
msg: &Value,
reply: Option<u64>,
) -> Result<Answer> {
let text = &text_field(msg)?;
self.emu()?;
self.wake_running(clock)?;
let waiting = self.recover.is_some() && self.lp.running;
let freezes = if waiting {
self.emu()?.check_typing(verb, text)?
} else {
self.emu()?.start_typing(verb, text)?
};
self.lp.stop();
let now = clock.now_ms();
self.autosave.touch(now);
self.send = Some(Send {
tag: reply,
freezes,
transfer: false,
started: now,
due: now,
stopping: None,
waiting: waiting.then(|| Waiting::Typing(verb.to_string(), text.to_string())),
});
Ok(Answer::Later)
}
fn write_op(&mut self, cmd: CommandKind, msg: &Value, bytes: Option<Vec<u8>>) -> Result<Op> {
let given = match msg.get("dir") {
None | Some(Value::Null) => None,
Some(v) => Some(
v.as_array()
.and_then(|a| {
a.iter()
.map(|s| s.as_str().map(str::to_string))
.collect::<Option<Vec<_>>>()
})
.ok_or("\"dir\" must be an array of directory names")?,
),
};
let name = || str_field(msg, "name").map(str::to_string);
let dir = Vec::new();
if cmd == CommandKind::StoreText {
let text = text_field(msg)?;
let (dir, target) = self.text_target(msg)?;
if let Some(was) = msg.get("was").and_then(Value::as_str) {
self.emu()?.check_unchanged(&dir, &target, was)?;
}
return Ok(Op::StoreText { dir, target, text });
}
if cmd == CommandKind::StoreScreen {
let name = match msg.get("name") {
None | Some(Value::Null) => None,
Some(_) => Some(name()?),
};
let screen = self.screen_of(msg)?;
let dir = match (given, &name) {
(Some(d), _) => d,
(None, Some(_)) => self.emu()?.memory_tree()?.path,
(None, None) => Vec::new(),
};
return Ok(Op::StoreScreen {
dir,
name,
replace: msg.get("replace").and_then(Value::as_bool).unwrap_or(false),
screen,
});
}
if cmd == CommandKind::Backup {
return Ok(Op::Backup);
}
let mut op = match cmd {
CommandKind::StoreFile => {
let data = match bytes {
Some(b) => b,
None => {
let b64 = str_field(msg, "data")?;
if b64.len() > MAX_FILE_BYTES.div_ceil(3) * 4 {
return Err(
format!("the file is larger than {MAX_FILE_BYTES} bytes").into()
);
}
base64_decode(b64).map_err(|e| format!("data: {e}"))?
}
};
Op::Store {
dir,
name: name()?,
data,
replace: msg.get("replace").and_then(Value::as_bool),
}
}
CommandKind::FetchFile => Op::Fetch {
dir,
name: name()?,
text: msg.get("text").and_then(Value::as_bool).unwrap_or(false),
},
CommandKind::Purge => Op::Purge { dir, name: name()? },
CommandKind::Rename => Op::Rename {
dir,
name: name()?,
to: str_field(msg, "to")?.to_string(),
},
CommandKind::CreateDir => Op::CreateDir { dir, name: name()? },
CommandKind::Copy | CommandKind::Move => Op::Copy {
dir,
name: name()?,
to: msg
.get("to")
.and_then(Value::as_array)
.and_then(|a| {
a.iter()
.map(|s| s.as_str().map(str::to_string))
.collect::<Option<Vec<_>>>()
})
.ok_or("\"to\" must be an array of directory names")?,
replace: msg.get("replace").and_then(Value::as_bool).unwrap_or(false),
remove: cmd == CommandKind::Move,
},
CommandKind::ChangeDir if given.is_none() => {
return Err("missing array field \"dir\"".into());
}
CommandKind::ChangeDir => Op::ChangeDir { dir },
_ => {
let flag = msg
.get("flag")
.and_then(Value::as_i64)
.and_then(|f| i32::try_from(f).ok())
.ok_or("missing number field \"flag\"")?;
let on = msg
.get("on")
.and_then(Value::as_bool)
.ok_or("missing boolean field \"on\"")?;
Op::SetFlag { flag, on }
}
};
if let Op::Store { dir, .. }
| Op::Fetch { dir, .. }
| Op::Purge { dir, .. }
| Op::Rename { dir, .. }
| Op::CreateDir { dir, .. }
| Op::Copy { dir, .. }
| Op::ChangeDir { dir } = &mut op
{
*dir = match given {
Some(d) => d,
None => self.emu()?.memory_tree()?.path,
};
}
Ok(op)
}
fn screen_of(&mut self, msg: &Value) -> Result<saturnus_objects::Graphic> {
let lcd = self.emu()?.machine().lcd();
let (width, height) = (lcd.width(), lcd.height());
let packed = match msg.get("pixels") {
None | Some(Value::Null) => crate::host::pack_bits(&lcd.pixels),
Some(_) => {
let b64 = str_field(msg, "pixels")?;
let given =
|k: &str, d: usize| msg.get(k).and_then(Value::as_u64).unwrap_or(d as u64);
if given("width", width) != width as u64 || given("height", height) != height as u64
{
return Err(format!("the screen is {width} by {height} pixels").into());
}
let bytes = base64_decode(b64).map_err(|e| format!("pixels: {e}"))?;
if bytes.len() != crate::host::packed_row_bytes(width) * height {
return Err(format!("pixels: not {width} by {height} pixels").into());
}
bytes
}
};
saturnus_objects::Graphic::from_packed(width as u32, height as u32, &packed)
.map_err(Into::into)
}
fn text_target(&mut self, msg: &Value) -> Result<(Vec<String>, Target)> {
let target = match (msg.get("name"), msg.get("level")) {
(Some(_), None) => Target::Variable(str_field(msg, "name")?.to_string()),
(None, Some(l)) => Target::Level(
l.as_u64()
.and_then(|n| usize::try_from(n).ok())
.filter(|&n| n >= 1)
.ok_or("\"level\" must be a stack level (1 or more)")?,
),
_ => return Err("give either \"name\" or \"level\"".into()),
};
let dir = match msg.get("dir") {
None | Some(Value::Null) => self.emu()?.memory_tree()?.path,
Some(v) => v
.as_array()
.and_then(|a| {
a.iter()
.map(|s| s.as_str().map(str::to_string))
.collect::<Option<Vec<_>>>()
})
.ok_or("\"dir\" must be an array of directory names")?,
};
Ok((dir, target))
}
fn set_clock(&mut self, clock: &dyn Clock, msg: &Value, reply: Option<u64>) -> Result<Answer> {
let wall_ms = clock.now_ms();
let time = crate::clock::ClockTime::from_json(msg)?;
let ms = match msg.get("millisecond") {
None | Some(Value::Null) => 0.0,
Some(v) => v
.as_f64()
.filter(|ms| (0.0..1000.0).contains(ms))
.ok_or("\"millisecond\" must be a number from 0 to 999")?,
};
let now = crate::clock::Now { time, ms, wall_ms };
if let Some(h) = &self.halted {
return Err(format!("the CPU is halted: {h}").into());
}
if self.recover.is_some() {
return Err(crate::clock::BUSY.into());
}
if let Some(why) = self.emu()?.clock_refusal() {
return Err(why.into());
}
self.wake_running(clock)?;
if self.lp.behind_ms() > 0.0 {
return Err(crate::clock::BUSY.into());
}
let e = self.emu()?;
if crate::clock::by_command(e.model()) {
let (op, _) = e.clock_write(&now, &crate::clock::Pace::UNBOUNDED, clock)?;
return self.start_transfer(clock, op, reply);
}
let pace = self.lp.clock_pace();
let e = self.emu()?;
e.set_clock_by_keys(&now, &pace, clock)?;
self.autosave.touch(clock.now_ms());
self.after_keys(clock);
Ok(Value::Null.into())
}
fn start_transfer(&mut self, clock: &dyn Clock, op: Op, reply: Option<u64>) -> Result<Answer> {
self.emu()?;
self.wake_running(clock)?;
let waiting = if self.recover.is_some() && self.lp.running {
Some(Waiting::Transfer(op))
} else {
self.emu()?.start_transfer(op)?;
None
};
self.lp.stop();
let now = clock.now_ms();
self.autosave.touch(now);
self.send = Some(Send {
tag: reply,
freezes: true,
transfer: true,
started: now,
due: now,
stopping: None,
waiting,
});
Ok(Answer::Later)
}
fn typing_turn(&mut self, clock: &dyn Clock) {
let (Some(send), Some(e)) = (self.send.as_mut(), self.emu.as_mut()) else {
return;
};
let started = send.started;
let transfer = send.transfer;
let start = clock.now_ms();
let mut result = Ok(false);
while matches!(result, Ok(false)) && clock.now_ms() - start < self.lp.pacing.typing_tick_ms
{
result = if send.waiting.is_some() {
match answer_boot(e, &mut self.recover) {
Ok(true) => match send.waiting.take() {
Some(Waiting::Typing(verb, text)) => {
e.start_typing(&verb, &text).map(|_| false)
}
Some(Waiting::Transfer(op)) => e.start_transfer(op).map(|_| false),
None => Ok(false),
},
other => other.map(|_| false),
}
} else if transfer {
e.transfer_step(TYPING_STEP_MS)
} else {
e.typing_step(TYPING_STEP_MS)
};
}
let now = clock.now_ms();
self.lp.work_ms += now - start;
if matches!(result, Ok(false))
&& now - started > WALL_LIMIT_MS
&& !transfer
&& send.waiting.is_none()
&& e.typing_end_wait()
{
for _ in 0..WAIT_END_STEPS {
result = e.typing_step(TYPING_STEP_MS);
if !matches!(result, Ok(false)) {
break;
}
e.typing_end_wait();
}
}
match result {
Ok(false) if now - started > WALL_LIMIT_MS => self.end_typing(
clock,
Some(
format!(
"{} ran out of wall-clock time ({} s)",
if transfer { "the transfer" } else { "typing" },
WALL_LIMIT_MS / 1000.0
)
.into(),
),
),
Ok(false) => {
if let Some(s) = self.send.as_mut() {
s.due = now;
}
self.flush(clock, true);
}
Ok(true) => self.end_typing(clock, None),
Err(err) => self.end_typing(clock, Some(err)),
}
}
fn end_typing(&mut self, clock: &dyn Clock, error: Option<Error>) {
let Some(mut send) = self.send.take() else {
return;
};
if let (Some(err), Some(e)) = (&error, self.emu.as_mut())
&& send.transfer
&& e.transferring()
{
if send.stopping.is_none() && !matches!(err, Error::Halted(_)) {
e.stop_transfer();
let now = clock.now_ms();
send.stopping = Some(err.clone());
send.started = now;
send.due = now;
self.send = Some(send);
return;
}
e.abandon_transfer();
}
let error = match (send.stopping.take(), error) {
(Some(why), None) => Some(match self.emu.as_mut().map(Emulator::transfer_result) {
Some(Err(e)) if e.to_string() != crate::transfer::STOPPED => {
format!("{why}; {e}").into()
}
_ => why,
}),
(Some(why), Some(e)) => Some(format!("{why}; {e}").into()),
(None, e) => e,
};
self.autosave.touch(clock.now_ms());
let mut bytes = None;
let result = match (error, self.emu.as_mut()) {
(_, None) => Err("no ROM loaded".into()),
(None, Some(e)) if send.transfer => e.transfer_result().and_then(|(r, file)| {
bytes = file.map(|f| ("data", f));
value_of(&r)
}),
(None, Some(e)) => e.typing_result().and_then(|r| value_of(&r)),
(Some(err), Some(e)) => {
e.stop_typing();
e.stop_transfer();
Err(err)
}
};
if send.transfer {
if let Some(e) = self.emu.as_mut() {
e.reshow();
}
self.watch.force = true;
}
if send.freezes {
self.send_status();
}
match &result {
Err(e @ Error::Halted(_)) => {
let e = e.clone();
self.halt(clock, e);
}
_ => self.set_running(clock, self.lp.running),
}
self.respond(clock, send.tag, result, bytes);
}
fn flush(&mut self, clock: &dyn Clock, now: bool) {
if self.serial
&& let Some(e) = self.emu.as_mut()
{
self.serial_out.held.extend(e.machine_mut().serial_drain());
let slack = self.lp.pacing.timer_slack_ms;
if let Some(bytes) = self.serial_out.take(clock.now_ms(), slack, now) {
self.event(Event::Serial(SerialEvent { bytes }));
}
}
let frozen = self.send.as_ref().is_some_and(|s| s.freezes);
if !frozen && let Some(e) = self.emu.as_mut() {
let errors = e.take_errors();
let keys = e.keys_if_changed();
let t = clock.now_ms();
let due = now
|| self
.last_frame
.is_none_or(|f| t - f >= self.lp.pacing.frame_ms);
let frame = if due { e.frame_if_changed() } else { None };
for err in errors {
self.event(Event::Error(ErrorEvent {
message: err.to_string(),
}));
}
if let Some(k) = keys {
self.event(Event::Keys(k));
}
if let Some(f) = frame {
self.last_frame = Some(t);
self.event(Event::Frame(f));
}
if self.send.is_none()
&& let Some(e) = self.emu.as_mut()
&& pacing::asleep(e)
&& let Some(m) = e.menu_if_changed()
{
self.event(Event::Menu(m));
}
}
self.send_status();
self.poll_memory(clock);
self.poll_save(clock);
}
fn settled(&self) -> bool {
self.send.is_none()
&& self.halted.is_none()
&& self.emu.as_ref().is_some_and(pacing::asleep)
}
fn poll_save(&mut self, clock: &dyn Clock) {
let settled = self.settled();
if self
.autosave
.poll(clock.now_ms(), self.lp.pacing.timer_slack_ms, settled)
{
self.emit_save();
}
}
fn emit_save(&mut self) {
let Some(e) = self.emu.as_ref() else {
return;
};
let saved = Saved {
model: e.model().name(),
rom_name: self.rom_name.clone(),
cycles: e.machine().cycles(),
state: e.save_state(),
};
self.autosave.clear();
self.autosave.saves += 1;
self.out.push(Output::Save(saved));
}
fn send_status(&mut self) {
let status = self.status();
if self.last_status.as_ref() != Some(&status) {
self.last_status = Some(status.clone());
self.event(Event::Status(status));
}
}
fn poll_memory(&mut self, clock: &dyn Clock) {
let quiet = self.send.is_none()
&& self
.emu
.as_ref()
.is_none_or(|e| !self.lp.running || pacing::asleep(e));
if self.watch.poll(self.emu.as_ref(), quiet, clock) {
self.event(Event::MemoryChanged(MemoryChanged {}));
}
}
}