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
   4
   5       The total number of bytes in all of the segments that require a
   6       buffer to be created in the destination address space.  This is
   7       specified so that the kernel can allocate one large buffer for all
   8       segments before traversing the segment list.  When returning from a
   9       method, the buffer size only includes buffers allocated by the
  10       caller; "inout" segments where the caller specified a non-NULL ptr,
  11       and the callee did not increase the length, are not included
  12       (because the kernel does not need to allocate a caller-side buffer
  13       for them).
  14
  15    objlist_ptr   1       Pointer to the object list
  16    objlist_len   2       Length of the object list
  17
  18       The object list is a list of pointers into segment data describing
  19       where object IDs can be found.  When copying a segment to the
  20       destination address space, it will convert all IDs (allocating a new
  21       ID if necessary).  The object list must be in order (first by
  22       segment, then by address); an exception may be thrown if it is out
  23       of order or if it contains invalid entries.  Segments with object
  24       IDs cannot have the Shared flag.  Unmarshalling code should always
  25       verify that any ID it expects is actually in the object list.
  26
  27         ptrlist_ptr   3       Pointer to the pointer list
  28         ptrlist_len   4       Length of the pointer list
  29
  30            The pointer list, like the object list, is a list of pointers to
  31            segment data.  Each pointer pointed to must also point within
  32            segment data, and will be modified by the ORB when copied to point
  33            to the equivalent location in the destination address space.  The
  34            pointer list must be in order (first by segment, then by address);
  35            an exception may be thrown if it is out of order of if it contains
  36            invalid entries.  Segments with internal pointers cannot have the
  37            Shared flag (shared segments can still be pointed to, of course).
  38            Unmarshalling code should always verify that any internal pointer it
  39            expects actually points within a valid segment.
  40
  41    num_segments  5       Number of data segments
  42    segment.ptr   6+n*3   Pointer to data segment
  43    segment.len   7+n*3   Length of data segment in bytes
  44    segment.flags 8+n*3   Attributes of data segment
  45
  46       Each segment describes data being transmitted to and/or from the
  47       callee.  For out segments, the caller may designate a buffer to hold
  48       the data, or it may leave the ptr field NULL.  The caller may
  49       replace an out segment pointer with its own (it must do this if it
  50       was NULL), and it may change the length of the segment.  Except when
  51       flags such as Push or Shared force the kernel to map, rather than
  52       copy, the data, it will choose which method to use based on the
  53       size, page-alignment, and overmap status of the segment.
  54
  55 Segment Flags (see doc/orb/memory-management for more details):
  56    In            0x01    Data is copied/mapped from caller to callee
  57    Out           0x02    Data is copied/mapped from callee to caller
  58    Shared        0x04    A permanent shared mapping is created
  59    Push          0x08    The region is unmapped from the source and
  60                          transferred to the destination.
  61    Inline        0x10    The callee cannot change the length of an
  62                          Out segment.  Ignored for In segments.
  63    Immutable     0x20    The segment is to be mapped read-only in
  64                          the destination.
  65    Copy        0x8000    The segment is permanently copied into the
  66                          destination address space, with read/write
  67                          access (unless Immutable is set).