pub const CPU_SNAPSHOT_VERSION: u8 = 4;Expand description
Schema version for the CPU snapshot blob.
- v1 (v0.9.0 ..): registers + interrupt latches + cycle bookkeeping.
- v2 (W3-Stage-4 promotion, 2026-06-10): appends the master-clock
substrate pipeline —
master_clock(u64) + themc_need_nmi/mc_prev_need_nmi/mc_run_irq/mc_prev_run_irq/mc_prev_nmi_linelatches (1 byte each). - v3 (v2.0.0 “Timebase” rc.1, ADR 0028): the byte layout is
IDENTICAL to v2 —
cyclesandmaster_clockare both still written, unchanged. What changes is the guarantee: as of the beta.1–beta.4 one-clock promote,cyclesis no longer an independently-tracked counter (it is assigned fromBus::cycle_count()at everystart_cycle, seecpu.rs), so a v3 blob’scycles/master_clockpair is guaranteed internally consistent by construction in a way a pre-promote v1/v2 blob was only coincidentally consistent (kept in sync by parallel increments, not derivation). The version bump exists to make that distinction an explicit, checked contract rather than an implicit assumption — see ADR 0028 for the full MAJOR-boundary decision. v1/v2 blobs are no longer upconverted;Cpu::restorerejects any version other thanCPU_SNAPSHOT_VERSION(the caller-sideNes::restore_inneralready enforced this via a strict per-section equality check before this bump — the upconvert path removed here was dead code, unreachable through the only real caller). - v4 (v2.6.7 “Detent”): appends
skip_irq_sample_q(1 byte), the one-cycle delay ofskip_irq_samplethathandle_interruptsreads. nesdev’sCPU_interruptsstates that interrupts are polled before an instruction’s second cycle but not before the third cycle of a TAKEN BRANCH, so suppressing the poll needs the flag’s value on the previous cycle as well as this one. It is genuine emulation state read back on the next tick, not derivable from the rest of the blob — a restore that dropped it would resume with the NMI dispatch gate (themc_prev_need_nmicopy; the edge latchmc_need_nmiruns every cycle regardless) re-opened a cycle early on any snapshot landing inside a taken branch. Serialized rather than allowlisted, whichsnapshot_schema_auditsays has been the right answer every time it has come up.