From 6a6298c4743fd4c4470cff19d57d43a774d569c4 Mon Sep 17 00:00:00 2001
From: Christopher RYU <software-ryucats@disavowed.jp>
Date: Tue, 11 Jul 2023 12:54:14 +0900
Subject: [PATCH] Add a few comments (from S. Elliott at AppleFritter)

---
 firmware/Makefile |  4 +--
 firmware/util.s   | 70 +++++++++++++++++++++++++++--------------------
 2 files changed, 42 insertions(+), 32 deletions(-)

diff --git a/firmware/Makefile b/firmware/Makefile
index 148cc70..0f072b2 100644
--- a/firmware/Makefile
+++ b/firmware/Makefile
@@ -1,6 +1,6 @@
 all: util.bin 16.bin 13.bin legend-franklin.bin legend-usci.bin
-	cat util.bin 16.bin 13.bin legend-franklin.bin > franklin.bin
-	cat util.bin 16.bin 13.bin legend-usci.bin > usci.bin
+	cat util.bin 16.bin 13.bin legend-franklin.bin > firmware-franklin.bin
+	cat util.bin 16.bin 13.bin legend-usci.bin > firmware-usci.bin
 
 legend-franklin.bin:
 	ca65 --target apple2 -o legend-franklin.o legend.s
diff --git a/firmware/util.s b/firmware/util.s
index 9495a28..7561e5a 100644
--- a/firmware/util.s
+++ b/firmware/util.s
@@ -7,6 +7,7 @@
         .setcpu "6502"
         .org $c600
 
+A2L      :=     $3e
 MON_WAIT :=	$FCA8
 GETLNZ :=	$FD67
 BELL :=		$FF3A
@@ -14,68 +15,77 @@ IORTS :=        $FF58
 GETNUM :=       $FFA7
 
 
-        lda     #$A3
-        sta     $33
+        lda     #$A3            ; '#'
+        sta     $33             ; set input-prompt character to '#'
 LC604:  jsr     BELL
-LC607:  jsr     GETLNZ
+LC607:  jsr     GETLNZ          ; start new line and take input
         lda     #$00
         sta     $F2
-LC60E:  sta     $C010
+LC60E:  sta     $C010           ; clear keyboard strobe
         sta     $F3
         ldy     $F2
-        jsr     GETNUM
+        jsr     GETNUM          ; parse hex into A2, A has last char xor $b0
+                                ; plus $89
         sty     $F2
-        cmp     #$C6
-        beq     LC607
-        cmp     #$EC
-        beq     LC64E
-        cmp     #$F0
-        beq     LC676
-        cmp     #$F3
-        beq     LC657
+        cmp     #$C6            ; $C6 from $8D (return)
+        beq     LC607           ; no more input, go prompt for new input
+        cmp     #$EC            ; 'S'
+        beq     CMD_S
+        cmp     #$F0            ; 'W'
+        beq     CMD_W
+        cmp     #$F3            ; 'Z'
+        beq     CMD_Z
         ldy     #$7F
-        cmp     #$06
-        beq     LC67C
-        cmp     #$EB
-        beq     LC641
+        cmp     #$06            ; 'M'
+        beq     CMD_MX
+        cmp     #$EB            ; 'R'
+        beq     CMD_R
         ldx     #$06
         stx     $F3
-        cmp     #$F1
-        beq     LC67C
-        cmp     #$EA
-        bne     LC604
-        brk
-LC641:  lda     #$50
+        cmp     #$F1            ; 'X'
+        beq     CMD_MX
+        cmp     #$EA            ; 'Q'
+        bne     LC604           ; BEEP and prompt for new input
+        brk                     ; 'Q' exits out
+
+; 'R'
+CMD_R:  lda     #$50
         sta     $FC
         txa
         adc     #$00
         sta     $F3
         lda     #$00
         beq     LC651
-LC64E:  lda     $3E
+
+; 'S': seek logical-track index in A2L ('22S' seeks logical track $22)
+CMD_S:  lda     A2L
         asl     a
 LC651:  sta     $F0
         ldy     #$FF
-        bne     LC67C
-LC657:  lda     $3E
+        bne     CMD_MX
+
+; 'Z'
+CMD_Z:  lda     A2L
         asl     a
         sta     $F1
         ldy     #$00
-        beq     LC67C
+        beq     CMD_MX
 LC660:  lda     #$50
         jsr     MON_WAIT
         sta     $C088,x
-        ldy     $3E
+        ldy     A2L
 LC66A:  jsr     MON_WAIT
         dey
         bpl     LC66A
         bmi     LC68E
 LC672:  lda     #$00
         beq     LC60E
-LC676:  lda     $3E
+
+; 'W'
+CMD_W:  lda     A2L
         sta     $FF
         ldy     #$0F
-LC67C:  sty     $09
+CMD_MX: sty     $09
         jsr     IORTS
         tsx
         lda     $0100,x