mos6502-workbench 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e571e6524c8eeb4f5d75ead1597f41b2d44368caddcb82601f5e23a2b224996d
+  data.tar.gz: 6cee28a119d02c442aba8d842b20ffb35729e05b6ec3756a9ed25bc0f7bb01eb
+SHA512:
+  metadata.gz: cdf3e343f341c81befa6e337c9ee9c4d6c97a73101f888dc3c90c1e2a0f8741ad3f043cfa7c780f90c36fa68a472f2eb8d4d1ce2f45103fe9b3925170d7eded7
+  data.tar.gz: e93431909a662ecc65d251e736fcf60d1cf36a3d154eef3da35bacecbef8fe340fc4fafaa4e269431562fe68523924fb7f235883c8f7c0871d8c8378f0d4c2af

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nigel Brookes-Thomas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,189 @@
+# MOS6502 Workbench
+
+`mos6502-workbench` is a Ruby MOS 6502 toolkit for building, running, and
+debugging 6502 programs. It packages a tested NMOS 6502 CPU emulator together
+with an assembler, disassembler, Intel HEX support, a pluggable memory bus for
+machine builders, runnable examples, and an optional Ratatui-powered terminal
+UI.
+
+## Features
+
+- NMOS 6502 CPU emulator with IRQ, NMI, BRK, RTI, decimal mode, and stack support
+- Two-pass assembler with labels, expressions, `.org`, `.byte`, and `.word`
+- Disassembler that derives its decode table from the emulator opcode map
+- Intel HEX import and export
+- Pluggable `Bus`, `Machine`, `RAM`, `ROM`, and `Device` primitives for custom computers
+- CPU step tracing, bus access tracing, and coarse cycle counting for external debuggers and devices
+- Example programs and helper scripts
+- Optional TUI for stepping through execution, inspecting registers, memory, and stack state
+- RSpec suite with coverage gating plus an opt-in Klaus Dormann functional ROM harness
+
+## Installation
+
+From RubyGems:
+
+```bash
+gem install mos6502-workbench
+```
+
+For local development:
+
+```bash
+bundle install
+```
+
+## Usage
+
+The canonical require path is:
+
+```ruby
+require 'mos6502/workbench'
+```
+
+The main namespace remains `MOS6502`, so existing code written against the
+emulator classes can stay the same:
+
+```ruby
+require 'mos6502/workbench'
+
+cpu = MOS6502::CPU.new
+cpu.load([0xA9, 0x42, 0x85, 0x10, 0x00], start_address: 0x8000)
+cpu.reset
+cpu.run(max_instructions: 2)
+
+puts cpu.read_byte(0x0010)
+```
+
+## Building A Machine
+
+The gem now exposes a small machine-building surface:
+
+- `MOS6502::Bus` for 16-bit address decoding
+- `MOS6502::Device` as the peripheral/storage base class
+- `MOS6502::RAM` and `MOS6502::ROM` as ready-made devices
+- `MOS6502::Machine` as a composition root around a CPU plus mapped devices
+
+Example:
+
+```ruby
+require 'mos6502/workbench'
+
+machine = MOS6502::Machine.new
+machine.map_ram(start_address: 0x0000, end_address: 0x7fff)
+
+rom = Array.new(0x8000, 0xea)
+rom[0x0000] = 0xa9 # LDA #$42
+rom[0x0001] = 0x42
+rom[0x0002] = 0x8d # STA $2000
+rom[0x0003] = 0x00
+rom[0x0004] = 0x20
+rom[0x7ffc] = 0x00 # reset vector -> $8000
+rom[0x7ffd] = 0x80
+
+machine.map_rom(rom, start_address: 0x8000)
+machine.power_on
+machine.run(max_instructions: 2)
+
+puts machine.cpu.read_byte(0x2000) # => 0x42
+```
+
+Custom devices should subclass `MOS6502::Device` and implement `read_byte` and
+`write_byte`. If they need timed behaviour, they can also override `tick(cycles)`.
+
+## Tracing And Timing
+
+The emulator now exposes a few hooks intended for downstream machine projects:
+
+- `cpu.cycle_count` and `cpu.last_cycles` track coarse base-cycle timing
+- `cpu.subscribe_steps { |event| ... }` receives instruction-level trace events
+- `bus.subscribe_accesses { |event| ... }` receives memory read/write events
+- `machine.step`, `machine.run`, `machine.irq`, and `machine.nmi` tick mapped devices using the CPU's base cycle counts
+
+The current cycle counts are base timings only. They intentionally do not yet
+model page-crossing penalties, taken-branch penalties, or a full cycle-accurate
+bus.
+
+## Command-Line Tools
+
+The gem ships with these executables:
+
+- `assemble`
+- `disassemble`
+- `run_assembled_program`
+- `run_klaus_functional_test`
+
+Examples:
+
+```bash
+assemble examples/countdown.asm
+assemble --write tmp/countdown.bin examples/countdown.asm
+assemble --format intel_hex --write tmp/countdown.hex examples/countdown.asm
+
+disassemble --start '$8000' tmp/countdown.bin
+
+run_assembled_program examples/countdown.asm 20
+run_assembled_program --tui examples/countdown.asm
+```
+
+The TUI supports:
+
+- `space` to run or pause
+- `n` to single-step
+- `r` to reset
+- `[` and `]` to change autoplay speed
+- `h` and `l` to move the watch-memory window
+- `q` to quit
+
+## Assembler Support
+
+The assembler currently supports:
+
+- labels written as `name:`
+- directives: `.org`, `.byte`, `.word`
+- hex (`$8000`), binary (`%1010`), decimal (`42`), and character (`'A'`) literals
+- expressions using labels, `+`, `-`, `<`, `>`, and `*` for the current address
+- the official opcode/addressing-mode set implemented by the emulator
+
+See [examples/README.md](examples/README.md) for sample programs and workflows.
+For machine-building examples, see:
+
+- `examples/simple_machine.rb`
+- `examples/traced_machine.rb`
+
+## Development
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run RuboCop:
+
+```bash
+bundle exec rubocop --cache false
+```
+
+Build the gem locally:
+
+```bash
+gem build mos6502-workbench.gemspec
+```
+
+Run the opt-in Klaus functional ROM test:
+
+```bash
+RUN_ROM_TESTS=1 bundle exec rspec spec/rom_spec.rb
+```
+
+## Project Layout
+
+- `lib/mos6502/workbench.rb` is the canonical gem entrypoint
+- `lib/mos6502/workbench/` contains the emulator, bus/device/machine primitives, assembler, disassembler, Intel HEX loader, TUI, and version support
+- `bin/` contains executable helpers
+- `examples/` contains sample assembly programs
+- `spec/` contains the automated test suite and ROM harness
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/bin/assemble

