From df1d8e29dd22fc1c423c9e30a5198b34534a5f97 Mon Sep 17 00:00:00 2001
From: Phil Budne <phil@ultimate.com>
Date: Fri, 11 Mar 2016 11:23:59 -0500
Subject: [PATCH 1/6] update sys NOTES

---
 src/sys/NOTES.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/sys/NOTES.md b/src/sys/NOTES.md
index 4767761..78ba1e3 100644
--- a/src/sys/NOTES.md
+++ b/src/sys/NOTES.md
@@ -5,6 +5,8 @@ uid -1 is superuser
 
 process 1 is "init", runs as superuser
 
+there are ten process slots, pids are 18 bits.
+
 DISK
 ====
 
@@ -28,7 +30,7 @@ inode format
 ------------
 ```
    i.flags
-        400000  free?? (checked/toggled by icreat)
+        400000  in use
         200000  large file
         000040  special file
         000020  directory
@@ -69,3 +71,10 @@ i numbers
   11    "display" (graphic-2) special file
   12    "pptout" (paper tape punch) special file
 ```
+
+swapping
+--------
+
+Only one process is in memory at any time (in the high half of the 8KW
+memory).  The ten processes are swapped to the last ten tracks of the
+disk.

From 802ab257b9788963c672ada95f1684516ad13920 Mon Sep 17 00:00:00 2001
From: Phil Budne <phil@ultimate.com>
Date: Fri, 11 Mar 2016 16:01:01 -0500
Subject: [PATCH 2/6] sys: kernel comments

---
 src/sys/s1.s  |  14 ++--
 src/sys/s2.s  |  10 +--
 src/sys/s3.s  |   8 +-
 src/sys/s5.s  | 159 +++++++++++++++++++-----------------
 src/sys/s6.s  |  15 ++--
 src/sys/s7.s  | 222 ++++++++++++++++++++++++++------------------------
 src/sys/s8.s  |  39 +++++----
 src/sys/sop.s |  26 +++---
 8 files changed, 260 insertions(+), 233 deletions(-)

diff --git a/src/sys/s1.s b/src/sys/s1.s
index 6b71282..27ed5e3 100644
--- a/src/sys/s1.s
+++ b/src/sys/s1.s
@@ -9,7 +9,7 @@ orig:
 . = orig+7
    -1				" only ever set (to -1): never read?!
 
-. = orig+020			" syscall (CAL) processing
+. = orig+020			" syscall (CAL) and user "interrupt" processing
    1f				" addr for "CAL I": store return here on "CAL"
    iof				" interrupts off
    dac u.ac			" save user AC
@@ -19,8 +19,8 @@ orig:
    dac 020			" restore location 20
    lac u.ac			" restore user AC
    jmp 1f+1			" join "CAL I" processing
-   1f
-1: 0
+   1f				" literal to restore location 20
+1: 0				" "CAL I" PC stored here
    iof				" interrupts off
    dac u.ac			" save user AC
    lacq
@@ -64,7 +64,7 @@ sysexit:			" common system call exit code
    jms dskio; 07000		" save to disk?
 1:
    dzm .insys			" clear "in system call" flag
-   jms chkint			" pending interrupt?
+   jms chkint			" pending user interrupt?
       skp			"  no
    jmp .save			"   yes: dump core
    jms copy; u.rq+2; 10; 6	" restore auto-index locations 10-15
@@ -169,12 +169,14 @@ locsw:			" table of system addresses for sysloc
 locn:
    .-locsw-1
 
-	" check if interrupt for user
+	" check if "interrupt" for current process
 	" checks .int1 and .int2 (contain i-number of interrupt source)
+	" compared against process stdin
+	"
 	" call:
 	" .insys/ 0
 	"   jms chkint
-	"    no: no interrupt, or intflg set (discards interupt)
+	"    no: no interrupt, or intflg set (discards interrupt)
 	"   yes: PI off, .insys set
 chkint: 0
    lac .insys
diff --git a/src/sys/s2.s b/src/sys/s2.s
index 64d6f93..e597963 100644
--- a/src/sys/s2.s
+++ b/src/sys/s2.s
@@ -121,7 +121,7 @@
    lac i.uniq
    dac d.uniq
    -1
-   tad i.nlks
+   tad i.nlks			" decrement link count!
    dac i.nlks
 "** 01-s1.pdf page 9
    jms iput
@@ -138,10 +138,10 @@
    jms dput
    lac u.base
    jms iget
-   isz i.nlks
-   jmp 1f
-   jms itrunc
-   dzm i.flags
+   isz i.nlks			" increment link count
+   jmp 1f			"  not zero
+   jms itrunc			" zero links: free blocks
+   dzm i.flags			" clear status (free inode)
 1:
    jms iput
    jmp sysexit
