lib9p: idl: 9P2000: Fix comments

1 files changed, 19 insertions, 10 deletions

diff --git a/lib9p/idl/2002-9P2000.9p b/lib9p/idl/2002-9P2000.9p
index f0df7d1..14253f7 100644
--- a/lib9p/idl/2002-9P2000.9p
+++ b/lib9p/idl/2002-9P2000.9p
@@ -16,6 +16,7 @@
 # https://github.com/plan9foundation/plan9/tree/main/sys/man/5
 # https://man.cat-v.org/plan_9/5/
 # https://github.com/plan9foundation/plan9/blob/main/sys/include/fcall.h
+# https://github.com/plan9foundation/plan9/blob/main/sys/include/libc.h
 # https://github.com/plan9foundation/plan9/blob/main/sys/src/lib9p/srv.c
 version "9P2000"
 
@@ -36,17 +37,17 @@ struct d_signed = "len[4,max=s32_max] len*(dat[1])"
 # string - u16le `n`, then `n` bytes of UTF-8, without any nul-bytes
 struct s = "len[2] len*(utf8[1])"
 
-# "d"? mode - file permissions and attributes
+# "D"ir-entry "M"ode - file permissions and attributes
 bitfield dm = 4
 	"31=DIR"
 	"30=APPEND"
 	"29=EXCL"
-	# DMMOUNT has been around in Plan 9 forever, but is
-	# undocumented, and is explicitly excluded from the 9P2000
-	# draft RFC.  As I understand it, DMMOUNT indicates that the
-	# file is mounted by the kernel as a 9P transport; that the
-	# kernel has a lock on doing I/O on it, so userspace can't do
-	# I/O on it.
+	# DMMOUNT has been around in Plan 9 forever (CHMOUNT in <4e),
+	# but is undocumented, and is explicitly excluded from the
+	# 9P2000 draft RFC.  As I understand it, DMMOUNT indicates
+	# that the file is mounted by the kernel as a 9P transport;
+	# that the kernel has a lock on doing I/O on it, so userspace
+	# can't do I/O on it.
 	"28=_PLAN9_MOUNT"
 	"27=AUTH"
 	"26=TMP"
@@ -68,7 +69,7 @@ bitfield qt = 1
 	"7=DIR"
 	"6=APPEND"
 	"5=EXCL"
-	"4=_PLAN9_MOUNT" # see "MOUNT" in "dm" above
+	"4=_PLAN9_MOUNT" # See "_PLAN9_MOUNT" in "dm" above.
 	"3=AUTH"
 	# Fun historical fact: QTTMP was a relatively late addition to
 	# Plan 9, in 2003-12.
@@ -110,13 +111,14 @@ struct stat = "stat_size[2,val=end-&kern_type]"
               "file_last_modified_uid[s]"
 
 # "O"pen flags (flags to pass to Topen and Tcreate)
+# Unused bits *must* be 0.
 bitfield o = 1
 	"0=mode_0" # low bit of the 2-bit READ/WRITE/RDWR/EXEC enum
 	"1=mode_1" # high bit of the 2-bit READ/WRITE/RDWR/EXEC enum
 	#"2=unused"
 	#"3=unused"
 	"4=TRUNC"
-	#"5=unused"
+	#"5=_reserved_CEXEC" # close-on-exec
 	"6=RCLOSE" # remove-on-close
 	#"7=unused"
 
@@ -128,6 +130,13 @@ bitfield o = 1
 	"MODE_MASK = 0b00000011"
 	"FLAG_MASK = 0b11111100"
 
+# A 9P2000 session goes:
+#
+#    version()
+#    [auth_fid=auth]
+#    attach([auth_fid])
+#    ...
+
 msg Tversion = "size[4,val=end-&size] typ[1,val=100] tag[tag] max_msg_size[4] version[s]"
 msg Rversion = "size[4,val=end-&size] typ[1,val=101] tag[tag] max_msg_size[4] version[s]"
 msg Tauth    = "size[4,val=end-&size] typ[1,val=102] tag[tag] afid[fid] uname[s] aname[s]"
@@ -145,7 +154,7 @@ msg Ropen    = "size[4,val=end-&size] typ[1,val=113] tag[tag] qid[qid] iounit[4]
 msg Tcreate  = "size[4,val=end-&size] typ[1,val=114] tag[tag] fid[fid] name[s] perm[dm] mode[o]"
 msg Rcreate  = "size[4,val=end-&size] typ[1,val=115] tag[tag] qid[qid] iounit[4]"
 msg Tread    = "size[4,val=end-&size] typ[1,val=116] tag[tag] fid[fid] offset[8,max=s64_max] count[4,max=s32_max]"
-msg Rread    = "size[4,val=end-&size] typ[1,val=117] tag[tag] data[d_signed]" # for directories `data` is the sequence "cnt*(entries[stat])"
+msg Rread    = "size[4,val=end-&size] typ[1,val=117] tag[tag] data[d_signed]" # For directories `data` is the sequence "cnt*(entries[stat])".
 msg Twrite   = "size[4,val=end-&size] typ[1,val=118] tag[tag] fid[fid] offset[8,max=s64_max] data[d_signed]"
 msg Rwrite   = "size[4,val=end-&size] typ[1,val=119] tag[tag] count[4]"
 msg Tclunk   = "size[4,val=end-&size] typ[1,val=120] tag[tag] fid[fid]"