Add distributors to liability disclaimer. Need to update file headers.

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

diff --git a/doc/orb/marshalling b/doc/orb/marshalling
index ab429bb8e853ee0e27a0e02154c8dbb6ff96f98b..286eff4115b71229c264405d93f84e60165aa156 100644 (file)
--- a/doc/orb/marshalling
+++ b/doc/orb/marshalling
@@ -24,7 +24,7 @@ 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 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
@@ -37,6 +37,26 @@ 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
 -----------------------