diff --git a/src/sys/s3.s b/src/sys/s3.s
index baec05c..0037d69 100644
--- a/src/sys/s3.s
+++ b/src/sys/s3.s
@@ -231,7 +231,7 @@ sww:
 	" read routine for ttyin special file
 rttyi:
    jms chkint1
-   lac d1
+   lac d1		" ** written d3 ttyin2
    jms getchar
       jmp 1f
    and o177
@@ -258,9 +258,9 @@ wttyo:
    xor o400000
    dac sfiles+1
    lacq
-   tls
-   sad o12
-   jms putcr
+   tls				" load output buffer
+   sad o12			" newline?
+   jms putcr			"  yes, put CR as well
    jmp fallr
 1:
    lacq
diff --git a/src/sys/s5.s b/src/sys/s5.s
index f83f6e8..055ed17 100644
--- a/src/sys/s5.s
+++ b/src/sys/s5.s
@@ -88,132 +88,141 @@ fput: 0
    jmp fput i
 t = t+1
 
+	" helper for special device write routines
+	" return to caller with next character to write:
+	" when done return character count to user.
 forall: 0
    lac u.base
    sad u.limit
-   jmp 1f
-   lac u.base
-   ral
-   lac u.base i
-   snl
-   lrs 9
-   and o777
-   jmp forall i
-fallr:
-   lac u.base
-   add o400000
-   dac u.base
+   jmp 1f			" done
+   lac u.base			" get base pointer (again?)
+   ral				" rotate MSB into LINK
+   lac u.base i			" fetch word via base pointer
+   snl				" link set?
+   lrs 9			"  no: get low 9 bits
+   and o777			" mask to 9 bits
+   jmp forall i			" return char
+fallr:				" jump here for subsequent characters
+   lac u.base			" get base
+   add o400000			" advance pointer
+   dac u.base			" start from top
    jmp forall+1
 1:
    lac u.count
    dac u.ac
    jmp sysexit
 
+	" wait for a condition variable
+	" call:
+	"   jmr sleep; sfiles+N
 sleep: 0
-   law ulist-1
-   dac 8
+   law ulist-1		" pointer to process table
+   dac 8		" in index register
    lac o200000
-   lmq
+   lmq			" get 200000 in MQ
 1:
-   lac u.ulistp i
-   sad 8 i
-   jmp 1f
+   lac u.ulistp i	" get current process status word
+   sad 8 i		" compare to next process table entry
+   jmp 1f		"  match
+   isz 8		" no match: skip other 3 words of process table
    isz 8
    isz 8
-   isz 8
-   cla; lrs 1
-   jmp 1b
+   cla; lrs 1		" shift MQ down one
+   jmp 1b		" loop
 1:
-   tad o100000
+   tad o100000		" mark process not ready
    dac u.ulistp i
-   lac sleep i
+   lac sleep i		" get sleep variable pointer
    dac 9f+t
-   lac 9f+t i
-   omq
-   dac 9f+t i
-   isz sleep
+   lac 9f+t i		" get sleep variable contents
+   omq			" or in MQ (bit vector of processes waiting)
+   dac 9f+t i		" save
+   isz sleep		" skip sleep variable pointer
    jmp sleep i
 t = t+1
 
 "** 01-s1.pdf page 30
 
+	" look for a free directory entry??
 dslot: 0
    dzm di
    skp
 1:
    isz di
    lac di
-   jms dget
-   lac d.i
-   sza
-   jmp 1b
-   jmp dslot i
+   jms dget			" get directory entry
+   lac d.i			" get i number
+   sza				" zero (free)?
+   jmp 1b			"  no keep looking
+   jmp dslot i			" yes: return index
 
 	" called with:
 	" AC/ mode
+	" name/ file name
 icreat: 0
-   dac 9f+t
+   dac 9f+t			" save mode in t0
    jms dslot
-   lac o20
+   lac o20			" look for a free inode starting at 17
    dac ii
 1:
    isz ii
    lac ii
    jms iget
    lac i.flags
-   spa
-   jmp 1b
+   spa				" "in use" bit bit clear?
+   jmp 1b			"  no, guess again
    lac ii
    dac d.i
    jms copy; name; d.name; 4
-   isz s.uniq
+   isz s.uniq			" get a new unique number
    lac s.uniq
-   dac d.uniq
-   dac i.uniq
-   lac 9f+t
-   xor o400000
+   dac d.uniq			" save in directory entry
+   dac i.uniq			" and inode
+   lac 9f+t			" get mode
+   xor o400000			" set "in use"
    dac i.flags
-   lac u.uid
-   dac i.uid
+   lac u.uid			" get user
+   dac i.uid			" set owner
    -1