@@ -0,0 +1,122 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'mos6502/workbench'
+
+options = {
+  format: 'flat',
+  origin: nil,
+  size: nil,
+  fill_byte: 0x00,
+  bytes_per_record: 16,
+  write_path: nil
+}
+
+parse_number = lambda do |value|
+  next nil if value.nil?
+
+  case value
+  when Integer
+    value
+  when /\A\$([0-9a-fA-F]+)\z/
+    Regexp.last_match(1).to_i(16)
+  when /\A%([01]+)\z/
+    Regexp.last_match(1).to_i(2)
+  else
+    Integer(value, 10)
+  end
+end
+
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: bin/assemble [options] path/to/file.asm'
+
+  opts.on('-w', '--write PATH', 'Write assembled output to PATH') do |value|
+    options[:write_path] = value
+  end
+
+  opts.on('--format FORMAT', 'Output format: flat or intel_hex') do |value|
+    options[:format] = value
+  end
+
+  opts.on('--origin VALUE', 'Flat-binary base address, e.g. $8000 or 32768') do |value|
+    options[:origin] = value
+  end
+
+  opts.on('--size VALUE', 'Flat-binary size in bytes, e.g. $1000 or 4096') do |value|
+    options[:size] = value
+  end
+
+  opts.on('--fill VALUE', 'Gap fill byte, e.g. $FF or 0') do |value|
+    options[:fill_byte] = value
+  end
+
+  opts.on('--bytes-per-record VALUE', 'Intel HEX payload size per record') do |value|
+    options[:bytes_per_record] = value
+  end
+end
+
+parser.parse!(ARGV)
+path = ARGV.shift
+
+unless path
+  warn parser
+  exit 1
+end
+
+source = File.read(path)
+program = MOS6502::Assembler.new.assemble(source)
+
+puts "Entry point: $#{format('%04X', program.entry_point)}"
+puts "Address range: $#{format('%04X', program.start_address)}-$#{format('%04X', program.end_address - 1)}" unless program.segments.empty?
+puts
+puts 'Labels:'
+program.labels.sort.each do |name, address|
+  puts "  #{name.ljust(16)} $#{format('%04X', address)}"
+end
+
+puts
+puts 'Segments:'
+program.segments.each do |segment|
+  puts "  Segment @ $#{format('%04X', segment.start_address)} (#{segment.bytes.length} bytes)"
+  segment.bytes.each_slice(16).with_index do |slice, index|
+    address = segment.start_address + (index * 16)
+    bytes = slice.map { |byte| format('%02X', byte) }.join(' ')
+    puts "    $#{format('%04X', address)}: #{bytes}"
+  end
+end
+
+if options[:write_path]
+  format = case options[:format].downcase
+           when 'flat', 'bin', 'binary'
+             :flat
+           when 'intel_hex', 'ihex', 'hex'
+             :intel_hex
+           else
+             warn "Unsupported output format: #{options[:format]}"
+             exit 1
+           end
+
+  puts
+
+  case format
+  when :flat
+    origin = parse_number.call(options[:origin])
+    size = parse_number.call(options[:size])
+    fill_byte = parse_number.call(options[:fill_byte]) || 0x00
+    program.write_flat_binary(options[:write_path], origin:, size:, fill_byte:)
+    size = File.size(options[:write_path])
+    puts "Wrote flat binary: #{options[:write_path]} (#{size} bytes)"
+  when :intel_hex
+    if options[:origin] || options[:size] || options[:fill_byte] != 0x00
+      warn '--origin, --size, and --fill only apply to flat binary output'
+      exit 1
+    end
+
+    bytes_per_record = parse_number.call(options[:bytes_per_record]) || 16
+    program.write_intel_hex(options[:write_path], bytes_per_record:)
+    line_count = File.readlines(options[:write_path], chomp: true).length
+    puts "Wrote Intel HEX: #{options[:write_path]} (#{line_count} records)"
+  end
+end

