Improve sys annotations

Finally understand location 7 (incremented at 60Hz)
	setting it to -1 causes clock interrupt every jiffy
Improve comments in dsktrans
Clarify cnop/cskp usage in iread/iwrite code
	iwrite and iread have common code
	entry at iwrite save return address at iread
		and overwrites return address to "skp" inst
	entry at iread puts "nop" inst at iwrite
	"xct iwrite" skips on write entry

src/sys/s1.s

@@ -6,12 +6,16 @@ orig:
    hlt				" overwritten with interrupt return addr
    jmp pibreak			" dispatch to interrupt processing
 
-. = orig+7
+. = orig+7			" real time (60Hz) clock
-   -1				" only ever set (to -1): never read?!
+   -1				" -1 will cause "clock overflow" on next tick
+				" Overflow is checked by "clsf" instr
+				" in PI service (pibreak) routine,
+				" reset to -1 after tick handling
+				" results in an interrupt every "jiffy"
 
 . = orig+020			" syscall (CAL) and user "interrupt" processing
    1f				" addr for "CAL I": store return here on "CAL"
-   iof				" interrupts off
+   iof				" here on CAL: interrupts off
    dac u.ac			" save user AC
    lac 020			" save user return addr
    dac 1f			" save as if "CAL I"
@@ -22,29 +26,29 @@ orig:
    1f				" literal to restore location 20
 1: 0				" "CAL I" PC stored here
    iof				" interrupts off
-   dac u.ac			" save user AC
+   dac u.ac			" save user AC in user area
    lacq
-   dac u.mq			" save user MQ
+   dac u.mq			" save user MQ in user area
    lac 8
-   dac u.rq			" save user auto-index location 8
+   dac u.rq			" save user auto-index location 8 in uarea
    lac 9
-   dac u.rq+1			" save user auto-index location 9
+   dac u.rq+1			" save auto-index location 9 in user area
-   jms copy; 10; u.rq+2; 6	" save user auto-index locations 10-15
+   jms copy; 10; u.rq+2; 6	" save auto-index locations 10-15 (using 8/9!)
-   lac 1b			" load user PC after system call
+   lac 1b			" load user PC
-   dac u.rq+8			" save user PC
+   dac u.rq+8			" save in user area
    -1				" load -1
    dac .savblk			" set "save" flag (cleared by disk I/O?)
    dac .insys			" set "in system" flag
-   lac uquant			" load user quantum count
+   lac uquant			" load user quantum (tick) count
-   jms betwen; d0; maxquant	" check if between 0 & maxquant??
+   jms betwen; d0; maxquant	" check if between 0 & maxquant (30 jiffies)
-      jms swap			" no: swap processes
+      jms swap			"  no: quantum expired: swap process out
    ion				" interrupts on
    -1
    tad u.rq+8			" get address of system call
-   jms laci			" load AC indirect??
+   jms laci			" load system call instruction
-   jms betwen; o20001; swn	" range check
+   jms betwen; o20001; swn	" range check (expects CAL I!)
       jmp badcal		" bad system call
-   tad swp			" add system call table base
+   tad swp			" add "jmp syscall_table_base"
    dac .+1			" save as next instruction
    jmp .. i			" dispatch system call
 
@@ -137,7 +141,7 @@ swp:			" system call dispatch table
    .chdir; .chmod; .chown; badcal; .sysloc; badcal; .capt; .rele
    .status; badcal; .smes; .rmes; .fork
 swn:
-   .-swp-1 i		" count of system calls, plus indirect!
+   .-swp-1 i		" last system call number: "CAL I n"
 
 	" AC/ new value for intflg (non-zero to ignore interrupt char)
 	"   sys intrp

src/sys/s4.s

@@ -56,8 +56,7 @@ free: 0
    jmp free i		" Return from the routine
 t = t+1
 
-	" load AC indirect (without using indirect!)
+	" "load ac indirect"
-	" need to avoid use of indirect in interrupt service routines
 	" AC/ address
 	"   jms laci
 	" AC/ contents of address
@@ -143,7 +142,7 @@ copyz: 0
 t = t+1
 
 	" Character queue management routines
-	" (CALLED FROM PI: USE OF INDIRECT AVOIDED!)
+	" (CALLED FROM PI: USE OF INDIRECT AVOIDED TO AVOID DISK DMA UNDERRUN)
 
 	" Queue numbers:
 	"  0: free list
@@ -366,42 +365,44 @@ t = t+1
 
 	" perform disk I/O (both filesystem buffer and swapping)
 	" passed physical (BCD) disk address
+	" waits for disk interrupt: no overlapped operation
+	" to avoid disk DMA underrun
 	" called:
-	"   jms dsktrans; -WC; MAC; addr_ptr; dsld_ptr
+	"   jms dsktrans; -words; mem_addr; disk_addr_ptr; op_ptr_ptr
 dsktrans: 0
-   -10
+   -10				" set retry counter
    dac 9f+t
 1:
    -1
-   tad dsktrans
+   tad dsktrans			" get arg pointer
-   dac 12
+   dac 12			" store as auto-index
 "** 01-s1.pdf page 26
    dscs				" clear status register
-   lac 12 i
+   lac 12 i			" pick up word count
    dslw				" load WC
-   lac 12 i
+   lac 12 i			" pick up memory address
    dslm				" load MAC
