badline 0.16.1 → 0.18.0

data/lib/badline/kim1/keyed_state.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    class Bus
+      # The RAM, the expansion's too, and the last byte on the bus, in a
+      # keyed snapshot module (BL-RAM). The 6530s keep their own 64 bytes.
+      module KeyedState
+        def save_fields(out)
+          @ram.save_fields(out, "ram")
+          out.int("data", @data)
+        end
+
+        def load_fields(input)
+          @ram.load_fields(input, "ram")
+          @data = input.byte("data", @data)
+        end
+      end
+
+      include KeyedState
+    end
+
+    class Panel
+      # The panel's fields in a keyed snapshot module (BL-PANEL): the
+      # TTY/KB jumper, the key held down, the digit lit and its segments
+      # since the cycle they lit, the cycles each segment has been lit,
+      # and what each digit last showed and when. The teletype restores
+      # the line in.
+      module KeyedState
+        def save_fields(out)
+          out.bool("tty", @tty).int("held", @held).int("digit", @digit).int("segments", @segments)
+          out.int("since", @since).ints("lit", @lit).ints("shown", @shown).ints("shown_at", @shown_at)
+        end
+
+        def load_fields(input)
+          @tty = input.bool("tty", false)
+          held = input.int("held", -1)
+          @held = held.between?(0, KEYS.length - 1) ? held : -1
+          digit = input.int("digit", -1)
+          @digit = digit.between?(0, DIGITS - 1) ? digit : -1
+          @segments = input.masked("segments", 0, 0x7f)
+          @since = input.int("since", 0)
+          input.ints_into("lit", @lit)
+          input.ints_into("shown", @shown)
+          input.ints_into("shown_at", @shown_at)
+        end
+      end
+
+      include KeyedState
+    end
+
+    class Tape
+      # The deck's fields in a keyed snapshot module (BL-DECK): whether
+      # PLAY or RECORD is down, how far into the tape the deck is, the next
+      # of the tape's edges to play and PB7's level from it, the level U2
+      # last drove PB7 to, and the tape itself under tape.*: its file's
+      # path, and the time from each crossing to the next, from the start.
+      # The tape goes back in from the module, and STOP after a recording
+      # writes it to that path.
+      module KeyedState
+        def save_fields(out)
+          out.bool("playing", @playing).bool("recording", @recording).int("position", position)
+          out.int("next_edge", @next_edge).bool("high", @high).bool("output_high", @output_high)
+          crossings = @tape.crossings
+          gaps = crossings.each_with_index.map { |time, index| index.zero? ? time : time - crossings[index - 1] }
+          out.text("tape.path", @tape.path).ints("tape.gaps", gaps)
+        end
+
+        def load_fields(input)
+          time = 0
+          crossings = input.ints("tape.gaps", []).map { |gap| time += gap }
+          @tape = Storage::KIMTape.new(input.text("tape.path", ""), crossings:)
+          @playing = input.bool("playing", false)
+          @recording = input.bool("recording", false) && !@playing
+          @stopped_at = input.int("position", 0)
+          @started = @clock.cycles
+          @edges = @playing ? @tape.edges : []
+          @next_edge = input.int("next_edge", 0).clamp(0, @edges.length)
+          @high = input.bool("high", true)
+          @output_high = input.bool("output_high", true)
+        end
+      end
+
+      include KeyedState
+    end
+
+    # The machine's own fields in a keyed snapshot module (BL-MACHINE):
+    # the family, its setup (Snapshot::KIM1Setup), the cycle count, the
+    # SST switch and U3's PB7 wiring, and under host.* whether type_keys
+    # is typing, the keys it has still to press, by their place in KEY_NAMES, the one held, when
+    # the next goes, and the on_init handlers still to run. The badline
+    # version that wrote it is written for reports and never read.
+    module KeyedState
+      # The keys type_keys presses, as host.pending_keys numbers them.
+      KEY_NAMES = (Panel::KEYS + %w[ST RS]).freeze
+
+      # How many more on_init handlers the machine a snapshot was taken of
+      # had yet to run than this one has. Nil until the machine is restored.
+      attr_reader :init_handlers_lost
+
+      # Whether a snapshot saves now (Machine::Settling): the CPU between
+      # instructions or jammed.
+      def settled_for_snapshot? = @cpu.boundary? || @cpu.jammed?
+
+      # Nothing on the board defers its work.
+      def settle_chips_for_snapshot = nil
+
+      def save_machine_fields(out)
+        out.text("family", "kim1").text("written_by", VERSION)
+        Snapshot::KIM1Setup.of(self).write_fields(out)
+        out.int("cycles", @cycles).bool("sst", @sst).bool("irq_wired", @irq_wired)
+        pending = @pending_keys
+        out.bool("host.typing", !pending.nil?)
+        out.ints("host.pending_keys", pending.map { |name| KEY_NAMES.index(name) }) if pending
+        out.bool("host.key_down", @key_down).int("host.next_key_at", @next_key_at)
+        out.int("host.init_pending", @cycles <= @init_threshold ? @init_handlers.length : 0)
+      end
+
+      def load_machine_fields(input)
+        @cycles = input.int("cycles", @cycles)
+        @sst = input.bool("sst", false)
+        @irq_wired = input.bool("irq_wired", false)
+        pending = input.ints("host.pending_keys", []).filter_map { |index| KEY_NAMES[index] if index >= 0 }
+        @pending_keys = input.bool("host.typing", false) ? pending : nil
+        @key_down = input.bool("host.key_down", false)
+        @next_key_at = input.int("host.next_key_at", 0)
+        @init_handlers_lost = [input.int("host.init_pending", 0) - @init_handlers.length, 0].max
+      end
+    end
+
+    include KeyedState
+  end
+end

