badline 0.17.0 → 0.18.0

data/lib/badline/kim1/sound.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # The KIM-1's sound: U2's PB7, the tape output, which programs such as
+    # the First Book of KIM's music player toggle, or with the speaker
+    # wired, U3's PA0, where the User Manual's chapter 5 puts a speaker.
+    # Machine::LineSound turns it into samples.
+    class Sound
+      include Machine::LineSound
+
+      # Whether the speaker on U3's PA0 is wired, and plays in place of PB7.
+      attr_accessor :speaker
+
+      def initialize(monitor, user)
+        @monitor = monitor
+        @user = user
+        @speaker = false
+        init_line_sound
+      end
+
+      def model = :pb7
+
+      private
+
+      def line_high? = @speaker ? @user.port_a_output.anybits?(0x01) : @monitor.port_b_output.anybits?(0x80)
+    end
+  end
+end

data/lib/badline/kim1/tape.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # The cassette deck on U2's PB7 (User Manual, appendix E). Playing, it
+    # drives PB7 as the board's PLL and comparator would from the tape
+    # (Storage::KIMTape#edges), which the monitor's LOADT ($1873) reads.
+    # Recording, it puts each change of PB7, which DUMPT ($1800) toggles as
+    # a square wave, on the tape as a crossing, in place of whatever was
+    # on the tape from there on. Stopping a recording writes the tape to
+    # its file.
+    #
+    # Nothing on the board starts or stops the deck: the tape moves while
+    # PLAY or RECORD is down, a microsecond, a cycle, at a time.
+    class Tape
+      attr_reader :tape
+
+      # +clock+ answers +cycles+.
+      def initialize(clock)
+        @clock = clock
+        @tape = Storage::KIMTape.new
+        @playing = false
+        @recording = false
+        @stopped_at = 0
+        @started = 0
+        @edges = []
+        @next_edge = 0
+        @high = true
+        @output_high = true
+      end
+
+      def playing? = @playing
+
+      def recording? = @recording
+
+      # How far into the tape the deck is, in microseconds.
+      def position = moving? ? @stopped_at + @clock.cycles - @started : @stopped_at
+
+      # Puts `tape` in the deck, wound back to its start.
+      def insert_tape(tape)
+        stop
+        @tape = tape
+        @stopped_at = 0
+      end
+
+      # Takes the tape out, leaving a blank one with no file.
+      def eject
+        insert_tape(Storage::KIMTape.new)
+      end
+
+      def rewind
+        stop
+        @stopped_at = 0
+      end
+
+      # Presses PLAY.
+      def play
+        stop
+        @edges = @tape.edges
+        at = @stopped_at
+        index = 0
+        index += 1 while index < @edges.length && @edges[index] <= at
+        @next_edge = index
+        @high = index.even?
+        start
+        @playing = true
+      end
+
+      # Presses RECORD and PLAY.
+      def record
+        stop
+        @tape.erase_from(@stopped_at)
+        start
+        @recording = true
+      end
+
+      def stop
+        finish_recording = @recording
+        @stopped_at = position
+        @playing = @recording = false
+        @tape.save if finish_recording && !@tape.path.empty?
+      end
+
+      # PB7 as the deck drives it, in bit 7 of a port B read: the
+      # comparator's level while the tape plays, and high otherwise.
+      def input
+        return 0xff unless @playing
+
+        at = position
+        edges = @edges
+        while @next_edge < edges.length && edges[@next_edge] <= at
+          @high = !@high
+          @next_edge += 1
+        end
+        @high ? 0xff : 0x7f
+      end
+
+      # U2's port B after a write to it, which records a change of PB7.
+      def output(port_b)
+        high = port_b.anybits?(0x80)
+        return if high == @output_high
+
+        @output_high = high
+        @tape.record(position) if @recording
+      end
+
+      private
+
+      def moving? = @playing || @recording
+
+      def start
+        @started = @clock.cycles
+      end
+    end
+  end
+end

