Struct FrameRunner 

pub struct FrameRunner<const EXT_CLOCK_HZ: u32, const TIME_FRAME_HZ: u32> { /* private fields */ }

A helper for running emulated frames.

FRAME_PERIOD = 1 / TIME_FRAME_HZ

|<-        FRAME_PERIOD         ->|
t1          t2                   t3
<- emulate -><====== sleep =======>

The FrameRunner keeps track of and manages the emulated time. It holds the instance of TClock and a current frame limit.

The implementation methods running the emulation expect an instance of a Z80 emulator implementing the Cpu trait and the system bus emulator implementing Memory, Io and BusDevice traits.

• EXT_CLOCK_HZ: an external clock frequency in hertz (NOT THE CPU CLOCK).
• TIME_FRAME_HZ: how many frames per second the emulation will run.

Implementations

impl<const EXT_HZ: u32, const FRAME_HZ: u32> FrameRunner<EXT_HZ, FRAME_HZ>

pub fn debug_preview<C: Cpu, M>(&self, cpu: &C, bus: &M) -> CpuDebug

where M: Memory<Timestamp = Ts>,

Return a CpuDebug as a preview of the instruction to execute next.

The instruction shown will not necessarily be the one that will execute next in cases such as:

• An IRQ can be requested before CPU fetches the instructions.
• The memory page 0x2000 - 0x3FFF might contain the RAM page and will change the contents to the ROM page when the CPU fetches an instruction.
• A more than one of 0xFD/0xDD prefixes in a row resides in memory at PC.

pub fn debug_step<C: Cpu, M>( &mut self, cpu: &mut C, bus: &mut M, ) -> (Option<CpuDebug>, Ts)

where M: Memory<Timestamp = Ts> + Io<Timestamp = Ts> + BusDevice<Timestamp = Ts>,

Run emulation step and return a pair of an optional CpuDebug of an executed instruction and a step duration in T-states.

Returns (None, Ts) if Cpu was already halted.

pub fn debug_runto_int<C: Cpu, M>( &mut self, cpu: &mut C, bus: &mut M, ) -> (Option<CpuDebug>, Ts)

where M: Memory<Timestamp = Ts> + Io<Timestamp = Ts> + BusDevice<Timestamp = Ts>,

Run emulation and stop on an IRQ request. Return a pair of an optional CpuDebug of the last instruction and a total duration in T-states.

Returns (None, Ts) if CPU was already halted and no interrupt occured or a frame has passed.

pub fn debug_runto_ret<C: Cpu, M>( &mut self, cpu: &mut C, bus: &mut M, ) -> (Option<CpuDebug>, Ts)

where M: Memory<Timestamp = Ts> + Io<Timestamp = Ts> + BusDevice<Timestamp = Ts>,

Run emulation until a RET/RET cc/RETI/RETN is successfully executed. Return a pair of an optional CpuDebug of the last instruction and a total duration in T-states.

Returns (None, Ts) if a frame has passed before any RET instruction.

pub fn run_until_brkpt<C: Cpu, M>( &mut self, cpu: &mut C, bus: &mut M, brkpts: &[u16], ) -> (Option<usize>, Ts)

where M: Memory<Timestamp = Ts> + Io<Timestamp = Ts> + BusDevice<Timestamp = Ts>,

Run emulation until PC equals to one of the brkpoints. Return a pair of an optional brkpoint index and a total duration in T-states.

Returns ((None, Ts)) if no brkpoints were hit and a frame has passed.

NOTE: brkpts MUST be sorted!

impl<const EXT_HZ: u32, const FRAME_HZ: u32> FrameRunner<EXT_HZ, FRAME_HZ>

pub const EXT_CLOCK_HZ: u32 = EXT_HZ

The external clock frequency used by peripherals.

pub const TIME_FRAME_HZ: u32 = FRAME_HZ

Emulation frames frequency.

pub const FRAME_DURATION: Duration

A real-time duration of a single frame.

pub const fn clock_is_valid(clock_hz: Ts) -> bool

Return whether the clock_hz is a valid CPU clock for this runner.

pub fn external_clock_tstates(&self) -> u32

Return the external clock period in the number of T-states.

The external clock drives some peripherals.

pub fn new(clock_hz: Ts) -> Self

Create a new runner.

clock_hz: a CPU clock in T-states per second. It must be divisible by Self::EXT_CLOCK_HZ * 2.

Panics if the clock is invalid.

pub fn frame_duration() -> Duration

A real-time duration of a single running frame.

pub fn start<C: Cpu, M>(&mut self, cpu: &mut C, bus: &mut M)

where M: BusDevice<Timestamp = Ts>,

Reset everything including clock and the frame limit counter.

This function should be called before very first step.

pub fn step<C: Cpu, M>(&mut self, cpu: &mut C, bus: &mut M) -> Ts

where M: Memory<Timestamp = Ts> + Io<Timestamp = Ts> + BusDevice<Timestamp = Ts>,

Run the emulation for a period of a single frame and return the frame duration in emulated T-states.

pub fn reset<C: Cpu, M>(&mut self, cpu: &mut C, bus: &mut M)

where M: BusDevice<Timestamp = Ts>,

Reset the cpu and bus devices.

pub fn nmi<C: Cpu, M>(&mut self, cpu: &mut C, bus: &mut M) -> Option<Ts>

where M: Memory<Timestamp = Ts> + Io<Timestamp = Ts>,

Trigger a non-maskable interrupt and return a number of T-states that it took on success.