Merge pull request #150 from philbudne/syssleep

system: annotations about sleeping (both devices and messages)

src/sys/s3.s

@@ -8,8 +8,8 @@
 	"	can return directly (from caller of searchu)
 	"	index location 8 points to next process table entry
 searchu: 0
-   lac searchu i		" fetch argument
-   dac 9f+t+1			" in t1
+   lac searchu i		" fetch worker routine
+   dac 9f+t+1			" save in t1
    -mnproc			" loop counter
    dac 9f+t			" in t0
    law ulist-1			" ulist ptr
@@ -89,16 +89,16 @@ t= t+1
 badcal:				" bad (unimplemented) system call
    clon				" clear any pending clock interrupt?
    -1
-   dac 7			" set location 7 to -1?!
+   dac 7			" ask for new interrupt on next tick
 	" fall into "save" system call
 	" Ken says save files could be resumed, and used for checkpointing!
 .save:				" "sys save" system call
    lac d1			" get inode 1 (core file?)
-   jms iget
+   jms iget			" load inode
    cla
    jms iwrite; 4096; 4096	" dump core
    jms iwrite; userdata; 64	" and user area
-   jms iput
+   jms iput			" write inode
 
 .exit:
    lac u.dspbuf
@@ -106,7 +106,7 @@ badcal:				" bad (unimplemented) system call
    jmp .+3			"  no
    law dspbuf			"   yes: get default display buffer
    jms movdsp			"   move display
-   jms awake
+   jms awake			" wake waiting smes (will try & fail)
    lac u.ulistp i
    and o77777			" mark process table entry free
    dac u.ulistp i
@@ -120,7 +120,7 @@ badcal:				" bad (unimplemented) system call
 	" AC/ sending pid
 	" MQ/ message
 .rmes:
-   jms awake
+   jms awake			" wake anyone waiting to send to us
    lac o100000			" mark this process "not ready"
    tad u.ulistp i		" by incrementing status
    dac u.ulistp i
@@ -129,15 +129,15 @@ badcal:				" bad (unimplemented) system call
    dac 9f+t			" pointer to msg status in proc table
    -1
    dac 9f+t i			" set to -1 (waiting for message)
-   jms swap			" switch processes
-   law 2
+   jms swap			" swap out
+   law 2			" here when ready (with message)
    tad u.ulistp
    dac 9f+t
    lac 9f+t i			" get msg status word
    cma				" complement (get sender pid)
    dac u.ac			" return in user AC
    dzm 9f+t i			" clear status word
-   isz 9f+t
+   isz 9f+t			" point to message
    lac 9f+t i			" get message
    dac u.mq			" return in user MQ
    dzm 9f+t i			" clear message
@@ -152,73 +152,74 @@ t = t+1
 	" returns with message delivered, or error if process does not exist
 .smes:
    lac u.ac			" get pid from user AC
-   sna spa			" >0?
+   sna spa			" non-zero?
    jms error			"  no: error
    jms searchu; 1f		" search for process
    law 2
    tad u.ulistp
    dac 9f+t
-   dzm 9f+t i
+   dzm 9f+t i			" clear ulist 3rd word (not waiting)
    jms error
 1: 0				" worker for searchu
-   lac lu+1			" get pid
+   lac lu+1			" get process pid
    sad u.ac			" match?
    skp				"  yes
-   jmp 1b i			"   no
+   jmp 1b i			"   no: return
    lac lu+2			" get mailbox status
    sad dm1			" -1?
-   jmp 1f			"  yes
+   jmp 1f			"  yes: process in rmes: ok to send
    lac o100000			" no: bump our process status (to notready?)
    tad u.ulistp i
    dac u.ulistp i
    law 2
    tad u.ulistp
    dac 9f+t
-   lac u.ac
-   dac 9f+t i
+   lac u.ac			" get dest pid
+   dac 9f+t i			" save in 3rd word of our ulist entry
    jms swap
-   law 2
+   law 2			" where when swapped ready
    tad u.ulistp
    dac 9f+t
