saturnus_core/lib.rs
1#![cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]
2//! Core library of the Saturnus emulator: Saturn CPU, bus, modules and
3//! per-model machine wiring. No I/O and no threads: this crate must build
4//! for `wasm32`.
5//!
6//! The public API is the [`Machine`] and what it takes and returns:
7//! [`Model`], [`io::Key`], [`Port`], the display ([`Lcd`],
8//! [`Framebuffer`], [`Annunciators`]), [`Error`] and [`Halt`], and a
9//! disassembler for traces ([`disasm`]). The CPU, the bus and the I/O
10//! chips are internal; the `internals` feature exposes them, without any
11//! stability promise, for this crate's own ROM-gated tests and its `boot`
12//! example.
13//!
14//! Hardware facts are cited as `wiki: <page>` referring to the calculator
15//! wiki (see `kb/docs/knowledge-sources.md`).
16
17mod bus;
18mod cpu;
19pub mod disasm;
20mod error;
21pub mod io;
22mod machine;
23mod modules;
24mod state;
25
26pub use cpu::ADDR_MASK;
27pub use error::Error;
28#[cfg(feature = "profile")]
29pub use machine::profile::{Bucket, Profile};
30pub use machine::{
31 Annunciators, CARD_MAX_BYTES, CARD_MIN_BYTES, Framebuffer, Halt, INTL_17B_BYTES, LCD_HEIGHT,
32 LCD_HEIGHT_28S, LCD_HEIGHT_42S, LCD_WIDTH, LCD_WIDTH_28S, Lcd, Machine, Model, NEW_CARD_BYTES,
33 Port, pioneer_address_order,
34};
35pub use state::STATE_FORMAT;
36
37/// The CPU, the bus and the display renderer for this crate's ROM-gated
38/// tests and the `boot` example (feature `internals`). Not part of the
39/// public API: anything here may change in any release.
40#[cfg(feature = "internals")]
41#[doc(hidden)]
42pub mod internals {
43 pub use crate::bus::{Chip, Select};
44 pub use crate::cpu::instr::{DatSize, Instruction, Ptr, Reg};
45 pub use crate::cpu::{Decoded, decode, disassemble};
46 use crate::machine::{Lcd, Machine};
47
48 /// The display rendered from `m`'s display registers, reading the
49 /// bitmaps through `peek`.
50 pub fn render_lcd(m: &Machine, peek: impl Fn(u32) -> u8) -> Lcd {
51 Lcd::render(&m.hw.io, peek)
52 }
53
54 /// The address ranges the display reads its rows from.
55 pub fn lcd_row_spans(m: &Machine) -> impl Iterator<Item = (u32, u32)> {
56 Lcd::row_spans(&m.hw.io)
57 }
58}
59
60// The README (the crate's page on crates.io) compiles as a doctest.
61#[cfg(doctest)]
62#[doc = include_str!("../README.md")]
63struct ReadmeDoctests;