From efb0553d7fd9e7f9ae082ba49f28b33f5b42fffa Mon Sep 17 00:00:00 2001
From: Phil Budne <phil@ultimate.com>
Date: Thu, 3 Mar 2016 21:14:35 -0500
Subject: [PATCH] system comments

---
 src/sys/s1.s |  2 +-
 src/sys/s2.s | 24 ++++++++++++------------
 src/sys/s4.s |  5 +++--
 src/sys/s5.s | 40 ++++++++++++++++++++--------------------
 src/sys/s7.s | 18 +++++++++---------
 src/sys/s8.s | 11 +++++++----
 6 files changed, 52 insertions(+), 48 deletions(-)

diff --git a/src/sys/s1.s b/src/sys/s1.s
index 2fce6fb..f50088c 100644
--- a/src/sys/s1.s
+++ b/src/sys/s1.s
@@ -139,7 +139,7 @@ swp:			" system call dispatch table
 swn:
    .-swp-1 i		" count of system calls, plus indirect!
 
-	" AC/ new value for intflg
+	" AC/ new value for intflg (non-zero to ignore interrupt char)
 	"   sys intrp
 .intrp:
    lac u.ac
diff --git a/src/sys/s2.s b/src/sys/s2.s
index b6e4baf..4006ed5 100644
--- a/src/sys/s2.s
+++ b/src/sys/s2.s
@@ -205,24 +205,24 @@
    lac u.cdir			" get current working directory
    jms namei; 0:0		" search for file
       jms error			" error: return -1
-   jms iget
+   jms iget			" load inode
    jms access			" check access (may return w/ error to user)
    lac i.flags			" get file flags
    and o20			" get directory bit
    sna				" is directory?
-   jmp open1			"  no
+   jmp open1			"  no, join common code
    lac mode			" get access mode
    and d1			" get write bit
    sna				" write access?
    jmp open1			"  no, continue
    lac u.uid			" yes: get uid?
-   sma				" negative (-1 is superuser)
+   sma				" negative? (-1 is superuser)
    jms error			"  no: return error
-   jmp open1
+   jmp open1			" yes: join common code
 
 .creat:
-   lac d1				" mode bit 1 (write?)
-   dac mode				" save for access call
+   lac d1			" mode bit 1 (write)
+   dac mode			" save for access call
    jms arg
    dac .+2
    jms copy; ..; name; 4
@@ -244,12 +244,12 @@
    jmp open1
 1:
    jms access
-   lac u.ac
-   and o17
+   lac u.ac			" get access bits from user AC (zero for lock!)
+   and o17			" mask to permissions
    jms icreat
-open1:
-   jms fassign
-      jms error
+open1:				" common exit for open/creat
+   jms fassign			" assign fd slot
+      jms error			"  none free, return -1
    jmp sysexit
 
 "** 01-s1.pdf page 11
@@ -312,7 +312,7 @@ open1:
       jms error			"  no: error
    dac u.limit			" yes: save as limit
    jms finac			" get fnode with fd from user AC
-   lac f.flags			" get file table flags
+   lac f.flags			" get open file table flags
    and d1			" open for write?
    sna				"  yes, skip
    jms error			"   no: error
diff --git a/src/sys/s4.s b/src/sys/s4.s
index b09118d..5d37eec 100644
--- a/src/sys/s4.s
+++ b/src/sys/s4.s
@@ -1,7 +1,7 @@
 "** 01-s1.pdf page 21
 " s4
 
-	" allocate a free disk block
+	" allocate a free disk block for a file (data or indirect)
 alloc: 0
    -1
    tad s.nfblks
@@ -287,6 +287,8 @@ dskrd: 0
    jms collapse
    jmp dskrd i
 
+	" write a file block (data, inode or indirect)
+	" AC/ block
 dskwr: 0
    jms betwen; d2; d7999
       jms halt
@@ -298,7 +300,6 @@ dskwr: 0
    jmp dskwr i
 t = t+3
 
-	" called with:
 	" AC/ block
 	"   jms dskio; dsld_bits
 dskio: 0
diff --git a/src/sys/s5.s b/src/sys/s5.s
index cc0db25..f83f6e8 100644
--- a/src/sys/s5.s
+++ b/src/sys/s5.s
@@ -31,35 +31,35 @@ access: 0
    jms error			" no: return error from system call
 
 fassign: 0
-   -10
-   dac 9f+t
+   -10				" loop count
+   dac 9f+t			" in t0
 1:
-   lac 9f+t
-   tad d10
-   jms fget
+   lac 9f+t			" get count
+   tad d10			" turn into fd
+   jms fget			" fetch open file into "fnode"
       jms halt " will not happen
-   lac f.flags
-   sma
-   jmp 1f
-   isz 9f+t
+   lac f.flags			" get fnode flags
+   sma				" sign bit set (active)?
+   jmp 1f			"  no: free
+   isz 9f+t			" increment loop count & loop until zero
    jmp 1b
    jmp fassign i
 1:
-   lac mode
-   xor o400000
-   dac f.flags
-   lac ii
-   dac f.i
+   lac mode			" get mode from system call
+   xor o400000			" set sign bit
+   dac f.flags			" save in fnode
+   lac ii			" get i-number
+   dac f.i			" save in fnode
    lac 9f+t
-   tad d10
-   dac u.ac
-   dzm f.badd
-   jms fput
-   isz fassign
+   tad d10			" get fd
+   dac u.ac			" return in user AC
+   dzm f.badd			" clear file offset in fnode
+   jms fput			" copy fnode back into u.ofiles
+   isz fassign			" give skip return
    jmp fassign i
 t = t+1
 
-	" get inode fpr an open file
+	" load fnode (open file entry) from u.ofiles
 	" AC/ user fd
 	"   jms fget
 	"    bad fd
diff --git a/src/sys/s7.s b/src/sys/s7.s
index 9ef5a2e..81034bb 100644
--- a/src/sys/s7.s
+++ b/src/sys/s7.s
@@ -106,16 +106,16 @@ dsprestart:
    rlpd
    jmp piret
 
-1: ksf
-   jmp 1f
+1: ksf			" (TTY) keyboard flag set?
+   jmp 1f		"  no
 
    lac ttydelay
    sma
    isz ttydelay
-   krb
-   dac char
-   sad o375
-   jmp intrp1
+   krb			" read keyboard buffer
+   dac char		" save in char
+   sad o375		" interrupt char ('}'?)
+   jmp intrp1		"  yes
    lac d1
    jms putchar
       dzm char
@@ -330,9 +330,9 @@ putcr: 0
    cla
    jmp putcr i
 
-intrp1:
-   lac d6
-   dac .int1
+intrp1:			" here with keyboard interrupt
+   lac d6		" get keyboard special device number
+   dac .int1		" save as interrupt source
    lac d1
    jms getchar
       skp
diff --git a/src/sys/s8.s b/src/sys/s8.s
index 4466a23..afce88c 100644
--- a/src/sys/s8.s
+++ b/src/sys/s8.s
@@ -229,7 +229,10 @@ dnode:				" directory entry:
    d.uniq: .=.+1		" unique number from directory inode
       . = dnode+8
 fnode:				" open file entry
-   f.flags: .=.+1
-   f.badd: .=.+1
-   f.i: 0
-
+   f.flags: .=.+1		" see below
+   f.badd: .=.+1		" offset
+   f.i: 0			" file i-number
+"	f.flags:
+"		400000	in use
+"		000002	read
+"		000001	write