Skip to main content

Machine

Struct Machine 

Source
pub struct Machine { /* private fields */ }
Expand description

A complete calculator: CPU, hardware and the clock that ties them.

Implementations§

Source§

impl Machine

Source

pub fn new(model: Model, rom_packed: &[u8]) -> Result<Self, Error>

Build a powered-on model from its packed ROM image. The image must have exactly Model::rom_bytes bytes; for the 49G it is the 2 MB flash image (or the same unpacked, 4 MB), for the 39G and 40G the 1 MB ROM (or the same unpacked, 2 MB), for the 17BII also the 96 KB international image, mapped from #00000 to #2FFFF; see Model::accepts_rom_len. A Pioneer image in dump order is put in address order first (pioneer_address_order).

Source

pub fn reset(&mut self)

Hardware reset: CPU registers, memory controller (all chips unconfigured), bank latch and I/O registers back to power-on; RAM contents, cards, held keys and the serial wire’s queues are kept.

Source

pub fn model(&self) -> Model

The emulated model.

Source

pub fn cycles(&self) -> u64

CPU cycles elapsed since construction.

Source

pub fn is_shutdown(&self) -> bool

True while the CPU is stopped by SHUTDN.

Source

pub fn step(&mut self) -> Result<u32, Halt>

Execute one instruction, or, while shut down, skip time up to the next event (at most one second). Returns the cycles that elapsed (0 when the call only woke the CPU).

Source

pub fn step_for(&mut self, budget: u64) -> Result<u32, Halt>

As Machine::step, but a shut-down CPU skips at most budget cycles (at least 1), so a caller can stop at its own next event.

Source

pub fn run_cycles(&mut self, n: u64) -> Result<(), Halt>

Run until the cycle counter has advanced by at least n.

Source

pub fn has_key(&self, k: Key) -> bool

Whether the model’s keyboard has k (Model::has_key).

Source

pub fn key_down(&mut self, k: Key) -> Result<(), Error>

Press k. Pressing ON raises the (non-maskable) ON interrupt. A key the model lacks (see Machine::has_key) is refused with Error::KeyNotOnModel and changes nothing.

Source

pub fn key_up(&mut self, k: Key) -> Result<(), Error>

Release k; a key the model lacks is refused as by Machine::key_down.

Source

pub fn key_is_down(&self, k: Key) -> bool

Whether k is held down (pressed and not released).

Source

pub fn release_all_keys(&mut self)

Release every key of the keyboard matrix and ON at once, as if the user let go of all of them; nothing else changes (a host’s own key queue is its own to clear).

Source

pub fn peek(&self, addr: u32) -> u8

The nibble at addr through the current memory mapping, without side effects.

Source

pub fn poke(&mut self, addr: u32, value: u8)

Write nibble value (low 4 bits) at addr through the current memory mapping, as a CPU write would: RAM and cards take it, mask ROM ignores it, and a write into the I/O registers or the 49G’s flash has the side effects the CPU’s would. For hosts that patch memory (a debugger’s poke, a test setting a flag).

Source

pub fn pc(&self) -> u32

The program counter: the address of the next instruction.

Source

pub fn contrast(&self) -> u8

The display contrast as the ROM set it: the raw 5-bit value, 0-31, higher is darker (see Model::contrast_range).

Source

pub fn display_on(&self) -> bool

Whether the display is switched on: DON of the model’s display controller (#100 bit 3 on the 48 family, DSPCTL bit 3 on the 42S’s Lewis). The one place hosts ask.

Source

pub fn lcd(&self) -> Lcd

The current LCD pixels: 131x64, or 131x16 on the 42S. While an UNCNFG has taken the display bitmaps out of the memory map, the picture from before it (see HeldFrame in hardware.rs).

Source

pub fn framebuffer(&self) -> Framebuffer

The current display: pixels, annunciators and contrast. The annunciators are dark while TIMER2 is stopped (wiki: emulators/emu48 SP19, “TIMER2CTRL’s RUN bit also governs the annunciators”) or AON is clear.

Source

pub fn insert_card(&mut self, port: Port, packed: &[u8]) -> Result<(), Error>

Insert a writable RAM card into port (wiki: hardware/card-ports). packed holds two nibbles per byte, the even address in the low nibble, like a ROM image; its length must be a power of two from CARD_MIN_BYTES to Model::card_max_bytes for the port (128 KB on both 48SX ports and 48GX port 1, 4 MB on 48GX port 2). A card already in the port is replaced. With card detection enabled the ROM sees a card-detect interrupt.

Source

pub fn remove_card(&mut self, port: Port) -> bool

Remove the card from port; returns whether there was one.

Source

pub fn rom_nibbles(&self) -> &[u8] ⓘ

The system ROM (the 49G’s whole flash, all 16 banks in order) as the machine holds it, one nibble per element. A host reads the ROM’s own tables from it (command names, see saturnus-objects) without going through the current memory mapping.

Source

pub fn rom_generation(&self) -> u64

A number that moves whenever Machine::rom_nibbles may have changed (the 49G’s flash programmed or erased, or replaced by a loaded state); constant for mask ROM. Cheap: a host that caches something read from the ROM compares it on every use.

Source

pub fn card_image(&self, port: Port) -> Option<Vec<u8>>

The contents of the card in port, packed like Machine::insert_card takes them, or None for an empty port.

Source

pub fn has_serial(&self) -> bool

Whether the model has a serial port (see Model::has_serial); false on the 42S. Hosts that bridge the serial line check this first.

Source

pub fn serial_push(&mut self, bytes: &[u8])

Queue bytes arriving on the serial wire. The UART receives them one per 11.375 bit times at the baud rate in #10D, starting now, while emulated time runs. Bytes arriving while the port is off (IOC SON clear) or looped back (TCS LPB) are lost, as on the real line. On a model without a serial port (Machine::has_serial false: the 42S) this does nothing: the bytes are not queued, Machine::serial_pending stays 0 and nothing is ever received.

Source

pub fn serial_drain(&mut self) -> Vec<u8> ⓘ

The bytes the calculator transmitted since the last drain.

Source

pub fn serial_pending(&self) -> usize

Pushed bytes not yet delivered to the UART’s receive register.

Source

pub fn serial_clear_inbound(&mut self) -> usize

Drop pushed bytes that have not started on the wire yet, e.g. when the host on the other end disconnects; a byte already on the wire finishes. Returns how many were dropped.

Source

pub fn serial_on(&self) -> bool

Whether the calculator’s serial port is on (IOC SON): its software opened it (a Kermit server, XRECV, OPENIO). Bytes arriving while it is off are lost.

Source

pub fn serial_baud(&self) -> u32

The serial baud rate the calculator selected (#10D).

Source

pub fn idle_cycles(&self) -> Option<u64>

While the CPU is shut down with nothing to wake it: the cycles it will skip before the next timer or UART event (or keyboard poll while a key is held), so a host can sleep for real instead of stepping. None while the CPU runs or a wake condition holds.

Source§

impl Machine

Source

pub fn save_state(&self) -> Vec<u8> ⓘ

Serialize the complete mutable state (a versioned binary format, documented in the crate’s src/state.rs). The ROM is not included; Machine::load_state needs a machine built from the same ROM.

Source

pub fn load_state(&mut self, data: &[u8]) -> Result<(), Error>

Replace the machine’s state with one from Machine::save_state. On error the machine is left unchanged.

Trait Implementations§

Source§

impl Clone for Machine

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for Machine

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.