-   dac i.nlks
-   dzm i.size
-   jms copyz; i.dskps; 7
-   jms iput
-   jms dput
+   dac i.nlks			" -1 links?!
+   dzm i.size			" empty
+   jms copyz; i.dskps; 7	" clear disk block numbers
+   jms iput			" write inode
+   jms dput			" write directory entry
    jmp icreat i
 t = t+1
 
+	" output character to display
 dspput: 0
-   and o177
+   and o177			" mask to 7 bits
    sna
-   jmp i dspput
-   sad o14
-   jmp 1f
-   lmq
-   sad o12
-   jms dspnl
-   lac dsploc i
-   sad o400000
-   jmp dspleft
-   omq
-   dac dsploc i
-   isz dsploc
+   jmp i dspput			" discard NUL
+   sad o14			" Form Feed?
+   jmp 1f			"  yes
+   lmq				" save char in MQ
+   sad o12			" newline?
+   jms dspnl			"  yes
+   lac dsploc i			" get display word
+   sad o400000			" TRAP?
+   jmp dspleft			"  yes
+   omq				" no: get character back
+   dac dsploc i			" save as "character 2"
+   isz dsploc			" advance display pointer
    jmp i dspput
 
 "** 01-s1.pdf page 31
 
-1:
-   jms dspinit
+1:				" here on form feed
+   jms dspinit			" clear display
    jmp dspput i
 
 dspleft:
-   lac dsploc
-   sad edspbuf
-   jmp 1f
+   lac dsploc			" get display pointer
+   sad edspbuf			" end of the buffer?
+   jmp 1f			"  yes
    dac 8
-   lac o400000
-   dac 8 i
+   lac o400000			" get TRAP instruction
+   dac 8 i			" store
    cla; llss 18+7
    dac dsploc i
    jmp dspput i
@@ -225,17 +234,17 @@ dspnl: 0
    isz dsplno
    jmp dspnl i
 1:
-   lac o2000
-   wbl
+   lac o2000			" get bit for push button 7
+   wbl				" write button lights
    isz dspput
    jmp dspput i
 
 dspinit: 0
-   lac dspbufp3
-   dac dsploc
-   lac o400000
-   dac dspbuf+3
-   dzm dsplno
+   lac dspbufp3			" get pointer to dspbuf+3
+   dac dsploc			" store location
+   lac o400000			" display "TRAP" instruction
+   dac dspbuf+3			" save in buffer
+   dzm dsplno			" clear display line number
    jmp dspinit i
 
 movdsp: 0
diff --git a/src/sys/s6.s b/src/sys/s6.s
index f1d07be..14baa21 100644
--- a/src/sys/s6.s
+++ b/src/sys/s6.s
@@ -151,12 +151,14 @@ iput: 0
    jmp iput i
 t = t+3
 
+	" allocate directory entry
+	" AC/ entry number
 dget: 0
-   dac di
-   alss 3
-   dac 9f+t
-   jms pget
-   dac 9f+t+1
+   dac di			" save entry number
+   alss 3			" get word number
+   dac 9f+t			" save in t0
+   jms pget			" get free disk block
+   dac 9f+t+1			" save in t1
    jms dskrd
    lac 9f+t
    and o77
@@ -185,7 +187,8 @@ dput: 0
 
 t = t+3
 
-	" allocate a block for a file, returns disk block number
+	" get a block number for a file, returns disk block number
+	" allocates block if not allocated
 	" AC/ file offset
 	"   jms pget
 	" AC/ disk block number
diff --git a/src/sys/s7.s b/src/sys/s7.s
index 356e193..fd1e8d9 100644
--- a/src/sys/s7.s
+++ b/src/sys/s7.s
@@ -38,18 +38,18 @@ pibreak:			" priority interrupt break processing "chain"
 	"** written: ttydelay -> ttyd1
 	"** written: ttyrestart -> ttyres1
 
-	" referenced in iread:
-cnop:
-   nop
+cnop:			" fetched as constant in iread
+   nop			
    -1
-   dac 7		" set location 7 to -1
+   dac 7		" set location 7 to -1 (nothing ever clears it)
    clon			" enable clock interrupts, reset flag
-   lac ttydelay
-   spa
-   isz ttydelay
-   skp
-   jms ttyrestart
-   lac .dspb	"** START CROSSED OUT: written: lac tty
+   lac ttydelay		" tty delay positive?
+   spa			"  yes: skip to skp
+   isz ttydelay		"   no: done delaying?
+   skp			"    not done
+   jms ttyrestart	"     yes: start output
+	"** START CROSSED OUT: written: lac tty
+   lac .dspb
    sna
    jmp piret
    isz .dsptm