data/lib/badline/kim1/teletype.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # A teletype on the KIM-1's 20 mA loop, full duplex, at `baud`
+    # (User Manual, section 2.6 and figure 3.7).
+    #
+    # It sends what #type is given on its line to the board, a start bit,
+    # eight data bits from the lowest and two stop bits a character, and
+    # the board takes the line in on U2's PA7 while PB5 is low. It prints
+    # what the board's printer line carries: PB0, which the monitor drives,
+    # and, through the NAND U26, every bit coming in, so the hardware
+    # echoes what is typed. It reads each character at its own baud,
+    # sampling the middle of each bit from the start bit's edge, a start
+    # bit high again by its middle a glitch, and keeps all it has printed
+    # in #output, without bit 7.
+    #
+    # The monitor reads a character only while it waits for one, so the
+    # teletype sends the next only once both lines have been quiet for
+    # GAP_CHARACTERS characters' time. After a reset it sends RUBOUT, which
+    # the monitor times to learn the baud.
+    class Teletype
+      RUBOUT = 0x7f
+      GAP_CHARACTERS = 2
+
+      # The cycles from a reset to the RUBOUT, by when the monitor waits
+      # for its start bit.
+      RUBOUT_DELAY = 2_000
+
+      BAUDS = [110, 300, 1200, 2400, 4800, 9600].freeze
+
+      # The bits of a character: the start bit, eight data bits and two
+      # stop bits.
+      FRAME_BITS = 11
+
+      attr_reader :baud, :output
+
+      def initialize(panel, baud: 9600)
+        @panel = panel
+        @queue = []
+        @output = +""
+        @line_high = true
+        @sending = 0
+        @sent = FRAME_BITS
+        @send_start = 0
+        @quiet_until = 0
+        @receiving = false
+        @received = 0
+        @bits = 0
+        @edge = 0
+        @sample_at = 0
+        @last_printer = true
+        self.baud = baud
+      end
+
+      # Sets the rate both ways, which the monitor learns at the next reset.
+      def baud=(baud)
+        raise ArgumentError, "no teletype at #{baud} baud" unless BAUDS.include?(baud)
+
+        @baud = baud
+      end
+
+      # Queues `text`'s bytes to send, its letters in capitals, as a Model
+      # 33 types them.
+      def type(text)
+        text.upcase.bytes.each { |byte| @queue << byte }
+      end
+
+      # Whether characters are queued or on their way in or out.
+      def busy? = !@queue.empty? || @sent < FRAME_BITS || @receiving
+
+      # Whether the line to the board is high, its idle level.
+      def line_high? = @line_high
+
+      # Drops what was on its way in and sends RUBOUT once the monitor
+      # is ready for it, at cycle `now`.
+      def reset!(now)
+        @queue.clear
+        @sent = FRAME_BITS
+        drive(true)
+        @queue << RUBOUT
+        @quiet_until = now + RUBOUT_DELAY
+      end
+
+      # Runs cycle `now`, with the printer line `printer_high`.
+      def cycle!(now, printer_high)
+        send_bits(now)
+        receive(now, printer_high)
+      end
+
+      # The teletype's fields in a keyed snapshot module (BL-TTY): the
+      # baud, what is queued, the character going out and the one coming
+      # in, by the cycles they started at, and all it has printed.
+      def save_fields(out)
+        out.int("baud", @baud).ints("queue", @queue).bytes("output", @output)
+        out.bool("line_high", @line_high).int("send.byte", @sending).int("send.bits", @sent)
+        out.int("send.start", @send_start).int("quiet_until", @quiet_until)
+        out.bool("receive.busy", @receiving).int("receive.byte", @received).int("receive.bits", @bits)
+        out.int("receive.edge", @edge).int("receive.sample_at", @sample_at).bool("printer_high", @last_printer)
+      end
+
+      def load_fields(input)
+        baud = input.int("baud", @baud)
+        @baud = BAUDS.include?(baud) ? baud : @baud
+        @queue = input.ints("queue", []).map { |byte| byte & 0xff }
+        @output = input.bytes("output", "".b).dup
+        @line_high = input.bool("line_high", true)
+        @sending = input.int("send.byte", 0) & 0xff
+        @sent = input.int("send.bits", FRAME_BITS).clamp(0, FRAME_BITS)
+        @send_start = input.int("send.start", 0)
+        @quiet_until = input.int("quiet_until", 0)
+        @receiving = input.bool("receive.busy", false)
+        @received = input.int("receive.byte", 0) & 0xff
+        @bits = input.int("receive.bits", 0).clamp(-1, 8)
+        @edge = input.int("receive.edge", 0)
+        @sample_at = input.int("receive.sample_at", 0)
+        @last_printer = input.bool("printer_high", true)
+        @panel.tty_in_high = @line_high
+      end
+
+      private
+
+      # The cycles `halves` half bits take, rounded up.
+      def half_bits(halves) = ((halves * 500_000) + @baud - 1) / @baud
+
+      # Each bit goes out once its time from the start bit has passed.
+      def send_bits(now)
+        if @sent >= FRAME_BITS
+          start_character(now) if !@queue.empty? && !@receiving && now >= @quiet_until
+        elsif now >= @send_start + half_bits(2 * @sent)
+          drive(bit_high?(@sent))
+          @sent += 1
+          @quiet_until = now + half_bits(2 * GAP_CHARACTERS * FRAME_BITS) if @sent == FRAME_BITS
+        end
+      end
+
+      # The character's eleven bits, the start bit going out now.
+      def start_character(now)
+        @sending = @queue.shift
+        @sent = 0
+        @send_start = now
+        send_bits(now)
+      end
+
+      # The start bit low, the data bits from the lowest, the stop bits
+      # high.
+      def bit_high?(index)
+        return false if index.zero?
+        return true if index > 8
+
+        @sending.anybits?(1 << (index - 1))
+      end
+
+      def drive(high)
+        return if high == @line_high
+
+        @line_high = high
+        @panel.tty_in_high = high
+      end
+
+      def receive(now, printer_high)
+        if @receiving
+          sample(now, printer_high) if now >= @sample_at
+        elsif @last_printer && !printer_high
+          @receiving = true
+          @received = 0
+          @bits = -1
+          @edge = now
+          @sample_at = now + half_bits(1)
+        end
+        @last_printer = printer_high
+      end
+
+      # The middle of the start bit, which has to be low still, each data
+      # bit's, then the stop bit's.
+      def sample(now, printer_high)
+        if @bits.negative?
+          @receiving = !printer_high
+          @bits = 0
+        elsif @bits < 8
+          @received |= 1 << @bits if printer_high
+          @bits += 1
+        else
+          @receiving = false
+          @output << (@received & 0x7f).chr if printer_high
+          @quiet_until = [@quiet_until, now + half_bits(2 * GAP_CHARACTERS * FRAME_BITS)].max
+          return
+        end
+        @sample_at = @edge + half_bits((2 * @bits) + 3)
+      end
+    end
+  end
+end

