web-a2e 1.0.0

package/src/core/disassembler/disassembler.hpp

@@ -0,0 +1,171 @@
+/*
+ * disassembler.hpp - 65C02 instruction disassembler interface
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <vector>
+
+namespace a2e {
+
+/**
+ * Standalone 6502/65C02 disassembler
+ *
+ * Returns raw structured data for frontend rendering.
+ */
+
+// Addressing modes
+enum class AddrMode : uint8_t {
+  IMP = 0,   // Implied
+  ACC = 1,   // Accumulator
+  IMM = 2,   // Immediate #$nn
+  ZP = 3,    // Zero Page $nn
+  ZPX = 4,   // Zero Page,X $nn,X
+  ZPY = 5,   // Zero Page,Y $nn,Y
+  ABS = 6,   // Absolute $nnnn
+  ABX = 7,   // Absolute,X $nnnn,X
+  ABY = 8,   // Absolute,Y $nnnn,Y
+  IND = 9,   // Indirect ($nnnn)
+  IZX = 10,  // Indexed Indirect ($nn,X)
+  IZY = 11,  // Indirect Indexed ($nn),Y
+  REL = 12,  // Relative (branches)
+  ZPI = 13,  // Zero Page Indirect ($nn) - 65C02
+  AIX = 14,  // Absolute Indexed Indirect ($nnnn,X) - 65C02
+  ZPR = 15   // Zero Page Relative (BBR/BBS) - 65C02
+};
+
+// Instruction categories for syntax highlighting
+enum class InstrCategory : uint8_t {
+  BRANCH = 0,   // Jumps and branches
+  LOAD = 1,     // Load/store
+  MATH = 2,     // Math and logic
+  STACK = 3,    // Stack and register operations
+  FLAG = 4,     // Flag operations
+  UNKNOWN = 5   // Unknown/illegal opcodes
+};
+
+// Opcode info structure (maps opcode byte to mnemonic, mode, category)
+struct OpcodeInfo {
+  uint8_t mnemonicIndex;
+  uint8_t mode;      // AddrMode enum value
+  uint8_t category;  // InstrCategory enum value
+};
+
+/**
+ * Get pointer to the 256-entry opcode table
+ */
+const OpcodeInfo* getOpcodeTable();
+
+/**
+ * Get the number of mnemonics in the mnemonic table
+ */
+int getMnemonicCount();
+
+// Disassembled instruction data - 16 bytes per instruction
+// Layout: [address:2][target:2][length:1][opcode:1][op1:1][op2:1][mode:1][cat:1][mnem:4][pad:2]
+struct DisasmInstruction {
+  uint16_t address;       // offset 0-1: Memory address
+  uint16_t target;        // offset 2-3: Branch/jump target address
+  uint8_t length;         // offset 4: Instruction length (1-3)
+  uint8_t opcode;         // offset 5: Opcode byte
+  uint8_t operand1;       // offset 6: First operand byte
+  uint8_t operand2;       // offset 7: Second operand byte
+  uint8_t mode;           // offset 8: AddrMode enum value
+  uint8_t category;       // offset 9: InstrCategory enum value
+  char mnemonic[4];       // offset 10-13: Mnemonic (null-padded)
+  uint8_t padding[2];     // offset 14-15: Alignment padding
+};
+
+// Result structure for disassembly
+struct DisasmResult {
+  std::vector<DisasmInstruction> instructions;
+};
+
+/**
+ * Get the length of an instruction given its opcode
+ */
+int getInstructionLength(uint8_t opcode);
+
+/**
+ * Get mnemonic string for an opcode
+ */
+const char* getMnemonic(uint8_t opcode);
+
+/**
+ * Get mnemonic string by index (for use with DisasmInstruction.mnemonicIndex)
+ */
+const char* getMnemonicByIndex(uint8_t index);
+
+/**
+ * Get addressing mode for an opcode
+ */
+AddrMode getAddressingMode(uint8_t opcode);
+
+/**
+ * Get instruction category for an opcode
+ */
+InstrCategory getInstructionCategory(uint8_t opcode);
+
+/**
+ * Disassemble a single instruction from raw data
+ */
+DisasmInstruction disassembleInstruction(const uint8_t *data, size_t size,
+                                          uint16_t address);
+
+/**
+ * Disassemble a block of raw binary data (linear)
+ */
+DisasmResult disassembleBlock(const uint8_t *data, size_t size,
+                              uint16_t baseAddress);
+
+/**
+ * Instruction flow classification
+ */
+enum class FlowType : uint8_t {
+  SEQUENTIAL = 0,     // Continue to next instruction
+  CONDITIONAL = 1,    // Branch may or may not be taken (Bxx, BBRx, BBSx)
+  UNCONDITIONAL = 2,  // Always transfers control (JMP abs, BRA)
+  CALL = 3,           // Subroutine call (JSR) - returns to next instruction
+  RETURN = 4,         // Returns via stack (RTS, RTI)
+  INDIRECT = 5,       // Indirect jump - target unknown (JMP indirect)
+  HALT = 6            // Stops execution (BRK, STP, WAI)
+};
+
+/**
+ * Get the flow type of an instruction
+ */
+FlowType getFlowType(uint8_t opcode);
+
+/**
+ * Disassemble using recursive descent / control flow analysis
+ *
+ * This approach traces execution paths from entry points to better
+ * distinguish code from data:
+ * 1. Decode instruction at entry point
+ * 2. If sequential, continue to next instruction
+ * 3. If branch/jump, add target to visit list
+ * 4. If JSR, add target AND return address
+ * 5. If RTS/RTI/indirect jump, stop this path
+ * 6. Repeat until no more addresses to visit
+ *
+ * @param data Raw binary data
+ * @param size Size of data in bytes
+ * @param baseAddress Memory address of first byte
+ * @param entryPoints List of known entry points to start tracing from
+ * @return Disassembly result with instructions sorted by address
+ */
+DisasmResult disassembleWithFlowAnalysis(const uint8_t *data, size_t size,
+                                          uint16_t baseAddress,
+                                          const std::vector<uint16_t> &entryPoints);
+
+/**
+ * Convenience overload with single entry point (defaults to baseAddress)
+ */
+DisasmResult disassembleWithFlowAnalysis(const uint8_t *data, size_t size,
+                                          uint16_t baseAddress);
+
+} // namespace a2e

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