@@ -61,23 +61,24 @@ cnop:
    jmp piret
    jmp dsprestart "** END CROSSED OUT
 
-1: dssf
-   jmp 1f
+1: dssf				" disk flag set?
+   jmp 1f			"  no
 
-   -1
+   -1				" set .dskb = -1
    dac .dskb
 
 "** 01-s1.pdf page 42
 
-   dsrs
+   dsrs				" get disk status in .dske
    dac .dske
-   dscs
+   dscs				" clear status register
    jmp piret
 
-1: lds		"** BEGIN CROSSED OUT
-   sma ral
-   jmp 1f
-   cdf
+		"** BEGIN CROSSED OUT
+1: lds				" load display status (see 03-scope.pdf pg 25)
+   sma ral			" edges flag??
+   jmp 1f			"  not set
+   cdf				" clear display flags?
    lac .dspb
    sna
    jmp piret
@@ -88,89 +89,89 @@ cnop:
    jmp piret
 dsprestart:
    lac d1
-   dac .dspb
-   lac dspbufp
-   beg
+   dac .dspb			" set .dsbp = 1
+   lac dspbufp			" load display buf pointer
+   beg				" start display processor
    -10
-   dac .dsptm
+   dac .dsptm			" set .dsptm = -10 (10 ticks)
    jmp piret
 
-1: sna ral
-   jmp .+3
-   dpcf
-   jmp piret
-   sma
-   jmp 1f
-   lda
-   dac .lpba
-   rlpd
+1: sna ral			" dataphone flag set (bit 7)??
+   jmp .+3			"  no
+   dpcf				" clear dataphone flag
+   jmp piret			" return
+   sma				" light pen flags (bit 2)
+   jmp 1f			"  no
+   lda				" G-2: load display address
+   dac .lpba			" save
+   rlpd				" G-2: resume after light pen stop
    jmp piret
 
-1: ksf			" (TTY) keyboard flag set?
-   jmp 1f		"  no
+1: ksf				" (TTY) keyboard flag set?
+   jmp 1f			"  no
 
-   lac ttydelay
-   sma
+   lac ttydelay		" get TTY delay
+   sma				"
    isz ttydelay
-   krb			" read keyboard buffer
-   dac char		" save in char
-   sad o375		" interrupt char (TTY ALT MODE?)
-   jmp intrp1		"  yes
+   krb				" read keyboard buffer
+   dac char			" save in char
+   sad o375			" interrupt char (TTY ALT MODE?)
+   jmp intrp1			"  yes
    lac d1
    jms putchar
       dzm char
-   lac sfiles+0
-   jms wakeup
-   dac sfiles+0
-   lac char
-   sad o212
-   skp
-   jmp piret
-   lac sfiles+1
-   sma
-   xor o400000
-   dac sfiles+1
+   lac sfiles+0			" get sleep word for ttyin
+   jms wakeup			" wake processes
+   dac sfiles+0			" clear sleep word
+   lac char			" get character
+   sad o212			" odd condition (break???)
+   skp				"  yes
+   jmp piret			"   no: done
+   lac sfiles+1			" get ttyout wait word
+   sma				" bit for process 1 already set?
+   xor o400000			" no, make it so
+   dac sfiles+1			" save back
 
 "** 01-s1.pdf page 43
 
-   jms putcr
-   jms ttyrestart
+   jms putcr			" output CR next
+   jms ttyrestart		" start output
    jmp piret
 
-1: tsf
-   jmp 1f
+1: tsf				" TTY output flag set?
+   jmp 1f			"  no
 
-   tcf
-   jms ttyrestart
+   tcf				" yes: clear flag
+   jms ttyrestart		" transmit next character
    jmp piret
 
 ttyrestart: 0
-   lac ttydelay
-   spa
-   jmp ttyrestart i
-   lac nttychar
-   dzm nttychar
-   sza
-   jmp 3f
-   isz ttydelay
+   lac ttydelay			" get tty delay
+   spa				" positive?
+   jmp ttyrestart i		"  no: keep waiting
+   lac nttychar			" get pending CR, if any
+   dzm nttychar			" clear it
+   sza				" need to send CR?
+   jmp 3f			"  yes
+   isz ttydelay			" increment ttydelay (make more positive)
    lac d2
-   jms getchar
-      jmp 2f
+   jms getchar			" get a character
+      jmp 2f			"  none found??
 3:
-   tls
-   sad o12
-   jms putcr
-   sad o15
-   skp
-   jmp ttyrestart i
-   lac ttydelay
-   tad o20
-   rcr
-   cma
-   dac ttydelay
+   tls				" start output
+   sad o12			" newline?
+   jms putcr			" yes: put CR next
+   sad o15			" CR?
+   skp				"  yes
+   jmp ttyrestart i		"   no: return
+   lac ttydelay			" get current tty delay
+   tad o20			" bump by 16
+   rcr				" divide by two
+   cma				" complement
+   dac ttydelay			" save
    jmp ttyrestart i
 2:
