badline 0.16.1 → 0.18.0

data/lib/badline/kernal_trap/ieee.rb

@@ -54,7 +54,9 @@ module Badline
         address_device if @listening
       end
 
-      def addressed? = @bus.peek(zero_page.device) == @device
+      # The device TALK or LISTEN addresses: the one in A or in FA, as the
+      # layout says.
+      def addressed? = (@layout.device_in_a ? @cpu.a : @bus.peek(zero_page.device)) == @device
 
       # TALK and LISTEN end with the command sent under ATN, which stays
       # low, and A holding $FF.
@@ -116,7 +118,7 @@ module Badline
       def acptr
         return unless @talking
 
-        @layout.listen_to_talker(@bus)
+        @layout.byte_received(@bus)
         byte, status = received
         time_serial_byte(Routine::ACPTR_TIMEOUT)
         @cpu.a = byte

data/lib/badline/kernal_trap/ieee_layout.rb

@@ -2,70 +2,122 @@
 
 module Badline
   module KernalTrap
-    # Where a PET KERNAL keeps the eight IEEE-488 bus primitives, which are
-    # internal routines, not jump table entries, and the ZeroPage of its
-    # file variables. Each ROM set has its own.
-    #
-    # TALK and LISTEN take no device number in A: they send $40 or $20
-    # ORed with FA. UNTALK and UNLISTEN send $5F and $3F through the same
-    # code, and SECOND, TKSA, UNTALK and UNLISTEN end by letting go of ATN
-    # (VIA PB2) themselves. Each handshake times out on VIA timer 1, which
-    # the ROM starts with a write of $FF to $E845. LOAD and SAVE run in the
-    # ROM, through the primitives. +overwrites_device+ says UNTALK and
-    # UNLISTEN store their command in FA before they send it.
+    # The +keep+ of an IEEELineStep that only reads its register.
+    IEEE_LINE_READ = -1
+
+    # One step a KERNAL takes on the IEEE-488 bus's lines: a write of +set+
+    # to the register at +address+, or with a +keep+ mask the register read
+    # first, its +keep+ bits kept and +set+ ORed in, or with keep
+    # IEEE_LINE_READ only a read. Returns the value written, or read.
+    IEEELineStep = Data.define(:address, :keep, :set) do
+      def act_on(bus)
+        return bus.peek(address) if keep == IEEE_LINE_READ
+
+        value = keep.zero? ? set : (bus.peek(address) & keep) | set
+        bus.poke(address, value)
+        value
+      end
+    end
+
+    # The steps a KERNAL takes on the bus's lines at each moment the traps
+    # stand in for, each run in order (#run_steps), the last one's value
+    # returned: +timer+ starts the timer that times out each byte's
+    # handshake, +attention+ readies the bus and pulls ATN low for TALK
+    # and LISTEN, +byte_sent+ ends a byte sent, +release_attention+ ends
+    # SECOND, TKSA, UNTALK and UNLISTEN by letting ATN go, +listen_to_talker+
+    # ends TKSA with the computer listening, +byte_received+ ends ACPTR,
+    # and +release+ ends UNTALK and UNLISTEN.
+    IEEELines = Data.define(:timer, :attention, :byte_sent, :release_attention, :listen_to_talker, :byte_received,
+                            :release) do
+      def run_steps(steps, bus)
+        value = 0
+        steps.each { |step| value = step.act_on(bus) }
+        value
+      end
+    end
+
+    # Where a KERNAL keeps the eight IEEE-488 bus primitives, which are
+    # internal routines, not jump table entries, the ZeroPage of its file
+    # variables, and the steps it takes on the bus's lines (IEEELines).
+    # Each ROM set has its own.
     #