data/lib/badline/kim1.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require "badline/kim1/cpu"
+require "badline/kim1/rriots"
+require "badline/kim1/tape"
+require "badline/kim1/panel"
+require "badline/kim1/key_entry"
+require "badline/kim1/bus"
+require "badline/kim1/sound"
+require "badline/kim1/teletype"
+require "badline/kim1/host_terminal"
+
+module Badline
+  # The MOS KIM-1: a 6502 at 1 MHz, 1K of RAM and two 6530 RRIOTs, U2
+  # with the monitor in its ROM and U3 with the tape routines (KIM1::Bus).
+  # U2's ports drive the keypad and the six LED digits (Panel), and its PB7
+  # the audio output (Sound) and the cassette (Tape). Nothing pulls IRQ
+  # unless U3's PB7 is wired to it, as the User Manual's appendix H has the
+  # user do for U3's timer.
+  #
+  # RS resets the CPU and both 6530s, and ST pulls NMI, which the monitor
+  # leaves to the vector at $17FA: $1C00 there saves the registers and
+  # shows the PC. With the SST switch on, every instruction outside the
+  # monitor ends in an NMI (CPU#single_step). With the TTY/KB jumper
+  # fitted, the monitor talks to a teletype (Teletype) in place of the
+  # keypad and display. It runs headless.
+  class KIM1
+    include Machine::Clocking
+    include Machine::Settling
+    include KeyEntry
+
+    # The cycle by which the monitor is scanning the display, with a
+    # margin.
+    BOOT_CYCLES = 10_000
+
+    attr_reader :bus, :cpu, :u2, :u3, :panel, :teletype, :cycles, :init_threshold
+
+    # Whether the SST switch is on.
+    attr_accessor :sst
+
+    # Whether U3's PB7, its timer's interrupt, is wired to IRQ.
+    attr_accessor :irq_wired
+
+    # The 1 MHz clock. With no video, a frame is nominal: 64 by 260
+    # cycles, some 60 a second.
+    TIMING = Timing.new(clock_hz: 1_000_000, cycles_per_line: 64, lines_per_frame: 260, crop: [0, 0, 0, 0],
+                        pixel_width: 1, dots: 1)
+
+    def family = :kim1
+
+    def ram = @bus.ram
+
+    # Reads and writes memory as the CPU sees it, through the bus.
+    def peek(addr) = @bus.peek(addr)
+
+    def poke(addr, value) = @bus.poke(addr, value)
+
+    # With +tty+ the TTY/KB jumper is fitted, and the monitor talks to a
+    # teletype at +baud+ (Teletype::BAUDS) in place of the keypad and
+    # display. +ram+ names the RAM, one of Bus::RAM_CONFIGURATIONS, or
+    # nil for the stock 1K.
+    def initialize(tty: false, baud: 9600, ram: nil)
+      @cycles = 0
+      @panel = Panel.new(self)
+      @panel.tty = tty
+      @u2 = MonitorRRIOT.new(rom: ROM.read("kim1/6530-002.rom"), peripheral: @panel)
+      @u3 = UserRRIOT.new(rom: ROM.read("kim1/6530-003.rom"))
+      @panel.connect(@u2)
+      @bus = Bus.new(@u2, @u3, ram: ram || :"1k")
+      @cpu = CPU.new(@bus)
+      @sst = false
+      @irq_wired = false
+      @sound = Sound.new(@u2, @u3)
+      @teletype = Teletype.new(@panel, baud:)
+      @teletype.reset!(0) if tty
+      @init_handlers = []
+      @init_threshold = BOOT_CYCLES
+      @pending_keys = nil
+      @key_down = false
+      @next_key_at = 0
+    end
+
+    # Whether the TTY/KB jumper is fitted.
+    def tty? = @panel.tty
+
+    # Fits or takes out the TTY/KB jumper.
+    def tty=(fitted)
+      @panel.tty = fitted
+    end
+
+    def timing = TIMING
+
+    # Types `text` on the teletype with the jumper fitted, and otherwise
+    # presses the keys it names (KeyEntry#type_keys).
+    def type_text(text)
+      return type_keys(text) unless @panel.tty
+
+      @teletype.type(text)
+    end
+
+    # What the teletype has printed: #output holds it all.
+    def capture_output = @teletype
+
+    # What a front end plays: U2's PB7 or the speaker (Sound), which
+    # answers #record and #drain_samples.
+    def sound_source = @sound
+
+    # Whether the speaker on U3's PA0 is wired, and plays in place of PB7.
+    def speaker? = @sound.speaker
+
+    def speaker=(wired)
+      @sound.speaker = wired
+    end
+
+    # The machine as the pause menu names it.
+    def model_label = "KIM-1, #{ram_kb}K RAM"
+
+    # The RAM in K (Bus#ram_kb).
+    def ram_kb = @bus.ram_kb
+
+    # No drive plugs into the KIM-1, and nothing is mounted.
+    def true_drive = nil
+
+    def mounted? = false
+
+    def mounted_path = ""
+
+    # The 6530s count ahead of the CPU. With SST on, the board pulls NMI
+    # ahead of an opcode fetch outside the monitor.
+    def cycle!
+      handle_init if @cycles == @init_threshold
+      feed_keys unless @pending_keys.nil?
+
+      @u2.cycle!
+      @u3.cycle!
+      @sound.cycle! if @sound.recording?
+      @teletype.cycle!(@cycles, @u2.port_b_output.anybits?(0x01) && @teletype.line_high?) if @panel.tty
+      @cpu.irq = @irq_wired && @u3.irq?
+      @cpu.single_step if @sst
+      @cpu.cycle!
+
+      @cycles += 1
+    end
+
+    # RS: the RST line resets the CPU and both 6530s. RAM keeps what it
+    # holds. A teletype then sends RUBOUT for the monitor to time.
+    def reset!
+      @u2.reset!
+      @u3.reset!
+      @cpu.reset!
+      @teletype.reset!(@cycles) if @panel.tty
+    end
+
+    alias press_reset reset!
+
+    # Switches the machine off and on: RAM starts cleared, and RS resets
+    # everything else.
+    def power_cycle!
+      @bus.power_on!
+      reset!
+    end
+
+    # ST: an edge on NMI.
+    def press_stop
+      @cpu.nmi = true
+    end
+
+    # Holds down the key Panel::KEYS names `name`.
+    def press_key(name)
+      @panel.press(name)
+    end
+
+    def release_key
+      @panel.release
+    end
+
+    # The segments each LED digit shows (Panel#display).
+    def display = @panel.display
+
+    # The display as text, such as "0200 A9" (Panel#display_text).
+    def display_text = @panel.display_text
+
+    # The cassette deck on U2's PB7.
+    def tape = @panel.tape
+  end
+end
+
+require "badline/snapshot/kim1_setup"
+require "badline/kim1/keyed_state"
+require "badline/kim1/keyed_modules"