← Supporting evidence

Evidence record

experiments/xroar/run.py

From Windows Application to Portable Emulation Platform

11,769 bytes

#!/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())

SHA-2565df810e9539831497f951cbceb69749f5d874263e0466682e3fe96298b8977a6

A closer look

Open original