-    # The ROM drives the bus's control lines from three chips: ATN from VIA
-    # PB2 and NRFD from PB1 at $E840, NDAC from PIA 2's CA2 and DAV from its
-    # CB2, through the control registers at $E821 and $E823, which the ROM
-    # writes $34 to pull a line low and $3C to let it go, and the data lines
-    # from PIA 2's port B at $E822. The steps below leave the lines as each
-    # primitive leaves them.
+    # On a PET, TALK and LISTEN take no device number in A: they send $40
+    # or $20 ORed with FA. UNTALK and UNLISTEN send $5F and $3F through the
+    # same code, and SECOND, TKSA, UNTALK and UNLISTEN end by letting go of
+    # ATN themselves. LOAD and SAVE run in the ROM, through the primitives.
+    # +overwrites_device+ says UNTALK and UNLISTEN store their command in
+    # FA before they send it. +device_in_a+ says TALK and LISTEN take the
+    # device in A, as the CBM-II's do, where a PET's ignore A and read FA.
     IEEELayout = Data.define(:talk, :listen, :second, :tksa, :ciout, :untalk, :unlisten, :acptr, :overwrites_device,
-                             :zero_page) do
-      # The KERNAL is mapped unless an 8096's board lies over it.
+                             :device_in_a, :zero_page, :lines) do
+      # The KERNAL is mapped unless something lies over it.
       def kernal_mapped?(bus) = bus.kernal_mapped?
 
-      # Starts VIA timer 1, which times out the handshake of each byte.
+      # Starts the timer that times out the handshake of each byte.
       def time_serial_byte(bus, _timer_high)
-        bus.poke(0xe845, 0xff)
+        lines.run_steps(lines.timer, bus)
       end
 
-      # TALK and LISTEN: NRFD and NDAC let go, then ATN pulled low.
+      # TALK and LISTEN: the handshake lines let go, then ATN pulled low.
       def attention(bus)
-        bus.poke(0xe840, bus.peek(0xe840) | 0x02)
-        bus.poke(0xe821, 0x3c)
-        bus.poke(0xe840, bus.peek(0xe840) & 0xfb)
+        lines.run_steps(lines.attention, bus)
       end
 
       # The end of a byte sent: DAV and the data lines let go.
       def byte_sent(bus)
-        bus.poke(0xe823, 0x3c)
-        bus.poke(0xe822, 0xff)
+        lines.run_steps(lines.byte_sent, bus)
       end
 
       # The end of SECOND, TKSA, UNTALK and UNLISTEN: ATN let go. Returns
       # the value written, which the ROM leaves in A.
       def release_attention(bus)
-        value = bus.peek(0xe840) | 0x04
-        bus.poke(0xe840, value)
-        value
+        lines.run_steps(lines.release_attention, bus)
       end
 
-      # TKSA and ACPTR end listening: NRFD and NDAC pulled low.
+      # TKSA ends listening: NRFD and NDAC pulled low.
       def listen_to_talker(bus)
-        bus.poke(0xe840, bus.peek(0xe840) & 0xfd)
-        bus.poke(0xe821, 0x34)
+        lines.run_steps(lines.listen_to_talker, bus)
+      end
+
+      # ACPTR ends listening as well.
+      def byte_received(bus)
+        lines.run_steps(lines.byte_received, bus)
       end
 
       # The end of UNTALK and UNLISTEN, which address the bus as TALK and
-      # LISTEN do, send their command and let ATN go.
+      # LISTEN do, send their command and let ATN go. Returns the value
+      # the ROM leaves in A.
       def release_serial_lines(bus)
-        attention(bus)
-        byte_sent(bus)
-        release_attention(bus)
+        lines.run_steps(lines.release, bus)
       end
     end
 
