#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
pub mod clock;
mod error;
pub mod host;
pub mod layout;
pub mod menulabels;
pub mod protocol;
pub mod romid;
pub mod sha256;
pub mod skins;
pub mod transfer;
pub mod typing;
pub mod wire;
use saturnus_core::io::Key;
use saturnus_core::{Annunciators, LCD_HEIGHT, LCD_WIDTH, Lcd};
use saturnus_core::{Machine, Model};
use saturnus_objects::{Flags, NameTable, UserMemory, Variable, menus, softkeys};
use serde::ser::SerializeMap;
use std::sync::Arc;
pub use error::{Error, Result};
pub const FRAMEBUFFER_BYTES: usize = LCD_WIDTH * LCD_HEIGHT;
pub fn pack_pixels(lcd: &Lcd) -> Vec<u8> {
let mut out = Vec::with_capacity(lcd.width() * lcd.height());
for row in &lcd.pixels {
out.extend(row.iter().map(|&on| u8::from(on)));
}
out
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct AnnunciatorFlags(pub Annunciators);
impl serde::Serialize for AnnunciatorFlags {
fn serialize<S: serde::Serializer>(&self, s: S) -> std::result::Result<S::Ok, S::Error> {
let list = self.0.list();
let mut map = s.serialize_map(Some(list.len()))?;
for (name, on) in list {
map.serialize_entry(name, &on)?;
}
map.end()
}
}
#[derive(Clone, Debug, serde::Serialize)]
pub struct MemoryTree {
pub path: Vec<String>,
pub variables: Vec<Variable>,
}
#[derive(Debug)]
pub struct Emulator {
machine: Machine,
cycle_debt: f64,
queue: host::KeyQueue,
shown: Option<host::Frame>,
shown_keys: Option<Vec<&'static str>>,
names: std::cell::RefCell<Option<(u64, Arc<NameTable>)>>,
menus: std::cell::RefCell<Option<(u64, Option<Arc<menus::Menus>>)>>,
menu_seen: Option<[u32; 6]>,
shown_menu: Option<Option<Vec<Option<softkeys::ShownKey>>>>,
menu_presses: u64,
menu_dirty: bool,
menu_force: bool,
typing: Option<typing::Job>,
transfer: Option<transfer::Transfer>,
}
impl Emulator {
pub fn new(model: Model, rom: &[u8]) -> Result<Self> {
let machine = Machine::new(model, rom)?;
Ok(Self {
queue: host::KeyQueue::new(model),
machine,
cycle_debt: 0.0,
shown: None,
shown_keys: None,
names: std::cell::RefCell::new(None),
menus: std::cell::RefCell::new(None),
menu_seen: None,
shown_menu: None,
menu_presses: 0,
menu_dirty: true,
menu_force: false,
typing: None,
transfer: None,
})
}
pub fn from_machine(machine: Machine) -> Self {
Self {
queue: host::KeyQueue::new(machine.model()),
machine,
cycle_debt: 0.0,
shown: None,
shown_keys: None,
names: std::cell::RefCell::new(None),
menus: std::cell::RefCell::new(None),
menu_seen: None,
shown_menu: None,
menu_presses: 0,
menu_dirty: true,
menu_force: false,
typing: None,
transfer: None,
}
}
pub fn rehearsal(&self) -> Self {
let mut e = Self::from_machine(self.machine.clone());
e.cycle_debt = self.cycle_debt;
e
}
pub fn into_machine(self) -> Machine {
self.machine
}
pub fn machine_mut(&mut self) -> &mut Machine {
&mut self.machine
}
pub fn run_ms(&mut self, ms: f64) -> Result<f64> {
if !ms.is_finite() || ms <= 0.0 {
return Ok(0.0);
}
let want = ms * f64::from(self.machine.model().clock_hz()) / 1000.0 + self.cycle_debt;
let whole = want.floor();
if whole < 1.0 {
self.cycle_debt = want;
return Ok(0.0);
}
let start = self.machine.cycles();
let n = whole as u64;
let result = self.machine.run_cycles(n);
let ran = self.machine.cycles() - start;
self.cycle_debt = want - ran as f64;
result?;
Ok(ran as f64)
}
fn key(&self, name: &str) -> Result<Key> {
Key::from_name(name).ok_or_else(|| format!("unknown key {name:?}").into())
}
pub fn key_down(&mut self, name: &str) -> Result<()> {
let k = self.key(name)?;
Ok(self.machine.key_down(k)?)
}
pub fn key_up(&mut self, name: &str) -> Result<()> {
let k = self.key(name)?;
Ok(self.machine.key_up(k)?)
}
pub fn load_state(&mut self, data: &[u8]) -> Result<()> {
self.machine.load_state(data)?;
self.menu_dirty = true;
self.cycle_debt = 0.0;
self.queue.clear();
self.typing = None;
self.transfer = None;
Ok(())
}
pub fn idle_ms(&self) -> Option<f64> {
self.machine
.idle_cycles()
.map(|c| c as f64 * 1000.0 / f64::from(self.machine.model().clock_hz()))
}
pub(crate) fn step_cycles(&self, ms: f64) -> u64 {
let per_ms = f64::from(self.machine.model().clock_hz()) / 1000.0;
(ms.max(1.0) * per_ms) as u64
}
pub fn machine(&self) -> &Machine {
&self.machine
}
fn user_memory(&self) -> Result<UserMemory<'_>> {
UserMemory::of(&self.machine).map_err(Into::into)
}
fn names(&self) -> Arc<NameTable> {
let generation = self.machine.rom_generation();
let mut cached = self.names.borrow_mut();
match &*cached {
Some((g, names)) if *g == generation => names.clone(),
_ => {
let names = Arc::new(NameTable::of(&self.machine));
*cached = Some((generation, names.clone()));
names
}
}
}
fn menus(&self) -> Option<Arc<menus::Menus>> {
let generation = self.machine.rom_generation();
let mut cached = self.menus.borrow_mut();
match &*cached {
Some((g, m)) if *g == generation => m.clone(),
_ => {
let names = self.names();
let m = menus::read(self.machine.rom_nibbles(), &names).map(Arc::new);
*cached = Some((generation, m.clone()));
m
}
}
}
pub fn menu_keys(&self) -> Result<Option<Vec<Option<softkeys::ShownKey>>>> {
if menulabels::reads(self.machine.model()) {
return Ok(menulabels::read(&self.machine));
}
self.user_memory()?;
let Some(defs) = self.menus() else {
return Ok(None);
};
Ok(softkeys::read(&self.machine, &defs)?)
}
pub fn menu_if_changed(&mut self) -> Option<host::MenuKeys> {
if menulabels::reads(self.machine.model()) {
let keys = menulabels::read(&self.machine);
return self.menu_news(keys);
}
self.user_memory().ok()?;
if self.typing.is_some() || self.transfer.is_some() {
self.menu_dirty = true;
return None;
}
let seen = softkeys::signature(&self.machine).ok();
let presses = self.queue.presses_started();
let same = seen.is_some()
&& seen == self.menu_seen
&& presses == self.menu_presses
&& !self.menu_dirty
&& self.shown_menu.is_some();
if same {
return None;
}
self.menu_seen = seen;
self.menu_presses = presses;
self.menu_dirty = false;
let keys = self.menu_keys().ok().flatten();
self.menu_news(keys)
}
fn menu_news(
&mut self,
keys: Option<Vec<Option<softkeys::ShownKey>>>,
) -> Option<host::MenuKeys> {
let force = std::mem::take(&mut self.menu_force);
if !force && self.shown_menu.as_ref().unwrap_or(&None) == &keys {
self.shown_menu = Some(keys);
return None;
}
self.shown_menu = Some(keys.clone());
Some(host::MenuKeys { keys })
}
pub fn memory_refusal(&self) -> Option<String> {
self.user_memory().err().map(|e| e.to_string())
}
pub fn memory_tree(&self) -> Result<MemoryTree> {
let u = self.user_memory()?;
let path = u.current_path()?;
let variables = u.tree()?;
Ok(MemoryTree { path, variables })
}
pub fn stack(&self) -> Result<Vec<serde_json::Value>> {
let names = self.names();
let levels = self.user_memory()?.with_names(&names).stack_described()?;
Ok(levels)
}
pub fn stack_top(&self) -> Result<serde_json::Value> {
let names = self.names();
let (depth, level1) = self.user_memory()?.with_names(&names).stack_top()?;
Ok(serde_json::json!({"depth": depth, "level1": level1}))
}
pub fn flags(&self) -> Result<Flags> {
Ok(self.user_memory()?.flags()?)
}
pub fn object_at(&self, address: u32) -> Result<serde_json::Value> {
let names = self.names();
let obj = self
.user_memory()?
.with_names(&names)
.object_described(address)?;
Ok(obj)
}
pub fn memory_changes(&self) -> Result<u64> {
Ok(self.user_memory()?.change_counter()?)
}
}
impl Emulator {
pub fn model(&self) -> Model {
self.machine.model()
}
pub fn save_state(&self) -> Vec<u8> {
self.machine.save_state()
}
pub fn reset(&mut self) {
self.machine.reset();
}
pub fn cycles(&self) -> f64 {
self.machine.cycles() as f64
}
pub fn emulated_ms(&self) -> f64 {
self.machine.cycles() as f64 * 1000.0 / f64::from(self.machine.model().clock_hz())
}
pub fn is_shutdown(&self) -> bool {
self.machine.is_shutdown()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn put(n: &mut [u8], at: usize, value: usize, width: usize) {
for i in 0..width {
n[at + i] = ((value >> (4 * i)) & 0xF) as u8;
}
}
fn put_rel(n: &mut [u8], at: usize, target: usize) {
put(n, at, (target + 0x100000 - at) & 0xFFFFF, 5);
}
fn library(n: &mut [u8], base: usize, id: usize, name: &str) {
let (header, hash, object) = (base, base + 0x40, base + 0x200);
let body = hash + 10;
let entry = body + 85;
put_rel(n, body + 5 * (name.len() - 1), entry);
put(n, entry, name.len(), 2);
for (i, b) in name.bytes().enumerate() {
put(n, entry + 2 + 2 * i, usize::from(b), 2);
}
put(n, entry + 2 + 2 * name.len(), 0, 3);
let numbers = entry + 2 + 2 * name.len() + 3;
put_rel(n, body + 80, numbers);
put(n, numbers, numbers - entry, 5);
let end = numbers + 5;
put(n, hash, 0x02A4E, 5);
put(n, hash + 5, end - hash - 5, 5);
let link = end;
put(n, link, 0x02A4E, 5);
put(n, link + 5, 10, 5);
put_rel(n, link + 10, object);
put(n, object - 6, id, 3);
put(n, object - 3, 0, 3);
put(n, object, 0x02D9D, 5);
put(n, object + 5, 0x0312B, 5);
put(n, header, id, 3);
put_rel(n, header + 3, hash);
put_rel(n, header + 13, link);
}
#[test]
fn names_follow_flash_changes() {
let marker = b"saturnus-marker!";
let mut image = vec![0xFFu8; Model::Hp49g.rom_bytes()];
image[0x100..0x110].copy_from_slice(marker);
let emu = Emulator::from_machine(Machine::new(Model::Hp49g, &image).unwrap());
assert_eq!(emu.names().xlib(0x123, 0), None);
let first = emu.names();
assert!(Arc::ptr_eq(&first, &emu.names()), "cached while unchanged");
let mut nibbles: Vec<u8> = image.iter().flat_map(|&b| [b & 0xF, b >> 4]).collect();
library(&mut nibbles, 5 * 0x40000 + 0x1000, 0x123, "FOO");
let packed: Vec<u8> = nibbles.chunks(2).map(|p| p[0] | (p[1] << 4)).collect();
let mut state = emu.machine().save_state();
let at = state
.windows(marker.len())
.position(|w| w == marker)
.unwrap()
- 0x100;
state[at..at + packed.len()].copy_from_slice(&packed);
let mut emu = emu;
emu.load_state(&state).unwrap();
let names = emu.names();
assert!(!Arc::ptr_eq(&first, &names), "rebuilt after the change");
assert_eq!(names.xlib(0x123, 0).and_then(|c| c.name), Some("FOO"));
}
#[test]
fn pixels_pack_one_byte_each_row_major() {
let mut lcd = Lcd::blank();
lcd.pixels[0][0] = true;
lcd.pixels[0][130] = true;
lcd.pixels[1][0] = true;
lcd.pixels[63][130] = true;
let fb = pack_pixels(&lcd);
assert_eq!(fb.len(), FRAMEBUFFER_BYTES);
assert_eq!(fb.len(), 8384);
let lit: Vec<usize> = (0..fb.len()).filter(|&i| fb[i] == 1).collect();
assert_eq!(lit, vec![0, 130, 131, 8383]);
assert!(fb.iter().all(|&b| b <= 1));
}
#[test]
fn annunciators_as_json() {
let json = |a| serde_json::to_string(&AnnunciatorFlags(a)).unwrap();
assert_eq!(
json(Annunciators::default()),
"{\"leftshift\":false,\"rightshift\":false,\"alpha\":false,\
\"alert\":false,\"busy\":false,\"transmit\":false,\"updown\":false,\
\"battery\":false,\"g\":false,\"rad\":false,\"suspended\":false}"
);
let j = json(Annunciators {
alpha: true,
busy: true,
..Annunciators::default()
});
assert!(j.contains("\"alpha\":true") && j.contains("\"busy\":true"));
assert!(j.contains("\"leftshift\":false"));
}
#[test]
fn rejects_wrong_rom_size() {
let e = Emulator::new(Model::Hp48sx, &[0u8; 1000]).unwrap_err();
assert!(e.to_string().contains("1000"), "{e}");
}
#[test]
fn run_ms_keeps_exact_time() {
let mut emu = Emulator::new(Model::Hp48sx, &vec![0u8; 256 * 1024]).unwrap();
let mut total = 0.0;
for _ in 0..100 {
match emu.run_ms(0.3) {
Ok(c) => total += c,
Err(e) => {
assert!(matches!(e, Error::Halted(_)), "{e}");
return;
}
}
}
assert!((total - 60_000.0).abs() < 100.0, "{total}");
assert_eq!(emu.run_ms(0.0), Ok(0.0));
assert_eq!(emu.run_ms(f64::NAN), Ok(0.0));
}
#[test]
fn keys_by_name_per_model() {
let mut emu = Emulator::new(Model::Hp48sx, &vec![0u8; 256 * 1024]).unwrap();
assert!(emu.key_down("enter").is_ok());
assert!(emu.key_up("enter").is_ok());
assert!(emu.key_down("f1").is_ok());
assert!(
emu.key_down("bogus")
.unwrap_err()
.to_string()
.contains("unknown key")
);
assert!(emu.key_down("apps").is_err());
}
#[test]
fn memory_view_errors() {
let emu = Emulator::new(Model::Hp48sx, &vec![0u8; 256 * 1024]).unwrap();
let e = emu.memory_tree().unwrap_err();
assert!(e.to_string().contains("no directory at HOME"), "{e}");
assert!(
matches!(&e, Error::Objects(o) if o.is_not_set_up()),
"{e:?}"
);
let flags = serde_json::to_string(&emu.flags().unwrap()).unwrap();
assert!(flags.contains("\"set\":[]"));
let emu = Emulator::new(Model::Hp38g, &vec![0u8; 512 * 1024]).unwrap();
assert!(emu.stack().unwrap_err().to_string().contains("aplets"));
let emu = Emulator::new(Model::Hp42s, &vec![0u8; 64 * 1024]).unwrap();
for e in [
emu.stack().unwrap_err(),
emu.memory_tree().unwrap_err(),
emu.flags().unwrap_err(),
] {
assert!(e.to_string().contains("42S has no RPL user memory"), "{e}");
}
}
#[test]
fn idle_ms_is_none_while_running() {
let emu = Emulator::new(Model::Hp48sx, &vec![0u8; 256 * 1024]).unwrap();
assert_eq!(emu.idle_ms(), None);
}
#[test]
fn state_round_trip() {
let mut emu = Emulator::new(Model::Hp48sx, &vec![0u8; 256 * 1024]).unwrap();
let _ = emu.run_ms(1.0);
let saved = emu.machine().save_state();
let cycles = emu.machine().cycles();
let _ = emu.run_ms(5.0);
emu.load_state(&saved).unwrap();
assert_eq!(emu.machine().cycles(), cycles);
assert!(emu.load_state(&[1, 2, 3]).is_err());
}
#[test]
fn a_state_load_drops_the_queued_presses() {
let mut emu = Emulator::new(Model::Hp48sx, &vec![0u8; 256 * 1024]).unwrap();
let _ = emu.run_ms(1.0);
let saved = emu.machine().save_state();
assert!(emu.press("1"));
assert!(emu.press("enter"));
assert!(emu.press_shifted("sqrt", "leftshift"));
emu.type_keys("2 3");
assert!(emu.keys_busy());
assert!(emu.load_state(&[1, 2, 3]).is_err());
assert!(emu.keys_busy(), "a failed load changes nothing");
emu.load_state(&saved).unwrap();
assert!(!emu.keys_busy(), "the queue is empty");
emu.pump();
assert_eq!(
emu.keys_if_changed().map(|k| k.down),
Some(vec![]),
"no key went down"
);
assert_eq!(
emu.machine().save_state(),
saved,
"the loaded machine as saved: no key pressed in it"
);
}
#[test]
fn a_state_load_drops_a_send_or_a_write_in_progress() {
let mut emu = Emulator::new(Model::Hp48sx, &vec![0u8; 256 * 1024]).unwrap();
let _ = emu.run_ms(1.0);
let saved = emu.machine().save_state();
emu.start_typing("insert", "12").unwrap();
assert!(emu.typing());
assert!(emu.load_state(&[1, 2, 3]).is_err());
assert!(emu.typing(), "a failed load keeps the send");
emu.load_state(&saved).unwrap();
assert!(!emu.typing(), "the send is gone");
assert!(emu.typing_step(10.0).is_err(), "no typing in progress");
emu.transfer = Some(transfer::Transfer::empty(emu.machine()));
assert!(emu.transferring());
assert!(emu.load_state(&[1, 2, 3]).is_err());
assert!(emu.transferring(), "a failed load keeps the write");
emu.load_state(&saved).unwrap();
assert!(!emu.transferring(), "the write is gone");
assert!(emu.transfer_step(10.0).is_err(), "no write in progress");
}
#[test]
fn hp42s_has_a_16_row_display_and_its_own_keys() {
let mut emu = Emulator::new(Model::Hp42s, &vec![0u8; 64 * 1024]).unwrap();
assert_eq!(emu.machine().lcd().height(), 16);
assert_eq!(pack_pixels(&emu.machine().lcd()).len(), 131 * 16);
assert!(emu.key_down("xeq").is_ok());
assert!(emu.key_down("exit").is_ok());
assert!(
emu.key_down("f1").is_err(),
"the 42S's menu keys keep their labels"
);
}
}
#[cfg(doctest)]
#[doc = include_str!("../README.md")]
struct ReadmeDoctests;