data/bin/disassemble

@@ -0,0 +1,58 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'mos6502/workbench'
+
+options = {
+  count: nil,
+  start: MOS6502::CPU::DEFAULT_LOAD_ADDRESS
+}
+
+parse_number = lambda do |value|
+  next nil if value.nil?
+
+  case value
+  when Integer
+    value
+  when /\A\$([0-9a-fA-F]+)\z/
+    Regexp.last_match(1).to_i(16)
+  when /\A%([01]+)\z/
+    Regexp.last_match(1).to_i(2)
+  else
+    Integer(value, 10)
+  end
+end
+
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: bin/disassemble [options] path/to/file.bin'
+
+  opts.on('--start VALUE', 'Load address of the first byte, e.g. $8000 or 32768') do |value|
+    options[:start] = value
+  end
+
+  opts.on('--count VALUE', 'Maximum number of instructions to decode') do |value|
+    options[:count] = value
+  end
+end
+
+parser.parse!(ARGV)
+path = ARGV.shift
+
+unless path
+  warn parser
+  exit 1
+end
+
+start_address = parse_number.call(options[:start]) || MOS6502::CPU::DEFAULT_LOAD_ADDRESS
+instruction_limit = parse_number.call(options[:count])
+bytes = File.binread(path)
+disassembler = MOS6502::Disassembler.new
+lines = disassembler.disassemble(bytes, start_address:, max_instructions: instruction_limit)
+
+puts "File: #{path}"
+puts "Start address: $#{format('%04X', start_address)}"
+puts "Instructions: #{lines.length}"
+puts
+puts disassembler.format_listing(lines)

data/bin/run_assembled_program

