#!/usr/bin/env python3 # SPDX-License-Identifier: GPL-3.0-or-later """Headless, authored-ROM comparison; raw artifacts remain outside this repo.""" from __future__ import annotations import argparse import datetime import hashlib import json import platform import re import subprocess from pathlib import Path COMMON = bytes.fromhex( "1a5010ce7000ce0000108e00004f1f8bc6108e4100" "documented source snapshot" ) REGISTERS = ("cc", "a", "b", "dp", "x", "y", "u", "s") ROOT = Path(__file__).resolve().parents[2] def sha(data: bytes) -> str: return hashlib.sha256(data).hexdigest() def execute(command: list[str], timeout: float = 30) -> subprocess.CompletedProcess: return subprocess.run(command, capture_output=True, timeout=timeout, check=False) def checked(command: list[str]) -> bytes: result = execute(command) if result.returncode: raise RuntimeError(f"command failed: {Path(command[0]).name}: " + result.stderr.decode(errors="replace")) return result.stdout def xroar_trace(text: str) -> list[dict]: rows = [] for line in text.splitlines(): match = re.match(r"^([0-9a-f]{4})\| ([0-9a-f]+)\s+(.*)$", line) if not match or "cc=" not in match[3]: continue registers = {name: int(value, 16) for name, value in re.findall(r"\b(cc|a|b|dp|x|y|u|s)=([0-9a-f]+)", match[3])} if set(registers) != set(REGISTERS): raise RuntimeError("XRoar trace row lacks the compared register set") rows.append({"pc": int(match[1], 16), "opcode": match[2], "after": registers}) return rows def normalize(rows: list[dict]) -> list[dict]: return [{"pc": row["pc"], "after": {name: row["after"][name] for name in REGISTERS}} for row in rows] def encoded(value: object) -> bytes: return json.dumps(value, sort_keys=True, separators=(",", ":")).encode() def main() -> int: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument("--source", type=Path, required=True, help="Read-only VCC Plus checkout") parser.add_argument("--library", type=Path, required=True, help="Fresh VCCCore Release static library") parser.add_argument("--xroar", type=Path, required=True, help="Installed XRoar 1.12 executable") parser.add_argument("--raw-dir", type=Path, required=True, help="New directory outside the paper repository") parser.add_argument("--output", type=Path, required=True, help="New result JSON; existing evidence is preserved") args = parser.parse_args() if args.output.exists(): parser.error("Choose a new result JSON path") source, library, xroar, raw = (p.resolve() for p in (args.source, args.library, args.xroar, args.raw_dir)) if raw == ROOT or ROOT in raw.parents or raw.exists(): parser.error("--raw-dir must be a new directory outside the paper repository") for path in (source, library, xroar): if not path.exists(): parser.error(f"Missing input: {path}") input_paths = sorted(p for folder in (source / "src/core", source / "src/devices") for p in folder.rglob("*") if p.is_file()) source_hashes = {p.relative_to(source).as_posix(): sha(p.read_bytes()) for p in input_paths} if not source_hashes: parser.error("Source tree has no core/device inputs") raw.mkdir(parents=True) (raw / "empty.conf").write_text("") executable = raw / "vcc-fixture" compile_command = ["xcrun", "clang++", "-std=c++17", "-O2", "-mmacosx-version-min=14.0", "-I", str(source / "src/core"), str(Path(__file__).with_name("vcc-fixture.cpp")), str(library), "-o", str(executable)] compiled = execute(compile_command) (raw / "compile.stdout").write_bytes(compiled.stdout) (raw / "compile.stderr").write_bytes(compiled.stderr) if compiled.returncode: raise RuntimeError("Fixture compilation failed; inspect external raw directory") version = checked([str(xroar), "-V"]).decode().splitlines()[0] cpu_help = checked([str(xroar), "-machine-cpu", "help"]).decode() results = { "schema_version": 1, "experiment": "authored_common_instruction_and_ram_readback_comparison", "executed_at_utc": datetime.datetime.now(datetime.timezone.utc).isoformat(), "source_repository_url": "https://vccplus-git.brianholman.com/VCCPlus/VCCPlusOSS/src/branch/main/", "source_inputs_sha256": source_hashes, "vcc_library_sha256": sha(library.read_bytes()), "xroar_version": version, "xroar_executable_sha256": sha(xroar.read_bytes()), "xroar_cpu_help_6309_unverified": "UNVERIFIED" in cpu_help, "host": {"architecture": platform.machine(), "macos": platform.mac_ver()[0]}, "xroar_executable_architectures": checked(["lipo", "-archs", str(xroar)]).decode().strip(), "vcc_fixture_architectures": checked(["lipo", "-archs", str(executable)]).decode().strip(), "compiler": checked(["xcrun", "clang++", "--version"]).decode().splitlines()[0], "configuration": {"ram_kib": 512, "cartridge": "none", "ui": "null", "audio": "null", "config": "explicit empty file", "auto_save": False, "private_inputs": False, "wall_timeout_seconds_per_run": 10, "xroar_fallback_timeout_seconds": 0.01}, "comparison": {"instruction_rows_per_case": 115, "pc": "instruction entry", "registers": list(REGISTERS), "register_observation": "after instruction", "starts_after_explicit_initialization": True, "excluded_registers": ["e", "f", "v", "md"], "excluded_initial_reset_state": True}, "cases": [], "limits": [ "Small authored fixture; not exhaustive CPU conformance or full software compatibility.", "XRoar labels its 6309 implementation UNVERIFIED.", "XRoar MD is not directly exposed by this trace; native case observes executed LDMD #$01.", "RAM readback in XRoar is inferred from every guest ADDA accumulator delta, not snapshot decoding.", "E/F/V reset values differ and are neither used nor compared.", "No cross-emulator cycle, raster, interrupt, audio, latency, or performance comparison.", "An x86_64 XRoar executable running on this arm64 host is translated execution, not physical Intel qualification." ] } for name, processor, machine_name, prefix in ( ("mc6809", "6809", "coco3", b""), ("hd6309_emulation", "6309", "coco3h", b""), ("hd6309_ldmd_native", "6309", "coco3h", bytes.fromhex("113d01")), ): guest = prefix + COMMON rom = bytearray([255] * 32768) rom[:len(guest)] = guest for vector in range(0x7ff0, 0x8000, 2): rom[vector:vector + 2] = b"\x80\x00" rom_path, snapshot = raw / f"{name}.rom", raw / f"{name}.sna" rom_path.write_bytes(rom) start, stop = 0x8015 + len(prefix), 0x8000 + len(guest) - 2 command = [str(xroar), "-c", str(raw / "empty.conf"), "-no-config-auto-save", "-ui", "null", "-ao", "null", "-machine", machine_name, "-machine-cpu", processor, "-ram", "512", "-extbas", str(rom_path), "-no-cart", "-no-ratelimit", "-trace", "-trap", f"pc=0x{stop:04x}", "-trap-snap", str(snapshot), "-trap-timeout", "0", "-timeout", "0.01"] observed_x = execute(command, 10) observed_v = execute([str(executable), str(rom_path), processor, hex(start), hex(stop)], 10) for suffix, data in (("xroar.stdout", observed_x.stdout), ("xroar.stderr", observed_x.stderr), ("vcc.json", observed_v.stdout), ("vcc.stderr", observed_v.stderr)): (raw / f"{name}.{suffix}").write_bytes(data) if observed_x.returncode or observed_v.returncode: raise RuntimeError(f"{name}: emulator failed; inspect external raw directory") full_x_trace = xroar_trace(observed_x.stdout.decode()) begins = next((i for i, row in enumerate(full_x_trace) if row["pc"] == start), None) if begins is None: raise RuntimeError(f"{name}: XRoar did not reach initialized comparison entry") x_trace = full_x_trace[begins:] v_data = json.loads(observed_v.stdout) nx, nv = normalize(x_trace), normalize(v_data["trace"]) previous_a, readback = None, [] for row in x_trace: if row["opcode"] == "aba0": if previous_a is None: raise RuntimeError("No prior accumulator value for RAM readback") readback.append({"address": row["after"]["y"] - 1, "value": (row["after"]["a"] - previous_a) & 255}) previous_a = row["after"]["a"] expected = list(range(1, 17)) expected_registers = {"cc": 0x54, "a": 0x88, "b": 0, "dp": 0, "x": 0x4110, "y": 0x4110, "u": 0, "s": 0x7000} checks = { "both_exit_zero": observed_x.returncode == observed_v.returncode == 0, "xroar_stop_snapshot_created": snapshot.is_file() and snapshot.stat().st_size > 0, "xroar_stop_instruction_not_executed": all(row["pc"] != stop for row in full_x_trace), "vcc_stopped_before_expected_pc": v_data["stopped_before_pc"] == stop, "instruction_count": len(nx) == len(nv) == 115, "all_compared_instruction_states_equal": nx == nv, "xroar_final_registers_expected": nx[-1]["after"] == expected_registers, "vcc_final_registers_expected": {k: v_data["registers"][k] for k in REGISTERS} == expected_registers, "vcc_direct_ram_expected": v_data["memory_4100"] == expected, "xroar_each_guest_ram_read_expected": readback == [{"address": 0x4100 + i, "value": i + 1} for i in range(16)], "vcc_mode_expected": v_data["registers"]["native"] == bool(prefix), "xroar_ldmd_prefix_observed_when_requested": not prefix or full_x_trace[0]["opcode"] == "113d01", } case = {"case": name, "status": "pass" if all(checks.values()) else "fail", "rom_sha256": sha(bytes(rom)), "rom_bytes": len(rom), "comparison_start": start, "stop_pc": stop, "xroar_instructions_total": len(full_x_trace), "compared_instructions": len(nx), "registers": v_data["registers"], "vcc_reported_instruction_cycles": v_data["cycles"], "ram_4100": v_data["memory_4100"], "xroar_guest_readback": readback, "xroar_normalized_trace_sha256": sha(encoded(nx)), "vcc_normalized_trace_sha256": sha(encoded(nv)), "checks": checks, "raw_artifact_hashes": {f"{name}.{suffix}": sha((raw / f"{name}.{suffix}").read_bytes()) for suffix in ("xroar.stdout", "xroar.stderr", "vcc.json", "vcc.stderr", "sna")}} results["cases"].append(case) print(name + ": " + case["status"] + "; 115 instruction states and 16 guest RAM readbacks") results["status"] = "pass" if all(case["status"] == "pass" for case in results["cases"]) else "fail" if any(sha((source / name).read_bytes()) != expected for name, expected in source_hashes.items()): raise RuntimeError("Source inputs changed during measurement") output = args.output output.parent.mkdir(parents=True, exist_ok=True) output.write_text(json.dumps(results, indent=2) + "\n") return 0 if results["status"] == "pass" else 1 if __name__ == "__main__": raise SystemExit(main())