web-a2e 1.0.0

package/src/core/disk-image/dsk_disk_image.hpp

@@ -0,0 +1,204 @@
+/*
+ * dsk_disk_image.hpp - DSK/DO/PO raw sector disk image format support
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+#pragma once
+
+#include "disk_image.hpp"
+#include <array>
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace a2e {
+
+/**
+ * DskDiskImage - DSK/DO/PO disk image format support
+ *
+ * DSK is a raw sector image format commonly used for Apple II disk images.
+ * It stores 35 tracks x 16 sectors x 256 bytes = 143,360 bytes (140KB).
+ *
+ * There are two sector ordering schemes:
+ * - DOS order (.dsk, .do): Sectors stored in DOS 3.3 logical order
+ * - ProDOS order (.po): Sectors stored in ProDOS physical order
+ *
+ * This class converts the raw sector data to/from GCR-encoded nibbles
+ * on-the-fly, simulating how a real Disk II controller reads/writes.
+ */
+class DskDiskImage : public DiskImage {
+public:
+  // Disk geometry constants
+  static constexpr int TRACKS = 35;
+  static constexpr int SECTORS_PER_TRACK = 16;
+  static constexpr int BYTES_PER_SECTOR = 256;
+  static constexpr int TRACK_SIZE =
+      SECTORS_PER_TRACK * BYTES_PER_SECTOR; // 4096 bytes
+  static constexpr int DISK_SIZE = TRACKS * TRACK_SIZE; // 143360 bytes
+
+  // Nibble track size (approximate, varies slightly per track)
+  static constexpr int NIBBLES_PER_TRACK = 6656;
+
+  DskDiskImage();
+  ~DskDiskImage() override = default;
+
+  // ===== Loading =====
+  bool load(const uint8_t *data, size_t size,
+            const std::string &filename) override;
+  bool isLoaded() const override { return loaded_; }
+  Format getFormat() const override { return format_; }
+
+  // ===== Reset =====
+  void resetState() override;
+
+  // ===== Head Positioning =====
+  void setPhase(int phase, bool on) override;
+  int getQuarterTrack() const override { return quarter_track_; }
+  int getTrack() const override { return quarter_track_ / 4; }
+  void setQuarterTrack(int quarter_track) override {
+    quarter_track_ = std::max(0, std::min(quarter_track, (TRACKS - 1) * 4));
+  }
+
+  // ===== Geometry =====
+  int getTrackCount() const override { return TRACKS; }
+  bool hasData() const override;
+
+  // ===== Data Access =====
+  void advanceBitPosition(uint64_t current_cycles) override;
+  uint8_t readNibble() override;
+
+  // ===== Write Operations =====
+  void writeNibble(uint8_t nibble) override;
+
+  // ===== Bit-Level Access (for LSS) =====
+  uint8_t readBit() override;
+  void writeBit(uint8_t bit) override;
+
+  // ===== Status =====
+  bool isWriteProtected() const override { return write_protected_; }
+  bool isModified() const override { return modified_; }
+  std::string getFormatName() const override;
+  const uint8_t *getSectorData(size_t *size) const override;
+  const uint8_t *exportData(size_t *size) override;
+
+  // ===== Debug Methods =====
+  uint8_t getNibbleAt(int track, int position) const override;
+  int getTrackNibbleCount(int track) const override;
+  size_t getCurrentNibblePosition() const override { return bit_position_ / 8; }
+
+  // ===== DSK-specific =====
+
+  /**
+   * Check if this is a ProDOS-order image
+   */
+  bool isProDOSOrder() const { return format_ == Format::PO; }
+
+  /**
+   * Get the volume number (default 254)
+   */
+  uint8_t getVolumeNumber() const { return volume_number_; }
+
+  /**
+   * Set the volume number for address field encoding
+   */
+  void setVolumeNumber(uint8_t volume) { volume_number_ = volume; }
+
+private:
+  // Raw sector data storage
+  std::array<uint8_t, DISK_SIZE> sector_data_{};
+
+  // Nibblized track cache
+  struct NibbleTrack {
+    std::vector<uint8_t> nibbles;
+    std::vector<bool> is_sync;  // true = 10-bit self-sync byte
+    bool dirty = false; // Track has been modified
+    bool valid = false; // Track has been nibblized
+  };
+  std::array<NibbleTrack, TRACKS> nibble_tracks_{};
+
+  // State
+  Format format_ = Format::Unknown;
+  bool loaded_ = false;
+  bool write_protected_ = false;
+  bool modified_ = false;
+  uint8_t volume_number_ = 254;
+
+  // Head position (0-139 quarter-tracks)
+  int quarter_track_ = 0;
+  uint8_t phase_states_ = 0; // Bit field of active phases
+  int current_phase_ = 0; // Current phase where head is settled (for stepper)
+
+  // Nibble position within current track
+  size_t nibble_position_ = 0;
+
+  // Bit stream cache (parallel to nibble cache, for LSS bit-level access)
+  struct BitTrack {
+    std::vector<uint8_t> bits;   // Packed bit data, MSB first (same as WOZ)
+    uint32_t bit_count = 0;
+    bool dirty = false;
+    bool valid = false;
+  };
+  std::array<BitTrack, TRACKS> bit_tracks_{};
+  uint32_t bit_position_ = 0;
+
+  // Cycle count for disk rotation timing
+  uint64_t last_cycle_count_ = 0;
+
+  // ===== Internal Methods =====
+
+  /**
+   * Detect disk format from content (ProDOS vs DOS order)
+   * Checks for filesystem signatures rather than relying on file extension
+   */
+  Format detectFormat(const std::string &filename) const;
+
+  /**
+   * Nibblize a track from sector data
+   */
+  void nibblizeTrack(int track);
+
+  /**
+   * Denibblize a track back to sector data
+   */
+  void denibblizeTrack(int track);
+
+  /**
+   * Update head position based on phase magnet states
+   * Called when a phase is turned OFF to check if stepping should occur
+   */
+  void updateHeadPosition();
+
+  /**
+   * Get the logical sector number for a physical sector
+   */
+  int getLogicalSector(int physical_sector) const;
+
+  /**
+   * Ensure the current track is nibblized
+   */
+  void ensureTrackNibblized();
+
+  /**
+   * Ensure the current track has a valid bit stream cache
+   */
+  void ensureTrackBitified();
+
+  /**
+   * Convert a dirty bit track back to nibbles for denibblization
+   */
+  void bitTrackToNibbleTrack(int track);
+
+  /**
+   * Decode a 4-and-4 encoded byte pair
+   */
+  static uint8_t decode4and4(uint8_t odd, uint8_t even);
+
+  /**
+   * Decode 6-and-2 encoded data back to 256 bytes
+   */
+  static bool decode6and2(const uint8_t *encoded, uint8_t *output);
+};
+
+} // namespace a2e