+    # A PET drives the bus's control lines from three chips: ATN from VIA
+    # PB2 and NRFD from PB1 at $E840, NDAC from PIA 2's CA2 and DAV from its
+    # CB2, through the control registers at $E821 and $E823, which the ROM
+    # writes $34 to pull a line low and $3C to let it go, and the data lines
+    # from PIA 2's port B at $E822. Each handshake times out on VIA timer 1,
+    # which the ROM starts with a write of $FF to $E845. The steps leave the
+    # lines as each primitive leaves them.
+    PET_ATTENTION = [
+      IEEELineStep.new(address: 0xe840, keep: 0xff, set: 0x02),
+      IEEELineStep.new(address: 0xe821, keep: 0, set: 0x3c),
+      IEEELineStep.new(address: 0xe840, keep: 0xfb, set: 0)
+    ].freeze
+    PET_BYTE_SENT = [
+      IEEELineStep.new(address: 0xe823, keep: 0, set: 0x3c),
+      IEEELineStep.new(address: 0xe822, keep: 0, set: 0xff)
+    ].freeze
+    PET_RELEASE_ATTENTION = [IEEELineStep.new(address: 0xe840, keep: 0xff, set: 0x04)].freeze
+    PET_LISTEN = [IEEELineStep.new(address: 0xe840, keep: 0xfd, set: 0),
+                  IEEELineStep.new(address: 0xe821, keep: 0, set: 0x34)].freeze
+    PET_LINES = IEEELines.new(
+      timer: [IEEELineStep.new(address: 0xe845, keep: 0, set: 0xff)].freeze,
+      attention: PET_ATTENTION, byte_sent: PET_BYTE_SENT, release_attention: PET_RELEASE_ATTENTION,
+      listen_to_talker: PET_LISTEN, byte_received: PET_LISTEN,
+      release: (PET_ATTENTION + PET_BYTE_SENT + PET_RELEASE_ATTENTION).freeze
+    )
+
     # The file variables of the BASIC 2 and BASIC 4 KERNALs, which keep
     # them at the same addresses. SAVE copies STAL at $FB to SAL at $C7 and
     # walks SAL up to EAL at $C9. LOAD keeps no MEMUSS: it stores each byte
@@ -90,24 +142,24 @@ module Badline
     # LISTEN without a secondary address.
     PET_BASIC1_LAYOUT = IEEELayout.new(
       talk: 0xf0b6, listen: 0xf0ba, second: 0xf12c, tksa: 0xf15b,
-      ciout: 0xf167, untalk: 0xf17a, unlisten: 0xf17e, acptr: 0xf187, overwrites_device: true,
-      zero_page: PET_BASIC1_ZERO_PAGE
+      ciout: 0xf167, untalk: 0xf17a, unlisten: 0xf17e, acptr: 0xf187, overwrites_device: true, device_in_a: false,
+      zero_page: PET_BASIC1_ZERO_PAGE, lines: PET_LINES
     )
 
     # BASIC 2, 901465-03. Its LOAD sends the secondary address after TALK
     # with SECOND, not TKSA.
     PET_BASIC2_LAYOUT = IEEELayout.new(
       talk: 0xf0b6, listen: 0xf0ba, second: 0xf128, tksa: 0xf164,
-      ciout: 0xf16f, untalk: 0xf17f, unlisten: 0xf183, acptr: 0xf18c, overwrites_device: false,
-      zero_page: PET_ZERO_PAGE
+      ciout: 0xf16f, untalk: 0xf17f, unlisten: 0xf183, acptr: 0xf18c, overwrites_device: false, device_in_a: false,
+      zero_page: PET_ZERO_PAGE, lines: PET_LINES
     )
 
     # BASIC 4, 901465-22. LISTEN at $F0D5 is the operand of the BIT
     # instruction that skips it on the way from TALK.
     PET_BASIC4_LAYOUT = IEEELayout.new(
       talk: 0xf0d2, listen: 0xf0d5, second: 0xf143, tksa: 0xf193,
-      ciout: 0xf19e, untalk: 0xf1ae, unlisten: 0xf1b9, acptr: 0xf1c0, overwrites_device: false,
-      zero_page: PET_ZERO_PAGE
+      ciout: 0xf19e, untalk: 0xf1ae, unlisten: 0xf1b9, acptr: 0xf1c0, overwrites_device: false, device_in_a: false,
+      zero_page: PET_ZERO_PAGE, lines: PET_LINES
     )
   end
 end

