<!--
  lib9p/idl/0000-README.md - Overview of 9P protocol definitions

  Copyright (C) 2024-2025  Luke T. Shumaker <lukeshu@lukeshu.com>
  SPDX-License-Identifier: AGPL-3.0-or-later
  -->

# 9P protocol definitions

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 = "FIELDNAME[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.
A field that is repeated a variable number of times be wrapped in
parenthesis and prefixed with the fieldname containing that count:
`OTHERFIELDNAME*(FIELDNAME[FIELDTYPE])`.

`,val=` and `,max` take a string of `+`/`-` tokens and values; a value
can be
 - a decimal numeric constant (eg: `107`),
 - `&fieldname` to refer to the offset of a field name in that struct,
 - the special value `end` to refer to the offset of the end of the
   struct,

A parser for this syntax is given in `__init__.py`.  However,
`__init__.py` places the somewhat arbitrary undocumented restrictions
on fields referenced as the count for a repeated field.