1 files changed, 48 insertions, 0 deletions
diff --git a/lib9p/idl/00-README.md b/lib9p/idl/00-README.md
new file mode 100644
index 0000000..f53acf9
--- /dev/null
+++ b/lib9p/idl/00-README.md
@@ -0,0 +1,48 @@
+# 9P protocol definitions
+<!--
+  Copyright (C) 2024  Luke T. Shumaker <lukeshu@lukeshu.com>
+  SPDX-Licence-Identifier: AGPL-3.0-or-later
+  -->
+
+This directory contains several `*.9p` files, each of which describes
+a 9P protocol variant.
+
+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
+(the client "Transmits" T-messages and "Receives" R-messages).  The
+type of a message is represented by a u8 ID; T-messages are even and
+R-messages are odd.
+
+Messages are made up of the primitives; unsigned little-endian
+integers, identified with the following single-character mnemonics:
+
+ - 1 = u8
+ - 2 = u16le
+ - 4 = u32le
+ - 8 = u16le
+
+Out of these primitives, we can make other numeric types,
+
+	num NUMNAME = PRIMITIVE_TYPE
+
+bitfields,
+
+	bitfield BFNAME = PRIMITIVE_TYPE "NBIT=NAME... ALIAS=VAL..."
+
+structures,
+
+	struct STRUCTNAME = "FILENAME[FIELDTYPE]..."
+
+and messages (which are a special-case of structures).
+
+	msg Tname = "size[4,val=end-&size] typ[1,val=TYP] tag[tag] REST..."
+
+Struct fields that have numeric types (either primitives or `num`
+types) can add to their type `,val=` and/or `,max=` to specify what
+the exact value must be and/or what the maximum (inclusive) value is.
+
+`,val=` and `,max` take a string of `+`/`-` tokens and values; a value
+can either be a decimal numeric constant (eg: `107`), the `&fieldname`
+to refer to the offset of a field name in that struct, or the special
+value `end` to refer to the offset of the end of the struct.