-   lac 12 i
+   lac 12 i			" get disk_addr_ptr
-   jms laci
+   jms laci			" get disk address
-   dsld				" load TA & SA
+   dsld				" load BCD track and sector (TA & SA)
-   dzm .dskb
+   dzm .dskb			" clear disk interrupt indicator
-   lac 12 i
+   lac 12 i			" load status (op) pointer pointer
-   jms laci
+   jms laci			" fetch pointer
-   jms laci
+   jms laci			" fetch op
-   dsls				" load status
+   dsls				" load status register (sets busy, int enb)
    lac .dskb			" check for interrupt
    sna
-   jmp .-2
+   jmp .-2			" loop until interrupt seen
    lac .dske			" get status from interrupt
    sma
    jmp 12 i			" return
-   isz 9f+t
+   isz 9f+t			" increment retry counter
-   jmp 1b
+   jmp 1b			"  less than 10 tries: try again
    jms halt " 10 disk errors
 t = t+1
 
 halt: 0
-   isz 9f+t			" spin for a while (process interrupts)
+   isz 9f+t			" spin for a while (process interrupts?)
    jmp .-1
    iof				" disable interrupts
    hlt				" halt

src/sys/s6.s

@@ -270,12 +270,10 @@ t = t+3
 	" AC/ file offset
 	"    jms iwrite; addr; count
 
-iwrite: 0
+iwrite: 0				" set to skp (or nop by iread)
    dac 9f+t				" save arg in t0
    lac iwrite				" load return address
-
 "** 01-s1.pdf page 38
-
    dac iread				" save as iread return addr
    lac cskp				" load skip instruction
    dac iwrite				" save as iwrite instruction
@@ -287,7 +285,7 @@ iwrite: 0
 iread: 0
    dac 9f+t				" save offset in t0
    lac cnop				" get nop
-   dac iwrite				" save as iwrite instruction
+   dac iwrite				" save in iwrite return location
 1:					" common code for iread/iwrite
    -1
    tad iread i				" get word before return addr
@@ -322,17 +320,17 @@ iread: 0
    tad dm1
    xct iwrite				" skip if write
    jmp .+3
-   dac 10
+   dac 10				" here on read
-cskp:
+cskp:					" literal for store to iwrite
    skp
-   dac 11
+   dac 11				" here on write
 2:
    lac 11 i
    dac 10 i
    isz 9f+t
    isz 9f+t+1
    jmp 3f
-      xct iwrite
+      xct iwrite			" skip if write
       jmp 4f
       lac 9f+t
       jms betwen; d0; i.size
@@ -348,7 +346,7 @@ cskp:
    and o77
    sza
    jmp 2b
-   xct iwrite
+   xct iwrite			" skip if write
    jmp 1b
    lac 9f+t+3
    jms dskwr

src/sys/s7.s

@@ -25,23 +25,24 @@ pibreak:		" priority interrupt break processing "chain"
    dac dpwrite		" dpwrite = -1
    jmp piret	"** END OF CROSSOUT
 
-1: clsf			" clock overflow (line frequency ticks)?
+1: clsf			" clock overflow (60hz tick increment of loc 7 (-1))
    jmp 1f		"  no
 
    lpb			" load display push buttons
    dac pbsflgs		" save
    isz s.tim+1		" increment low order tick count
-   skp			"  no overflow, skip second increment
+   skp			"  no overflow, skip high order word increment
    isz s.tim		"   low order overflowed, increment high order count
-   isz uquant		"    increment user quantum counter
+			"   ("never" skips: 36 bits overflows every 36 years!)
-	"** written: ttydelay -> ttyd1
+   isz uquant		"    increment user quantum counter (ignore overflow)
+			"     (18 bits overflows in 72 minutes)
+	"** written: ttydelay -> ttyd1 ;
 	"** written: ttyrestart -> ttyres1
-
+cnop:			" constant location for iread (stored at iwrite!)
-cnop:			" fetched as constant in iread
    nop
    -1
-   dac 7		" set location 7 to -1 (nothing ever checks/clears it?)
+   dac 7		" reset rt clock count to -1 (overflow on next tick)
-   clon			" enable clock interrupts, reset flag
+   clon			" enable clock interrupts, clear overflow flag
    lac ttydelay		" tty delay positive?
    spa			"  yes: skip to skp
    isz ttydelay		"   no: done delaying?
@@ -129,7 +130,7 @@ dsprestart:
    jmp piret		"   no: done
    lac sfiles+1		" get ttyout sleep word
    sma			" highest bit set?
-   xor o400000		" no, make it so (why???)
+   xor o400000		" no, make it so
    dac sfiles+1		" save back
 
 "** 01-s1.pdf page 43
@@ -168,7 +169,7 @@ ttyrestart: 0
    tad o20		" bump by 16
    rcr			" divide by two
    cma			" complement
-   dac ttydelay		" save
+   dac ttydelay		" save as delay countdown
    jmp ttyrestart i
 2:
    lac sfiles+1		" run out of characters to send: wake user(s)

src/sys/s8.s

@@ -123,7 +123,7 @@ coldentry:
    dzm 0100 " not re-entrant
    caf				" clear all flags
    ion				" enable interrupts
-   clon				" clear clock flag
+   clon				" clear clock overflow flag
    law 3072			" initialize display....
    wcga
    jms dspinit