@@ -0,0 +1,80 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'mos6502/workbench'
+
+options = {
+  instruction_budget: 16,
+  tui: false,
+  watch_base: nil
+}
+
+parse_number = lambda do |value|
+  next nil if value.nil?
+
+  case value
+  when Integer
+    value
+  when /\A\$([0-9a-fA-F]+)\z/
+    Regexp.last_match(1).to_i(16)
+  when /\A%([01]+)\z/
+    Regexp.last_match(1).to_i(2)
+  else
+    Integer(value, 10)
+  end
+end
+
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: bin/run_assembled_program [options] path/to/file.asm [instruction_count]'
+
+  opts.on('--tui', 'Launch the interactive TUI visualizer') do
+    options[:tui] = true
+  end
+
+  opts.on('--watch VALUE', 'Starting address for the TUI watch panel; defaults to the program entry point') do |value|
+    options[:watch_base] = value
+  end
+end
+
+parser.parse!(ARGV)
+
+path = ARGV[0]
+options[:instruction_budget] = (ARGV[1] || options[:instruction_budget]).to_i
+
+unless path
+  warn parser
+  exit 1
+end
+
+source = File.read(path)
+program = MOS6502::Assembler.new.assemble(source)
+cpu = program.load_into(MOS6502::CPU.new)
+
+if options[:tui]
+  MOS6502::TUI.new(
+    cpu:,
+    program:,
+    title: File.basename(path),
+    watch_base: parse_number.call(options[:watch_base])
+  ).run
+  exit 0
+end
+
+cpu.run(max_instructions: options[:instruction_budget])
+
+puts "Program: #{path}"
+puts "Instructions executed: #{cpu.instruction_count}"
+puts 'CPU snapshot:'
+cpu.snapshot.each do |key, value|
+  formatted = value.nil? ? 'nil' : format('$%04X', value)
+  formatted = format('$%02X', value) if %i[accumulator register_x register_y stack_pointer status last_opcode].include?(key) && !value.nil?
+  puts "  #{key.to_s.ljust(18)} #{formatted}"
+end
+
+puts
+puts 'Memory $0200-$0207:'
+(0x0200..0x0207).each do |address|
+  puts "  $#{format('%04X', address)} = $#{format('%02X', cpu.read_byte(address))}"
+end

data/bin/run_klaus_functional_test

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+require 'mos6502/workbench'
+require_relative '../spec/support/rom_runner'
+
+runner = ROMRunner::KlausFunctionalTest.new.load_image
+started_at = Time.now
+result = runner.run
+elapsed = Time.now - started_at
+
+puts "Klaus functional test: #{result.state}"
+puts "Program counter: $#{format('%04X', result.program_counter)}"
+puts "Instructions: #{result.instruction_count}"
+puts "Elapsed: #{format('%.2f', elapsed)}s"
+puts "Reason: #{result.reason}"
+
+exit(result.state == :passed ? 0 : 1)

data/examples/README.md

