Save States

A save state freezes the whole machine and restores it exactly: File ▸ Save State and File ▸ Load State.

A save state is Bizmuth’s own format, not one a real Spectrum used. It holds the whole emulated machine, including state a .z80 snapshot has no field for.

the CPU registers, and the point inside an instruction the processor had reached
all RAM, and the paging that decides what is visible
the video state: beam position, layers, palettes, sprites, the tilemap
the sound state: the AY chips, the beeper, the DAC
the peripherals: the CTC, DMA, DivMMC, Multiface, UART, floppy controller and real-time clock
the interrupt state, including an interrupt part-way through delivery
the tape in the deck and how far it has played
the SD card’s protocol state and, on a read-only card, the writes the guest has made to it

Restoring puts all of it back, and the machine continues from the same T-state.

Exclusions

The SD card image. A state records neither the card’s contents nor which card was attached. A state loads onto whatever card is attached at the time, and the restored machine sees that card as it is now.

Load a state with the card it was saved with. A different card, or the same card changed since, leaves NextZXOS holding a view of a filesystem that is no longer there.

Breakpoints. The breakpoints set when a state is loaded stay set; those set when it was saved are not restored.

Host settings. The maximum CPU speed, the 28 MHz memory wait, the IM2 daisy chain and whether the real-time clock is fitted follow the running session, not the state. So do the audio levels, the window size and the display options.

Files

States are written as .bzst files, compressed.

A state is for one machine. A Next state loads only on the Next, and a 48K state only on the 48K; switch machine first.

Version compatibility

The current format is version 16.

A state written with a different format version does not load. It is refused with a message giving its format version, whether that is older or newer, and the version this build reads:

savestate format v15 is older — the save/load format has changed since it was written (this build reads v16)

The format changes whenever the emulated machine gains or loses state. The release notes mark each change as Breaking.

There is no converter. Keep the version of Bizmuth that wrote a state you need, or make the state again.

Command line

Option	Effect
`--loadstate FILE`	restore a state in place of booting, with or without a window
`--savestate FILE`	write a compressed state at the end of a headless run
`--savestate-raw FILE`	the same, uncompressed
`--state-json FILE`	write the machine state as JSON at the end of a headless run

--loadstate takes precedence over --load, which is then ignored.

bizmuth --machine next --sd next.img --loadstate menu.bzst

Debugger commands

The ADP debugger takes savestate FILE and loadstate FILE. A path containing spaces is written in double quotes:

savestate "/tmp/before the crash.bzst"

Uses

A hard point in a game: save before it, and retry without reloading.
Development: freeze a program where something goes wrong, and return to that point.
A bug report: a state restores exactly, on any machine running the same Bizmuth. Send the card image with it, or the state restores onto a different filesystem from the one you saw.

A program that reads the real-time clock reads the host’s current time after a load, not the time it was saved at, so it can behave differently from the run that was saved.