web-a2e 1.0.0

package/src/core/cards/mockingboard/via6522.hpp

@@ -0,0 +1,163 @@
+/*
+ * via6522.hpp - VIA 6522 timer chip emulation
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <functional>
+
+namespace a2e {
+
+// Forward declaration
+class AY8910;
+
+// 6522 VIA (Versatile Interface Adapter) emulation
+// Two of these are used in the Mockingboard, each controlling one AY-3-8910
+class VIA6522 {
+public:
+    using IRQCallback = std::function<void()>;
+
+    VIA6522();
+
+    // Set VIA ID for debug logging (1 or 2)
+    void setViaId(int id);
+
+    // Enable/disable console debug logging
+    static void setDebugLogging(bool enabled);
+
+    // Register access
+    uint8_t read(uint8_t reg);
+    void write(uint8_t reg, uint8_t value);
+
+    // Timer update (call with CPU cycles elapsed)
+    void update(int cycles);
+
+    // Connect to PSG chip
+    void connectPSG(AY8910* psg) { psg_ = psg; }
+
+    // IRQ callback
+    void setIRQCallback(IRQCallback cb) { irqCallback_ = std::move(cb); }
+
+    // Reset
+    void reset();
+
+    // Check if IRQ is active
+    bool isIRQActive() const { return (ifr_ & ier_ & 0x7F) != 0; }
+
+    // Debug accessors
+    uint8_t getORA() const { return ora_; }
+    uint8_t getORB() const { return orb_; }
+    uint8_t getDDRA() const { return ddra_; }
+    uint8_t getDDRB() const { return ddrb_; }
+
+    // State serialization
+    size_t exportState(uint8_t* buffer) const;
+    void importState(const uint8_t* buffer);
+    static constexpr size_t STATE_SIZE = 32;
+
+    // Timer debug accessors
+    uint16_t getT1Counter() const { return t1Counter_; }
+    uint16_t getT1Latch() const { return t1Latch_; }
+    bool isT1Running() const { return t1Running_; }
+    bool hasT1Fired() const { return t1Fired_; }
+    uint8_t getACR() const { return acr_; }
+    uint8_t getIFR() const { return ifr_; }
+    uint8_t getIER() const { return ier_; }
+
+private:
+    // Register addresses
+    static constexpr int REG_ORB = 0x00;   // Output Register B / Input Register B
+    static constexpr int REG_ORA = 0x01;   // Output Register A / Input Register A
+    static constexpr int REG_DDRB = 0x02;  // Data Direction Register B
+    static constexpr int REG_DDRA = 0x03;  // Data Direction Register A
+    static constexpr int REG_T1CL = 0x04;  // Timer 1 Counter Low
+    static constexpr int REG_T1CH = 0x05;  // Timer 1 Counter High
+    static constexpr int REG_T1LL = 0x06;  // Timer 1 Latch Low
+    static constexpr int REG_T1LH = 0x07;  // Timer 1 Latch High
+    static constexpr int REG_T2CL = 0x08;  // Timer 2 Counter Low
+    static constexpr int REG_T2CH = 0x09;  // Timer 2 Counter High
+    static constexpr int REG_SR = 0x0A;    // Shift Register
+    static constexpr int REG_ACR = 0x0B;   // Auxiliary Control Register
+    static constexpr int REG_PCR = 0x0C;   // Peripheral Control Register
+    static constexpr int REG_IFR = 0x0D;   // Interrupt Flag Register
+    static constexpr int REG_IER = 0x0E;   // Interrupt Enable Register
+    static constexpr int REG_ORA_NH = 0x0F; // Output Register A (no handshake)
+
+    // IRQ flag bits
+    static constexpr uint8_t IRQ_CA2 = 0x01;
+    static constexpr uint8_t IRQ_CA1 = 0x02;
+    static constexpr uint8_t IRQ_SR = 0x04;
+    static constexpr uint8_t IRQ_CB2 = 0x08;
+    static constexpr uint8_t IRQ_CB1 = 0x10;
+    static constexpr uint8_t IRQ_T2 = 0x20;
+    static constexpr uint8_t IRQ_T1 = 0x40;
+    static constexpr uint8_t IRQ_ANY = 0x80;
+
+    // Port registers
+    uint8_t ora_ = 0;    // Output Register A
+    uint8_t orb_ = 0;    // Output Register B
+    uint8_t ddra_ = 0;   // Data Direction Register A (1 = output)
+    uint8_t ddrb_ = 0;   // Data Direction Register B (1 = output)
+    uint8_t ira_ = 0;    // Input Register A (external input)
+    uint8_t irb_ = 0;    // Input Register B (external input)
+
+    // Timer 1
+    uint16_t t1Counter_ = 0xFFFF;
+    uint16_t t1Latch_ = 0xFFFF;
+    bool t1Running_ = false;
+    bool t1Fired_ = false;
+
+    // Timer 2
+    uint16_t t2Counter_ = 0xFFFF;
+    uint8_t t2LatchLow_ = 0xFF;
+    bool t2Running_ = false;
+    bool t2Fired_ = false;
+
+    // Shift register
+    uint8_t sr_ = 0;
+
+    // Control registers
+    uint8_t acr_ = 0;   // Auxiliary Control Register
+    uint8_t pcr_ = 0;   // Peripheral Control Register
+    uint8_t ifr_ = 0;   // Interrupt Flag Register
+    uint8_t ier_ = 0;   // Interrupt Enable Register
+
+    // Connected PSG
+    AY8910* psg_ = nullptr;
+
+    // IRQ callback
+    IRQCallback irqCallback_;
+
+    // Helper methods
+    void updatePSG();
+    void checkIRQ();
+
+    // Previous PSG control state for edge detection
+    uint8_t prevPsgControl_ = 0;
+
+    // Track if a valid PSG address was latched (AppleWin-style)
+    bool psgAddressLatched_ = false;
+
+    // PSG state machine: operations only execute from INACTIVE state
+    enum PsgState { PSG_INACTIVE, PSG_READ, PSG_WRITE, PSG_LATCH };
+    PsgState psgState_ = PSG_INACTIVE;
+
+    // Bus-driven flag: true when PSG is driving port A data (READ state)
+    bool busDriven_ = false;
+
+    // Previous IRQ state for edge detection (only trigger on 0->1 transition)
+    bool prevIrqActive_ = false;
+
+    // IRQ delay - matches AppleWin's CheckTimerUnderflow behavior
+    int t1IrqDelay_ = 0;
+    int t2IrqDelay_ = 0;
+
+    // VIA identifier for debug logging
+    int viaId_ = 1;
+};
+
+} // namespace a2e

package/src/core/cards/mockingboard_card.cpp

@@ -0,0 +1,312 @@
+/*
+ * mockingboard_card.cpp - Mockingboard sound card implementation
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+#include "mockingboard_card.hpp"
+#include <cstring>
+#include <algorithm>
+
+namespace a2e {
+
+MockingboardCard::MockingboardCard() {
+    // Set IDs for debug logging
+    psg1_.setPsgId(1);
+    psg2_.setPsgId(2);
+    via1_.setViaId(1);
+    via2_.setViaId(2);
+
+    // Connect PSGs to VIAs
+    via1_.connectPSG(&psg1_);
+    via2_.connectPSG(&psg2_);
+
+    reset();
+}
+
+void MockingboardCard::setDebugLogging(bool enabled) {
+    AY8910::setDebugLogging(enabled);
+    VIA6522::setDebugLogging(enabled);
+}
+
+uint8_t MockingboardCard::readIO(uint8_t offset) {
+    // Mockingboard doesn't use I/O space ($C0C0-$C0CF)
+    // It uses ROM space for VIA registers
+    (void)offset;
+    return 0xFF;
+}
+
+void MockingboardCard::writeIO(uint8_t offset, uint8_t value) {
+    // Mockingboard doesn't use I/O space
+    (void)offset;
+    (void)value;
+}
+
+uint8_t MockingboardCard::peekIO(uint8_t offset) const {
+    (void)offset;
+    return 0xFF;
+}
+
+uint8_t MockingboardCard::readROM(uint8_t offset) {
+    if (!enabled_) return 0xFF;
+
+    // Address decoding for slot ROM space
+    // VIA 1 is mirrored at $C400-$C47F (active when bit 7 = 0)
+    // VIA 2 is mirrored at $C480-$C4FF (active when bit 7 = 1)
+    // Register is determined by bits 0-3
+
+    uint8_t reg = offset & 0x0F;
+
+    if ((offset & 0x80) == 0) {
+        // VIA 1 ($C400-$C47F)
+        return via1_.read(reg);
+    } else {
+        // VIA 2 ($C480-$C4FF)
+        return via2_.read(reg);
+    }
+}
+
+void MockingboardCard::writeROM(uint8_t offset, uint8_t value) {
+    if (!enabled_) return;
+
+    uint8_t reg = offset & 0x0F;
+
+    if ((offset & 0x80) == 0) {
+        // VIA 1 ($C400-$C47F)
+        via1_.write(reg, value);
+    } else {
+        // VIA 2 ($C480-$C4FF)
+        via2_.write(reg, value);
+    }
+}
+
+void MockingboardCard::reset() {
+    via1_.reset();
+    via2_.reset();
+    psg1_.reset();
+    psg2_.reset();
+    cycleAccum_ = 0.0;
+    sampleAccum_.clear();
+    sampleReadPos_ = 0;
+    dcStateL_ = 0.0f;
+    dcStateR_ = 0.0f;
+}
+
+bool MockingboardCard::arePsgsIdentical() const {
+    // Compare sound registers 0-13 (skip I/O ports 14-15)
+    for (int i = 0; i < 14; i++) {
+        if (psg1_.getRegister(i) != psg2_.getRegister(i)) return false;
+    }
+    return true;
+}
+
+void MockingboardCard::update(int cycles) {
+    if (!enabled_) return;
+
+    via1_.update(cycles);
+    via2_.update(cycles);
+
+    // Incremental audio generation: accumulate CPU cycles and generate
+    // audio samples at 48kHz rate. This ensures PSG register changes
+    // from VIA timer IRQ handlers are immediately reflected in output.
+    cycleAccum_ += cycles;
+    while (cycleAccum_ >= CYCLES_PER_SAMPLE) {
+        cycleAccum_ -= CYCLES_PER_SAMPLE;
+
+        float left = psg1_.generateSingleSample();
+        float right = psg2_.generateSingleSample();
+
+        // When both PSGs are programmed identically, use PSG1's output
+        // for both channels to eliminate phase cancellation from
+        // independent tone counters
+        if (arePsgsIdentical()) {
+            right = left;
+        }
+
+        sampleAccum_.push_back(left);
+        sampleAccum_.push_back(right);
+    }
+}
+
+void MockingboardCard::setIRQCallback(IRQCallback callback) {
+    // Both VIAs can trigger IRQ
+    via1_.setIRQCallback(callback);
+    via2_.setIRQCallback(callback);
+}
+
+bool MockingboardCard::isIRQActive() const {
+    return enabled_ && (via1_.isIRQActive() || via2_.isIRQActive());
+}
+
+size_t MockingboardCard::getStateSize() const {
+    return STATE_SIZE;
+}
+
+size_t MockingboardCard::serialize(uint8_t* buffer, size_t maxSize) const {
+    if (maxSize < STATE_SIZE) return 0;
+
+    size_t offset = 0;
+
+    // Enabled flag
+    buffer[offset++] = enabled_ ? 1 : 0;
+
+    // VIA1 and PSG1
+    offset += via1_.exportState(buffer + offset);
+    offset += psg1_.exportState(buffer + offset);
+
+    // VIA2 and PSG2
+    offset += via2_.exportState(buffer + offset);
+    offset += psg2_.exportState(buffer + offset);
+
+    return offset;
+}
+
+size_t MockingboardCard::deserialize(const uint8_t* buffer, size_t size) {
+    if (size < STATE_SIZE) return 0;
+
+    size_t offset = 0;
+
+    // Enabled flag
+    enabled_ = buffer[offset++] != 0;
+
+    // VIA1 and PSG1
+    via1_.importState(buffer + offset);
+    offset += VIA6522::STATE_SIZE;
+    psg1_.importState(buffer + offset);
+    offset += AY8910::STATE_SIZE;
+
+    // VIA2 and PSG2
+    via2_.importState(buffer + offset);
+    offset += VIA6522::STATE_SIZE;
+    psg2_.importState(buffer + offset);
+    offset += AY8910::STATE_SIZE;
+
+    // Reset DC filter state for clean audio restart
+    dcStateL_ = 0.0f;
+    dcStateR_ = 0.0f;
+
+    return offset;
+}
+
+void MockingboardCard::generateStereoSamples(float* buffer, int count, int sampleRate) {
+    if (!enabled_ || count <= 0) {
+        for (int i = 0; i < count * 2; i++) {
+            buffer[i] = 0.0f;
+        }
+        return;
+    }
+
+    if (static_cast<int>(audioBuffer1_.size()) < count) {
+        audioBuffer1_.resize(count);
+    }
+    if (static_cast<int>(audioBuffer2_.size()) < count) {
+        audioBuffer2_.resize(count);
+    }
+
+    psg1_.generateSamples(audioBuffer1_.data(), count, sampleRate);
+    psg2_.generateSamples(audioBuffer2_.data(), count, sampleRate);
+
+    bool identical = arePsgsIdentical();
+    for (int i = 0; i < count; i++) {
+        float left  = audioBuffer1_[i];
+        float right = identical ? left : audioBuffer2_[i];
+
+        // DC offset removal
+        dcStateL_ = DC_ALPHA * dcStateL_ + (1.0f - DC_ALPHA) * left;
+        dcStateR_ = DC_ALPHA * dcStateR_ + (1.0f - DC_ALPHA) * right;
+        buffer[i * 2]     = left - dcStateL_;
+        buffer[i * 2 + 1] = right - dcStateR_;
+    }
+}
+
+void MockingboardCard::generateStereoSamples(float* buffer, int count, int sampleRate, uint64_t startCycle, uint64_t endCycle) {
+    if (!enabled_ || count <= 0) {
+        for (int i = 0; i < count * 2; i++) {
+            buffer[i] = 0.0f;
+        }
+        return;
+    }
+
+    if (static_cast<int>(audioBuffer1_.size()) < count) {
+        audioBuffer1_.resize(count);
+    }
+    if (static_cast<int>(audioBuffer2_.size()) < count) {
+        audioBuffer2_.resize(count);
+    }
+
+    // Generate with proper timing
+    psg1_.generateSamples(audioBuffer1_.data(), count, sampleRate, startCycle, endCycle);
+    psg2_.generateSamples(audioBuffer2_.data(), count, sampleRate, startCycle, endCycle);
+
+    bool identical = arePsgsIdentical();
+    for (int i = 0; i < count; i++) {
+        float left  = audioBuffer1_[i];
+        float right = identical ? left : audioBuffer2_[i];
+
+        // DC offset removal
+        dcStateL_ = DC_ALPHA * dcStateL_ + (1.0f - DC_ALPHA) * left;
+        dcStateR_ = DC_ALPHA * dcStateR_ + (1.0f - DC_ALPHA) * right;
+        buffer[i * 2]     = left - dcStateL_;
+        buffer[i * 2 + 1] = right - dcStateR_;
+    }
+}
+
+int MockingboardCard::consumeStereoSamples(float* buffer, int frameCount) {
+    if (!enabled_ || frameCount <= 0) {
+        for (int i = 0; i < frameCount * 2; i++) {
+            buffer[i] = 0.0f;
+        }
+        return frameCount;
+    }
+
+    int availableFrames = static_cast<int>((sampleAccum_.size() - sampleReadPos_) / 2);
+    int framesToCopy = std::min(frameCount, availableFrames);
+
+    // Copy available accumulated samples
+    if (framesToCopy > 0) {
+        std::memcpy(buffer, sampleAccum_.data() + sampleReadPos_,
+                    framesToCopy * 2 * sizeof(float));
+        sampleReadPos_ += framesToCopy * 2;
+    }
+
+    // If we need more samples than accumulated, generate the remainder on the spot
+    // (handles slight timing drift between CPU execution and audio requests)
+    if (framesToCopy < frameCount) {
+        bool identical = arePsgsIdentical();
+        for (int i = framesToCopy; i < frameCount; i++) {
+            float left = psg1_.generateSingleSample();
+            float right = identical ? left : psg2_.generateSingleSample();
+            buffer[i * 2] = left;
+            buffer[i * 2 + 1] = right;
+        }
+    }
+
+    // DC offset removal converts unipolar PSG output to bipolar for audio playback.
+    // Identity check was already applied during accumulation in update() and
+    // in the overflow path above.
+    for (int i = 0; i < frameCount; i++) {
+        float left  = buffer[i * 2];
+        float right = buffer[i * 2 + 1];
+
+        dcStateL_ = DC_ALPHA * dcStateL_ + (1.0f - DC_ALPHA) * left;
+        dcStateR_ = DC_ALPHA * dcStateR_ + (1.0f - DC_ALPHA) * right;
+        buffer[i * 2]     = left - dcStateL_;
+        buffer[i * 2 + 1] = right - dcStateR_;
+    }
+
+    // Compact the buffer: remove consumed samples
+    if (sampleReadPos_ > 0) {
+        size_t remaining = sampleAccum_.size() - sampleReadPos_;
+        if (remaining > 0) {
+            std::memmove(sampleAccum_.data(), sampleAccum_.data() + sampleReadPos_,
+                         remaining * sizeof(float));
+        }
+        sampleAccum_.resize(remaining);
+        sampleReadPos_ = 0;
+    }
+
+    return frameCount;
+}
+
+} // namespace a2e

package/src/core/cards/mockingboard_card.hpp

@@ -0,0 +1,159 @@
+/*
+ * mockingboard_card.hpp - Mockingboard sound card
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+#pragma once
+
+#include "expansion_card.hpp"
+#include "mockingboard/via6522.hpp"
+#include "mockingboard/ay8910.hpp"
+#include <vector>
+
+namespace a2e {
+
+/**
+ * MockingboardCard - Mockingboard Sound Card
+ *
+ * Implements the ExpansionCard interface with direct ownership of VIA/PSG chips.
+ * The Mockingboard typically occupies slot 4, providing:
+ * - I/O space: $C0C0-$C0CF (unused - Mockingboard uses ROM space for VIA access)
+ *
+ * Note: The Mockingboard is unusual in that it uses the slot ROM space
+ * ($C400-$C4FF) for its VIA registers rather than the I/O space ($C0C0-$C0CF).
+ * This is because it needs more than 16 bytes of address space.
+ *
+ * VIA 1: $C400-$C47F (bit 7 = 0) - left channel PSG
+ * VIA 2: $C480-$C4FF (bit 7 = 1) - right channel PSG
+ */
+class MockingboardCard : public ExpansionCard {
+public:
+    using CycleCallback = std::function<uint64_t()>;
+
+    // State size for serialization: enabled(1) + VIA1(32) + PSG1(48) + VIA2(32) + PSG2(48) = 161
+    static constexpr size_t STATE_SIZE = 161;
+
+    MockingboardCard();
+    ~MockingboardCard() override = default;
+
+    // Delete copy
+    MockingboardCard(const MockingboardCard&) = delete;
+    MockingboardCard& operator=(const MockingboardCard&) = delete;
+
+    // Allow move
+    MockingboardCard(MockingboardCard&&) = default;
+    MockingboardCard& operator=(MockingboardCard&&) = default;
+
+    // ===== ExpansionCard Interface =====
+
+    // I/O space ($C0C0-$C0CF) - Mockingboard doesn't use this
+    uint8_t readIO(uint8_t offset) override;
+    void writeIO(uint8_t offset, uint8_t value) override;
+    uint8_t peekIO(uint8_t offset) const override;
+
+    // ROM space ($C400-$C4FF) - Contains VIA registers
+    uint8_t readROM(uint8_t offset) override;
+    void writeROM(uint8_t offset, uint8_t value) override;
+    bool hasROM() const override { return true; }
+
+    bool hasExpansionROM() const override { return false; }
+
+    void reset() override;
+    void update(int cycles) override;
+
+    void setIRQCallback(IRQCallback callback) override;
+    void setCycleCallback(CycleCallback callback) override {
+        cycleCallback_ = callback;
+        // Pass to PSGs for timestamped register writes
+        psg1_.setCycleCallback(callback);
+        psg2_.setCycleCallback(callback);
+    }
+
+    bool isIRQActive() const override;
+
+    size_t getStateSize() const override;
+    size_t serialize(uint8_t* buffer, size_t maxSize) const override;
+    size_t deserialize(const uint8_t* buffer, size_t size) override;
+
+    const char* getName() const override { return "Mockingboard"; }
+    uint8_t getPreferredSlot() const override { return 4; }
+
+    bool isEnabled() const override { return enabled_; }
+    void setEnabled(bool enabled) override { enabled_ = enabled; }
+
+    // ===== Audio Generation =====
+
+    /**
+     * Generate stereo audio samples (legacy, no timing)
+     */
+    void generateStereoSamples(float* buffer, int count, int sampleRate);
+
+    /**
+     * Generate stereo audio samples with proper timing
+     */
+    void generateStereoSamples(float* buffer, int count, int sampleRate, uint64_t startCycle, uint64_t endCycle);
+
+    /**
+     * Consume accumulated stereo samples (from incremental generation).
+     * Returns actual number of sample frames consumed.
+     * If fewer samples available than requested, generates remaining on the spot.
+     */
+    int consumeStereoSamples(float* buffer, int frameCount);
+
+    /**
+     * Enable/disable debug logging
+     * @param enabled true to enable
+     */
+    void setDebugLogging(bool enabled);
+
+    // ===== Debug Access =====
+    const VIA6522& getVIA1() const { return via1_; }
+    const VIA6522& getVIA2() const { return via2_; }
+    const AY8910& getPSG1() const { return psg1_; }
+    const AY8910& getPSG2() const { return psg2_; }
+    AY8910& getPSG1() { return psg1_; }
+    AY8910& getPSG2() { return psg2_; }
+
+private:
+    // Two VIA chips
+    VIA6522 via1_;  // $C400-$C47F (bit 7 = 0)
+    VIA6522 via2_;  // $C480-$C4FF (bit 7 = 1)
+
+    // Two PSG chips
+    AY8910 psg1_;   // Connected to VIA1 (left channel)
+    AY8910 psg2_;   // Connected to VIA2 (right channel)
+
+    // Enabled state
+    bool enabled_ = true;
+
+    // Callbacks
+    CycleCallback cycleCallback_;
+
+    // Preallocated audio buffers to avoid heap allocations in audio hot path
+    mutable std::vector<float> audioBuffer1_;
+    mutable std::vector<float> audioBuffer2_;
+
+    // Phase coherence: when both PSGs have identical sound registers (0-13),
+    // use PSG1's output for both channels. This eliminates phase cancellation
+    // caused by independent tone counters producing anti-phase waveforms
+    // when Mockingboard music mirrors content to both PSGs.
+    bool arePsgsIdentical() const;
+
+    // Per-channel DC offset removal (high-pass filter)
+    // Converts unipolar PSG output to bipolar for audio playback.
+    // Slow time constant (~200ms at 48kHz) avoids tracking musical content.
+    static constexpr float DC_ALPHA = 0.9999f;
+    float dcStateL_ = 0.0f;
+    float dcStateR_ = 0.0f;
+
+    // Incremental audio generation state
+    // CPU cycles per audio sample at 48kHz: 1,023,000 / 48,000 ≈ 21.3125
+    static constexpr double CYCLES_PER_SAMPLE = 1023000.0 / 48000.0;
+    double cycleAccum_ = 0.0;                   // Fractional CPU cycle accumulator
+    std::vector<float> sampleAccum_;             // Accumulated stereo samples (interleaved L/R)
+    size_t sampleReadPos_ = 0;                   // Read position in accumulated buffer
+};
+
+} // namespace a2e