-   dzm 9f+t i
-   jmp .smes
+   dzm 9f+t i			" clear 3rd word of ulist entry
+   jmp .smes			" restart smes
 1:
    -3
    tad 8
-   dac 9f+t			" pointer to dest process ulist entry
-   lac o700000			" complement process status? marks ready??
+   dac 9f+t			" pointer to dest process ulist entry word 0
+   lac o700000			" decrement process status: marks ready
    tad 9f+t i
    dac 9f+t i
    isz 9f+t
-   isz 9f+t			" point to mailbox word?
+   isz 9f+t			" point to message status
    lac u.pid			" get our pid
    cma				" complement
-   dac 9f+t i			" store in mailbox??
+   dac 9f+t i			" store in status
    isz 9f+t			" advance to next word
    lac u.mq			" get user MQ
    dac 9f+t i			" save as message
    jmp okexit
 t = t+1
 
-	" wake up process hanging on rmes for current process??
+	" wake up all processes hanging on smes to current process
 awake: 0
    jms searchu; 1f
    jmp awake i
 1: 0				" searchu worker
    lac u.pid			" get caller pid
-   sad lu+2			" match mailbox status?
+   sad lu+2			" waiting to send to us?
    skp				"  yes
    jmp 1b i			"   no, return
    -3
    tad 8			" get pointer to process table entry
    dac 9f+t			" save in t0
 "** 01-s1.pdf page 17
-   lac o700000
-   tad 9f+t i			" complement process status (mark ready)??
+   lac o700000			" decrement process status (mark ready)
+   tad 9f+t i
    dac 9f+t i
    jmp 1b i			" return from worker
 t = t+1
 
+	" device read/write switch
 swr:
 sww:
    jmp .-4 i
@@ -227,7 +228,7 @@ sww:
 
 .halt: jms halt
 
-	" read routine for ttyin special file
+	" read routine (upper half) for ttyin special file
 rttyi:
    jms chkint1
    lac d1		" ** written d3 ttyin2
@@ -244,25 +245,25 @@ rttyi:
    jms swap
    jmp rttyi
 
-	" write routine for ttyout special file
+	" write (upper half) routine for ttyout special file
 wttyo:
    jms chkint1
    jms forall
    sna
    jmp fallr
-   lmq
-   lac sfiles+1
-   spa
-   jmp 1f
-   xor o400000
+   lmq				" save char in MQ
+   lac sfiles+1			" get sleep word
+   spa				" check if device busy
+   jmp 1f			"  yes
+   xor o400000			" mark as busy
    dac sfiles+1
-   lacq
+   lacq				" get saved char
    tls				" load output buffer
    sad o12			" newline?
    jms putcr			"  yes, put CR as well
    jmp fallr
 1:
-   lacq
+   lacq				" get saved char
    dac char
    lac d2	"** written: d6 ttyout
    jms putchar
@@ -272,7 +273,7 @@ wttyo:
    jms swap
    jmp wttyo
 
-	" read routine for (display) "keyboard" special file
+	" read routine (upper half) for (display) "keyboard" special file
 rkbdi:
    jms chkint1
    lac d3
@@ -323,7 +324,7 @@ wdspo:
    jmp wdspo
 
 
-	" read routine for paper tape reader special file
+	" read routine (upper half) for paper tape reader special file
 rppti:
    lac d4
    jms getchar
@@ -331,7 +332,7 @@ rppti:
    alss 9
    jmp passone
    lac sfiles+3			" get sleep word
-   sma				" high bit set?
+   sma				" device busy?
    rsa				"  no: reader select alphanumeric mode
 1:
    jms sleep; sfiles+3
@@ -339,19 +340,19 @@ rppti:
    jmp rppti
 "** 01-s1.pdf page 19
 
-	" write routine for paper tape punch special file
+	" write routine (upper half) for paper tape punch special file
 wppto:
    jms forall
    sna
    jmp fallr
    lmq