@@ -0,0 +1,147 @@
+# Assembler Examples
+
+These files are small, self-contained samples you can assemble and run with the
+project scripts. The directory also includes Ruby examples for composing a full
+machine with the gem's `Bus`, `Machine`, and `Device` APIs.
+
+## Quick Start
+
+Assemble a file and inspect the emitted bytes:
+
+```bash
+bin/assemble examples/countdown.asm
+```
+
+Write a flat binary to disk:
+
+```bash
+bin/assemble --write tmp/countdown.bin examples/countdown.asm
+```
+
+Write Intel HEX instead of a padded binary image:
+
+```bash
+bin/assemble --format intel_hex --write tmp/countdown.hex examples/countdown.asm
+```
+
+Write a padded flat binary image with an explicit origin and fill byte:
+
+```bash
+bin/assemble --origin '$8000' --size '$20' --fill '$FF' --write tmp/countdown_padded.bin examples/countdown.asm
+```
+
+Run an assembled program for a fixed number of instructions and inspect the CPU
+snapshot plus a small RAM window:
+
+```bash
+bin/run_assembled_program examples/countdown.asm 16
+```
+
+Launch the interactive TUI visualizer instead of the plain text snapshot:
+
+```bash
+bin/run_assembled_program --tui examples/countdown.asm
+```
+
+Disassemble a flat binary back into a readable listing:
+
+```bash
+bin/assemble --write tmp/countdown.bin examples/countdown.asm
+bin/disassemble --start '$8000' tmp/countdown.bin
+```
+
+## Samples
+
+`examples/countdown.asm`
+
+- Shows immediate loads, a backward branch, RAM writes, and a terminal self-loop.
+- After enough instructions, `$0200` will contain `00` and `$0201` will contain `21` (`'!'`).
+
+```bash
+bin/run_assembled_program examples/countdown.asm 20
+```
+
+Or explore it interactively:
+
+```bash
+bin/run_assembled_program --tui examples/countdown.asm
+```
+
+`examples/labels_and_data.asm`
+
+- Shows `.org`, `.byte`, `.word`, labels, and the `<label` / `>label` low-byte and high-byte helpers.
+- The program copies the address and contents of `message` into `$0200-$0203`.
+
+```bash
+bin/assemble examples/labels_and_data.asm
+bin/run_assembled_program examples/labels_and_data.asm 12
+```
+
+`examples/branching.asm`
+
+- Shows a small loop that decrements RAM until it reaches zero.
+- Uses `jmp *` as a compact end-of-program self-loop.
+
+```bash
+bin/run_assembled_program examples/branching.asm 12
+```
+
+`examples/primes.asm`
+
+- Finds all prime numbers from `2` through `255` using repeated trial division.
+- Writes the primes sequentially to `$0300...` and stores the final count in `$02FF`.
+- After enough instructions, `$02FF` will contain `54`, and the first bytes at `$0300` will be `02 03 05 07 0B ...`.
+
+```bash
+bin/assemble examples/primes.asm
+bin/run_assembled_program examples/primes.asm 300000
+```
+
+`examples/simple_machine.rb`
+
+- Shows the smallest ROM-booting machine built from `Machine`, `RAM`, and `ROM`.
+- Boots from the reset vector at `$FFFC/$FFFD`, stores `42` at `$2000`, and loops.
+
+```bash
+ruby examples/simple_machine.rb
+```
+
+`examples/traced_machine.rb`
+
+- Shows a custom memory-mapped device built by subclassing `MOS6502::Device`.
+- Demonstrates CPU step tracing and bus access tracing while a ROM writes to a fake I/O register.
+
+```bash
+ruby examples/traced_machine.rb
+```
+
+## Writing Your Own
+
+The current assembler supports:
+
+- labels written as `name:`
+- directives: `.org`, `.byte`, `.word`
+- literals in hex (`$8000`), binary (`%1010`), decimal (`42`), and character form (`'A'`)
+- expressions with labels, `+`, `-`, `<`, `>`, and `*` for the current address
+- the official opcode/addressing-mode set currently implemented by the emulator
+
+The easiest workflow is:
+
+1. Copy one of the sample files.
+2. Run `bin/assemble your_file.asm` to check the emitted bytes and label addresses.
+3. Run `bin/assemble --write your_file.bin your_file.asm` if you want a flat binary file.
+4. Run `bin/assemble --format intel_hex --write your_file.hex your_file.asm` if you want a sparse Intel HEX file.
+5. Add `--origin`, `--size`, and `--fill` when you need a padded flat image for a ROM/socket layout.
+   Quote `$`-prefixed hex literals in your shell, for example `--origin '$8000'`.
+6. Run `bin/run_assembled_program your_file.asm N` to step it on the emulator.
+7. Run `bin/disassemble --start '$8000' your_file.bin` to inspect a generated binary listing.
+8. Run `bin/run_assembled_program --tui your_file.asm` for the live dashboard.
+
+## TUI Controls
+
+- `space` toggles autoplay
+- `n` executes one instruction while paused
+- `r` resets the CPU without reloading the file
+- `[` and `]` slow down or speed up autoplay
+- `h` and `l` move the watch-memory window
+- `q` exits the TUI

data/examples/branching.asm

@@ -0,0 +1,16 @@
+; Demonstrates labels, branches, current-address expressions, and a simple loop.
+
+.org $8000
+
+start:
+  lda #$03
+  sta $0200
+
+tick:
+  dec $0200
+  lda $0200
+  bne tick
+
+finished:
+  nop
+  jmp *

data/examples/countdown.asm

@@ -0,0 +1,17 @@
+; Count down from 5, mirror the X register into RAM, and leave a marker byte.
+
+.org $8000
+
+start:
+  ldx #$05
+
+loop:
+  dex
+  stx $0200
+  bne loop
+
+  lda #'!'
+  sta $0201
+
+done:
+  jmp done