-   lac sfiles+1
+   lac sfiles+1			" run out of characters to send: wake user(s)
    jms wakeup
    dac sfiles+1
    jmp ttyrestart i	"** written arrow up 2 copies
@@ -270,7 +271,7 @@ ttyrestart: 0
    lac sfiles+6
    jms wakeup
    dac sfiles+6
-   cla
+   cla					" clear button lights
    wbl
    jmp piret	"** END CROSSED OUT
 
@@ -292,35 +293,42 @@ piret:					" return from priority interrupt
    ion					" reenable interrupts
    jmp 0 i				" return from interrupt
 
+	" wake sleeping processes
+	" NOTE!! Called from interrupt service, so avoids indirect!!!
+	" call:
+	" AC/ sfiles word (bit vector of processes to wake)
+	"   jms wakeup
+	" AC/ 0 (to store in sfiles word)
 wakeup: 0
-   dac 9f+t
+   dac 9f+t				" save vector in t0
    -mnproc
-   dac 9f+t+1
-   lac tadu
+   dac 9f+t+1				" loop count in t1
+   lac tadu				" get "tad ulist"
    dac 2f
-   lac dacu
+   lac dacu				" get "dac ulist"
    dac 2f+1
 1:
    lac 9f+t
-   ral
+   ral					" rotate vector up one
    dac 9f+t
-   sma
-   jmp 2f+2
-   lac o700000
-2: tad ..
+   sma					" high bit set?
+   jmp 2f+2				"  no: skip the fun
+   lac o700000				" yes: decrement process status (wake)
+2: tad ..				" (avoiding indirect)
    dac ..
-   lac 2b
+   lac 2b				" advance tad operand by 4 words
    tad d4
    dac 2b
-   lac 2b+1
+   lac 2b+1				" advance tad operand by 4 words
    tad d4
    dac 2b+1
-   isz 9f+t+1
-   jmp 1b
-   cla
+   isz 9f+t+1				" done?
+   jmp 1b				"  no, keep going
+   cla					" return zero in AC
    jmp wakeup i
 t = t+2
 
+	" call to output CR after LF (NL)
 putcr: 0
    lac o15
    dac nttychar
@@ -347,26 +355,26 @@ intrp1:			" here with TTY interrupt character
    lac sfiles+1
    jms wakeup
    dac sfiles+1
-   jms chkint
-      jmp piret
-   jmp 1f
-intrp2:
+   jms chkint			" check if user interrupted
+      jmp piret			"  no, return from PI
+   jmp 1f			" yes: return from system call
+intrp2:				" here with display interrupt character
    lac d7
    dac .int2
-   lac d3
+   lac d3			" drain keyboard buffer?
    jms getchar
       skp
    jmp .-3
-   lac sfiles+2
+   lac sfiles+2			" wake up any "keyboard" sleepers
    jms wakeup
    dac sfiles+2
-   lac sfiles+6
+   lac sfiles+6			" wake up any "display" sleepers
    jms wakeup
    dac sfiles+6
-   jms chkint
-      jmp piret
+   jms chkint			" check if user interrupted
+      jmp piret			"  no, return from PI
 1:
-   lac 0
-   dac 020
-   lac .ac
-   jmp 021
+   lac 0			" get interrupt PC
+   dac 020			" save as system call return PC
+   lac .ac			" restore AC from interrupt
+   jmp 021			" join system call processing!!!
diff --git a/src/sys/s8.s b/src/sys/s8.s
index 6b88276..6660eb3 100644
--- a/src/sys/s8.s
+++ b/src/sys/s8.s
@@ -8,11 +8,10 @@ dspbsz = 270
 ndskbs = 4
 
 " flags
-	" interupt flags
 .insys: 0			" "in system"
-.int1: 0			" inode for interrupt 1
-.int2: 0			" inode for interrupt 2
-.ac: 0				" saved AC from interrupt
+.int1: 0			" inode for user interrupt 1
+.int2: 0			" inode for user interrupt 2
+.ac: 0				" saved AC from Priotity Interrupt
 .savblk: 0			" set by system call, cleared by disk i/o
 .dsptm: 0			" display restart countdown (10 ticks)
 .dskb: 0			" set on disk interrupt
@@ -107,7 +106,10 @@ q2:
 dsploc: .=.+1
 dsplno: .=.+1
 dspbuf:
