system comments

src/sys/s3.s

@@ -1,9 +1,12 @@
 "** 01-s1.pdf page 14
 " s3
 
+	" search for user (process)
 	" call:
-	"   jms searchu; addr
-
+	"   jms searchu; worker_routine_addr
+	" worker called with copy of a process table entry in "lu"
+	"	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
@@ -27,7 +30,7 @@ searchu: 0
    jmp searchu i
 t = t+2
 
-	" look for process:
+	" look for a process with matching status
 	"   jms lookfor; status
 	"    found: ulist ptr in AC
 	"   not found
@@ -45,9 +48,13 @@ lookfor: 0
    -3
    tad 8			" roll index 8 back to this entry
    and o17777
-   isz lookfor			" skip argument
+   isz lookfor			" skip lookfor argument
    jmp lookfor i		" non-skip return
 
+	" fork system call:
+	"   sys fork
+	"    return at +1 in parent, child pid in AC
+	"   return at +2 in child, parent pid in AC
 .fork:
    jms lookfor; 0 " not-used	" find an unused process slot
       skp
@@ -55,26 +62,26 @@ lookfor: 0
    dac 9f+t			" save ulist ptr in t0
    isz uniqpid			" generate new pid
    lac uniqpid
-   dac u.ac			" return in AC
+   dac u.ac			" return in child pid in AC
    law sysexit
    dac u.swapret		" return from system call when swapped back in
-   lac o200000			" change process status to out/ready
+   lac o200000			" change process status to out/ready (1->3)
    tad u.ulistp i
    dac u.ulistp i
    jms dskswap; 07000		" swap parent out
    lac 9f+t			" get unused ulist slot back
    dac u.ulistp			" set ulist pointer
-   lac o100000			" mark child in/ready
+   lac o100000			" mark child in/notready? (3->2)
    xor u.ulistp i
    dac u.ulistp i
-   lac u.pid
+   lac u.pid			" get old (parent) pid
 "** 01-s1.pdf page 15
-   dac u.ac			" return parent pid in AC?
+   dac u.ac			" return parent pid in AC
    lac uniqpid
    dac u.pid			" set child pid
-   isz 9f+t
+   isz 9f+t			" advance to second word in process table
    dac 9f+t i			" set pid in process table
-   isz u.rq+8			" increment return address from sys call
+   isz u.rq+8			" give skip return
    dzm u.intflg			" clear int flag
    jmp sysexit			" return in child process
 t= t+1
@@ -82,28 +89,30 @@ t= t+1
 badcal:				" bad (unimplemented) system call
    clon				" clear any pending clock interrupt?
    -1
-   dac 7			" set location 7 to -1
-.save:
-   lac d1
+   dac 7			" set location 7 to -1?!
+	" 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
    cla
-   jms iwrite; 4096; 4096
-   jms iwrite; userdata; 64
+   jms iwrite; 4096; 4096	" dump core
+   jms iwrite; userdata; 64	" and user area
    jms iput
 
 .exit:
    lac u.dspbuf
-   sna					" process using display?
-   jmp .+3				"  no
-   law dspbuf				"   yes
-   jms movdsp
+   sna				" process using display?
+   jmp .+3			"  no
+   law dspbuf			"   yes
+   jms movdsp			"   move display
    jms awake
    lac u.ulistp i
-   and o77777				" mark process table entry free
+   and o77777			" mark process table entry free
    dac u.ulistp i
    isz u.ulistp
-   dzm u.ulistp i			" clear pid in process table
-   jms swap
+   dzm u.ulistp i		" clear pid in process table
+   jms swap			" find a new process to run
 
 .rmes:
    jms awake
@@ -131,25 +140,28 @@ badcal:				" bad (unimplemented) system call
 t = t+1
 
 "** 01-s1.pdf page 16
+	" smes system call
+	" AC/ pid
+	"   sys smes
 .smes:
-   lac u.ac
-   sna spa
-   jms error
-   jms searchu; 1f
+   lac u.ac			" get pid from user AC
+   sna spa			" >0?
+   jms error			"  no: error
+   jms searchu; 1f		" search for process
    law 2
    tad u.ulistp
    dac 9f+t
    dzm 9f+t i
    jms error
-1: 0
-   lac lu+1
-   sad u.ac
-   skp
-   jmp 1b i
-   lac lu+2
-   sad dm1
-   jmp 1f
-   lac o100000
+1: 0				" worker for searchu
+   lac lu+1			" get pid
+   sad u.ac			" match?
+   skp				"  yes
+   jmp 1b i			"   no
+   lac lu+2			" get mailbox
+   sad dm1			" -1?
+   jmp 1f			"  yes
+   lac o100000			" no: increment process status
    tad u.ulistp i
    dac u.ulistp i
    law 2
@@ -184,19 +196,19 @@ t = t+1
 awake: 0
    jms searchu; 1f
    jmp awake i
-1: 0
-   lac u.pid
-   sad lu+2
-   skp
-   jmp 1b i
+1: 0				" searchu worker
+   lac u.pid			" get caller pid
+   sad lu+2			" match process table entry?
+   skp				"  yes
+   jmp 1b i			"   no, return
    -3
-   tad 8
-   dac 9f+t
+   tad 8			" get pointer to pid in process table??
+   dac 9f+t			" save in t0
 "** 01-s1.pdf page 17
-   lac o700000
+   lac o700000			" set high bits
    tad 9f+t i
    dac 9f+t i
-   jmp 1b i
+   jmp 1b i			" return from worker
 t = t+1
 
 swr:
@@ -207,15 +219,16 @@ sww:
 
 .halt: jms halt
 
+	" read routine for ttyin special file
 rttyi:
    jms chkint1
    lac d1
    jms getchar
       jmp 1f
    and o177
-   jms betwen; o101; o132
-      skp
-   tad o40
+   jms betwen; o101; o132	" upper case?
+      skp			"  no
+   tad o40			"   yes: convert to lower
    alss 9
    jmp passone
 1:
@@ -223,6 +236,7 @@ rttyi:
    jms swap
    jmp rttyi
 
+	" write routine for ttyout special file
 wttyo:
    jms chkint1
    jms forall
@@ -250,6 +264,7 @@ wttyo:
    jms swap
    jmp wttyo
 
+	" read routine for (display) "keyboard" special file
 rkbdi:
    jms chkint1
    lac d3
@@ -289,6 +304,7 @@ rkbdi:
    jms swap
    jmp rkbdi
 
+	" write routine for (graphic) "display" special file
 wdspo:
    jms chkint1
    jms forall
@@ -299,6 +315,7 @@ wdspo:
    jmp wdspo
 
 
+	" read routine for paper tape reader special file
 rppti:
    lac d4
    jms getchar
@@ -314,6 +331,7 @@ rppti:
    jmp rppti
 "** 01-s1.pdf page 19
 
+	" write routine for paper tape punch special file
 wppto:
    jms forall
    sna
@@ -338,6 +356,7 @@ wppto:
    jms swap
    jmp wppto
 
+	" common exit for special file
 passone:
    sad o4000
    jmp okexit