data/lib/badline/kim1/bus.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # The CPU's bus. The board decodes A10-A12 into eight 1K blocks and
+    # leaves A13-A15 alone, so the 8K repeats through all 64K, and the
+    # vectors at $FFFA-$FFFF are the monitor's at $1FFA-$1FFF (User Manual,
+    # figure 3.12 and section 6.2):
+    #
+    # $0000-$03FF - the 1K of RAM
+    # $0400-$16FF - nothing
+    # $1700-$173F - U3's ports and timer, its 16 registers repeated
+    # $1740-$177F - U2's
+    # $1780-$17BF - U3's 64 bytes of RAM
+    # $17C0-$17FF - U2's
+    # $1800-$1BFF - U3's ROM, the tape routines
+    # $1C00-$1FFF - U2's ROM, the monitor
+    #
+    # A read from nothing finds the last byte on the bus. Writes to ROM
+    # and to nothing go nowhere.
+    #
+    # The board takes more RAM, as RAM_CONFIGURATIONS names it: the stock
+    # 1K, 5K with a board in K1-K4 filling $0400-$13FF, or those 5K and
+    # RAM at $2000-$DFFF, with an expansion that decodes A13-A15 and
+    # repeats the first 8K only at $E000-$FFFF, so the vectors are still
+    # the monitor's (User Manual, sections 6.1 and 6.2).
+    class Bus
+      include Addressable
+
+      RAM_CONFIGURATIONS = %i[1k 5k expanded].freeze
+
+      # The RAM, and the one of RAM_CONFIGURATIONS it comes as.
+      attr_reader :ram, :ram_configuration
+
+      # The last byte the CPU read or wrote.
+      attr_reader :data
+
+      # +monitor+ is U2, the 6530-002, and +user+ U3, the 6530-003, with
+      # the RAM `ram` names.
+      def initialize(monitor, user, ram: :"1k")
+        addressable_at(0, length: 2**16)
+        raise ArgumentError, "no KIM-1 RAM configuration named #{ram}" unless RAM_CONFIGURATIONS.include?(ram)
+
+        @u2 = monitor
+        @u3 = user
+        @ram_configuration = ram
+        # The end of RAM in the first 8K, and where the first 8K stops
+        # repeating, past the RAM above it.
+        @low_end = ram == :"1k" ? 0x0400 : 0x1400
+        @mirror_end = ram == :expanded ? 0xe000 : 0x2000
+        @ram = Memory.new([], length: @mirror_end == 0x2000 ? @low_end : @mirror_end, start: 0)
+        @data = 0
+      end
+
+      # The RAM in K, without the 6530s' 64 bytes each.
+      def ram_kb = (@low_end + @mirror_end - 0x2000) >> 10
+
+      # Whether RAM answers at `addr`, the board's or a 6530's.
+      def ram?(addr)
+        offset = addr < 0x2000 || addr >= @mirror_end ? addr & 0x1fff : addr
+        offset < @low_end || offset >= 0x2000 || offset.between?(0x1780, 0x17ff)
+      end
+
+      def peek(addr)
+        offset = addr < 0x2000 || addr >= @mirror_end ? addr & 0x1fff : addr
+        @data = if offset < @low_end || offset >= 0x2000
+                  @ram.peek(offset)
+                elsif offset >= 0x1c00
+                  @u2.read_rom(offset)
+                elsif offset >= 0x1800
+                  @u3.read_rom(offset)
+                elsif (offset >> 8) == 0x17
+                  read_chips(offset)
+                else
+                  @data
+                end
+      end
+
+      def poke(addr, value)
+        @data = value
+        offset = addr < 0x2000 || addr >= @mirror_end ? addr & 0x1fff : addr
+        if offset < @low_end || offset >= 0x2000
+          @ram.poke(offset, value)
+        elsif (offset >> 8) == 0x17
+          write_chips(offset, value)
+        end
+      end
+
+      def power_on!
+        @ram.clear!
+        @u2.ram.map! { 0 }
+        @u3.ram.map! { 0 }
+      end
+
+      private
+
+      # A6 picks U2 over U3, and A7 the RAM over the registers.
+      def read_chips(offset)
+        ram = offset.anybits?(0x80)
+        if offset.anybits?(0x40)
+          ram ? @u2.read_ram(offset) : @u2.peek(offset & 0x0f)
+        else
+          ram ? @u3.read_ram(offset) : @u3.peek(offset & 0x0f)
+        end
+      end
+
+      def write_chips(offset, value)
+        ram = offset.anybits?(0x80)
+        if offset.anybits?(0x40)
+          ram ? @u2.write_ram(offset, value) : @u2.poke(offset & 0x0f, value)
+        else
+          ram ? @u3.write_ram(offset, value) : @u3.poke(offset & 0x0f, value)
+        end
+      end
+    end
+  end
+end