-   0065057;0147740;0160000
+   0065057;0147740;0160000	" display commands: see 03-scope.pdf pg 20
+	" PARAM: clear blink, clear light pen, scale=1, intensity=3
+	" X-Y: invisible, no delay, Y=01740 (992)
+	" X-Y: invisible, settling delay, X=0
    .=.+30
 coldentry:
    dzm 0100 " not re-entrant
@@ -134,13 +136,13 @@ coldentry:
 dskbuf = 07700
 dskbs: .=.+65+65+65+65
 edskbsp: .
-uquant: .=.+1
-dspbufp: .=.+1
-pbsflgs: .=.+2
+uquant: .=.+1			" number of ticks user has been running
+dspbufp: .=.+1			" pointer to display buffer
+pbsflgs: .=.+2			" buttons on last tick, last button interrupt
 mode: .=.+1
-nttychar: .=.+1
+nttychar: .=.+1			" CR to send next, or zero
 npptchar: .=.+1
-ttydelay: .=.+1
+ttydelay: .=.+1			" delay count for TTY output
 name: .=.+4
 lnkaddr: .=.+1
 char: .=.+1
@@ -148,6 +150,9 @@ dskaddr: .=.+1
 uniqpid: 1			" pid generator
 lu: .=.+4			" user (process) table entry copy
 sfiles: .=.+10			" wait addresses for special files
+		" (bit vector of waiting processes?)
+		" offsets:	0: ttyin, 1: ttyout, 2: keyboard,
+		"		3: ptr,   4: ptp,    6: display
 dpdata:
    dpstat: .=.+1
    dpread: .=.+1
@@ -211,21 +216,21 @@ userdata:			" "ustruct" (swappable)
 ii: .=.+1			" number of i-node in inode:
 inode:				" disk inode in memory:
    i.flags: .=.+1		" inode flags
-				" 400000 free?? (checked/toggled by icreat)
+				" 400000 in use
 				" 200000 large file
-				" 000040 special device (indicated by inum)?
-				" 000020  directory
+				" 000040 special device (indicated by inum)
+				" 000020 directory
 				" 000010 owner read
 				" 000004 owner write
 				" 000002 world read
 				" 000001 world write
-   i.dskps: .=.+7		" disk block pointers (indirect if "large file")
+   i.dskps: .=.+7		" disk block numbers (indirect if "large file")
    i.uid: .=.+1			" owner
-   i.nlks: .=.+1		" link count
-   i.size: .=.+1
+   i.nlks: .=.+1		" link count (negative)
+   i.size: .=.+1		" size (in words)
    i.uniq: .=.+1		" unique number
       .= inode+12
-di: .=.+1
+di: .=.+1			" directory index
 dnode:				" directory entry:
    d.i: .=.+1			" inode number
    d.name: .=.+4		" name (space padded)
diff --git a/src/sys/sop.s b/src/sys/sop.s
index ada9499..f57abc1 100644
--- a/src/sys/sop.s
+++ b/src/sys/sop.s
@@ -67,9 +67,9 @@ krb = 0700312			" KBD: read buffer
 tsf = 0700401			" TTY: skip if flag set
 tcf = 0700402			" TTY: clear flag
 tls = 0700406			" TTY: load buffer, select
-sck = 0704301			" S-2: skip on console keyboard
-cck = 0704304			" S-2: clear console keyboard
-lck = 0704312			" S-2: load console keyboard
+sck = 0704301			" G-2: skip on console keyboard
+cck = 0704304			" G-2: clear console keyboard
+lck = 0704312			" G-2: load console keyboard
 rsf = 0700101			" PTR: skip if flag set
 rsa = 0700104			" PTR: select alphanumeric mode
 rrb = 0700112			" PTR: clear flag, or read buffer
@@ -77,16 +77,16 @@ psf = 0700201			" PTP: skip if flag set
 pcf = 0700202			" PTP: clear flag
 psa = 0700204			" PTP: alphanumeric mode
 cdf = 0700501			" ???
-lds = 0701052			" S-2: load display status
-lda = 0701012			" S-2: load display address
-wcga = 0704206			" S-2: ???
-raef = 0700742			" S-2: resume after edges flag
-rlpd = 0700723			" S-2: resume after light pen stop, disabled
-beg = 0700547			" S-2: begin
-spb = 0704401			" S-2: skip on push button flag
-cpb = 0704404			" S-2: clear push button flag
-lpb = 0704412			" S-2: load push buttons
-wbl = 0704424			" S-2: write button lights
+lds = 0701052			" G-2: load display status
+lda = 0701012			" G-2: load display address
+wcga = 0704206			" G-2: ???
+raef = 0700742			" G-2: resume after edges flag
+rlpd = 0700723			" G-2: resume after light pen stop, disabled
+beg = 0700547			" G-2: begin
+spb = 0704401			" G-2: skip on push button flag
+cpb = 0704404			" G-2: clear push button flag
+lpb = 0704412			" G-2: load push buttons
+wbl = 0704424			" G-2: write button lights
 dprs = 0704752			" dataphone: read status
 dpsf = 0704741			" dataphone: skip on flag
 dpcf = 0704761			" dataphone: clear flag

