hg80 1.0.0

//! Acceptance run against a published set of processor test vectors.
//!
//! The vectors are not carried in this repository. Point `HG80_FUSE_DIR` at a directory holding
//! `tests.in` and `tests.expected`, or place them in `tests/fuse`, and this runs. Without them it
//! reports that it was skipped.

use hg80::{BusCycle, BusRequest, Cpu, Host, InterruptMode};
use std::collections::BTreeMap;
use std::path::PathBuf;

#[derive(Clone, PartialEq, Eq, Debug)]
struct Event {
    time: u32,
    label: &'static str,
    address: u16,
    data: Option<u8>,
}

impl std::fmt::Display for Event {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self.data {
            Some(data) => write!(
                formatter,
                "{:5} {} {:04x} {data:02x}",
                self.time, self.label, self.address
            ),
            None => write!(
                formatter,
                "{:5} {} {:04x}",
                self.time, self.label, self.address
            ),
        }
    }
}

// The vectors timestamp each event against the T-state the transfer lands on, so the log is built
// from the machine cycles the core reports rather than from anything it is asked mid-instruction.
// Reports arrive in the order the cycles ran and before the following cycle's own transfer — see
// `BusCycle` — so whatever was recorded since the last report belongs to the cycle now described.
struct Machine {
    memory: Vec<u8>,
    data: Option<u8>,
    time: u32,
    events: Vec<Event>,
    vector_base: u8,
    refresh_counter: u8,
}

impl Machine {
    fn new() -> Self {
        Self {
            memory: vec![0; 0x10000],
            data: None,
            time: 0,
            events: Vec::new(),
            vector_base: 0,
            refresh_counter: 0,
        }
    }

    // A fetch longer than four T-states carries the refresh address over the extra ones, not the
    // address it fetched from, and a cycle is reported with one address for the whole of it.
    //
    // So this counts refreshes itself. What that costs: the vectors stop witnessing the address bus
    // during those T-states. It still witnesses the refresh register, which it compares in the final
    // state, and the same address is compared where an internal cycle follows a fetch — the
    // instruction-by-instruction comparison reads it from the bus there. The per-T-state address is
    // also compared against a simulation of the hardware by the cycle diff.
    fn refreshed(&mut self) -> u16 {
        self.refresh_counter =
            (self.refresh_counter & 0x80) | (self.refresh_counter.wrapping_add(1) & 0x7F);
        u16::from_be_bytes([self.vector_base, self.refresh_counter])
    }

    fn at(&mut self, time: u32, label: &'static str, address: u16, data: Option<u8>) {
        self.events.push(Event {
            time,
            label,
            address,
            data,
        });
    }

    // A port cycle is timestamped a T-state in, and the vectors record the contention around it
    // separately: once at the start when the address is in the contended bank, and once or three
    // times after depending on whether the port is odd.
    fn port(&mut self, label: &'static str, port: u16, data: Option<u8>) {
        let time = self.time;
        let contended = port & 0xC000 == 0x4000;
        let odd = port & 1 != 0;
        if contended {
            self.at(time, "PC", port, None);
        }
        self.at(time + 1, label, port, data);
        match (contended, odd) {
            (true, true) => {
                for late in 1..=3 {
                    self.at(time + late, "PC", port, None);
                }
            }
            (true | false, false) => self.at(time + 1, "PC", port, None),
            (false, true) => {}
        }
    }

    // A memory cycle is one contention marker at its start, the transfer at the T-state it settles
    // on, and a further marker for each T-state the host asked to have inserted after that.
    fn memory(&mut self, label: &'static str, address: u16, base: u32, length: u32, tail: u16) {
        let (time, data) = (self.time, self.data);
        self.at(time, "MC", address, None);
        self.at(time + base, label, address, data);
        for extra in base..length {
            self.at(time + extra, "MC", tail, None);
        }
    }

    fn internal(&mut self, address: u16, length: u32) {
        for offset in 0..length {
            let time = self.time + offset;
            self.at(time, "MC", address, None);
        }
    }
}

impl Host for Machine {
    fn read(&mut self, address: u16, _at: u32) -> u8 {
        let value = self.memory[address as usize];
        self.data = Some(value);
        value
    }

    fn write(&mut self, address: u16, value: u8, _at: u32) {
        self.memory[address as usize] = value;
        self.data = Some(value);
    }

    fn input(&mut self, port: u16, _at: u32) -> u8 {
        let value = (port >> 8) as u8;
        self.data = Some(value);
        value
    }

    fn output(&mut self, port: u16, value: u8, _at: u32) {
        let _ = port;
        self.data = Some(value);
    }

