X-Git-Url: http://git.buserror.net/cgi-bin/gitweb.cgi?p=polintos%2Fscott%2Fpriv.git;a=blobdiff_plain;f=doc%2Forb%2Fmarshalling;h=e56e350a0d3eebc3c991906f4ad856a9112fc42c;hp=a400d8860d0ef8f2aee4954a69788b766be6d51d;hb=b5cbe98949d5b279965d607c9618d404b26d4760;hpb=f413d22bf73f826dacc8881cbfb902e77aa1a84d

diff --git a/doc/orb/marshalling b/doc/orb/marshalling
index a400d88..e56e350 100644
--- a/doc/orb/marshalling
+++ b/doc/orb/marshalling
@@ -1,28 +1,61 @@
-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
 -----------------------
@@ -37,5 +70,5 @@ Op2: Return 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.