web-a2e 1.0.0

package/tests/integration/test_emulator_debug.cpp

@@ -0,0 +1,344 @@
+/*
+ * test_emulator_debug.cpp - Integration tests for Emulator debug features
+ *
+ * Tests breakpoints, watchpoints, beam breakpoints, trace logging,
+ * cycle profiling, step over, step out, and related debug state.
+ */
+
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+
+#include "emulator.hpp"
+
+#include <memory>
+
+using namespace a2e;
+
+// Helper: create an initialized emulator ready for testing
+static std::unique_ptr<Emulator> makeEmulator() {
+    auto emu = std::make_unique<Emulator>();
+    emu->init();
+    return emu;
+}
+
+// ---------------------------------------------------------------------------
+// Breakpoints
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Breakpoint triggers when PC reaches address", "[emulator][debug][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    // Write a JMP $0400 loop at $0400: 4C 00 04
+    emu.writeMemory(0x0400, 0x4C); // JMP
+    emu.writeMemory(0x0401, 0x00); // low byte
+    emu.writeMemory(0x0402, 0x04); // high byte
+
+    // Set PC to $0400 and add breakpoint there
+    emu.setPC(0x0400);
+    emu.addBreakpoint(0x0400);
+
+    // Need to unpause since breakpoints pause on hit
+    // The first execution should immediately hit the breakpoint
+    emu.runCycles(100);
+
+    REQUIRE(emu.isBreakpointHit());
+    REQUIRE(emu.getBreakpointAddress() == 0x0400);
+}
+
+TEST_CASE("removeBreakpoint prevents breakpoint from triggering", "[emulator][debug][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    // Write NOP sled at $0400
+    for (int i = 0; i < 16; i++) {
+        emu.writeMemory(0x0400 + i, 0xEA); // NOP
+    }
+    // End with JMP $0400
+    emu.writeMemory(0x0410, 0x4C);
+    emu.writeMemory(0x0411, 0x00);
+    emu.writeMemory(0x0412, 0x04);
+
+    emu.setPC(0x0400);
+    emu.addBreakpoint(0x0408);
+
+    // Run - breakpoint should hit at $0408
+    emu.runCycles(100);
+    REQUIRE(emu.isBreakpointHit());
+    REQUIRE(emu.getBreakpointAddress() == 0x0408);
+
+    // Remove it and resume
+    emu.removeBreakpoint(0x0408);
+    emu.setPaused(false);
+    emu.runCycles(1000);
+
+    // Should NOT hit a breakpoint now (will just loop)
+    REQUIRE_FALSE(emu.isBreakpointHit());
+}
+
+TEST_CASE("enableBreakpoint(false) prevents breakpoint from triggering", "[emulator][debug][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    // NOP sled + JMP loop
+    for (int i = 0; i < 16; i++) {
+        emu.writeMemory(0x0400 + i, 0xEA);
+    }
+    emu.writeMemory(0x0410, 0x4C);
+    emu.writeMemory(0x0411, 0x00);
+    emu.writeMemory(0x0412, 0x04);
+
+    emu.setPC(0x0400);
+    emu.addBreakpoint(0x0408);
+    emu.enableBreakpoint(0x0408, false); // disable it
+
+    emu.runCycles(1000);
+    REQUIRE_FALSE(emu.isBreakpointHit());
+}
+
+TEST_CASE("getBreakpointAddress returns correct address on hit", "[emulator][debug][breakpoint]") {
+    Emulator emu;
+    emu.init();
+
+    emu.writeMemory(0x0500, 0x4C);
+    emu.writeMemory(0x0501, 0x00);
+    emu.writeMemory(0x0502, 0x05);
+
+    emu.setPC(0x0500);
+    emu.addBreakpoint(0x0500);
+    emu.runCycles(100);
+
+    REQUIRE(emu.isBreakpointHit());
+    REQUIRE(emu.getBreakpointAddress() == 0x0500);
+}
+
+// ---------------------------------------------------------------------------
+// Watchpoints
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Watchpoint triggers on write to watched address", "[emulator][debug][watchpoint]") {
+    Emulator emu;
+    emu.init();
+
+    // Add a write watchpoint on $0400
+    emu.addWatchpoint(0x0400, 0x0400, Emulator::WP_WRITE);
+
+    // Write a small program at $0300 that writes to $0400 then loops:
+    //   LDA #$42      ; A9 42
+    //   STA $0400     ; 8D 00 04
+    //   JMP $0305     ; 4C 05 03
+    emu.writeMemory(0x0300, 0xA9);
+    emu.writeMemory(0x0301, 0x42);
+    emu.writeMemory(0x0302, 0x8D);
+    emu.writeMemory(0x0303, 0x00);
+    emu.writeMemory(0x0304, 0x04);
+    emu.writeMemory(0x0305, 0x4C);
+    emu.writeMemory(0x0306, 0x05);
+    emu.writeMemory(0x0307, 0x03);
+
+    emu.setPC(0x0300);
+    emu.runCycles(100);
+
+    REQUIRE(emu.isWatchpointHit());
+    REQUIRE(emu.getWatchpointAddress() == 0x0400);
+}
+
+TEST_CASE("clearWatchpoints removes all watchpoints", "[emulator][debug][watchpoint]") {
+    Emulator emu;
+    emu.init();
+
+    emu.addWatchpoint(0x0400, 0x0400, Emulator::WP_WRITE);
+    emu.clearWatchpoints();
+
+    // Write to $0400 via a small program
+    emu.writeMemory(0x0300, 0xA9); // LDA #$42
+    emu.writeMemory(0x0301, 0x42);
+    emu.writeMemory(0x0302, 0x8D); // STA $0400
+    emu.writeMemory(0x0303, 0x00);
+    emu.writeMemory(0x0304, 0x04);
+    emu.writeMemory(0x0305, 0x4C); // JMP $0305
+    emu.writeMemory(0x0306, 0x05);
+    emu.writeMemory(0x0307, 0x03);
+
+    emu.setPC(0x0300);
+    emu.runCycles(100);
+
+    REQUIRE_FALSE(emu.isWatchpointHit());
+}
+
+// ---------------------------------------------------------------------------
+// Beam breakpoints
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Beam breakpoint triggers at specified scanline", "[emulator][debug][beam]") {
+    Emulator emu;
+    emu.init();
+
+    // Add beam breakpoint at scanline 100, any hPos (-1 = wildcard)
+    int32_t id = emu.addBeamBreakpoint(100, -1);
+    REQUIRE(id >= 0);
+
+    // Run enough cycles for the beam to reach scanline 100
+    // 100 scanlines * 65 cycles/scanline = 6500 cycles minimum
+    emu.runCycles(17030); // One full frame
+
+    REQUIRE(emu.isBeamBreakpointHit());
+}
+
+TEST_CASE("removeBeamBreakpoint prevents beam break from triggering", "[emulator][debug][beam]") {
+    Emulator emu;
+    emu.init();
+
+    int32_t id = emu.addBeamBreakpoint(100, -1);
+    emu.removeBeamBreakpoint(id);
+
+    emu.runCycles(17030);
+
+    REQUIRE_FALSE(emu.isBeamBreakpointHit());
+}
+
+TEST_CASE("clearAllBeamBreakpoints clears all beam breaks", "[emulator][debug][beam]") {
+    Emulator emu;
+    emu.init();
+
+    emu.addBeamBreakpoint(50, -1);
+    emu.addBeamBreakpoint(100, -1);
+    emu.clearAllBeamBreakpoints();
+
+    emu.runCycles(17030);
+
+    REQUIRE_FALSE(emu.isBeamBreakpointHit());
+}
+
+// ---------------------------------------------------------------------------
+// Trace log
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Trace records entries when enabled", "[emulator][debug][trace]") {
+    Emulator emu;
+    emu.init();
+
+    emu.setTraceEnabled(true);
+    emu.runCycles(200);
+
+    REQUIRE(emu.getTraceCount() > 0);
+    REQUIRE(emu.getTraceBuffer() != nullptr);
+    REQUIRE(emu.getTraceCapacity() > 0);
+}
+
+TEST_CASE("clearTrace resets trace count to zero", "[emulator][debug][trace]") {
+    Emulator emu;
+    emu.init();
+
+    emu.setTraceEnabled(true);
+    emu.runCycles(200);
+    REQUIRE(emu.getTraceCount() > 0);
+
+    emu.clearTrace();
+    REQUIRE(emu.getTraceCount() == 0);
+}
+
+// ---------------------------------------------------------------------------
+// Cycle profiling
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Profiling records cycles when enabled", "[emulator][debug][profile]") {
+    Emulator emu;
+    emu.init();
+
+    emu.setProfileEnabled(true);
+    emu.clearProfile();
+    emu.runCycles(1000);
+
+    // Check that at least one address has non-zero cycle counts
+    const uint32_t* profile = emu.getProfileCycles();
+    REQUIRE(profile != nullptr);
+
+    bool hasNonZero = false;
+    for (int i = 0; i < 65536; i++) {
+        if (profile[i] > 0) {
+            hasNonZero = true;
+            break;
+        }
+    }
+    REQUIRE(hasNonZero);
+}
+
+TEST_CASE("clearProfile resets all profile cycle counts", "[emulator][debug][profile]") {
+    Emulator emu;
+    emu.init();
+
+    emu.setProfileEnabled(true);
+    emu.runCycles(1000);
+    emu.clearProfile();
+
+    const uint32_t* profile = emu.getProfileCycles();
+    bool allZero = true;
+    for (int i = 0; i < 65536; i++) {
+        if (profile[i] != 0) {
+            allZero = false;
+            break;
+        }
+    }
+    REQUIRE(allZero);
+}
+
+// ---------------------------------------------------------------------------
+// Step Over
+// ---------------------------------------------------------------------------
+
+TEST_CASE("stepOver on JSR sets temp breakpoint after JSR", "[emulator][debug][stepover]") {
+    Emulator emu;
+    emu.init();
+
+    // Write JSR $0500 at $0400
+    emu.writeMemory(0x0400, 0x20); // JSR
+    emu.writeMemory(0x0401, 0x00); // low byte
+    emu.writeMemory(0x0402, 0x05); // high byte
+    // Write NOP at $0403
+    emu.writeMemory(0x0403, 0xEA);
+
+    // Write RTS at $0500 so the subroutine returns
+    emu.writeMemory(0x0500, 0x60); // RTS
+
+    emu.setPC(0x0400);
+    emu.setPaused(true);
+
+    uint16_t tempBp = emu.stepOver();
+
+    // stepOver on JSR should set temp breakpoint at PC+3 = $0403
+    REQUIRE(tempBp == 0x0403);
+}
+
+// ---------------------------------------------------------------------------
+// Step Out
+// ---------------------------------------------------------------------------
+
+TEST_CASE("stepOut sets temp breakpoint at return address from stack", "[emulator][debug][stepout]") {
+    Emulator emu;
+    emu.init();
+
+    // Simulate being inside a subroutine:
+    // Push a fake return address (e.g., $04FF, since RTS adds 1 -> $0500)
+    // onto the stack.
+    uint8_t sp = emu.getSP();
+
+    // Push high byte then low byte (as JSR does)
+    emu.writeMemory(0x0100 + sp, 0x04);   // PCH
+    sp--;
+    emu.writeMemory(0x0100 + sp, 0xFF);   // PCL
+    sp--;
+    emu.setSP(sp);
+
+    // Write a NOP loop at current PC
+    uint16_t pc = emu.getPC();
+    emu.writeMemory(pc, 0xEA);     // NOP
+    emu.writeMemory(pc + 1, 0xEA); // NOP
+
+    emu.setPaused(true);
+
+    uint16_t tempBp = emu.stepOut();
+
+    // stepOut reads stack: (PCL,PCH) = ($FF,$04) -> $04FF + 1 = $0500
+    REQUIRE(tempBp == 0x0500);
+}