    fn bus_cycle(&mut self, cycle: &BusCycle) {
        let length = cycle.t_states;
        match cycle.request {
            BusRequest::OpcodeFetch { address } => {
                let refresh = self.refreshed();
                self.memory("MR", address, 4, length, refresh);
            }
            BusRequest::MemoryRead { address } => self.memory("MR", address, 3, length, address),
            BusRequest::MemoryWrite { address, .. } => {
                self.memory("MW", address, 3, length, address);
            }
            BusRequest::PortRead { port } => self.port("PR", port, self.data),
            BusRequest::PortWrite { port, .. } => self.port("PW", port, self.data),
            BusRequest::Internal { address } | BusRequest::Refresh { address } => {
                self.internal(address, length);
            }
            // The vectors have no interrupts, so nothing else can reach here.
            _ => self.internal(0, length),
        }
        self.time += length;
        self.data = None;
    }
}

#[derive(Clone, Default, Debug, PartialEq, Eq)]
struct State {
    af: u16,
    bc: u16,
    de: u16,
    hl: u16,
    af_alt: u16,
    bc_alt: u16,
    de_alt: u16,
    hl_alt: u16,
    ix: u16,
    iy: u16,
    sp: u16,
    pc: u16,
    wz: u16,
    i: u8,
    r: u8,
    iff1: bool,
    iff2: bool,
    interrupt_mode: u8,
    halted: bool,
    t_states: u32,
}

#[derive(Clone, Debug)]
struct TestCase {
    name: String,
    state: State,
    memory: Vec<(u16, Vec<u8>)>,
}

#[derive(Clone, Debug)]
struct Expected {
    name: String,
    events: Vec<Event>,
    state: State,
    memory: Vec<(u16, Vec<u8>)>,
}

fn words(line: &str) -> Vec<u16> {
    line.split_whitespace()
        .filter_map(|word| u16::from_str_radix(word, 16).ok())
        .collect()
}

fn parse_input(text: &str) -> Vec<TestCase> {
    let mut cases = Vec::new();
    let mut lines = text.lines().peekable();

    while let Some(line) = lines.next() {
        let name = line.trim();
        if name.is_empty() {
            continue;
        }

        let registers = words(lines.next().unwrap_or_default());
        let control: Vec<&str> = lines
            .next()
            .unwrap_or_default()
            .split_whitespace()
            .collect();
        if registers.len() < 13 || control.len() < 7 {
            continue;
        }

        let state = State {
            af: registers[0],
            bc: registers[1],
            de: registers[2],
            hl: registers[3],
            af_alt: registers[4],
            bc_alt: registers[5],
            de_alt: registers[6],
            hl_alt: registers[7],
            ix: registers[8],
            iy: registers[9],
            sp: registers[10],
            pc: registers[11],
            wz: registers[12],
            i: u8::from_str_radix(control[0], 16).unwrap_or(0),
            r: u8::from_str_radix(control[1], 16).unwrap_or(0),
            iff1: control[2] == "1",
            iff2: control[3] == "1",
            interrupt_mode: control[4].parse().unwrap_or(0),
            halted: control[5] == "1",
            t_states: control[6].parse().unwrap_or(0),
        };

        let mut memory = Vec::new();
        for line in lines.by_ref() {
            let trimmed = line.trim();
            if trimmed == "-1" || trimmed.is_empty() {
                break;
            }
            if let Some(block) = parse_memory_line(trimmed) {
                memory.push(block);
            }
        }

        cases.push(TestCase {
            name: name.to_string(),
            state,
            memory,
        });
    }

    cases
}

fn parse_memory_line(line: &str) -> Option<(u16, Vec<u8>)> {
    let mut parts = line.split_whitespace();
    let start = u16::from_str_radix(parts.next()?, 16).ok()?;
    let mut bytes = Vec::new();
    for part in parts {
        if part == "-1" {
            break;
        }
        bytes.push(u8::from_str_radix(part, 16).ok()?);
    }
    Some((start, bytes))
}

