xfer to odin

[polintos/scott/priv.git] / doc / orb / marshalling

diff --git a/doc/orb/marshalling b/doc/orb/marshalling
index a400d8860d0ef8f2aee4954a69788b766be6d51d..ab429bb8e853ee0e27a0e02154c8dbb6ff96f98b 100644 (file)
--- a/doc/orb/marshalling
+++ b/doc/orb/marshalling
@@ -1,28 +1,41 @@
-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.
 
 Op1: Get Interface List
 -----------------------
@@ -37,5 +50,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.