doc/orb/parameter-info-block

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