fn parse_expected(text: &str) -> Vec<Expected> {
    let mut cases = Vec::new();
    let mut lines = text.lines().peekable();

    while let Some(line) = lines.next() {
        let name = line.trim();
        if name.is_empty() {
            continue;
        }

        let mut events = Vec::new();
        while let Some(peeked) = lines.peek() {
            let trimmed = peeked.trim();
            let is_event = trimmed
                .split_whitespace()
                .nth(1)
                .is_some_and(|word| matches!(word, "MC" | "MR" | "MW" | "PC" | "PR" | "PW"));
            if !is_event {
                break;
            }
            let parts: Vec<&str> = trimmed.split_whitespace().collect();
            let label = match parts[1] {
                "MC" => "MC",
                "MR" => "MR",
                "MW" => "MW",
                "PC" => "PC",
                "PR" => "PR",
                _ => "PW",
            };
            events.push(Event {
                time: parts[0].parse().unwrap_or(0),
                label,
                address: u16::from_str_radix(parts[2], 16).unwrap_or(0),
                data: parts
                    .get(3)
                    .and_then(|word| u8::from_str_radix(word, 16).ok()),
            });
            lines.next();
        }

        let registers = words(lines.next().unwrap_or_default());
        let control: Vec<&str> = lines
            .next()
            .unwrap_or_default()
            .split_whitespace()
            .collect();
        if registers.len() < 13 || control.len() < 7 {
            continue;
        }

        let state = State {
            af: registers[0],
            bc: registers[1],
            de: registers[2],
            hl: registers[3],
            af_alt: registers[4],
            bc_alt: registers[5],
            de_alt: registers[6],
            hl_alt: registers[7],
            ix: registers[8],
            iy: registers[9],
            sp: registers[10],
            pc: registers[11],
            wz: registers[12],
            i: u8::from_str_radix(control[0], 16).unwrap_or(0),
            r: u8::from_str_radix(control[1], 16).unwrap_or(0),
            iff1: control[2] == "1",
            iff2: control[3] == "1",
            interrupt_mode: control[4].parse().unwrap_or(0),
            halted: control[5] == "1",
            t_states: control[6].parse().unwrap_or(0),
        };

        let mut memory = Vec::new();
        while let Some(peeked) = lines.peek() {
            let trimmed = peeked.trim();
            if trimmed.is_empty() {
                break;
            }
            if let Some(block) = parse_memory_line(trimmed) {
                memory.push(block);
            }
            lines.next();
        }

        cases.push(Expected {
            name: name.to_string(),
            events,
            state,
            memory,
        });
    }

    cases
}

fn load(case: &TestCase) -> (Cpu, Machine) {
    let mut cpu = Cpu::new();
    cpu.reset();
    {
        let registers = cpu.registers_mut();
        registers.af = case.state.af;
        registers.bc = case.state.bc;
        registers.de = case.state.de;
        registers.hl = case.state.hl;
        registers.af_alt = case.state.af_alt;
        registers.bc_alt = case.state.bc_alt;
        registers.de_alt = case.state.de_alt;
        registers.hl_alt = case.state.hl_alt;
        registers.ix = case.state.ix;
        registers.iy = case.state.iy;
        registers.sp = case.state.sp;
        registers.pc = case.state.pc;
        registers.wz = case.state.wz;
        registers.i = case.state.i;
        registers.r = case.state.r;
        registers.iff1 = case.state.iff1;
        registers.iff2 = case.state.iff2;
        registers.interrupt_mode = match case.state.interrupt_mode {
            1 => InterruptMode::Mode1,
            2 => InterruptMode::Mode2,
            _ => InterruptMode::Mode0,
        };
    }
    cpu.set_halted(case.state.halted);

    let mut machine = Machine::new();
    machine.vector_base = case.state.i;
    machine.refresh_counter = case.state.r;
    for (start, bytes) in &case.memory {
        for (offset, byte) in bytes.iter().enumerate() {
            let address = start.wrapping_add(u16::try_from(offset).unwrap_or(0));
            machine.memory[address as usize] = *byte;
        }
    }

    (cpu, machine)
}

// Driven an instruction at a time, which is how a machine drives it. The suite runs each vector
// for at least its stated T-states and lets the instruction in progress finish, which is what a
// step does by construction — the edge-driven loop this replaced had to track prefixes by hand to
// know when it had reached a boundary.
fn run(case: &TestCase) -> (Vec<Event>, u32, Cpu, Machine) {
    let (mut cpu, mut machine) = load(case);
    let mut time = 0u32;

    while time < case.state.t_states {
        time += cpu.step(&mut machine);
        if time > 200_000 {
            break;
        }
    }

    (machine.events.clone(), time, cpu, machine)
}

fn final_state(cpu: &Cpu, time: u32) -> State {
    let registers = cpu.registers();
    State {
        af: registers.af,
        bc: registers.bc,
        de: registers.de,
        hl: registers.hl,
        af_alt: registers.af_alt,
        bc_alt: registers.bc_alt,
        de_alt: registers.de_alt,
        hl_alt: registers.hl_alt,
        ix: registers.ix,
        iy: registers.iy,
        sp: registers.sp,
        pc: registers.pc,
        wz: registers.wz,
        i: registers.i,
        r: registers.r,
        iff1: registers.iff1,
        iff2: registers.iff2,
        interrupt_mode: match registers.interrupt_mode {
            InterruptMode::Mode0 => 0,
            InterruptMode::Mode1 => 1,
            InterruptMode::Mode2 => 2,
        },
        halted: cpu.is_halted(),
        t_states: time,
    }
}