From 9372fa5f56eca5070268173ecee415c7771bff27 Mon Sep 17 00:00:00 2001
From: Phil Budne <phil@ultimate.com>
Date: Fri, 11 Mar 2016 16:32:11 -0500
Subject: [PATCH 3/6] sys: more comments

---
 src/sys/s3.s |  4 ++--
 src/sys/s4.s | 12 ++++++++++++
 src/sys/s5.s | 26 +++++++++++++-------------
 src/sys/s7.s | 22 +++++++++++-----------
 src/sys/s8.s | 12 +++++++++---
 5 files changed, 47 insertions(+), 29 deletions(-)

diff --git a/src/sys/s3.s b/src/sys/s3.s
index 0037d69..8f0eb7f 100644
--- a/src/sys/s3.s
+++ b/src/sys/s3.s
@@ -317,8 +317,8 @@ rkbdi:
 wdspo:
    jms chkint1
    jms forall
-   jms dspput
-      jmp fallr
+   jms dspput			" put char (fallr "returns" here)
+      jmp fallr			" go back for next (continuation!)
    jms sleep; sfiles+6
    jms swap
    jmp wdspo
diff --git a/src/sys/s4.s b/src/sys/s4.s
index e34ddc6..09e7f97 100644
--- a/src/sys/s4.s
+++ b/src/sys/s4.s
@@ -141,6 +141,9 @@ copyz: 0
    jmp copyz i			" return
 t = t+1
 
+	" put queued character
+	" CALLED FROM PI: AVOIDS INDIRECT!!
+	" queue number in AC
 putchar: 0
 "** 01-s1.pdf page 23
    dac 9f+t
@@ -157,6 +160,14 @@ putchar: 0
    jmp putchar i
 t = t+1
 
+	" get queued character
+	" CALLED FROM PI: AVOIDS INDIRECT!!
+	" queue number in AC:
+	"  1: tty input
+	"  2: tty output
+	"  3: display keyboard
+	"  4: paper tape reader
+	"  5: paper tape punch
 getchar: 0
    jms takeq
       jmp i getchar
@@ -168,6 +179,7 @@ getchar: 0
    isz getchar
    jmp i getchar
 
+	" CALLED FROM PI: AVOIDS INDIRECT!!
 takeq: 0
    rcl
    tad lacq1
diff --git a/src/sys/s5.s b/src/sys/s5.s
index 055ed17..95c4fb3 100644
--- a/src/sys/s5.s
+++ b/src/sys/s5.s
@@ -204,9 +204,9 @@ dspput: 0
    jms dspnl			"  yes
    lac dsploc i			" get display word
    sad o400000			" TRAP?
-   jmp dspleft			"  yes
-   omq				" no: get character back
-   dac dsploc i			" save as "character 2"
+   jmp dspleft			"  yes (first character)
+   omq				" no: or in second character
+   dac dsploc i			" save both characters
    isz dsploc			" advance display pointer
    jmp i dspput
 
@@ -219,19 +219,19 @@ dspput: 0
 dspleft:
    lac dsploc			" get display pointer
    sad edspbuf			" end of the buffer?
-   jmp 1f			"  yes
-   dac 8
+   jmp 1f			"  yes: light up a button!?
+   dac 8			" no: store in index
    lac o400000			" get TRAP instruction
-   dac 8 i			" store
-   cla; llss 18+7
-   dac dsploc i
+   dac 8 i			" store as next
+   cla; llss 18+7		" shift MQ upto "char1" position
+   dac dsploc i			" store word with char1
    jmp dspput i
 
-dspnl: 0
-   lac dsplno
-   sad d33
-   jmp 1f
-   isz dsplno
+dspnl: 0			" only called once!
+   lac dsplno			" get display line number
+   sad d33			" 33?
+   jmp 1f			"  yes: light a button!
+   isz dsplno			" no: increment line number
    jmp dspnl i
 1:
    lac o2000			" get bit for push button 7
diff --git a/src/sys/s7.s b/src/sys/s7.s
index fd1e8d9..40d08ae 100644
--- a/src/sys/s7.s
+++ b/src/sys/s7.s
@@ -338,29 +338,29 @@ putcr: 0
    cla
    jmp putcr i
 
-intrp1:			" here with TTY interrupt character
-   lac d6		" get keyboard special device number
-   dac .int1		" save as interrupt source
-   lac d1
+intrp1:				" here with TTY interrupt character
+   lac d6			" get keyboard special device number
+   dac .int1			" save as interrupt source
+   lac d1			" drain tty input buffer?
    jms getchar
       skp
    jmp .-3
