X-Git-Url: http://git.buserror.net/cgi-bin/gitweb.cgi?p=polintos%2Fscott%2Fpriv.git;a=blobdiff_plain;f=doc%2Forb%2Fparameter-info-block;h=b868a4474a0a7dcc6070fb7d6f9751716d6d3d38;hp=9438d1ddec0011131cf1a22bf22879914787690b;hb=bc696ad9b0d5a2ad04e2de5ad8b89f746dd78491;hpb=7da27a216a7f4bb3331fe315cdbec69bfcf2c762 diff --git a/doc/orb/parameter-info-block b/doc/orb/parameter-info-block index 9438d1d..b868a44 100644 --- a/doc/orb/parameter-info-block +++ b/doc/orb/parameter-info-block @@ -1,47 +1,55 @@ -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. + + 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. + + 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 should exist in the newobj 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. + 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 @@ -53,15 +61,13 @@ 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): - 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.