fn vector_files() -> Option<(String, String)> {
    let directory = std::env::var("HG80_FUSE_DIR").map_or_else(
        |_| PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/fuse"),
        PathBuf::from,
    );
    let input = std::fs::read_to_string(directory.join("tests.in")).ok()?;
    let expected = std::fs::read_to_string(directory.join("tests.expected")).ok()?;
    Some((input, expected))
}

/// Vectors where following the published expectation would mean getting the bus wrong.
///
/// The first five are conditional relative jumps whose condition fails. Such a jump still fetches
/// its displacement: the cycle is three T-states of a real read, with the address and data strobes
/// asserted, and a machine that contends its memory charges for it. The vectors record the
/// contention for that cycle but not the read. Every other observable agrees, T-states and
/// registers included.
///
/// The last is a halt. The vectors report the program counter still on the instruction that
/// halted; the processor leaves it past that instruction and fetches from there for as long as it
/// stays halted, which is also the address it returns to when an interrupt lifts it out. Following
/// the vectors would misplace every fetch made while halted, and halts are how a program waits for
/// an interrupt.
///
/// Neither is inference. The `branches` and `halted` programs in the cycle-by-cycle comparison
/// contain exactly these cases, and this crate and a simulation of the reference agree on both.
const RECORDED_DIVERGENCES: [&str; 6] = ["10", "20_2", "28_1", "30_2", "38_1", "76"];

#[test]
fn the_published_vectors_all_pass() {
    let Some((input, expected)) = vector_files() else {
        println!("skipped: no test vectors present");
        return;
    };

    let cases = parse_input(&input);
    let expectations: BTreeMap<String, Expected> = parse_expected(&expected)
        .into_iter()
        .map(|case| (case.name.clone(), case))
        .collect();

    let mut passed = 0;
    let mut memptr_only = 0;
    let mut aside_from_memptr = 0;
    let mut failures: Vec<String> = Vec::new();

    for case in &cases {
        let Some(want) = expectations.get(&case.name) else {
            continue;
        };

        let (events, time, cpu, machine) = run(case);
        let got = final_state(&cpu, time);

        let mut problems = Vec::new();
        if got.wz != want.state.wz {
            memptr_only += 1;
        }
        let mut ignoring = got.clone();
        ignoring.wz = want.state.wz;
        if ignoring == want.state && events == want.events {
            aside_from_memptr += 1;
        }
        if got != want.state {
            problems.push(format!(
                "state\n     got {got:?}\n    want {:?}",
                want.state
            ));
        }
        if events != want.events {
            let shown: Vec<String> = events.iter().map(ToString::to_string).collect();
            let wanted: Vec<String> = want.events.iter().map(ToString::to_string).collect();
            problems.push(format!(
                "events\n     got [{}]\n    want [{}]",
                shown.join(" | "),
                wanted.join(" | ")
            ));
        }
        for (start, bytes) in &want.memory {
            for (offset, byte) in bytes.iter().enumerate() {
                let address = start.wrapping_add(u16::try_from(offset).unwrap_or(0));
                let actual = machine.memory[address as usize];
                if actual != *byte {
                    problems.push(format!(
                        "memory {address:04x} got {actual:02x} want {byte:02x}"
                    ));
                }
            }
        }

        if problems.is_empty() {
            passed += 1;
        } else {
            failures.push(format!("{}: {}", case.name, problems.join("; ")));
        }
    }

    let total = cases.len();
    println!("{passed}/{total} vectors passed");
    println!(
        "{memptr_only} differ in the address latch; {aside_from_memptr} would pass without it"
    );

    let unexpected: Vec<&String> = failures
        .iter()
        .filter(|failure| {
            let name = failure.split(':').next().unwrap_or_default();
            !RECORDED_DIVERGENCES.contains(&name)
        })
        .collect();

    for failure in unexpected.iter().take(20) {
        println!("  {failure}");
    }

    assert!(
        unexpected.is_empty(),
        "{} vectors failed beyond the recorded divergences",
        unexpected.len()
    );
    assert_eq!(
        passed + RECORDED_DIVERGENCES.len(),
        total,
        "a recorded divergence now passes and should be removed from the list"
    );
}