doc/orb/parameter-info-block

   1 Parameter Info Block (PIB)
   2    Name            Size    Meaning
   3    buffer_size     32-bit  Size of the destination buffer, excluding
   4                            Copy segments.
   5
   6       The total number of bytes in all of the segments that require a
   7       buffer to be created in the destination address space, with each
   8       buffer individually rounded up to an 8-byte alignment.  This is
   9       specified so that the kernel can allocate one large buffer for all
  10       segments before traversing the segment list.  When returning from
  11       a method, the buffer size only includes buffers allocated by the
  12       caller; "inout" segments where the caller specified a non-NULL
  13       ptr, and the callee did not increase the length, are not included
  14       (because the kernel does not need to allocate a caller-side buffer
  15       for them).  The kernel may throw an exception if the actual size
  16       is greater than specified in this field.
  17
  18       This only covers the "normal" segments which are mapped only
  19       for the duration of the call.  Copy segments are handled
  20       separately.
  21
  22    copy_size       32-bit  Size of all Copy segments.
  23
  24       This is like buffer_size, but for Copy segments.
  25
  26    objlist_ptr     pointer Pointer to the object list
  27    newobj_ptr      pointer Pointer to the new object list.
  28    objlist_len     32-bit  Length of the object list, in IDs
  29    newobj_len      32-bit  Length of the new object list, in hashes.
  30
  31       The object list is a special segment that contains object IDs
  32       rather than arbitrary data.  Each object ID will be translated
  33       into the destination ID-space, allocating new IDs when
  34       necessary.  The IDs themselves are 32 bits each, unsigned,
  35       regardless of the pointer size.  The first object in the list
  36       is the object to receive the message.
  37
  38       Objects which live in this address space have the high bit
  39       clear; remote objects have the high bit set.  When sending an
  40       object reference that has not been exposed to the kernel
  41       before, its interface hash (SHA-1 of interface GUIDs) should
  42       exist in the newobj list.
  43
  44    num_segments    32-bit  Number of data segments
  45
  46    segment.ptr     pointer Pointer to data segment
  47    segment.len     32-bit  Length of data segment in bytes
  48    segment.flags   32-bit  Attributes of data segment
  49    reserved                Reserved for future use, and for
  50                            power-of-two indexing -- pad to
  51                            32 bytes.
  52
  53       Each segment describes data being transmitted to and/or from the
  54       callee.  For out segments, the caller may designate a buffer to hold
  55       the data, or it may leave the ptr field NULL.  The caller may
  56       replace an out segment pointer with its own (it must do this if it
  57       was NULL), and it may change the length of the segment.  Except when
  58       flags such as Push or Shared force the kernel to map, rather than
  59       copy, the data, it will choose which method to use based on the
  60       size, page-alignment, and overmap status of the segment.
  61
  62 Segment Flags (see doc/orb/memory-management for more details):
  63    In            0x01    Data is copied/mapped from caller to callee.
  64    Out           0x02    Data is copied/mapped from callee to caller.
  65                          The data is unmapped from the callee unless
  66                          Copy is set.
  67    Inline        0x04    The callee cannot change the length of an
  68                          Out segment, and the caller must provide the
  69                          buffer.  Ignored for In segments.
  70    Copy          0x08    The segment is permanently copied into the
  71                          destination address space, with read/write
  72                          access.