# net9p.txt - Definitions of 9P messages
#
# Copyright (C) 2024  Luke T. Shumaker <lukeshu@lukeshu.com>
# SPDX-Licence-Identifier: AGPL-3.0-or-later

# In the 9P protocol, each message has a type, and message types come
# in pairs (except "Rerror"); "T" and "R"; "T" messages are
# client->server requests, and "R" messages are server->client
# responses (I do not know what the Plan 9 designers intended "T" and
# "R" to stand for).  The type of a message is represented by a u8 ID.
#
# This file is a defines the the ID and format of each message type,
# and is used to generate implementation code.

# The format of each message (excluding the "size[4] msg_type[1]
# tag[2]" header) is written here as a sequence of
# "member_name[member_type]" struct members.
#
# The primitive member types types are the following single-character
# mnemonics:
#
#  - 1 = u8
#  - 2 = u16le
#  - 4 = u32le
#  - 8 = u16le
#
# A type expression may also be [type*count]" where "type" is the
# type, and then "count" is a previously-defined integer member.
#
# We also define a few reusable compound types:

# data (u32le `n`, then `n` bytes of data)
d = "len[8] dat[1*len]"

# string (u16le `n`, then `n` bytes of UTF-8)
s = "len[2] utf8[1*len]"

# qid (TODO)
q = "type[1] vers[4] path[8]"

# stat (TODO)
stat = "stat_size[2]"
       "kern_type[2]"
       "kern_dev[4]"
       "file_qid[q]"
       "file_mode[4]"
       "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]"

stat.u = stat + "file_extension[s] file_owner_n_uid[4] file_owner_n_gid[4] file_last_modified_n_uid[4]"

# "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 a better
# references.
100 = Tversion "max_msg_size[4] version[s]"
101 = Rversion "max_msg_size[4] version[s]"
102 = Tauth    "afid[4] uname[s] aname[s]" .u+="nxs_uname[4]"
103 = Rauth    "aqid[q]"
104 = Tattach  "fid[4] afid[4] uname[s] aname[s]" .u+="n_uname[4]"
105 = Rattach  "qid[q]"
#106 = Terror   "illegal"
107 = Rerror   "ename[s]" .u+="errno[4]"
108 = Tflush   "oldtag[2]"
109 = Rflush   ""
110 = Twalk    "fid[4] newfid[4] nwname[2] wname[s*nwname]"
111 = Rwalk    "nwqid[2] wqid[q*nwqid]"
112 = Topen    "fid[4] mode[1]"
113 = Ropen    "qid[q] iounit[4]"
114 = Tcreate  "fid[4] name[s] perm[4] mode[1]" .u+="extension[s]"
115 = Rcreate  "qid[q] iounit[4]"
116 = Tread    "fid[4] offset[8] count[4]" # base="returns a sequence of "entries[stat*cnt]""; .L=can't read directories
117 = Rread    "data[d]"
118 = Twrite   "fid[4] offset[8] data[d]"
119 = Rwrite   "count[4]"
120 = Tclunk   "fid[4]"
121 = Rclunk   ""
122 = Tremove  "fid[4]"
123 = Rremove  ""
124 = Tstat    "fid[4]"
125 = Rstat    "stat[stat]"
126 = Twstat   "fid[4] stat[stat]"
127 = Rwstat   ""

# "9P2000.u" Unix extension
# https://ericvh.github.io/9p-rfc/rfc9p2000.u.html
# https://github.com/ericvh/9p-rfc/blob/master/9p2000.u.xml
#
# (no new message type numbers)

# "9P2000.L" Linux extension
# https://github.com/chaos/diod/blob/master/protocol.md
#6 = Tlerror "illegal" # analogous to 106=Terror
7 = Rlerror "ecode[4]" # analogous to 107=Rerror
8 = Tstatfs "TODO"
9 = Rstatfs "TODO"
12 = Tlopen "TODO" # analogous to 112=Topen
13 = Rlopen "TODO" # analogous to 113=Ropen
14 = Tlcreate "TODO" # analogous to 114=Tcreate
15 = Rlcreate "TODO" # analogous to 115=Rcreate
16 = Tsymlink "TODO"
17 = Rsymlink "TODO"
18 = Tmknod "TODO"
19 = Rmknod "TODO"
20 = Trename "TODO"
21 = Rrename "TODO"
22 = Treadlink "TODO"
23 = Rreadlink "TODO"
24 = Tgetattr "TODO"
25 = Rgetattr "TODO"
26 = Tsetattr "TODO"
27 = Rsetattr "TODO"
#...
30 = Txattrwalk "TODO"
31 = Rxattrwalk "TODO"
32 = Txattrcreate "TODO"
33 = Rxattrcreate "TODO"
#...
40 = Treaddir "TODO"
41 = Rreaddir "TODO"
#...
50 = Tfsync "TODO"
51 = Rfsync "TODO"
52 = Tlock "TODO"
53 = Rlock "TODO"
54 = Tgetlock "TODO"
55 = Rgetlock "TODO"
# ...
70 = Tlink "TODO"
71 = Rlink "TODO"
72 = Tmkdir "TODO"
73 = Tmkdir "TODO"
74 = Trenameat "TODO"
75 = Rrenameat "TODO"
76 = Tunlinkat "TODO"
77 = Runlinkat "TODO"

# "9P2000.e" Erlang extension
# https://erlangonxen.org/more/9p2000e
# https://github.com/cloudozer/ling/blob/master/doc/9p2000e.md
#
# TODO

# qid.types
QTDIR     = 1<<7
QTAPPEND  = 1<<6
QTEXCL    = 1<<5
QTMOUNT   = 1<<4 # been around forever, but undocumented?
QTAUTH    = 1<<3
QTTMP     = 1<<2 # added to Plan 9 2003-12
QTSYMLINK = 1<<1 # .u
QTFILE    = 1<<0

DMDIR       = 1<<31
DMAPPEND    = 1<<30
DMEXCL      = 1<<29
DMMOUNT     = 1<<28
DMAUTH      = 1<<27
DMTMP       = 1<<26
#25
#24
DMDEVICE    = 1<<23 # .u
#22
DMNAMEDPIPE = 1<<21 # .u
DMSOCKET    = 1<<20 # .u
DMSETUID    = 1<<19 # .u
DMSETGID    = 1<<18 # .u