Update the PIB documentation.

diff --git a/doc/orb/parameter-info-block b/doc/orb/parameter-info-block
index 9438d1ddec0011131cf1a22bf22879914787690b..eeeb80095e0b3a6447861bbcc9b1254ee2d5653f 100644 (file)
--- a/doc/orb/parameter-info-block
+++ b/doc/orb/parameter-info-block
@@ -10,38 +10,23 @@ Parameter Info Block (PIB), all offsets in pointer-length words
       caller; "inout" segments where the caller specified a non-NULL ptr,
       and the callee did not increase the length, are not included
       (because the kernel does not need to allocate a caller-side buffer
       caller; "inout" segments where the caller specified a non-NULL ptr,
       and the callee did not increase the length, are not included
       (because the kernel does not need to allocate a caller-side buffer

-      for them).
-                 
+      for them).  The kernel may throw an exception if the actual
+      size is greater than specified in this field.
+

    objlist_ptr   1       Pointer to the object list
    objlist_len   2       Length of the object list
 
    objlist_ptr   1       Pointer to the object list
    objlist_len   2       Length of the object list
 

-      The object list is a list of pointers into segment data describing
-      where object IDs can be found.  When copying a segment to the
-      destination address space, it will convert all IDs (allocating a new
-      ID if necessary).  The object list must be in order (first by
-      segment, then by address); an exception may be thrown if it is out
-      of order or if it contains invalid entries.  Segments with object
-      IDs cannot have the Shared flag.  Unmarshalling code should always
-      verify that any ID it expects is actually in the object list.
-
-       ptrlist_ptr   3       Pointer to the pointer list
-       ptrlist_len   4       Length of the pointer list
-       
-          The pointer list, like the object list, is a list of pointers to
-          segment data.  Each pointer pointed to must also point within
-          segment data, and will be modified by the ORB when copied to point
-          to the equivalent location in the destination address space.  The
-          pointer list must be in order (first by segment, then by address);
-          an exception may be thrown if it is out of order of if it contains
-          invalid entries.  Segments with internal pointers cannot have the
-          Shared flag (shared segments can still be pointed to, of course). 
-          Unmarshalling code should always verify that any internal pointer it
-          expects actually points within a valid segment.
+      The object list is a special segment that contains object IDs
+      rather than arbitrary data.  Each object ID will be translated
+      into the destination ID-space, allocating new IDs when
+      necessary.

 
 

-   num_segments  5       Number of data segments
-   segment.ptr   6+n*3   Pointer to data segment
-   segment.len   7+n*3   Length of data segment in bytes
-   segment.flags 8+n*3   Attributes of data segment
+   num_segments  3       Number of data segments
+   segment.ptr   4+n*4   Pointer to data segment
+   segment.len   5+n*4   Length of data segment in bytes
+   segment.flags 6+n*4   Attributes of data segment
+   reserved      7+n*4   Reserved for future use, and to
+                         ensure power-of-two indexing

    
       Each segment describes data being transmitted to and/or from the
       callee.  For out segments, the caller may designate a buffer to hold
    
       Each segment describes data being transmitted to and/or from the
       callee.  For out segments, the caller may designate a buffer to hold


@@ -53,15 +38,16 @@ Parameter Info Block (PIB), all offsets in pointer-length words
       size, page-alignment, and overmap status of the segment.
 
 Segment Flags (see doc/orb/memory-management for more details):
       size, page-alignment, and overmap status of the segment.
 
 Segment Flags (see doc/orb/memory-management for more details):

-   In            0x01    Data is copied/mapped from caller to callee
-   Out           0x02    Data is copied/mapped from callee to caller
-   Shared        0x04    A permanent shared mapping is created
+   In            0x01    Data is copied/mapped from caller to callee.
+   Out           0x02    Data is copied/mapped from callee to caller.
+   Shared        0x04    A permanent shared mapping is created.

    Push          0x08    The region is unmapped from the source and
                          transferred to the destination.
    Inline        0x10    The callee cannot change the length of an
                          Out segment.  Ignored for In segments.
    Immutable     0x20    The segment is to be mapped read-only in
    Push          0x08    The region is unmapped from the source and
                          transferred to the destination.
    Inline        0x10    The callee cannot change the length of an
                          Out segment.  Ignored for In segments.
    Immutable     0x20    The segment is to be mapped read-only in

-                         the destination.
+                         the destination.  Ignored unless Shared is
+                         set.

    Copy        0x8000    The segment is permanently copied into the
                          destination address space, with read/write
    Copy        0x8000    The segment is permanently copied into the
                          destination address space, with read/write

-                         access (unless Immutable is set).
+                         access.