#!/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())
Evidence record
experiments/xroar/run.py
From Windows Application to Portable Emulation Platform
11,769 bytes
SHA-2565df810e9539831497f951cbceb69749f5d874263e0466682e3fe96298b8977a6