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    objlist_len     32-bit  Length of the object list, in IDs
  28
  29       The object list is a special segment that contains object IDs
  30       rather than arbitrary data.  Each object ID will be translated
  31       into the destination ID-space, allocating new IDs when
  32       necessary.  The IDs themselves are 32 bits each, unsigned,
  33       regardless of the pointer size.  The first object in the list
  34       is the object to receive the message.
  35
  36    num_segments    32-bit  Number of data segments
  37
  38    segment.ptr     pointer Pointer to data segment
  39    segment.len     32-bit  Length of data segment in bytes
  40    segment.flags   32-bit  Attributes of data segment
  41    reserved                Reserved for future use, and for
  42                            power-of-two indexing -- pad to
  43                            32 bytes.
  44
  45       Each segment describes data being transmitted to and/or from the
  46       callee.  For out segments, the caller may designate a buffer to hold
  47       the data, or it may leave the ptr field NULL.  The caller may
  48       replace an out segment pointer with its own (it must do this if it
  49       was NULL), and it may change the length of the segment.  Except when
  50       flags such as Push or Shared force the kernel to map, rather than
  51       copy, the data, it will choose which method to use based on the
  52       size, page-alignment, and overmap status of the segment.
  53
  54 Segment Flags (see doc/orb/memory-management for more details):
  55    In            0x01    Data is copied/mapped from caller to callee.
  56    Out           0x02    Data is copied/mapped from callee to caller.
  57                          The data is unmapped from the callee unless
  58                          Copy is set.
  59    Inline        0x04    The callee cannot change the length of an
  60                          Out segment, and the caller must provide the
  61                          buffer.  Ignored for In segments.
  62    Copy          0x08    The segment is permanently copied into the
  63                          destination address space, with read/write
  64                          access.