package/tests/integration/test_emulator_disk.cpp

@@ -0,0 +1,153 @@
+/*
+ * test_emulator_disk.cpp - Integration tests for Emulator disk operations
+ *
+ * Tests disk insert, eject, blank disk creation, two-drive support,
+ * filename tracking, SmartPort, and error handling through the
+ * Emulator facade.
+ */
+
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+
+#include "emulator.hpp"
+
+#include <cstring>
+#include <vector>
+
+using namespace a2e;
+
+// Standard DSK image size: 35 tracks * 16 sectors * 256 bytes
+static constexpr size_t DSK_SIZE = 143360;
+
+// Helper: create a valid-sized DSK image filled with a byte value
+static std::vector<uint8_t> makeDskImage(uint8_t fill = 0x00) {
+    return std::vector<uint8_t>(DSK_SIZE, fill);
+}
+
+// ---------------------------------------------------------------------------
+// Insert disk
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator insertDisk succeeds with valid DSK data", "[emulator][disk]") {
+    Emulator emu;
+    emu.init();
+
+    auto img = makeDskImage();
+    bool result = emu.insertDisk(0, img.data(), img.size(), "test.dsk");
+    REQUIRE(result);
+}
+
+TEST_CASE("Emulator getDiskFilename returns inserted filename", "[emulator][disk]") {
+    Emulator emu;
+    emu.init();
+
+    auto img = makeDskImage();
+    emu.insertDisk(0, img.data(), img.size(), "test.dsk");
+
+    const char* name = emu.getDiskFilename(0);
+    REQUIRE(name != nullptr);
+    REQUIRE(std::string(name) == "test.dsk");
+}
+
+// ---------------------------------------------------------------------------
+// Eject disk
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator ejectDisk clears the drive", "[emulator][disk]") {
+    Emulator emu;
+    emu.init();
+
+    auto img = makeDskImage();
+    emu.insertDisk(0, img.data(), img.size(), "test.dsk");
+    emu.ejectDisk(0);
+
+    // After ejecting, getDiskData should return nullptr
+    size_t dataSize = 0;
+    const uint8_t* data = emu.getDiskData(0, &dataSize);
+    REQUIRE(data == nullptr);
+}
+
+// ---------------------------------------------------------------------------
+// Blank disk
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator insertBlankDisk succeeds", "[emulator][disk]") {
+    Emulator emu;
+    emu.init();
+
+    bool result = emu.insertBlankDisk(0);
+    REQUIRE(result);
+}
+
+// ---------------------------------------------------------------------------
+// Two drives
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator supports two drives simultaneously", "[emulator][disk]") {
+    Emulator emu;
+    emu.init();
+
+    auto img0 = makeDskImage(0x00);
+    auto img1 = makeDskImage(0xFF);
+
+    bool r0 = emu.insertDisk(0, img0.data(), img0.size(), "disk1.dsk");
+    bool r1 = emu.insertDisk(1, img1.data(), img1.size(), "disk2.dsk");
+
+    REQUIRE(r0);
+    REQUIRE(r1);
+
+    REQUIRE(std::string(emu.getDiskFilename(0)) == "disk1.dsk");
+    REQUIRE(std::string(emu.getDiskFilename(1)) == "disk2.dsk");
+}
+
+// ---------------------------------------------------------------------------
+// getDisk reference
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator getDisk returns a valid Disk2Card reference", "[emulator][disk]") {
+    Emulator emu;
+    emu.init();
+
+    Disk2Card& disk = emu.getDisk();
+    REQUIRE(std::string(disk.getName()) == "Disk II");
+}
+
+// ---------------------------------------------------------------------------
+// SmartPort
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator isSmartPortCardInstalled reflects slot configuration", "[emulator][disk][smartport]") {
+    Emulator emu;
+    emu.init();
+
+    // By default, SmartPort is not installed (no card in slot 7)
+    // The result depends on default configuration
+    // Just verify the method is callable without crashing
+    bool installed = emu.isSmartPortCardInstalled();
+
+    if (installed) {
+        // If SmartPort is installed, insertSmartPortImage should be callable
+        // (actual success depends on data validity)
+        std::vector<uint8_t> hdvData(512 * 280, 0x00); // Minimal ProDOS volume
+        // This may or may not succeed depending on image validation
+        emu.insertSmartPortImage(0, hdvData.data(), hdvData.size(), "test.hdv");
+    }
+
+    // Either way, no crash
+    REQUIRE(true);
+}
+
+// ---------------------------------------------------------------------------
+// Invalid data
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator insertDisk with invalid size returns false", "[emulator][disk]") {
+    Emulator emu;
+    emu.init();
+
+    // A DSK image must be exactly 143360 bytes (or a valid NIB/WOZ size)
+    // An arbitrary size should be rejected
+    std::vector<uint8_t> badData(1000, 0x00);
+    bool result = emu.insertDisk(0, badData.data(), badData.size(), "bad.dsk");
+    REQUIRE_FALSE(result);
+}

