badline 0.15.0 → 0.16.0

data/lib/badline/kernal_trap/frames.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Badline
+  module KernalTrap
+    # The frames a drive takes and sends through the traps on a KERNAL's
+    # eight bus primitives, shared by the serial bus's (Serial) and the
+    # IEEE-488 bus's (IEEE): the traps going in and out, the bytes a
+    # listener gathers into a frame for the DOS, the bytes a talker sends,
+    # and the status they leave. The class that includes it, with Steps,
+    # answers each primitive and keeps @dos, @listening, @talking,
+    # @listen_channel, @talk_channel, @frame and @buffer.
+    module Frames
+      # Frame type in the high nibble of the secondary address
+      OPEN = 0xf0
+      CLOSE = 0xe0
+
+      # ST bits
+      DEVICE_NOT_PRESENT = 0x80
+      EOI = 0x40
+      READ_TIMEOUT = 0x02
+
+      NO_DATA = [0x0d, EOI | READ_TIMEOUT].freeze
+
+      def install
+        routines.each do |address, routine|
+          @cpu.install_trap(address) { call_routine(routine) if kernal_mapped? }
+        end
+        self
+      end
+
+      # Takes the traps out again, so the KERNAL's own routines run.
+      def uninstall
+        routines.each_key { |address| @cpu.remove_trap(address) }
+      end
+
+      private
+
+      def routines
+        {
+          @layout.talk => :talk,
+          @layout.listen => :listen,
+          @layout.second => :second,
+          @layout.tksa => :tksa,
+          @layout.ciout => :ciout,
+          @layout.untalk => :untalk,
+          @layout.unlisten => :unlisten,
+          @layout.acptr => :acptr
+        }
+      end
+
+      def call_routine(routine)
+        case routine
+        when :talk then talk
+        when :listen then listen
+        when :second then second
+        when :tksa then tksa
+        when :ciout then ciout
+        when :untalk then untalk
+        when :unlisten then unlisten
+        when :acptr then acptr
+        end
+      end
+
+      # CIOUT holds each byte back until the next one, or the UNLISTEN,
+      # comes, so the first byte of a frame sends nothing.
+      def ciout
+        return unless @listening
+
+        time_serial_byte(Routine::ISOUR_TIMEOUT) if !@buffer.empty? && accepted?
+        @buffer << @cpu.a
+        update_status(DEVICE_NOT_PRESENT) unless accepted?
+        @cpu.status.carry = false
+        return_to_caller
+      end
+
+      # The drive acknowledges every byte of an open or close frame, but
+      # takes data only on a channel it has open. Otherwise nothing holds
+      # the data line when a byte starts, so the KERNAL finds no device.
+      def accepted?
+        [OPEN, CLOSE].include?(@frame) || @dos.listening?(@listen_channel)
+      end
+
+      # UNLSN and UNTLK end by releasing the bus, and leave the port's last
+      # read in the accumulator.
+      def release_bus
+        @cpu.a = @layout.release_serial_lines(@bus)
+        @cpu.status.negative = @cpu.a.anybits?(0x80)
+        @cpu.status.zero = @cpu.a.zero?
+        return_to_caller
+      end
+
+      def deliver_frame
+        return unless @listen_channel
+
+        case @frame
+        when OPEN then @dos.open(@listen_channel, @buffer.pack("C*"))
+        when CLOSE then @dos.close(@listen_channel)
+        else @dos.write(@listen_channel, @buffer)
+        end
+        @buffer = []
+      end
+
+      def received
+        byte, eoi = @dos.read(@talk_channel)
+        return NO_DATA unless byte
+
+        [byte, eoi ? EOI : 0]
+      end
+
+      def update_status(bits)
+        return if bits.zero?
+
+        @bus.poke(zero_page.status, @bus.peek(zero_page.status) | bits)
+      end
+    end
+  end
+end

