-Parameter Info Block (PIB), all offsets in pointer-length words
- Name Offset Meaning
- buffer_size 0 Size of the destination buffer
+Parameter Info Block (PIB)
+ Name Size Meaning
+ buffer_size 32-bit 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
+ buffer to be created in the destination address space, with each
+ buffer individually rounded up to an 8-byte alignment. This is
specified so that the kernel can allocate one large buffer for all
- segments before traversing the segment list. When returning from a
- method, the buffer size only includes buffers allocated by the
- caller; "inout" segments where the caller specified a non-NULL ptr,
- and the callee did not increase the length, are not included
+ segments before traversing the segment list. When returning from
+ a method, the buffer size only includes buffers allocated by the
+ 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).
-
- objlist_ptr 1 Pointer to the object list
- objlist_len 2 Length of the object list
+ 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 32-bit Size of all Copy segments.
+
+ This is like buffer_size, but for Copy segments.
+
+ objlist_ptr pointer Pointer to the object list
+ newobj_ptr pointer Pointer to the new object list.
+ objlist_len 32-bit Length of the object list, in IDs
+ newobj_len 32-bit Length of the new object list, in entries.
+
+ 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. The first object in the list
+ is the object to receive the message.
- 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.
+ Objects which live in this address space have the high bit
+ clear; remote objects have the high bit set. When sending an
+ object reference that has not been exposed to the kernel
+ before, its interface hash (SHA-1 of interface GUIDs) should
+ exist in the newobj 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.
+ num_segments 32-bit Number of data segments
- 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
+ segment.ptr pointer Pointer to data segment
+ segment.len 32-bit Length of data segment in bytes
+ segment.flags 32-bit Attributes of data segment
+ reserved Reserved for future use, and for
+ power-of-two indexing -- pad to
+ 32 bytes.
Each segment describes data being transmitted to and/or from the
callee. For out segments, the caller may designate a buffer to hold
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
- 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.
- Copy 0x8000 The segment is permanently copied into the
+ In 0x01 Data is copied/mapped from caller to callee.
+ Out 0x02 Data is copied/mapped from callee to caller.
+ 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 (unless Immutable is set).
+ access.