data/lib/badline/kim1/cpu.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # The KIM-1's 6502, U1, on the KIM1::Bus.
+    #
+    # With the SST switch on, the board's U26 gate pulls NMI low through
+    # each opcode fetch outside K7, $1C00-$1FFF and its mirrors, where the
+    # monitor runs. The CPU takes the NMI at the end of the instruction
+    # that fetch starts, a 2-cycle one too, so the monitor steps a program
+    # one instruction at a time (User Manual, figure 5.6).
+    class CPU
+      include Badline::Chips::CPU::Core
+
+      # The K7 block's address lines, A10-A12, which the board decodes.
+      K7 = 0x1c00
+
+      # Pulls NMI if the next cycle fetches an opcode outside K7. The
+      # board calls it ahead of each cycle while SST is on.
+      def single_step
+        @nmi = true if boundary? && (@program_counter & K7) != K7
+      end
+    end
+  end
+end

data/lib/badline/kim1/host_terminal.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # The KIM-1's teletype on the host's terminal, for `badline kim1
+    # --headless`: what the terminal types goes down the line, and what
+    # the teletype prints comes out on it, without the NULs and RUBOUTs a
+    # terminal doesn't show. The machine runs at its own 1 MHz against the
+    # host's clock, catching up at most CATCH_UP seconds at a time, until
+    # Ctrl-C.
+    #
+    # `console` answers #typing, #read_text and #print_text, as
+    # Audio::Terminal does.
+    class HostTerminal
+      SLICE = 0.01
+      CATCH_UP = 0.1
+
+      def self.run(machine, console) = new(machine, console).run
+
+      # Builds the KIM-1 the command line's `options` name, loads the
+      # program they name (Media::KIM1Media), and runs it on `console`
+      # until Ctrl-C. Returns the exit status, 1 when the program won't
+      # load, which it warns about.
+      def self.start(options, console)
+        path = options.media_path
+        machine = Machine.for_options(options, path)
+        unless path.nil?
+          loaded = Media.attach(machine, path, autostart: true, kim1: Media::KIM1Media.loading(options))
+          console.print_text("#{loaded}\r\n")
+        end
+        run(machine, console)
+      rescue Machine::Unsupported, Storage::Papertape::FormatError, SystemCallError => e
+        warn "#{options.program}: #{path}: #{e.message}"
+        1
+      end
+
+      def initialize(machine, console)
+        @machine = machine
+        @console = console
+        @printed = 0
+        @started = 0.0
+      end
+
+      # Runs until Ctrl-C, and returns the exit status.
+      def run
+        @started = now
+        @console.print_text("KIM-1 teletype at #{@machine.teletype.baud} baud. Ctrl-C: Quit\r\n")
+        @console.typing { loop { step } }
+      rescue Interrupt
+        0
+      end
+
+      private
+
+      def step
+        text = @console.read_text(SLICE)
+        @machine.teletype.type(text) unless text.empty?
+        behind = ((now - @started) * 1_000_000).to_i - @machine.cycles
+        @machine.run_cycles([behind, (CATCH_UP * 1_000_000).to_i].min) if behind.positive?
+        print_output
+      end
+
+      def print_output
+        output = @machine.teletype.output
+        return if output.size == @printed
+
+        @console.print_text(output[@printed, output.size - @printed].gsub("\x00", "").gsub("\x7f", ""))
+        @printed = output.size
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/badline/kim1/key_entry.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # Pressing the panel's keys in turn, each long enough for the monitor
+    # to take it. The monitor takes a key it reads down on two scans in a
+    # row, after a scan with no key down, and a scan takes some 4,300
+    # cycles, so each key is held for HOLD_CYCLES and let go for
+    # RELEASE_CYCLES.
+    module KeyEntry
+      HOLD_CYCLES = 12_000
+      RELEASE_CYCLES = 8_000
+
+      # The panel's keys that type_keys takes by name. Any other word is a
+      # run of hex keys.
+      NAMED_KEYS = %w[AD DA GO PC + ST RS].freeze
+
+      # Presses the keys `text` names once the monitor is running: AD, DA,
+      # GO, PC, + and the hex digits, ST, which pulls NMI, and RS, which
+      # resets the machine. Words go by whitespace, and a word that isn't a
+      # key's name is a hex key for each of its characters, so
+      # "AD 0200 DA A9 +" presses nine keys, and the byte $AD goes in as
+      # "A D".
+      def type_keys(text)
+        keys = text.upcase.split.flat_map { |word| NAMED_KEYS.include?(word) ? [word] : word.chars }
+        unknown = keys.find { |key| !NAMED_KEYS.include?(key) && !Panel::KEYS.include?(key) }
+        raise ArgumentError, "no KIM-1 key named #{unknown}" unless unknown.nil?
+
+        on_init { queue_keys(keys) }
+      end
+
+      # Whether keys type_keys was given are still to be pressed.
+      def typing? = !@pending_keys.nil?
+
+      private
+
+      def queue_keys(keys)
+        @pending_keys = keys
+        @key_down = false
+        @next_key_at = @cycles
+      end
+
+      def feed_keys
+        return if @cycles < @next_key_at
+
+        if @key_down
+          release_key
+          @key_down = false
+          @next_key_at = @cycles + RELEASE_CYCLES
+        else
+          press_next_key
+        end
+      end
+
+      def press_next_key
+        keys = @pending_keys
+        name = keys.shift
+        if name.nil?
+          @pending_keys = nil
+          return
+        end
+        if name == "ST"
+          press_stop
+        elsif name == "RS"
+          press_reset
+        else
+          press_key(name)
+        end
+        @key_down = true
+        @next_key_at = @cycles + HOLD_CYCLES
+      end
+    end
+  end
+end