package/src/core/disk-image/gcr_encoding.cpp

@@ -0,0 +1,147 @@
+/*
+ * gcr_encoding.cpp - 6-and-2 and 4-and-4 GCR encoding for Apple II disk data
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+#include "gcr_encoding.hpp"
+#include <algorithm>
+#include <cstring>
+
+namespace a2e {
+namespace GCR {
+
+std::vector<uint8_t> encode6and2(const uint8_t *data)
+{
+  // The 6-and-2 encoding converts 256 bytes into 342 6-bit values
+  // which are then encoded into 342 disk nibbles plus a checksum
+
+  // Buffer for prenibblized data (342 bytes)
+  // First 86 bytes: auxiliary buffer (2 bits from each of 256 bytes)
+  // Next 256 bytes: primary buffer (6 bits from each data byte)
+  uint8_t buffer[342];
+  std::memset(buffer, 0, sizeof(buffer));
+
+  // Step 1: Build auxiliary buffer (first 86 bytes)
+  // Extract bits 0-1 from each data byte and pack them
+  // Each aux byte holds bits from 3 data bytes (or 2 for the last few)
+  for (int i = 0; i < 86; i++)
+  {
+    uint8_t val = 0;
+
+    // Bits from data[i] (bits 0,1 -> bits 0,1 of aux)
+    if (i < 86)
+    {
+      val = ((data[i] & 0x01) << 1) | ((data[i] & 0x02) >> 1);
+    }
+
+    // Bits from data[i+86] (bits 0,1 -> bits 2,3 of aux)
+    if (i + 86 < 256)
+    {
+      val |= ((data[i + 86] & 0x01) << 3) | ((data[i + 86] & 0x02) << 1);
+    }
+
+    // Bits from data[i+172] (bits 0,1 -> bits 4,5 of aux)
+    if (i + 172 < 256)
+    {
+      val |= ((data[i + 172] & 0x01) << 5) | ((data[i + 172] & 0x02) << 3);
+    }
+
+    buffer[i] = val;
+  }
+
+  // Step 2: Build primary buffer (next 256 bytes)
+  // Store bits 2-7 from each data byte (shifted right by 2)
+  for (int i = 0; i < 256; i++)
+  {
+    buffer[86 + i] = data[i] >> 2;
+  }
+
+  // Step 3: XOR encode and convert to disk nibbles
+  // Each byte is XORed with the previous byte's value (differential encoding)
+  // This allows the decoder to recover the original by XORing each value with previous
+  std::vector<uint8_t> result;
+  result.reserve(343);
+
+  // XOR encode in forward order
+  uint8_t prev = 0;
+  for (int i = 0; i < 342; i++)
+  {
+    uint8_t xor_val = buffer[i] ^ prev;
+    result.push_back(ENCODE_6_AND_2[xor_val & 0x3F]);
+    prev = buffer[i];
+  }
+
+  // Append checksum nibble (the last raw value before XOR)
+  result.push_back(ENCODE_6_AND_2[prev & 0x3F]);
+
+  return result;
+}
+
+std::vector<uint8_t> buildSector(uint8_t volume, uint8_t track,
+                                 uint8_t sector, const uint8_t *data)
+{
+  std::vector<uint8_t> nibbles;
+  nibbles.reserve(400); // Approximate sector size
+
+  // Gap 1: Self-sync bytes before address field (~12-16 sync bytes)
+  for (int i = 0; i < 14; i++)
+  {
+    nibbles.push_back(SYNC_BYTE);
+  }
+
+  // Address field prologue: D5 AA 96
+  nibbles.push_back(ADDR_PROLOGUE[0]);
+  nibbles.push_back(ADDR_PROLOGUE[1]);
+  nibbles.push_back(ADDR_PROLOGUE[2]);
+
+  // Address field data (4-and-4 encoded): volume, track, sector, checksum
+  auto [vol_odd, vol_even] = encode4and4(volume);
+  nibbles.push_back(vol_odd);
+  nibbles.push_back(vol_even);
+
+  auto [trk_odd, trk_even] = encode4and4(track);
+  nibbles.push_back(trk_odd);
+  nibbles.push_back(trk_even);
+
+  auto [sec_odd, sec_even] = encode4and4(sector);
+  nibbles.push_back(sec_odd);
+  nibbles.push_back(sec_even);
+
+  // Checksum is XOR of volume, track, sector
+  uint8_t addr_checksum = volume ^ track ^ sector;
+  auto [chk_odd, chk_even] = encode4and4(addr_checksum);
+  nibbles.push_back(chk_odd);
+  nibbles.push_back(chk_even);
+
+  // Address field epilogue: DE AA EB
+  nibbles.push_back(ADDR_EPILOGUE[0]);
+  nibbles.push_back(ADDR_EPILOGUE[1]);
+  nibbles.push_back(ADDR_EPILOGUE[2]);
+
+  // Gap 2: Sync bytes between address and data (~5-7 sync bytes)
+  for (int i = 0; i < 6; i++)
+  {
+    nibbles.push_back(SYNC_BYTE);
+  }
+
+  // Data field prologue: D5 AA AD
+  nibbles.push_back(DATA_PROLOGUE[0]);
+  nibbles.push_back(DATA_PROLOGUE[1]);
+  nibbles.push_back(DATA_PROLOGUE[2]);
+
+  // Data field: 343 nibbles (6-and-2 encoded 256 bytes + checksum)
+  std::vector<uint8_t> encoded_data = encode6and2(data);
+  nibbles.insert(nibbles.end(), encoded_data.begin(), encoded_data.end());
+
+  // Data field epilogue: DE AA EB
+  nibbles.push_back(DATA_EPILOGUE[0]);
+  nibbles.push_back(DATA_EPILOGUE[1]);
+  nibbles.push_back(DATA_EPILOGUE[2]);
+
+  return nibbles;
+}
+
+} // namespace GCR
+} // namespace a2e

package/src/core/disk-image/gcr_encoding.hpp

@@ -0,0 +1,78 @@
+/*
+ * gcr_encoding.hpp - GCR encoding tables and routines for Disk II emulation
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+#pragma once
+
+#include <array>
+#include <cstdint>
+#include <utility>
+#include <vector>
+
+namespace a2e {
+namespace GCR {
+
+// 6-and-2 encoding lookup table
+// Maps 6-bit values (0-63) to valid disk nibbles (bit 7 set, no adjacent zeros)
+constexpr std::array<uint8_t, 64> ENCODE_6_AND_2 = {
+    0x96, 0x97, 0x9A, 0x9B, 0x9D, 0x9E, 0x9F, 0xA6, 0xA7, 0xAB, 0xAC,
+    0xAD, 0xAE, 0xAF, 0xB2, 0xB3, 0xB4, 0xB5, 0xB6, 0xB7, 0xB9, 0xBA,
+    0xBB, 0xBC, 0xBD, 0xBE, 0xBF, 0xCB, 0xCD, 0xCE, 0xCF, 0xD3, 0xD6,
+    0xD7, 0xD9, 0xDA, 0xDB, 0xDC, 0xDD, 0xDE, 0xDF, 0xE5, 0xE6, 0xE7,
+    0xE9, 0xEA, 0xEB, 0xEC, 0xED, 0xEE, 0xEF, 0xF2, 0xF3, 0xF4, 0xF5,
+    0xF6, 0xF7, 0xF9, 0xFA, 0xFB, 0xFC, 0xFD, 0xFE, 0xFF};
+
+// Address field markers
+constexpr uint8_t ADDR_PROLOGUE[3] = {0xD5, 0xAA, 0x96};
+constexpr uint8_t ADDR_EPILOGUE[3] = {0xDE, 0xAA, 0xEB};
+
+// Data field markers
+constexpr uint8_t DATA_PROLOGUE[3] = {0xD5, 0xAA, 0xAD};
+constexpr uint8_t DATA_EPILOGUE[3] = {0xDE, 0xAA, 0xEB};
+
+// Self-sync byte
+constexpr uint8_t SYNC_BYTE = 0xFF;
+
+/**
+ * 4-and-4 encoding for address field values
+ * Splits byte into odd bits (first) and even bits (second)
+ * Each byte is OR'd with 0xAA to ensure high bit set
+ *
+ * @param value Byte to encode
+ * @return Pair of encoded bytes (odd bits, even bits)
+ */
+inline std::pair<uint8_t, uint8_t> encode4and4(uint8_t value) {
+  // Odd bits: bits 7,5,3,1 go to positions 6,4,2,0
+  uint8_t odd = 0xAA | ((value >> 1) & 0x55);
+  // Even bits: bits 6,4,2,0 stay in positions 6,4,2,0
+  uint8_t even = 0xAA | (value & 0x55);
+  return {odd, even};
+}
+
+/**
+ * Encode 256 bytes of sector data using 6-and-2 encoding
+ * Returns 343 nibbles (342 encoded data + 1 checksum)
+ *
+ * @param data Pointer to 256 bytes of sector data
+ * @return Vector of 343 encoded nibbles
+ */
+std::vector<uint8_t> encode6and2(const uint8_t *data);
+
+/**
+ * Build a complete sector as a nibble stream
+ * Includes sync bytes, address field, gap, and data field
+ *
+ * @param volume Volume number (typically 254)
+ * @param track Track number (0-34)
+ * @param sector Sector number (0-15)
+ * @param data Pointer to 256 bytes of sector data
+ * @return Vector of nibbles for the complete sector
+ */
+std::vector<uint8_t> buildSector(uint8_t volume, uint8_t track, uint8_t sector,
+                                 const uint8_t *data);
+
+} // namespace GCR
+} // namespace a2e