X-Git-Url: http://git.buserror.net/cgi-bin/gitweb.cgi?p=polintos%2Fscott%2Fpriv.git;a=blobdiff_plain;f=doc%2Forb%2Fmarshalling;h=054bdbe0b43710dd6974be09d485218f0893dcc6;hp=a400d8860d0ef8f2aee4954a69788b766be6d51d;hb=85ce56295c6eb99eba6334bad9d4b1b02ebf9cde;hpb=f413d22bf73f826dacc8881cbfb902e77aa1a84d diff --git a/doc/orb/marshalling b/doc/orb/marshalling index a400d88..054bdbe 100644 --- a/doc/orb/marshalling +++ b/doc/orb/marshalling @@ -1,28 +1,77 @@ -segment 0, byte 0 is a request code. Codes are: +---NOTE--- this is old, ignore. + +Will be deleted once I'm sure there's no information remaining that needs to +be copied elsewhere. + +Segment 0, byte 0 is a request code. Currently defined codes are: 0: Invoke Method 1: Get Interface List 2: Return Interface List Bytes 1-3 (32-bit) and 1-7 (64-bit) are reserved, and must be zero. All offsets described in the rest of this file are relative to the -first non-reserved byte (a.k.a. the message payload). The reserved -bytes do not need to be included in the message if the payload is -empty. +first non-reserved byte (a.k.a. the message payload); however, +offsets encoded in the message are relative to the beginning of the +segment, not the payload. The reserved bytes do not need to be +included in the message if the payload is empty. Op0: Invoke Method ------------------ -The segment 0 payload contains the method's arguments as if they were -a struct, followed by a depth-first traversal of any referenced -structs, excluding references which could potentially lead to loops -(i.e. references to types that exist in a parent node in the -traversal, or their supertypes) or aliases (i.e. references to types -that exist elsewhere in the traversal, or their supertypes). Where -loops or aliases are possible, the reference is encoded as a -segment/offset pair (a 32-bit word, segment is upper 6 bits), and the -data may be placed wherever the sender wishes. Non-inline arrays are -also encoded with segment/offset pairs. Object references are -encoded as 16-bit offsets into the objlist array. +The payload begins with the index of the interface being used, +followed by the index of the method. Both are 32-bit integers. + +After that, the payload contains the method's arguments as if they +were a struct. + +Non-inline structs and arrays (hereafter referred to as data chunks) +which contain object ids and/or references to other data chunks are +stored at arbitrary locations in segment 0, and are referenced as an +offset into the segment. + +Data chunks which do not contain object ids or references to other +data chunks (i.e. they are pure data, and do not need to be altered +for marshalling) are stored at arbitrary locations in arbitrary +segments. References to these pure data chunks are encoded as a +pointer-sized integer, with the upper N bits holding the segment and +the remaining bits holding the offset into that segment. The value +of N is architecture-defined, but should generally be 6 (this may +change once enough of the system is in place to do some benchmarks) +for 32-bit architectures and 32 for 64-bit architectures. + +Object references are encoded as pointer-sized offsets into the +objlist array. + +Virtual structs are prefaced with a header, which consists of +the following, in order: +1. 32-bit length of vstruct, including header, and all referenced +data chunks, which must be contiguously appended to the vstruct body +2. 32-bit offset of start of actual struct +3. 128-bit GUID of the most derived vstruct type +5. 32-bit objlist-offset of the vstruct's object handles, the first +of which is introspection object +6. 32-bit length of vstruct objlist in handles +7. 32-bit offset of an area within the vstruct where the objlist can +be copied. +8. 32-bit reserved field + +The requirement for all referenced data chunks to be contiguous with +the vstruct means that scatter-gather and zero-copy cannot be done; +however, it prevents the loss of derived-type data when only a base +type is known at unmarshalling time (the derived-type data could +later be accessed through introspection, or be passed to another +process that does know the derived type). For this reason, vstructs +should generally not be used to pass large chunks of data. + +Likewise, object handles must be preserved even if they are only +referenced in an unknown-type portion of the vstruct. To facilitate +this, all handles referenced from the vstruct must be contiguous in +the objlist (even if this means duplications), and there must be an +area in the vstruct blob where unmarshalling code can copy the +translated objlist. + +The introspection object reference at the beginning of the vstruct +objlist may be NULL. Op1: Get Interface List ----------------------- @@ -37,5 +86,5 @@ Op2: Return Interface List For async requests, objlist[1] is the object whose interfaces were requested. -The payload consists of a list of GUIDs of interfaces that the object +Segment 1 consists of a list of GUIDs of interfaces that the object supports.