From e0557be8997bf683d1440f9c226c41ebbafbe83d Mon Sep 17 00:00:00 2001
From: Warren Toomey <wkt@tuhs.org>
Date: Tue, 1 Mar 2016 17:20:41 +1000
Subject: [PATCH] src/cmd/cat.s: lots more comments added to the code.

---
 src/cmd/cat.s | 124 +++++++++++++++++++++++++-------------------------
 1 file changed, 63 insertions(+), 61 deletions(-)

diff --git a/src/cmd/cat.s b/src/cmd/cat.s
index eb39887..abb566a 100644
--- a/src/cmd/cat.s
+++ b/src/cmd/cat.s
@@ -10,17 +10,17 @@
    dac name
 
 loop:
-   sys open; name:0; 0;		" Open file, get fd back
+   sys open; name:0; 0		" Open file, get fd back
    spa
      jmp badfile		" Negative fd, exit with an error message
-   dac fi			" save file descriptor in fi
+   dac fi			" Save file descriptor in fi
 
 1:
-   jms getc			" get a character in AC
+   jms getc			" Get a character in AC
    sad o4
-     jmp 1f
-   jms putc			" write the character on stdout
-   jmp 1b
+     jmp 1f			" Break the loop when we get a ctrl-D
+   jms putc			" Write the character on stdout
+   jmp 1b			" and loop back
 
 1:
    lac fi			" Close the file descriptor in fi
@@ -57,16 +57,16 @@ nofiles:
 1: <no>; 040;  <fi>;<le>;<s 012
 
 done:
-   lac noc
+   lac noc			" Is the number of characters left zero?
    sna
-     sys exit
+     sys exit			" Yes, exit
    and d1
    sna cla
      jmp 1f
-   jms putc
-   jmp done
+   jms putc			" Print out the character
+   jmp done			" and loop back
 1:
-   lac noc
+   lac noc			
    rcr
    dac 1f
    lac fo			" Load fd 1, stdout
@@ -74,76 +74,78 @@ done:
    sys exit
 
 getc: 0
-   lac ipt
+   lac ipt			" Load the pointer to the next word in the buffer
    sad eipt
-     jmp 1f
-   dac 2f
-   add o400000
+     jmp 1f			" We've reached the end of the buffer, so read more
+   dac 2f			" Save the pointer
+   add o400000			" Flip the msb and save into ipt
    dac ipt
-   ral
-   lac 2f i
-   szl
-   lrss 9
-   and o177			" keep the lowest 7 bits
+   ral				" Move the msb into the link register
+   lac 2f i			" Load the word from the buffer
+   szl				" Skip if this is the second character in the word
+     lrss 9			" It's the first char, shift down the top character
+   and o177			" Keep the lowest 7 bits
    sna
-     jmp getc+1
-   jmp getc i			" return from subroutine
+     jmp getc+1			" Skip a NUL characters and read another one
+   jmp getc i			" Return the character from the subroutine
 1:
-   lac fi
+   lac fi			" Buffer is empty, read another 64 characters
    sys read; iipt+1; 64
    sna
-     jmp 1f
-   tad iipt
-   dac eipt
-   lac iipt
+     jmp 1f			" No characters were read in
+   tad iipt			" Add the word count to the base of the buffer
+   dac eipt			" and store in the end buffer pointer
+   lac iipt			" Reset the ipt to the base of the buffer
    dac ipt
-   jmp getc+1
+   jmp getc+1			" and loop back to get one character
 1:
-   lac o4
+   lac o4			" No character, return with ctrl-D
    jmp getc i			" return from subroutine
 
 putc: 0
-   and o177			" keep the lowest 7 bits
+   and o177			" Keep the lowest 7 bits and save into 2f+1
    dac 2f+1
-   lac opt
-   dac 2f
-   add o400000
-   dac opt
-   spa
-     jmp 1f
-   lac 2f i
+   lac opt			" Save the pointer to the empty buffer
+   dac 2f			" position to 2f
+   add o400000			" Flip the msb and save back into opt
+   dac opt			" This also has the effect of incrementing
+				" the opt pointer every second addition!
+
+   spa				" If the bit was set, we already have one
+     jmp 1f			" character at 2f+1. If no previous character,
+   lac 2f i			" merge the old and new character together
    xor 2f+1
-   jmp 3f
+   jmp 3f			" and go to the "save it in buffer" code
 1:
-   lac 2f+1
+   lac 2f+1			" Move the character up into the top half
    alss 9
 3:
-   dac 2f i
-   isz noc
-   lac noc
+   dac 2f i			" Save the word into the buffer
+   isz noc			" Add 1 to the char count, never skipping
+   lac noc			" Have we reached 128 characters, 64 words?
    sad d128
      skp
-   jmp putc i
-   lac fo			" load fd 1, stdout
-   sys write; iopt+1; 64
+   jmp putc i			" No, so return (more room still in the buffer)
+   lac fo			" Load fd1 (i.e stdout)
+   sys write; iopt+1; 64	" and write out the 64 words in the buffer
    lac iopt
-   dac opt
-   dzm noc
-   jmp putc i
+   dac opt			" Set opt pointing back to base of buffer
+   dzm noc			" Set the number of chars in the buffer to 0
+   jmp putc i			" and return
 
-2: 0;0
-ipt: 0
-eipt: 0
-iipt: .+1; .=.+64		" 64 word input buffer
-fi: 0
-opt: .+2
-iopt: .+1; .=.+64		" 64 word output buffer
-noc: 0
-fo: 1				" output file descriptor, fd 1 is stdout
+2: 0;0				" Current input and output word pointers
+ipt: 0				" Current input buffer base
+eipt: 0				" Pointer to end of data read in input buffer
+iipt: .+1; .=.+64		" 64 word input buffer and pointer to it
+fi: 0				" Input file descriptor
+opt: .+2			" Current output buffer base
+iopt: .+1; .=.+64		" 64 word output buffer and pointer to it
+noc: 0				" Number of output characters
+fo: 1				" Output file descriptor, fd 1 is stdout
 
-d1: 1				" octal and decimal constants
+d1: 1				" Octal and decimal constants
 o4:d4: 4
 d8: 8
-o400000: 0400000
-o177: 0177
-d128: 128
+o400000: 0400000		" Msb toggle bit
+o177: 0177			" ASCII mask
+d128: 128			" 128 words in the output buffer