Document new memory management semantics.

[polintos/scott/priv.git] / doc / orb / parameter-info-block

diff --git a/doc/orb/parameter-info-block b/doc/orb/parameter-info-block
index 2885294ed079b56ef0a17c938c93659f1b9b19b5..8f32e1cb40409afdc4004df163a5850bd98e976e 100644 (file)
--- a/doc/orb/parameter-info-block
+++ b/doc/orb/parameter-info-block
@@ -1,6 +1,7 @@
 Parameter Info Block (PIB), all offsets in pointer-length words
-   Name          Offset  Meaning
-   buffer_size   0       Size of the destination buffer
+   Name            Offset  Meaning
+   buffer_size     0       Size of the destination buffer, excluding
+                           Copy segments.
    
       The total number of bytes in all of the segments that require a
       buffer to be created in the destination address space.  This is
@@ -12,22 +13,31 @@ Parameter Info Block (PIB), all offsets in pointer-length words
       (because the kernel does not need to allocate a caller-side buffer
       for them).  The kernel may throw an exception if the actual
       size is greater than specified in this field.
+      
+      This only covers the "normal" segments which are mapped only
+      for the duration of the call.  Copy segments are handled
+      separately.
+   
+   copy_size       1       Size of all Copy segments.
+   
+      This is like buffer_size, but for Copy segments.  The pages
 
-   objlist_ptr   1       Pointer to the object list
-   objlist_len   2       Length of the object list, in IDs
+   objlist_ptr     2       Pointer to the object list
+   objlist_len     3       Length of the object list, in IDs
 
       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.  The IDs themselves are 32 bits each, unsigned,
-      regardless of the pointer size.
+      regardless of the pointer size.  The first object in the list
+      is the object to receive the message.
 
-   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 for
-                         power-of-two indexing
+   num_segments    4       Number of data segments
+   segment.ptr     5+n*4   Pointer to data segment
+   segment.len     6+n*4   Length of data segment in bytes
+   segment.flags   7+n*4   Attributes of data segment
+   reserved        8+n*4   Reserved for future use, and for
+                           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
@@ -41,14 +51,11 @@ Parameter Info Block (PIB), all offsets in pointer-length words
 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.
-   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.  Ignored unless Shared is
-                         set.
-   Copy        0x8000    The segment is permanently copied into the
+                         The data is unmapped from the callee unless
+                         Copy is set.
+   Inline        0x04    The callee cannot change the length of an
+                         Out segment, and the caller must provide the
+                         buffer.  Ignored for In segments.
+   Copy          0x08    The segment is permanently copied into the
                          destination address space, with read/write
                          access.