wip idl rewrite

1 files changed, 147 insertions, 0 deletions

diff --git a/lib9p/idl/01-9P2000.9p b/lib9p/idl/01-9P2000.9p
new file mode 100644
index 0000000..680d243
--- /dev/null
+++ b/lib9p/idl/01-9P2000.9p
@@ -0,0 +1,147 @@
+# 01-9P2000.9p - Definitions of 9P2000 messages
+#
+# Copyright (C) 2024  Luke T. Shumaker <lukeshu@lukeshu.com>
+# SPDX-Licence-Identifier: AGPL-3.0-or-later
+
+# "9P2000" base protocol
+# https://ericvh.github.io/9p-rfc/rfc9p2000.html
+# https://github.com/ericvh/9p-rfc/blob/master/9p2000.xml
+#
+# But due to incompleteness of the draft RFC, the Plan 9 manual
+# section-5 and the Plan 9 headers (particularly fcall.h) are often
+# better references.
+#
+# 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
+version "9P2000"
+
+# tag - identify a request/response pair
+num tag = 2
+
+# file identifier
+num fid = 4
+
+# data - u32le `n`, then `n` bytes of data
+struct d = "len[4] 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
+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.
+	"28=_PLAN9_MOUNT"
+	"27=AUTH"
+	"26=TMP"
+	#...
+	"8=OWNER_R"
+	"7=OWNER_W"
+	"6=OWNER_X"
+	"5=GROUP_R"
+	"4=GROUP_W"
+	"3=GROUP_X"
+	"2=OTHER_R"
+	"1=OTHER_W"
+	"0=OTHER_X"
+
+	"PERM=0777" # {OWNER,GROUP,OTHER}_{R,W,X}
+
+# QID Type - see `struct qid` below
+bitfield qt = 1
+	"7=DIR"
+	"6=APPEND"
+	"5=EXCL"
+	"4=_PLAN9_MOUNT" # see "MOUNT" in "dm" above
+	"3=AUTH"
+	# Fun historical fact: QTTMP was a relatively late addition to
+	# Plan 9, in 2003-12.
+	"2=TMP"
+	#"1=unused"
+
+	# "The name QTFILE, defined to be zero, identifies the value
+	# of the type for a plain file."
+	"FILE=0"
+
+# uni"Q"ue "ID"entification - "two files on the same server hierarchy
+# are the same if and only if their qids are the same"
+#
+#  - "path" is a unique uint64_t that does most of the work in the
+#    above statement about files being the same if their QIDs are the
+#    same; " If a file is deleted and recreated with the same name in
+#    the same directory, the old and new path components of the qids
+#    should be different"
+#
+#  - "vers" "is a version number for a file; typically, it is
+#    incremented every time the file is modified.
+#
+#  - "type" indicates "whether the file is a directory, append-only
+#    file, etc."; is an instance of the qid_type bitfield.
+struct qid = "type[qt] vers[4] path[8]"
+
+# stat - file status
+struct stat = "stat_size[2,val=end-&kern_type]"
+              "kern_type[2]"
+              "kern_dev[4]"
+              "file_qid[qid]"
+              "file_mode[dm]"
+              "file_atime[4]"
+              "file_mtime[4]"
+              "file_size[8]"
+              "file_name[s]"
+              "file_owner_uid[s]"
+              "file_owner_gid[s]"
+              "file_last_modified_uid[s]"
+
+# "O"pen flags (flags to pass to Topen and Tcreate)
+bitfield o = 1
+	"0=rwx_0" # low bit of the 2-bit READ/WRITE/RDWR/EXEC enum
+	"1=rwx_1" # high bit of the 2-bit READ/WRITE/RDWR/EXEC enum"
+	#"2=unused"
+	#"3=unused"
+	"4=TRUNC"
+	#"5=unused"
+	"6=RCLOSE" # remove-on-close
+	#"7=unused"
+
+	"READ  = 0" # make available for this FID: Tread()
+	"WRITE = 1" # make available for this FID: Twrite()
+	"RDWR  = 2" # make available for this FID: Tread() and Twrite()
+	"EXEC  = 3" # make available for this FID: Tread()
+
+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]"
+msg Rauth    = "size[4,val=end-&size] typ[1,val=103] tag[tag] aqid[qid]"
+msg Tattach  = "size[4,val=end-&size] typ[1,val=104] tag[tag] fid[fid] afid[fid] uname[s] aname[s]"
+msg Rattach  = "size[4,val=end-&size] typ[1,val=105] tag[tag] qid[qid]"
+#msg Terror   = "size[4,val=end-&size] typ[1,val=106] tag[tag] illegal"
+msg Rerror   = "size[4,val=end-&size] typ[1,val=107] tag[tag] ename[s]"
+msg Tflush   = "size[4,val=end-&size] typ[1,val=108] tag[tag] oldtag[2]"
+msg Rflush   = "size[4,val=end-&size] typ[1,val=109] tag[tag]"
+msg Twalk    = "size[4,val=end-&size] typ[1,val=110] tag[tag] fid[fid] newfid[fid] nwname[2,max=16] nwname*(wname[s])"
+msg Rwalk    = "size[4,val=end-&size] typ[1,val=111] tag[tag] nwqid[2,max=16] nwqid*(wqid[qid])"
+msg Topen    = "size[4,val=end-&size] typ[1,val=112] tag[tag] fid[fid] mode[o]"
+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] count[4]"
+msg Rread    = "size[4,val=end-&size] typ[1,val=117] tag[tag] data[d]" # 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] data[d]"
+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]"
+msg Rclunk   = "size[4,val=end-&size] typ[1,val=121] tag[tag]"
+msg Tremove  = "size[4,val=end-&size] typ[1,val=122] tag[tag] fid[fid]"
+msg Rremove  = "size[4,val=end-&size] typ[1,val=123] tag[tag]"
+msg Tstat    = "size[4,val=end-&size] typ[1,val=124] tag[tag] fid[fid]"
+msg Rstat    = "size[4,val=end-&size] typ[1,val=125] tag[tag] nstat[2,val=end-&stat] stat[stat]"          # See the "BUG" note in the RFC for the nstat field
+msg Twstat   = "size[4,val=end-&size] typ[1,val=126] tag[tag] fid[fid] nstat[2,val=end-&stat] stat[stat]" # See the "BUG" note in the RFC for the nstat field
+msg Rwstat   = "size[4,val=end-&size] typ[1,val=127] tag[tag]"