package/tests/integration/test_emulator_state.cpp

@@ -0,0 +1,163 @@
+/*
+ * test_emulator_state.cpp - Integration tests for Emulator state serialization
+ *
+ * Tests exportState, importState, round-trip fidelity, CPU state preservation,
+ * and error handling for invalid data.
+ */
+
+#define CATCH_CONFIG_MAIN
+#include "catch.hpp"
+
+#include "emulator.hpp"
+
+#include <cstring>
+#include <vector>
+
+using namespace a2e;
+
+// ---------------------------------------------------------------------------
+// Export state
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator exportState returns non-null data with size > 0", "[emulator][state]") {
+    Emulator emu;
+    emu.init();
+
+    size_t size = 0;
+    const uint8_t* data = emu.exportState(&size);
+
+    REQUIRE(data != nullptr);
+    REQUIRE(size > 0);
+}
+
+TEST_CASE("Emulator exportState size is reasonable", "[emulator][state]") {
+    Emulator emu;
+    emu.init();
+
+    size_t size = 0;
+    emu.exportState(&size);
+
+    // State includes 128KB RAM (main + aux), 16KB LC RAM, CPU state,
+    // soft switches, disk state, etc.  Should be at least 128KB.
+    REQUIRE(size >= 128 * 1024);
+    // But not unreasonably large (under 2MB)
+    REQUIRE(size < 2 * 1024 * 1024);
+}
+
+// ---------------------------------------------------------------------------
+// Import state
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator importState accepts previously exported data", "[emulator][state]") {
+    Emulator emu;
+    emu.init();
+
+    size_t size = 0;
+    const uint8_t* data = emu.exportState(&size);
+    REQUIRE(data != nullptr);
+
+    // Copy the exported data since import may reset internal buffers
+    std::vector<uint8_t> stateCopy(data, data + size);
+
+    bool result = emu.importState(stateCopy.data(), stateCopy.size());
+    REQUIRE(result);
+}
+
+// ---------------------------------------------------------------------------
+// Round-trip: memory preserved
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator state round-trip preserves memory", "[emulator][state]") {
+    Emulator emu;
+    emu.init();
+
+    // Write known values to several RAM locations
+    emu.writeMemory(0x0300, 0xDE);
+    emu.writeMemory(0x0301, 0xAD);
+    emu.writeMemory(0x0302, 0xBE);
+    emu.writeMemory(0x0303, 0xEF);
+
+    // Export
+    size_t size = 0;
+    const uint8_t* data = emu.exportState(&size);
+    std::vector<uint8_t> stateCopy(data, data + size);
+
+    // Reset clears memory
+    emu.reset();
+    // Verify memory was cleared (reset re-initializes)
+    // Note: after reset, ROM re-initializes; RAM at $0300 should be cleared
+    REQUIRE(emu.readMemory(0x0300) != 0xDE);
+
+    // Import previously saved state
+    bool result = emu.importState(stateCopy.data(), stateCopy.size());
+    REQUIRE(result);
+
+    // Memory should be restored
+    REQUIRE(emu.readMemory(0x0300) == 0xDE);
+    REQUIRE(emu.readMemory(0x0301) == 0xAD);
+    REQUIRE(emu.readMemory(0x0302) == 0xBE);
+    REQUIRE(emu.readMemory(0x0303) == 0xEF);
+}
+
+// ---------------------------------------------------------------------------
+// Round-trip: CPU state preserved
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator state round-trip preserves CPU registers", "[emulator][state]") {
+    Emulator emu;
+    emu.init();
+
+    // Set specific CPU register values
+    emu.setA(0x42);
+    emu.setX(0x13);
+    emu.setY(0x77);
+
+    // Export
+    size_t size = 0;
+    const uint8_t* data = emu.exportState(&size);
+    std::vector<uint8_t> stateCopy(data, data + size);
+
+    // Reset changes registers
+    emu.reset();
+    REQUIRE(emu.getA() != 0x42);
+
+    // Import
+    bool result = emu.importState(stateCopy.data(), stateCopy.size());
+    REQUIRE(result);
+
+    REQUIRE(emu.getA() == 0x42);
+    REQUIRE(emu.getX() == 0x13);
+    REQUIRE(emu.getY() == 0x77);
+}
+
+// ---------------------------------------------------------------------------
+// Invalid data
+// ---------------------------------------------------------------------------
+
+TEST_CASE("Emulator importState rejects garbage data", "[emulator][state]") {
+    Emulator emu;
+    emu.init();
+
+    // Create garbage data that does not have a valid magic header
+    std::vector<uint8_t> garbage(1024, 0xFF);
+    bool result = emu.importState(garbage.data(), garbage.size());
+    REQUIRE_FALSE(result);
+}
+
+TEST_CASE("Emulator importState rejects too-small data", "[emulator][state]") {
+    Emulator emu;
+    emu.init();
+
+    // Data smaller than the minimum header (8 bytes for magic + version)
+    std::vector<uint8_t> tooSmall(4, 0x00);
+    bool result = emu.importState(tooSmall.data(), tooSmall.size());
+    REQUIRE_FALSE(result);
+}
+
+TEST_CASE("Emulator importState rejects empty data", "[emulator][state]") {
+    Emulator emu;
+    emu.init();
+
+    bool result = emu.importState(nullptr, 0);
+    REQUIRE_FALSE(result);
+}