data/lib/badline/kim1/panel.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # The keypad and display on U2's ports (User Manual, figures 3.5 and
+    # 3.6), and the TTY/KB jumper.
+    #
+    # PB1-PB4 feed a 74145 decoder, U24. Its outputs 0-2 select the
+    # keypad's three rows, 3 the jumper, and 4-9 the six LED digits, left
+    # to right. PA0-PA6 drive the selected digit's segments a-g, a high
+    # line lighting one, and read the selected row's keys, a pressed key
+    # pulling its line low: PA6 is the row's first key, PA0 its seventh.
+    # Fitted, the jumper pulls PA0 low while output 3 is selected, which
+    # the monitor reads as teletype mode, and PA7 takes the teletype's
+    # line in (Teletype). PB7 is the cassette's line (Tape).
+    #
+    # Nothing holds the display lit. A program lights each digit in turn
+    # (the monitor's SCANDS, $1F1F), so the panel times how long each
+    # segment is lit from the writes to U2's ports: lit_cycles hands the
+    # totals to a front end, and display reads back what the digits show.
+    class Panel
+      # The keys of the matrix, by the code the monitor's GETKEY ($1F6A)
+      # gives them: the row times 7 plus the column.
+      KEYS = %w[0 1 2 3 4 5 6 7 8 9 A B C D E F AD DA + GO PC].freeze
+
+      # The monitor's segment patterns for 0-F, its table at $1FE7 without
+      # bit 7, which PA7 doesn't drive.
+      HEX_SEGMENTS = [0x3f, 0x06, 0x5b, 0x4f, 0x66, 0x6d, 0x7d, 0x07,
+                      0x7f, 0x6f, 0x77, 0x7c, 0x39, 0x5e, 0x79, 0x71].freeze
+
+      DIGITS = 6
+
+      # The decoder output of the leftmost digit.
+      FIRST_DIGIT = 4
+
+      # A digit lit for less than this many cycles at a time doesn't count
+      # as showing anything: the monitor passes its digits through that
+      # quickly between patterns.
+      SHOWN_CYCLES = 100
+
+      # A digit not lit for this many cycles, some five of the monitor's
+      # scans, reads as dark.
+      DARK_CYCLES = 20_000
+
+      # Whether the TTY/KB jumper is fitted.
+      attr_accessor :tty
+
+      # Whether the teletype's line in is high, its idle level. Low, it
+      # pulls PA7 low while PB5 is low, which gates it through.
+      attr_accessor :tty_in_high
+
+      # The cassette deck on PB7.
+      attr_reader :tape
+
+      # +clock+ answers +cycles+, the cycle each write to the ports lands
+      # on.
+      def initialize(clock)
+        @clock = clock
+        @rriot = nil
+        @tty = false
+        @tty_in_high = true
+        @tape = Tape.new(clock)
+        @held = -1
+        @digit = -1
+        @segments = 0
+        @since = 0
+        @lit = Array.new(DIGITS * 7, 0)
+        @shown = Array.new(DIGITS, 0)
+        @shown_at = Array.new(DIGITS, -DARK_CYCLES - 1)
+      end
+
+      # U2, whose port B selects the row the keys are read from.
+      def connect(rriot)
+        @rriot = rriot
+      end
+
+      # Holds down the key KEYS names `name`, and lets go of any other.
+      def press(name)
+        code = KEYS.index(name)
+        raise ArgumentError, "no KIM-1 key named #{name}" if code.nil?
+
+        @held = code
+      end
+
+      def release
+        @held = -1
+      end
+
+      # The name of the key held down, or nil.
+      def held = @held.negative? ? nil : KEYS[@held]
+
+      def read_a(_lines)
+        port_b = @rriot.port_b_output
+        row = decoded(port_b)
+        mask = @tty_in_high || port_b.anybits?(0x20) ? 0xff : 0x7f
+        mask &= 0xfe if row == 3 && @tty
+        held = @held
+        mask &= ~(0x40 >> (held % 7)) & 0xff if held >= 0 && held / 7 == row
+        mask
+      end
+
+      def read_b(_lines) = @tape.input
+
+      # The lines U2's ports drive after a write to them.
+      def lines_written(port_a, port_b)
+        @tape.output(port_b)
+        digit = decoded(port_b) - FIRST_DIGIT
+        digit = -1 unless digit >= 0 && digit < DIGITS
+        segments = digit.negative? ? 0 : port_a & 0x7f
+        return if digit == @digit && segments == @segments
+
+        now = @clock.cycles
+        end_lit(now)
+        @digit = digit
+        @segments = segments
+        @since = now
+      end
+
+      # The cycles each segment has been lit since the last call, seven to
+      # a digit from the left, a to g, and starts counting again.
+      def lit_cycles
+        now = @clock.cycles
+        end_lit(now)
+        @since = now
+        totals = @lit.dup
+        @lit.map! { 0 }
+        totals
+      end
+
+      # The segments, a in bit 0 to g in bit 6, each digit shows: its
+      # pattern the last time it was lit for SHOWN_CYCLES or more, or 0
+      # once it has been dark for DARK_CYCLES.
+      def display
+        now = @clock.cycles
+        Array.new(DIGITS) do |digit|
+          if digit == @digit && @segments != 0 && now - @since >= SHOWN_CYCLES
+            @segments
+          elsif now - @shown_at[digit] <= DARK_CYCLES
+            @shown[digit]
+          else
+            0
+          end
+        end
+      end
+
+      # The display as text, such as "0200 A9": a space for a dark digit
+      # and ? for a pattern that isn't a hex digit, with a space between
+      # the address and the data.
+      def display_text
+        chars = display.map do |segments|
+          next " " if segments.zero?
+
+          index = HEX_SEGMENTS.index(segments)
+          index.nil? ? "?" : index.to_s(16).upcase
+        end
+        "#{chars[0, 4].join} #{chars[4, 2].join}"
+      end
+
+      private
+
+      def decoded(port_b) = (port_b >> 1) & 0x0f
+
+      def end_lit(now)
+        digit = @digit
+        return if digit.negative? || @segments.zero?
+
+        lit = now - @since
+        7.times { |segment| @lit[(digit * 7) + segment] += lit if @segments.anybits?(1 << segment) }
+        return if lit < SHOWN_CYCLES
+
+        @shown[digit] = @segments
+        @shown_at[digit] = now
+      end
+    end
+  end
+end

data/lib/badline/kim1/rriots.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # Each 6530 a class of its own, so each keeps one type of peripheral.
+
+    # U2, the 6530-002: the monitor's ROM, and the ports that drive the
+    # keypad, the display, the teletype and the tape. Its peripheral is
+    # the Panel, which hears every write to the port and direction
+    # registers, so it can time how long each LED segment is lit.
+    class MonitorRRIOT < Chips::RRIOT
+      def reset!
+        super
+        @peripheral&.lines_written(port_a_output, port_b_output)
+      end
+
+      def poke(addr, value)
+        super
+        @peripheral.lines_written(port_a_output, port_b_output) if addr.nobits?(0x04)
+      end
+    end
+
+    # U3, the 6530-003: the tape routines' ROM, and the ports the
+    # application connector carries for the user, with nothing on them.
+    class UserRRIOT < Chips::RRIOT
+    end
+  end
+end

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