@@ -0,0 +1,267 @@
+/*
+ * disk_image.hpp - Abstract base class for disk image formats
+ *
+ * Written by
+ *  Mike Daley <michael_daley@icloud.com>
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+namespace a2e {
+
+/**
+ * DiskImage - Abstract base class for disk image formats
+ *
+ * This interface defines the contract for disk image implementations.
+ * The disk controller uses this interface to access disk data without
+ * needing to know the specific format details.
+ *
+ * The disk image manages head positioning internally based on stepper
+ * motor phase changes. The controller only knows about phases (0-3),
+ * not tracks. The disk image translates phase sequences into head
+ * movement using 4-phase stepper motor physics.
+ *
+ * Data access is nibble-based. The controller reads nibbles sequentially
+ * as the virtual disk spins. Each track contains a stream of nibbles
+ * that encode the sector data using GCR (Group Coded Recording).
+ */
+class DiskImage {
+public:
+  /**
+   * Disk image format types
+   */
+  enum class Format {
+    Unknown,
+    WOZ1,
+    WOZ2,
+    DSK, // Raw sector format (140KB, 35 tracks x 16 sectors x 256 bytes)
+    DO,  // DOS-order DSK (same as DSK)
+    PO   // ProDOS-order DSK
+  };
+
+  virtual ~DiskImage() = default;
+
+  // Non-copyable
+  DiskImage(const DiskImage &) = delete;
+  DiskImage &operator=(const DiskImage &) = delete;
+
+  // Movable
+  DiskImage(DiskImage &&) = default;
+  DiskImage &operator=(DiskImage &&) = default;
+
+  // ===== Loading =====
+
+  /**
+   * Load a disk image from raw data
+   * @param data Pointer to disk image data
+   * @param size Size of the data
+   * @param filename Original filename (for format detection)
+   * @return true on success, false on failure
+   */
+  virtual bool load(const uint8_t *data, size_t size,
+                    const std::string &filename) = 0;
+
+  /**
+   * Check if a disk image is currently loaded
+   * @return true if a valid disk image is loaded
+   */
+  virtual bool isLoaded() const = 0;
+
+  /**
+   * Get the format of the loaded disk image
+   * @return Format enum value
+   */
+  virtual Format getFormat() const = 0;
+
+  // ===== Head Positioning =====
+
+  /**
+   * Notify the disk of a phase magnet state change
+   * The disk image tracks phase states and moves the head accordingly
+   * using 4-phase stepper motor physics.
+   *
+   * @param phase Phase number (0-3)
+   * @param on true if phase is being activated, false if deactivated
+   */
+  virtual void setPhase(int phase, bool on) = 0;
+
+  /**
+   * Get the current quarter-track position (0-139)
+   * This is for display/debugging purposes only.
+   * @return Current quarter-track position
+   */
+  virtual int getQuarterTrack() const = 0;
+
+  /**
+   * Get the current track position (0-34)
+   * This is for display/debugging purposes only.
+   * @return Current track number (quarter_track / 4)
+   */
+  virtual int getTrack() const = 0;
+
+  /**
+   * Set the quarter-track position directly (for state restoration)
+   * @param quarter_track Quarter-track position (0-139)
+   */
+  virtual void setQuarterTrack(int quarter_track) = 0;
+
+  // ===== Geometry =====
+
+  /**
+   * Get the number of tracks on the disk
+   * Standard 5.25" disks have 35 tracks (0-34)
+   * @return Number of tracks
+   */
+  virtual int getTrackCount() const = 0;
+
+  /**
+   * Check if current head position has data
+   * @return true if the current position has data
+   */
+  virtual bool hasData() const = 0;
+
+  // ===== Data Access =====
+
+  /**
+   * Advance the bit position based on elapsed CPU cycles
+   * This simulates the disk rotating while the motor is on.
+   * Call this before reading to account for disk rotation during
+   * the time since the last read.
+   *
+   * @param current_cycles Current total CPU cycle count
+   */
+  virtual void advanceBitPosition(uint64_t current_cycles) = 0;
+
+  /**
+   * Read a nibble from the disk at the current position
+   * This simulates the disk read head reading data.
+   * The bit position advances as bits are read until a complete
+   * nibble (byte with high bit set) is assembled.
+   *
+   * @return The nibble read (high bit set for valid data)
+   */
+  virtual uint8_t readNibble() = 0;
+
+  // ===== Write Operations =====
+
+  /**
+   * Write a nibble to the disk at the current position
+   * This simulates the disk write head writing data.
+   * The bit position advances as bits are written.
+   *
+   * @param nibble The nibble to write (should have high bit set for valid GCR
+   * data)
+   */
+  virtual void writeNibble(uint8_t nibble) = 0;
+
+  /**
+   * Read a single bit from the disk at the current position
+   * Advances the bit position by one.
+   * Used by the Logic State Sequencer for cycle-accurate disk access.
+   *
+   * @return 0 or 1
+   */
+  virtual uint8_t readBit() = 0;
+
+  /**
+   * Write a single bit to the disk at the current position
+   * Advances the bit position by one.
+   * Used by the Logic State Sequencer for cycle-accurate disk access.
+   *
+   * @param bit The bit value (0 or 1)
+   */
+  virtual void writeBit(uint8_t bit) = 0;
+
+  // ===== Status =====
+
+  /**
+   * Check if the disk is write-protected
+   * @return true if write-protected
+   */
+  virtual bool isWriteProtected() const = 0;
+
+  /**
+   * Check if the disk has been modified
+   * @return true if modified since load
+   */
+  virtual bool isModified() const = 0;
+
+  /**
+   * Get a human-readable format name
+   * @return Format name string (e.g., "WOZ 2.0")
+   */
+  virtual std::string getFormatName() const = 0;
+
+  /**
+   * Get the raw sector data for saving (DSK format)
+   * @param size Output: size of the data
+   * @return Pointer to sector data, or nullptr if not available
+   */
+  virtual const uint8_t *getSectorData(size_t *size) const = 0;
+
+  /**
+   * Export disk data in its native format for saving
+   * This reconstructs the disk image file that can be saved to disk.
+   * The returned pointer is valid until the next call to exportData()
+   * or until the disk image is destroyed.
+   *
+   * @param size Output: size of the exported data
+   * @return Pointer to exported data, or nullptr if export not supported
+   */
+  virtual const uint8_t *exportData(size_t *size) = 0;
+
+  // ===== Debug Methods =====
+
+  /**
+   * Get a nibble at a specific track and position (debug only)
+   * @param track Track number (0-34)
+   * @param position Position in nibble stream
+   * @return Nibble value at that position
+   */
+  virtual uint8_t getNibbleAt(int track, int position) const = 0;
+
+  /**
+   * Get the number of nibbles in a track (debug only)
+   * @param track Track number (0-34)
+   * @return Number of nibbles in the track
+   */
+  virtual int getTrackNibbleCount(int track) const = 0;
+
+  /**
+   * Get the current nibble position within the track (debug only)
+   * @return Current nibble position
+   */
+  virtual size_t getCurrentNibblePosition() const = 0;
+
+  // ===== Reset =====
+
+  /**
+   * Reset runtime positioning state while preserving loaded disk data.
+   * Resets head position, phase states, bit position, and cycle counters
+   * back to initial values as if the disk was freshly inserted.
+   */
+  virtual void resetState() = 0;
+
+  // ===== Filename Tracking =====
+
+  /**
+   * Get the filename associated with this disk image
+   * @return Filename string
+   */
+  const std::string &getFilename() const { return filename_; }
+
+  /**
+   * Set the filename associated with this disk image
+   * @param filename The filename to set
+   */
+  void setFilename(const std::string &filename) { filename_ = filename; }
+
+protected:
+  DiskImage() = default;
+  std::string filename_;
+};
+
+} // namespace a2e