]> git.buserror.net Git - polintos/scott/priv.git/blob - doc/orb/parameter-info-block
Fix stupid strncmp() bug.
[polintos/scott/priv.git] / 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    newobj_ptr      pointer Pointer to the new object list.
28    objlist_len     32-bit  Length of the object list, in IDs
29    newobj_len      32-bit  Length of the new object list, in hashes.
30
31       The object list is a special segment that contains object IDs
32       rather than arbitrary data.  Each object ID will be translated
33       into the destination ID-space, allocating new IDs when
34       necessary.  The IDs themselves are 32 bits each, unsigned,
35       regardless of the pointer size.  The first object in the list
36       is the object to receive the message.
37
38       Objects which live in this address space have the high bit
39       clear; remote objects have the high bit set.  When sending an
40       object reference that has not been exposed to the kernel
41       before, its interface hash (SHA-1 of interface GUIDs) should
42       exist in the newobj list.
43
44    num_segments    32-bit  Number of data segments
45
46    segment.ptr     pointer Pointer to data segment
47    segment.len     32-bit  Length of data segment in bytes
48    segment.flags   32-bit  Attributes of data segment
49    reserved                Reserved for future use, and for
50                            power-of-two indexing -- pad to
51                            32 bytes.
52    
53       Each segment describes data being transmitted to and/or from the
54       callee.  For out segments, the caller may designate a buffer to hold
55       the data, or it may leave the ptr field NULL.  The caller may
56       replace an out segment pointer with its own (it must do this if it
57       was NULL), and it may change the length of the segment.  Except when
58       flags such as Push or Shared force the kernel to map, rather than
59       copy, the data, it will choose which method to use based on the
60       size, page-alignment, and overmap status of the segment.
61
62 Segment Flags (see doc/orb/memory-management for more details):
63    In            0x01    Data is copied/mapped from caller to callee.
64    Out           0x02    Data is copied/mapped from callee to caller.
65                          The data is unmapped from the callee unless
66                          Copy is set.
67    Inline        0x04    The callee cannot change the length of an
68                          Out segment, and the caller must provide the
69                          buffer.  Ignored for In segments.
70    Copy          0x08    The segment is permanently copied into the
71                          destination address space, with read/write
72                          access.