doc/orb/marshalling

   1 ---NOTE--- this is old, ignore.
   2
   3 Will be deleted once I'm sure there's no information remaining that needs to
   4 be copied elsewhere.
   5
   6 Segment 0, byte 0 is a request code.  Currently defined codes are:
   7  0: Invoke Method
   8  1: Get Interface List
   9  2: Return Interface List
  10
  11 Bytes 1-3 (32-bit) and 1-7 (64-bit) are reserved, and must be zero.
  12 All offsets described in the rest of this file are relative to the
  13 first non-reserved byte (a.k.a. the message payload); however,
  14 offsets encoded in the message are relative to the beginning of the
  15 segment, not the payload.  The reserved bytes do not need to be
  16 included in the message if the payload is empty.
  17
  18 Op0: Invoke Method
  19 ------------------
  20
  21 The payload begins with the index of the interface being used,
  22 followed by the index of the method.  Both are 32-bit integers.
  23
  24 After that, the payload contains the method's arguments as if they
  25 were a struct.
  26
  27 Non-inline structs and arrays (hereafter referred to as data chunks)
  28 which contain object ids and/or references to other data chunks are
  29 stored at arbitrary locations in segment 0, and are referenced as an
  30 offset into the segment.
  31
  32 Data chunks which do not contain object ids or references to other
  33 data chunks (i.e. they are pure data, and do not need to be altered
  34 for marshalling) are stored at arbitrary locations in arbitrary
  35 segments.  References to these pure data chunks are encoded as a
  36 pointer-sized integer, with the upper N bits holding the segment and
  37 the remaining bits holding the offset into that segment.  The value
  38 of N is architecture-defined, but should generally be 6 (this may
  39 change once enough of the system is in place to do some benchmarks)
  40 for 32-bit architectures and 32 for 64-bit architectures.
  41
  42 Object references are encoded as pointer-sized offsets into the
  43 objlist array.
  44
  45 Virtual structs are prefaced with a header, which consists of
  46 the following, in order:
  47 1. 32-bit length of vstruct, including header, and all referenced
  48 data chunks, which must be contiguously appended to the vstruct body
  49 2. 32-bit offset of start of actual struct
  50 3. 128-bit GUID of the most derived vstruct type
  51 5. 32-bit objlist-offset of the vstruct's object handles, the first
  52 of which is introspection object
  53 6. 32-bit length of vstruct objlist in handles
  54 7. 32-bit offset of an area within the vstruct where the objlist can
  55 be copied.
  56 8. 32-bit reserved field
  57
  58 The requirement for all referenced data chunks to be contiguous with
  59 the vstruct means that scatter-gather and zero-copy cannot be done;
  60 however, it prevents the loss of derived-type data when only a base
  61 type is known at unmarshalling time (the derived-type data could
  62 later be accessed through introspection, or be passed to another
  63 process that does know the derived type).  For this reason, vstructs
  64 should generally not be used to pass large chunks of data.
  65
  66 Likewise, object handles must be preserved even if they are only
  67 referenced in an unknown-type portion of the vstruct.  To facilitate
  68 this, all handles referenced from the vstruct must be contiguous in
  69 the objlist (even if this means duplications), and there must be an
  70 area in the vstruct blob where unmarshalling code can copy the
  71 translated objlist.
  72
  73 The introspection object reference at the beginning of the vstruct
  74 objlist may be NULL.
  75
  76 Op1: Get Interface List
  77 -----------------------
  78
  79 Return a "Return Interface List" message corresponding to the object
  80 in objlist[0].  For async requests, objlist[1] is the destination for
  81 the return message.
  82
  83 Op2: Return Interface List
  84 --------------------------
  85
  86 For async requests, objlist[1] is the object whose interfaces were
  87 requested.
  88
  89 Segment 1 consists of a list of GUIDs of interfaces that the object
  90 supports.