data/lib/badline/kernal_trap/ieee.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Badline
+  module KernalTrap
+    # The traps on a PET's IEEE-488 primitives (IEEELayout), which serve
+    # device 8 from the virtual drive as Serial does on the serial bus
+    # (Frames). Other devices fall through to the ROM, which finds nobody on
+    # the bus. It is no Routine, so that Routine's layout stays a Layout.
+    #
+    # The PET's primitives differ from the serial KERNALs': TALK and LISTEN
+    # address the device in FA, not in A, and BASIC 2's LOAD sends its
+    # channel after TALK with SECOND, not TKSA, so SECOND takes a talker's
+    # channel too. BASIC 1's UNTALK and UNLISTEN store their command in FA,
+    # and its LOAD and SAVE address the device in FA after an UNLISTEN, so
+    # they find no device, as on a real PET with those ROMs.
+    # Each trap leaves A and the lines the ROM drives as the routine does.
+    class IEEE
+      include IntegerHelper
+      include Steps
+      include Frames
+
+      # The command BASIC 1's UNTALK and UNLISTEN leave in FA.
+      UNTALK_COMMAND = 0x5f
+      UNLISTEN_COMMAND = 0x3f
+
+      def initialize(cpu:, bus:, layout:, dos:)
+        @cpu = cpu
+        @bus = bus
+        @layout = layout
+        @dos = dos
+        @device = Routine::DEVICE
+        @listening = false
+        @talking = false
+        @listen_channel = nil
+        @talk_channel = nil
+        @frame = OPEN
+        @buffer = []
+      end
+
+      private
+
+      def talk
+        @talk_channel = nil
+        @talking = addressed?
+        address_device if @talking
+      end
+
+      def listen
+        @listen_channel = nil
+        @listening = addressed?
+        address_device if @listening
+      end
+
+      def addressed? = @bus.peek(zero_page.device) == @device
+
+      # TALK and LISTEN end with the command sent under ATN, which stays
+      # low, and A holding $FF.
+      def address_device
+        @layout.attention(@bus)
+        send_byte
+        @cpu.a = 0xff
+        set_flags
+        return_to_caller
+      end
+
+      # A close needs no data, and the drive closes the channel as the
+      # secondary address comes: BASIC 1's CLOSE sends no UNLISTEN after it.
+      def second
+        if @listening
+          @frame = @cpu.a & 0xf0
+          @listen_channel = @cpu.a & 0x0f
+          @buffer = []
+          close_channel if @frame == CLOSE
+        elsif @talking
+          @talk_channel = @cpu.a & 0x0f
+        else
+          return
+        end
+        send_byte
+        release_attention
+      end
+
+      def tksa
+        return unless @talking
+
+        @talk_channel = @cpu.a & 0x0f
+        send_byte
+        @layout.listen_to_talker(@bus)
+        release_attention
+      end
+
+      def untalk
+        return unless @talking
+
+        @talking = false
+        @bus.poke(zero_page.device, UNTALK_COMMAND) if @layout.overwrites_device
+        time_serial_byte(Routine::ISOUR_TIMEOUT)
+        release_bus
+      end
+
+      def unlisten
+        return unless @listening
+
+        @listening = false
+        @bus.poke(zero_page.device, UNLISTEN_COMMAND) if @layout.overwrites_device
+        deliver_frame
+        time_serial_byte(Routine::ISOUR_TIMEOUT)
+        release_bus
+      end
+
+      # ACPTR leaves the byte in A, with the flags PLA gives it, and the PET
+      # listening, NRFD and NDAC pulled low.
+      def acptr
+        return unless @talking
+
+        @layout.listen_to_talker(@bus)
+        byte, status = received
+        time_serial_byte(Routine::ACPTR_TIMEOUT)
+        @cpu.a = byte
+        set_flags
+        update_status(status)
+        @cpu.status.carry = false
+        return_to_caller
+      end
+
+      def close_channel
+        @dos.close(@listen_channel)
+        @listen_channel = nil
+      end
+
+      def send_byte
+        time_serial_byte(Routine::ISOUR_TIMEOUT)
+        @layout.byte_sent(@bus)
+      end
+
+      def release_attention
+        @cpu.a = @layout.release_attention(@bus)
+        set_flags
+        return_to_caller
+      end
+
+      def set_flags
+        @cpu.status.negative = @cpu.a.anybits?(0x80)
+        @cpu.status.zero = @cpu.a.zero?
+      end
+    end
+  end
+end