data/lib/badline/kim1/keyed_modules.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Badline
+  class KIM1
+    # The whole machine as keyed snapshot modules (Snapshot::Keyed), in the
+    # order a load applies them: BL-MACHINE with the setup, the RAM, U2 and
+    # U3, each with its 64 bytes, ports and timer, the panel, the cassette
+    # deck, the teletype, the sound's wiring and the CPU.
+    module KeyedModules
+      def save_modules
+        sound = @sound
+        [Snapshot::Keyed.section("BL-MACHINE") { |out| save_machine_fields(out) },
+         Snapshot::Keyed.section("BL-CPU") { |out| @cpu.save_fields(out) },
+         Snapshot::Keyed.section("BL-RAM") { |out| @bus.save_fields(out) },
+         Snapshot::Keyed.section("BL-U2") { |out| @u2.save_fields(out) },
+         Snapshot::Keyed.section("BL-U3") { |out| @u3.save_fields(out) },
+         Snapshot::Keyed.section("BL-PANEL") { |out| @panel.save_fields(out) },
+         Snapshot::Keyed.section("BL-DECK") { |out| @panel.tape.save_fields(out) },
+         Snapshot::Keyed.section("BL-TTY") { |out| @teletype.save_fields(out) },
+         Snapshot::Keyed.section("BL-SOUND") { |out| out.bool("speaker", sound.speaker) }]
+      end
+
+      # Raises Snapshot::FormatError for the modules of a machine built
+      # another way.
+      def load_modules(modules)
+        machine = modules.machine
+        check_snapshot_setup(Snapshot::KIM1Setup.read_fields(machine))
+        load_machine_fields(machine)
+        @bus.load_fields(modules.required("BL-RAM"))
+        @u2.load_fields(modules.required("BL-U2"))
+        @u3.load_fields(modules.required("BL-U3"))
+        @panel.load_fields(modules.required("BL-PANEL"))
+        @panel.tape.load_fields(modules.required("BL-DECK"))
+        @teletype.load_fields(modules.required("BL-TTY"))
+        @sound.speaker = modules.required("BL-SOUND").bool("speaker", false)
+        @cpu.load_fields(modules.required("BL-CPU"))
+        @cpu.restored!
+        self
+      end
+
+      private
+
+      def check_snapshot_setup(setup)
+        ours = Snapshot::KIM1Setup.of(self)
+        return if setup == ours
+
+        raise Snapshot::FormatError, "the snapshot is of a #{setup}, not a #{ours}"
+      end
+    end
+
+    include KeyedModules
+  end
+end