-   lac sfiles+4
-   spa
-   jmp 1f
-   xor o400000
+   lac sfiles+4			" get sleepers
+   spa				" busy?
+   jmp 1f			"  yes
+   xor o400000			" mark busy
    dac sfiles+4
-   lacq
-   psa
+   lacq				" get character
+   psa				" start output
    jmp fallr
 1:
    lacq

src/sys/s7.s

@@ -129,8 +129,8 @@ dsprestart:
    skp			"  yes
    jmp piret		"   no: done
    lac sfiles+1		" get ttyout sleep word
-   sma			" highest bit set?
-   xor o400000		" no, make it so
+   sma			" busy?
+   xor o400000		"  no, mark as busy now!
    dac sfiles+1		" save back
 
 "** 01-s1.pdf page 43
@@ -204,7 +204,7 @@ ttyrestart: 0
    sna			" have saved char?
    jmp .+5		"  no: jump to second rrb
    dac char		" yes: save as current char
-   rrb			" clear flag, read reader buffer
+   rrb			" clear flag, read ptr buffer
    dac npptchar		" save as saved char
    jmp .+3
    rrb			" here without saved char: read new
@@ -222,14 +222,14 @@ ttyrestart: 0
 2:
    lac npptchar		" get saved char (if any)
    sna			" had saved char?
-   jmp .+4		"  no: wake up writer
+   jmp .+4		"  no
    dac char		" yes: save as char to send
    dzm npptchar		" clear saved char
    jmp 3b
    rsa			" reader select alphanumeric mode
    lac sfiles+3
    jms wakeup		" wake sleepers; returns zero
-   xor o400000		" set high bit (rsa before sleep)
+   xor o400000		" mark busy (rsa before sleep @ rppti)
    dac sfiles+3
    jmp piret
 3:
@@ -285,7 +285,7 @@ ttyrestart: 0
    dac crread
    jmp piret
 
-1: crrb			" read card reader buffer??
+1: crrb			" clear CR flag for good measure???
 
 piret:			" return from priority interrupt
    lac 0		" get LINK (in bit 0)
@@ -314,7 +314,7 @@ wakeup: 0
    dac 9f+t
    sma			" high bit set?
    jmp 2f+2		"  no: skip the fun
-   lac o700000		" yes: decrement process status (wake)
+   lac o700000		" yes: decrement process status (mark ready)
 2: tad ..		" (avoiding indirect)
    dac ..
    lac 2b		" advance tad operand by 4 words

src/sys/s8.s

@@ -159,7 +159,7 @@ uniqpid: 1			" pid generator
 lu: .=.+4			" user (process) table entry copy
 sfiles: .=.+10			" wait addresses for special files
 		" (bit vectors of waiting processes?)
-		" bit zero (MSB) is special, bit 1 first ulist entry, ....
+		" bit zero (MSB) means busy?, bit 1 first ulist entry, ....
 		" offsets:	0: ttyin, 1: ttyout, 2: keyboard,
 		"		3: ptr,   4: ptp,    6: display
 dpdata:				" dataphone data
@@ -191,8 +191,9 @@ sysdata:			" system data 64 words saved to disk
 	" second word: process pid
 	" third word:  smes/rmes status:
 	"	 0: not waiting
-	"	-1: this process waiting (rmes)
-	"	other: complement of sender pid
+	"	rmes: -1 (waiting for message)
+	"	smes: pid of process we're waiting to send to
+	"	      complement sender pid in dest process
 	" fourth word: smes message
 ulist:
    0131000;1;0;0
@@ -211,7 +212,7 @@ userdata:			" "ustruct" (swappable)
    u.rq: .=.+9			" user 010-017, user PC
    u.uid: -1			" user id
    u.pid: 1			" process id
-   u.cdir: 3			" connected directory (inode number?)
+   u.cdir: 3			" current directory (i-num?)
    u.ulistp: ulist		" pointer to process table entry
    u.swapret: 0			" kernel routine to resume at after swap in
    u.base: 0			" start of user buffer