data/lib/badline/kernal_trap/ieee_layout.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+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 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.
+    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.
+      def kernal_mapped?(bus) = bus.kernal_mapped?
+
+      # Starts VIA timer 1, which times out the handshake of each byte.
+      def time_serial_byte(bus, _timer_high)
+        bus.poke(0xe845, 0xff)
+      end
+
+      # TALK and LISTEN: NRFD and NDAC 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)
+      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)
+      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
+      end
+
+      # TKSA and ACPTR end listening: NRFD and NDAC pulled low.
+      def listen_to_talker(bus)
+        bus.poke(0xe840, bus.peek(0xe840) & 0xfd)
+        bus.poke(0xe821, 0x34)
+      end
+
+      # The end of UNTALK and UNLISTEN, which address the bus as TALK and
+      # LISTEN do, send their command and let ATN go.
+      def release_serial_lines(bus)
+        attention(bus)
+        byte_sent(bus)
+        release_attention(bus)
+      end
+    end
+
+    # 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
+    # at STAL, which starts at the file's own address, and ends with EAL
+    # set from it, so +load_address+ names STAL.
+    PET_ZERO_PAGE = ZeroPage.new(
+      status: 0x96, verify: 0x9d, start_address: 0xc7, end_address: 0xc9, filename_length: 0xd1,
+      secondary_address: 0xd3, device: 0xd4, filename_address: 0xda, save_start: 0xfb, load_address: 0xfb
+    )
+
+    # BASIC 1's, some of them outside the zero page: ST at $020C and VERCK
+    # at $020B. SAVE copies STAL at $F7 to SAL at $E3 and walks SAL up to
+    # EAL at $E5. LOAD from the IEEE bus stores each byte at STAL, which it
+    # sets to $0400 itself.
+    PET_BASIC1_ZERO_PAGE = ZeroPage.new(
+      status: 0x020c, verify: 0x020b, start_address: 0xe3, end_address: 0xe5, filename_length: 0xee,
+      secondary_address: 0xf0, device: 0xf1, filename_address: 0xf9, save_start: 0xf7, load_address: 0xf7
+    )
+
+    # BASIC 1, 901447-06 and 901447-07. Its UNTALK and UNLISTEN store $5F
+    # and $3F in FA at $F1 before they send it. LOAD and SAVE send TALK and
+    # 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
+    )
+
+    # 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
+    )
+
+    # 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
+    )
+  end
+end

data/lib/badline/kernal_trap/keyed_state.rb

@@ -117,10 +117,10 @@ module Badline
       end
     end
 
-    class Serial
-      # The serial trap's fields under `prefix`: whether device 8 listens
-      # or talks, on which channel, the frame it is in and the bytes it has
-      # gathered.
+    module Frames
+      # The serial or IEEE-488 trap's fields under `prefix`: whether device
+      # 8 listens or talks, on which channel, the frame it is in and the
+      # bytes it has gathered.
       def save_fields(out, prefix)
         out.bool("#{prefix}listening", @listening).bool("#{prefix}talking", @talking)
         out.optional_int("#{prefix}listen_channel", @listen_channel)

data/lib/badline/kernal_trap/routine.rb

@@ -3,10 +3,11 @@
 module Badline
   module KernalTrap
     # Base class for the PC traps on KERNAL routines. Holds the device
-    # number they answer for, the layout of the KERNAL they trap, and the
-    # return that stands in for the trapped routine's RTS.
+    # number they answer for and the layout of the KERNAL they trap, and
+    # takes its Steps around them.
     class Routine
       include IntegerHelper
+      include Steps
 
       DEVICE = 8
 
@@ -19,57 +20,6 @@ module Badline
         @bus = bus
         @layout = layout
       end
