-segment 0, byte 0 is a request code. Codes are:
+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 id 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. 128-bit GUID of the most derived vstruct type
+2. 160-bit SHA-1 of the vstruct type info
+3. 32-bit objlist-offset of an introspection object
+4. 32-bit length of vstruct, including header, and all referenced
+data chunks, which must be contiguously appended to the vstruct body
+5. 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.
+
+The introspection object reference may be NULL; in this case, the
+SHA-1 field is ignored.
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.
projects / polintos / scott / priv.git / blobdiff