// SPDX-License-Identifier: GPL-3.0-or-later
// Paper experiment: exercises the real VCCCore API using an authored ROM.
#include "MachineSession.h"
#include <algorithm>
#include <cstdint>
#include <exception>
#include <functional>
#include <iostream>
#include <limits>
#include <sstream>
#include <stdexcept>
#include <string>
#include <tuple>
#include <vector>
using namespace VCC::Mac;
namespace {
struct Result { std::string name; bool passed; std::string detail; };
struct GuestResult {
std::string processor;
std::vector<Result> checks;
std::uint64_t beforeCycles = 0, afterCycles = 0, beforeFrames = 0, afterFrames = 0;
std::uint32_t ramBytes = 0;
};
void require(bool condition, const char* message) {
if (!condition) throw std::runtime_error(message);
}
std::string quote(const std::string& value) {
std::ostringstream out; out << '"';
for (const unsigned char c : value) {
switch (c) {
case '"': out << "\\\""; break;
case '\\': out << "\\\\"; break;
case '\n': out << "\\n"; break;
case '\r': out << "\\r"; break;
case '\t': out << "\\t"; break;
default: if (c >= 32) out << c; else out << '?';
}
}
out << '"'; return out.str();
}
bool sameCpu(const VCC::CPUState& a, const VCC::CPUState& b) {
return std::tie(a.DP,a.CC,a.MD,a.A,a.B,a.E,a.F,a.X,a.Y,a.U,a.S,a.PC,a.V,a.IsNative6309,a.phyAddr,a.block)
== std::tie(b.DP,b.CC,b.MD,b.A,b.B,b.E,b.F,b.X,b.Y,b.U,b.S,b.PC,b.V,b.IsNative6309,b.phyAddr,b.block);
}
bool sameMmu(const VCC::MMUState& a, const VCC::MMUState& b) {
if (std::tie(a.Enabled,a.ActiveTask,a.RamVectors,a.RomMap,a.Task0,a.Task1,a.AllRAM,a.Prefix,a.RAMBytes,a.RAMVectorAddress)
!= std::tie(b.Enabled,b.ActiveTask,b.RamVectors,b.RomMap,b.Task0,b.Task1,b.AllRAM,b.Prefix,b.RAMBytes,b.RAMVectorAddress)) return false;
for (std::size_t i=0; i<a.Effective.size(); ++i) {
const auto &x=a.Effective[i], &y=b.Effective[i];
if (std::tie(x.Page,x.RAMStart,x.SourceStart,x.Source) != std::tie(y.Page,y.RAMStart,y.SourceStart,y.Source)) return false;
}
return true;
}
struct State {
Snapshot session;
DebugSnapshot debug;
DebugMemoryRange ram;
};
State capture(MachineSession& machine) {
State value;
value.session=machine.snapshot();
value.debug=machine.debuggerSnapshot(0,65536);
value.ram=machine.debuggerMemoryRange(0,value.debug.mmu.RAMBytes,true);
return value;
}
void sameState(const State& a, const State& b) {
require(sameCpu(a.session.cpu,b.session.cpu),"CPU registers changed during inspection");
require(sameCpu(a.debug.cpu,b.debug.cpu),"debug CPU registers changed during inspection");
require(sameMmu(a.debug.mmu,b.debug.mmu),"MMU state changed during inspection");
require(a.session.generation==b.session.generation && a.session.cycles==b.session.cycles && a.session.frames==b.session.frames,
"generation or guest clocks changed during inspection");
require(a.session.state==b.session.state && a.session.debuggerProgramRevision==b.session.debuggerProgramRevision &&
a.session.debuggerMappingFingerprint==b.session.debuggerMappingFingerprint,"session identity changed during inspection");
require(a.debug.memory==b.debug.memory && a.debug.memoryAvailable==b.debug.memoryAvailable,"logical inspection buffers changed");
require(a.ram.bytes==b.ram.bytes && a.ram.available==b.ram.available,"physical RAM changed during inspection");
require(a.debug.breakpoints==b.debug.breakpoints && a.debug.disabledBreakpoints==b.debug.disabledBreakpoints &&
a.debug.stopReason==b.debug.stopReason,"debugger state changed during inspection");
require(bool(a.session.frame)==bool(b.session.frame),"published frame existence changed");
if (a.session.frame && b.session.frame) {
require(a.session.frame->pixels==b.session.frame->pixels && a.session.frame->number==b.session.frame->number &&
a.session.frame->generation==b.session.frame->generation,"published frame changed during inspection");
}
}
void check(GuestResult& guest, const std::string& name, const std::function<std::string()>& operation) {
try { guest.checks.push_back({name,true,operation()}); }
catch (const std::exception& error) { guest.checks.push_back({name,false,error.what()}); }
}
template<class F> void rejected(F operation, const char* message) {
bool refused=false;
try { operation(); } catch (const std::invalid_argument&) { refused=true; }
require(refused,message);
}
std::vector<std::uint8_t> authoredRom() {
std::vector<std::uint8_t> rom(0x8000,0x12);
// INC $4000; BRA $8000. Shared MC6809/HD6309 instructions, no ROM payload.
const std::uint8_t code[]={0x7c,0x40,0x00,0x20,0xfb};
std::copy(std::begin(code),std::end(code),rom.begin());
rom[0x7ffe]=0x80; rom[0x7fff]=0x00;
return rom;
}
GuestResult exercise(Processor processor, const std::string& name) {
GuestResult guest; guest.processor=name;
MachineSession machine;
machine.load(authoredRom(),processor);
machine.resume(); machine.advance(); machine.pause();
auto baseline=capture(machine);
guest.ramBytes=baseline.debug.mmu.RAMBytes;
guest.beforeCycles=baseline.session.cycles; guest.beforeFrames=baseline.session.frames;
check(guest,"authored_guest_executes_real_frame",[&]{
require(baseline.session.state==RunState::Paused,"machine did not pause");
require(baseline.session.cycles>0 && baseline.session.frames>0,"guest did not execute a real frame");
require(baseline.ram.bytes.size()==512*1024,"fixture did not have 512 KiB RAM");
return "Authored INC/BRA ROM executed at least one frame using the selected real CPU engine.";
});
check(guest,"logical_io_availability_is_explicit",[&]{
require(baseline.debug.memory.size()==65536 && baseline.debug.memoryAvailable.size()==65536,"incomplete logical capture");
for (unsigned address=0xff00;address<=0xff3f;++address)
require(baseline.debug.memoryAvailable[address]==0,"PIA/I/O value was presented as available");
require(baseline.debug.memoryAvailable[0x4000]!=0 && baseline.debug.memoryAvailable[0xff90]!=0 &&
baseline.debug.memoryAvailable[0xfffe]!=0,"safe RAM/GIME/vector view unexpectedly unavailable");
return "PIA window is unavailable; RAM, non-destructive GIME view, and ROM reset vector are available.";
});
check(guest,"repeated_observations_preserve_full_machine_state",[&]{
for (unsigned repeat=0;repeat<16;++repeat) {
const auto logical=machine.debuggerMemoryRange(0x3ff0,64,false);
const auto physical=machine.debuggerMemoryRange(0,guest.ramBytes,true);
const auto screen=machine.debuggerGraphicsCapture();
const auto manual=machine.debuggerGraphicsPreview(false,false,0x4000,DebugGraphicsMode::HSCREEN2);
require(!screen.displayed.pixels.empty() && !manual.pixels.empty(),"graphics capture was empty");
require(logical.bytes.size()==64 && physical.bytes.size()==guest.ramBytes,"memory range length mismatch");
sameState(baseline,capture(machine));
}
return "Sixteen repetitions of logical/complete-physical/graphics observations preserved all compared registers, clocks, generation, MMU fields, RAM bytes, availability masks and published pixels.";
});
check(guest,"logical_physical_backing_agrees",[&]{
const auto& backing=baseline.debug.mmu.Effective[2];
require(backing.Source==VCC::MMUSource::RAM,"fixture RAM address is overlaid");
const auto physical=machine.debuggerMemoryRange(backing.SourceStart,16,true);
const auto logical=machine.debuggerMemoryRange(0x4000,16,false);
require(logical.bytes==physical.bytes,"logical bytes differ from actual physical RAM backing");
sameState(baseline,capture(machine));
return "Logical $4000 and its observed effective physical RAM backing agree without remapping.";
});
check(guest,"invalid_ranges_reject_without_state_change",[&]{
rejected([&]{machine.debuggerMemoryRange(0,0,false);},"zero-length logical range accepted");
rejected([&]{machine.debuggerMemoryRange(0xffff,2,false);},"wrapping logical range accepted");
rejected([&]{machine.debuggerMemoryRange(0x10000,1,false);},"out-of-range logical address accepted");
rejected([&]{machine.debuggerMemoryRange(guest.ramBytes-1,2,true);},"physical range crossing RAM end accepted");
rejected([&]{machine.debuggerMemoryRange(std::numeric_limits<std::uint32_t>::max(),2,true);},"overflowing physical range accepted");
rejected([&]{machine.debuggerSnapshot(0,65537);},"oversized logical snapshot accepted");
sameState(baseline,capture(machine));
return "Six invalid range/snapshot requests threw invalid_argument and left the compared machine state unchanged.";
});
check(guest,"stale_source_step_identities_reject_without_execution",[&]{
const auto before=machine.snapshot();
std::vector<DebugSourceInstruction> instructions{{before.cpu.PC,1,{0x12},{}}};
for (unsigned changed=0;changed<4;++changed) {
auto generation=before.generation, revision=before.debuggerProgramRevision, mapping=before.debuggerMappingFingerprint;
auto pc=before.cpu.PC;
if(changed==0) ++generation;
if(changed==1) ++revision;
if(changed==2) mapping^=1;
if(changed==3) pc^=1;
bool correctRefusal=false;
try {machine.debuggerStepSource(SourceStepMode::Into,instructions,generation,revision,mapping,pc);}
catch(const std::invalid_argument& error) {correctRefusal=std::string(error.what()).find("paused program changed")!=std::string::npos;}
require(correctRefusal,"stale source-step identity was not refused by the identity guard");
sameState(baseline,capture(machine));
}
return "Independently stale generation, program revision, mapping fingerprint and PC were rejected before execution.";
});
const auto retained=machine.debuggerMemoryRange(0x4000,64,false);
const auto retainedBytes=retained.bytes;
const auto oldByte=retainedBytes.front();
const auto oldFrame=baseline.session.frame;
const auto oldPixels=oldFrame ? oldFrame->pixels : std::vector<std::uint32_t>{};
check(guest,"retained_capture_survives_explicit_guest_ram_edit",[&]{
const auto replacement=std::uint8_t(oldByte^0xff);
machine.debuggerWriteMemory(0x4000,{replacement});
require(machine.debuggerMemoryRange(0x4000,1,false).bytes.front()==replacement,"explicit RAM edit did not occur");
require(retained.bytes==retainedBytes,"retained immutable range changed after explicit edit");
require(baseline.debug.memory[0x4000]==oldByte,"retained debug snapshot changed after explicit edit");
return "A confirmed live RAM change did not alter previously retained memory captures.";
});
check(guest,"retained_capture_survives_real_frame_execution",[&]{
const auto before=machine.snapshot();
machine.resume(); machine.advance(); machine.pause();
const auto after=machine.snapshot();
require(after.cycles>before.cycles && after.frames>before.frames,"guest did not advance after explicit resume");
require(retained.bytes==retainedBytes && baseline.debug.memory[0x4000]==oldByte,"retained RAM observation changed during later execution");
require(oldFrame && oldFrame->pixels==oldPixels,"retained published frame changed during later execution");
guest.afterCycles=after.cycles; guest.afterFrames=after.frames;
return "Real CPU/frame progress occurred while retained memory and prior published pixels remained unchanged.";
});
check(guest,"retained_capture_survives_reset_and_new_generation",[&]{
const auto before=machine.snapshot(); machine.reset(); const auto after=machine.snapshot();
require(after.generation>before.generation,"reset did not advance generation");
require(retained.bytes==retainedBytes && baseline.debug.memory[0x4000]==oldByte,"reset changed retained memory buffers");
require(oldFrame && oldFrame->pixels==oldPixels,"reset changed retained frame pixels");
require(baseline.session.generation<after.generation,"retained snapshot generation was overwritten");
return "Cold reset advanced machine generation without invalidating owned bytes/pixels in prior captures.";
});
machine.shutdown();
return guest;
}
}
int main() {
std::vector<GuestResult> guests;
bool passed=true;
try {
guests.push_back(exercise(Processor::MC6809,"MC6809"));
guests.push_back(exercise(Processor::HD6309,"HD6309"));
} catch(const std::exception& error) {
std::cout << "{\"fatal\":" << quote(error.what()) << ",\"passed\":false}\n"; return 1;
}
std::cout << "{\"schema_version\":1,\"experiment\":\"observer_invariants\",\"fixture\":\"authored_32KiB_INC_BRA_ROM\",\"guests\":[";
for(std::size_t i=0;i<guests.size();++i) {
if(i)std::cout<<',';
const auto& g=guests[i];
std::cout<<"{\"processor\":"<<quote(g.processor)<<",\"ram_bytes\":"<<g.ramBytes
<<",\"cycles_before\":"<<g.beforeCycles<<",\"cycles_after\":"<<g.afterCycles
<<",\"frames_before\":"<<g.beforeFrames<<",\"frames_after\":"<<g.afterFrames<<",\"checks\":[";
for(std::size_t j=0;j<g.checks.size();++j) {
if(j)std::cout<<',';const auto& c=g.checks[j];passed=passed&&c.passed;
std::cout<<"{\"name\":"<<quote(c.name)<<",\"passed\":"<<(c.passed?"true":"false")<<",\"detail\":"<<quote(c.detail)<<'}';
}
std::cout<<"]}";
}
std::cout<<"],\"passed\":"<<(passed?"true":"false")<<"}\n";
return passed?0:1;
}
Evidence record
experiments/observer-invariants/probe.cpp
From Windows Application to Portable Emulation Platform
13,938 bytes
SHA-256aea706658a1d0a05357e3a572e631e8722c076e10351b59ef30ebf19ac8188b6