-
-      private
-
-      def kernal_mapped?
-        @layout.kernal_mapped?(@bus)
-      end
-
-      def zero_page = @layout.zero_page
-
-      # The two-byte value whose low byte is at +address+.
-      def peek_word(address)
-        uint16(@bus.peek(address), @bus.peek(address + 1))
-      end
-
-      def poke_word(address, value)
-        @bus.poke(address, low_byte(value))
-        @bus.poke(address + 1, high_byte(value))
-      end
-
-      # The ROM times each byte on the serial bus with a one-shot timer
-      # (Layout#time_serial_byte): ISOUR_TIMEOUT for a byte sent,
-      # ACPTR_TIMEOUT for one received.
-      def time_serial_byte(timer_high)
-        @layout.time_serial_byte(@bus, timer_high)
-      end
-
-      def return_to_caller
-        @cpu.program_counter = (uint16(pull_byte, pull_byte) + 1) & 0xffff
-      end
-
-      # Runs the ROM routines in order, each returning into the next, and
-      # the last one to the trapped routine's caller
-      def continue_with(first, *rest)
-        rest.reverse_each { |address| push_address((address - 1) & 0xffff) }
-        @cpu.program_counter = first
-      end
-
-      def push_address(address)
-        push_byte(high_byte(address))
-        push_byte(low_byte(address))
-      end
-
-      def push_byte(value)
-        @bus.poke(0x0100 + @cpu.stack_pointer, value)
-        @cpu.stack_pointer = (@cpu.stack_pointer - 1) & 0xff
-      end
-
-      def pull_byte
-        @cpu.stack_pointer = (@cpu.stack_pointer + 1) & 0xff
-        @bus.peek(0x0100 + @cpu.stack_pointer)
-      end
     end
   end
 end

data/lib/badline/kernal_trap/serial.rb

@@ -5,23 +5,15 @@ module Badline
     # PC traps on the KERNAL's serial bus primitives. Frames addressed to
     # device 8 go to a virtual drive instead of out over the IEC lines, so
     # OPEN/CHKIN/CHRIN reach a CBM DOS, and so do the block reads that
-    # loaders make through them. Other devices fall through to the ROM.
+    # loaders make through them (Frames). Other devices fall through to the
+    # ROM.
     #
     # With +device+ nil the traps answer no device, and every frame goes
     # out over the bus, to a true drive if one is plugged in.
     class Serial < Routine
-      attr_accessor :device
-
-      # Frame type in the high nibble of the secondary address
-      OPEN = 0xf0
-      CLOSE = 0xe0
-
-      # ST bits at $90
-      DEVICE_NOT_PRESENT = 0x80
-      EOI = 0x40
-      READ_TIMEOUT = 0x02
+      include Frames
 
-      NO_DATA = [0x0d, EOI | READ_TIMEOUT].freeze
+      attr_accessor :device
 
       def initialize(cpu:, bus:, layout:, dos:, device: DEVICE)
         super(cpu:, bus:, layout:)
@@ -35,46 +27,8 @@ module Badline
         @buffer = []
       end
 
-      def install
-        routines.each do |address, routine|
-          @cpu.install_trap(address) { call_routine(routine) if kernal_mapped? }
-        end
-        self
-      end
-
-      # Takes the traps out again, so the KERNAL's own routines run.
-      def uninstall
-        routines.each_key { |address| @cpu.remove_trap(address) }
-      end
-
       private
 
-      def routines
-        {
-          @layout.talk => :talk,
-          @layout.listen => :listen,
-          @layout.second => :second,
-          @layout.tksa => :tksa,
-          @layout.ciout => :ciout,
-          @layout.untalk => :untalk,
-          @layout.unlisten => :unlisten,
-          @layout.acptr => :acptr
-        }
-      end
-
-      def call_routine(routine)
-        case routine
-        when :talk then talk
-        when :listen then listen
-        when :second then second
-        when :tksa then tksa
-        when :ciout then ciout
-        when :untalk then untalk
-        when :unlisten then unlisten
-        when :acptr then acptr
-        end
-      end
-
       # Addressing the bus starts a new frame. The channel number arrives
       # in the secondary address that follows. Each byte sent under ATN,
       # and each byte of a frame, times its handshake with the serial timer
@@ -112,25 +66,6 @@ module Badline
         sent_under_atn
       end
 
-      # CIOUT holds each byte back until the next one, or the UNLISTEN,
-      # comes, so the first byte of a frame sends nothing.
-      def ciout
-        return unless @listening
-
-        time_serial_byte(ISOUR_TIMEOUT) if !@buffer.empty? && accepted?
-        @buffer << @cpu.a
-        update_status(DEVICE_NOT_PRESENT) unless accepted?
-        @cpu.status.carry = false
-        return_to_caller
-      end
-
-      # The drive acknowledges every byte of an open or close frame, but
-      # takes data only on a channel it has open. Otherwise nothing holds
-      # the data line when a byte starts, so the KERNAL finds no device.
-      def accepted?
-        [OPEN, CLOSE].include?(@frame) || @dos.listening?(@listen_channel)
-      end
-
       def unlisten
         return unless @listening
 