-   lac d2
+   lac d2			" drain tty output buffer?
    jms getchar
       skp
    jmp .-3
-   lac sfiles+0
+   lac sfiles+0			" wake ttyin sleepers
    jms wakeup
    dac sfiles+0
-   lac sfiles+1
+   lac sfiles+1			" wake ttyout sleepers
    jms wakeup
    dac sfiles+1
    jms chkint			" check if user interrupted
       jmp piret			"  no, return from PI
-   jmp 1f			" yes: return from system call
+   jmp 1f			" yes: return thru system call code (dump core)
 intrp2:				" here with display interrupt character
-   lac d7
-   dac .int2
+   lac d7			" get keyboard special device number
+   dac .int2			" save as interrupt source
    lac d3			" drain keyboard buffer?
    jms getchar
       skp
@@ -377,4 +377,4 @@ intrp2:				" here with display interrupt character
    lac 0			" get interrupt PC
    dac 020			" save as system call return PC
    lac .ac			" restore AC from interrupt
-   jmp 021			" join system call processing!!!
+   jmp 021			" join system call processing (dump core?)
diff --git a/src/sys/s8.s b/src/sys/s8.s
index 6660eb3..be013bb 100644
--- a/src/sys/s8.s
+++ b/src/sys/s8.s
@@ -93,10 +93,16 @@ o777760: 0777760
 dm3: -3
 dm1: -1
 
-9: .=.+t
-c1: .=.+1
-q1: q2;q2+90  "** ?? 98 ??
+9: .=.+t			" per-routine temp variables
+c1: .=.+1			" not used?
+q1: q2;q2+98	" ** 90?  96??	" queue element free list?
    .=.+14
+	" queues (two words each, head and tail pointers?)
+	"  1: tty input
+	"  2: tty output
+	"  3: display keyboard
+	"  4: paper tape reader
+	"  5: paper tape punch
 q2:
    .+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0
    .+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0;.+2;0

From 44e85f3fe15970af1db2b49bc226aa9e19a220cf Mon Sep 17 00:00:00 2001
From: Phil Budne <phil@ultimate.com>
Date: Fri, 11 Mar 2016 16:32:32 -0500
Subject: [PATCH 4/6] proto: update input device numbers (back to original
 values)

---
 build/proto | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/build/proto b/build/proto
index d8419c3..2836373 100644
--- a/build/proto
+++ b/build/proto
@@ -15,9 +15,9 @@ dd 	         drw-- -1 2
     system       drw-- -1 3
 	init     frwr- -1 ../bin/init
 	password frw-- -1 password
-        ttyin    irwr- -1 7
-        keyboard irwr- -1 8
-        pptin    irwr- -1 9
+        ttyin    irwr- -1 6
+        keyboard irwr- -1 7
+        pptin    irwr- -1 8
         ttyout   irwr- -1 11
         display  irwr- -1 12
         pptout   irwr- -1 13

From bf52dfb9e4fe7b28876ce7db7bdd87b6fc9ef986 Mon Sep 17 00:00:00 2001
From: Phil Budne <phil@ultimate.com>
Date: Fri, 11 Mar 2016 16:33:18 -0500
Subject: [PATCH 5/6] unixv0.sim: set tty input to 8 bit clean (no upper
 casing)

---
 build/unixv0.simh | 1 +
 1 file changed, 1 insertion(+)

diff --git a/build/unixv0.simh b/build/unixv0.simh
index ddd4927..4591561 100644
--- a/build/unixv0.simh
+++ b/build/unixv0.simh
@@ -3,6 +3,7 @@ set cpu eae
 set cpu history=100
 show cpu
 
+set tti 8b
 set rb ena
 att rb image.fs
 show dev

From adc6fdcc509d2a5f976637e0dfcaac9a945d62ea Mon Sep 17 00:00:00 2001
From: Phil Budne <phil@ultimate.com>
Date: Fri, 11 Mar 2016 16:33:53 -0500
Subject: [PATCH 6/6] sys NOTES.md: update i.nlnks comment

---
 src/sys/NOTES.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/sys/NOTES.md b/src/sys/NOTES.md
index 78ba1e3..ec56a6d 100644
--- a/src/sys/NOTES.md
+++ b/src/sys/NOTES.md
@@ -41,7 +41,7 @@ inode format
             01  world write
    i.dskps      7 block numbers (all indirect blocks if "large file")
    i.uid        owner
-   i.nlks       link count
+   i.nlks       link count (negative)
    i.size       size (in words?)
    i.uniq       unique value assigned at creation
 ```