← Supporting evidence

Evidence record

experiments/observer-invariants/probe.cpp

From Windows Application to Portable Emulation Platform

13,938 bytes

// 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;
}

SHA-256aea706658a1d0a05357e3a572e631e8722c076e10351b59ef30ebf19ac8188b6

A closer look

Open original