-segment 0, byte 0 is a request code. Codes are:
+---NOTE--- this is old, ignore.
+
+Will be deleted once I'm sure there's no information remaining that needs to
+be copied elsewhere.
+
+Segment 0, byte 0 is a request code. Currently defined codes are:
0: Invoke Method
1: Get Interface List
2: Return Interface List
Bytes 1-3 (32-bit) and 1-7 (64-bit) are reserved, and must be zero.
All offsets described in the rest of this file are relative to the
-first non-reserved byte (a.k.a. the message payload). The reserved
-bytes do not need to be included in the message if the payload is
-empty.
+first non-reserved byte (a.k.a. the message payload); however,
+offsets encoded in the message are relative to the beginning of the
+segment, not the payload. The reserved bytes do not need to be
+included in the message if the payload is empty.
Op0: Invoke Method
------------------
-The segment 0 payload contains the method's arguments as if they were
-a struct, followed by a depth-first traversal of any referenced
-structs, excluding references which could potentially lead to loops
-(i.e. references to types that exist in a parent node in the
-traversal, or their supertypes) or aliases (i.e. references to types
-that exist elsewhere in the traversal, or their supertypes). Where
-loops or aliases are possible, the reference is encoded as a
-segment/offset pair (a 32-bit word, segment is upper 6 bits), and the
-data may be placed wherever the sender wishes. Non-inline arrays are
-also encoded with segment/offset pairs. Object references are
-encoded as 16-bit offsets into the objlist array.
+The payload begins with the index of the interface being used,
+followed by the index of the method. Both are 32-bit integers.
+
+After that, the payload contains the method's arguments as if they
+were a struct.
+
+Non-inline structs and arrays (hereafter referred to as data chunks)
+which contain object ids and/or references to other data chunks are
+stored at arbitrary locations in segment 0, and are referenced as an
+offset into the segment.
+
+Data chunks which do not contain object ids or references to other
+data chunks (i.e. they are pure data, and do not need to be altered
+for marshalling) are stored at arbitrary locations in arbitrary
+segments. References to these pure data chunks are encoded as a
+pointer-sized integer, with the upper N bits holding the segment and
+the remaining bits holding the offset into that segment. The value
+of N is architecture-defined, but should generally be 6 (this may
+change once enough of the system is in place to do some benchmarks)
+for 32-bit architectures and 32 for 64-bit architectures.
+
+Object references are encoded as pointer-sized offsets into the
+objlist array.
+
+Virtual structs are prefaced with a header, which consists of
+the following, in order:
+1. 32-bit length of vstruct, including header, and all referenced
+data chunks, which must be contiguously appended to the vstruct body
+2. 32-bit offset of start of actual struct
+3. 128-bit GUID of the most derived vstruct type
+5. 32-bit objlist-offset of the vstruct's object handles, the first
+of which is introspection object
+6. 32-bit length of vstruct objlist in handles
+7. 32-bit offset of an area within the vstruct where the objlist can
+be copied.
+8. 32-bit reserved field
+
+The requirement for all referenced data chunks to be contiguous with
+the vstruct means that scatter-gather and zero-copy cannot be done;
+however, it prevents the loss of derived-type data when only a base
+type is known at unmarshalling time (the derived-type data could
+later be accessed through introspection, or be passed to another
+process that does know the derived type). For this reason, vstructs
+should generally not be used to pass large chunks of data.
+
+Likewise, object handles must be preserved even if they are only
+referenced in an unknown-type portion of the vstruct. To facilitate
+this, all handles referenced from the vstruct must be contiguous in
+the objlist (even if this means duplications), and there must be an
+area in the vstruct blob where unmarshalling code can copy the
+translated objlist.
+
+The introspection object reference at the beginning of the vstruct
+objlist may be NULL.
Op1: Get Interface List
-----------------------
For async requests, objlist[1] is the object whose interfaces were
requested.
-The payload consists of a list of GUIDs of interfaces that the object
+Segment 1 consists of a list of GUIDs of interfaces that the object
supports.