@@ -148,15 +83,6 @@ module Badline
         release_bus
       end
 
-      # UNLSN and UNTLK end by releasing ATN, the clock and the data line,
-      # and leave the port's last read in the accumulator.
-      def release_bus
-        @cpu.a = @layout.release_serial_lines(@bus)
-        @cpu.status.negative = @cpu.a.anybits?(0x80)
-        @cpu.status.zero = @cpu.a.zero?
-        return_to_caller
-      end
-
       def acptr
         return unless @talking
 
@@ -167,30 +93,6 @@ module Badline
         @cpu.status.carry = false
         return_to_caller
       end
-
-      def deliver_frame
-        return unless @listen_channel
-
-        case @frame
-        when OPEN then @dos.open(@listen_channel, @buffer.pack("C*"))
-        when CLOSE then @dos.close(@listen_channel)
-        else @dos.write(@listen_channel, @buffer)
-        end
-        @buffer = []
-      end
-
-      def received
-        byte, eoi = @dos.read(@talk_channel)
-        return NO_DATA unless byte
-
-        [byte, eoi ? EOI : 0]
-      end
-
-      def update_status(bits)
-        return if bits.zero?
-
-        @bus.poke(zero_page.status, @bus.peek(zero_page.status) | bits)
-      end
     end
   end
 end

data/lib/badline/kernal_trap/steps.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Badline
+  module KernalTrap
+    # The steps the PC traps on KERNAL routines share, on the @cpu, @bus
+    # and @layout of the trap that includes them, which includes
+    # IntegerHelper too: the layout's checks and timer, the zero page's
+    # words, and the return that stands in for the trapped routine's RTS.
+    # Routine includes them, and so does each trap that isn't a Routine,
+    # so every trap class keeps its own layout's type.
+    module Steps
+      private
+
+      def kernal_mapped?
+        @layout.kernal_mapped?(@bus)
+      end
+
+      def zero_page = @layout.zero_page
+
+      # The two-byte value whose low byte is at +address+.
+      def peek_word(address)
+        uint16(@bus.peek(address), @bus.peek(address + 1))
+      end
+
+      def poke_word(address, value)
+        @bus.poke(address, low_byte(value))
+        @bus.poke(address + 1, high_byte(value))
+      end
+
+      # The ROM times each byte on the serial bus with a one-shot timer
+      # (Layout#time_serial_byte): Routine::ISOUR_TIMEOUT for a byte sent,
+      # Routine::ACPTR_TIMEOUT for one received.
+      def time_serial_byte(timer_high)
+        @layout.time_serial_byte(@bus, timer_high)
+      end
+
+      def return_to_caller
+        @cpu.program_counter = (uint16(pull_byte, pull_byte) + 1) & 0xffff
+      end
+
+      # Runs the ROM routines in order, each returning into the next, and
+      # the last one to the trapped routine's caller
+      def continue_with(first, *rest)
+        rest.reverse_each { |address| push_address((address - 1) & 0xffff) }
+        @cpu.program_counter = first
+      end
+
+      def push_address(address)
+        push_byte(high_byte(address))
+        push_byte(low_byte(address))
+      end
+
+      def push_byte(value)
+        @bus.poke(0x0100 + @cpu.stack_pointer, value)
+        @cpu.stack_pointer = (@cpu.stack_pointer - 1) & 0xff
+      end
+
+      def pull_byte
+        @cpu.stack_pointer = (@cpu.stack_pointer + 1) & 0xff
+        @bus.peek(0x0100 + @cpu.stack_pointer)
+      end
+    end
+  end
+end

data/lib/badline/kernal_trap.rb

@@ -1,11 +1,15 @@
 # frozen_string_literal: true
 
 require "badline/kernal_trap/layout"
+require "badline/kernal_trap/ieee_layout"
+require "badline/kernal_trap/steps"
 require "badline/kernal_trap/routine"
 require "badline/kernal_trap/dos"
 require "badline/kernal_trap/file_routine"
 require "badline/kernal_trap/load"
 require "badline/kernal_trap/save"
+require "badline/kernal_trap/frames"
 require "badline/kernal_trap/serial"
+require "badline/kernal_trap/ieee"
 require "badline/kernal_trap/chrout"
 require "badline/kernal_trap/keyed_state"