diff options
author | marha <marha@users.sourceforge.net> | 2010-12-25 14:33:36 +0000 |
---|---|---|
committer | marha <marha@users.sourceforge.net> | 2010-12-25 14:33:36 +0000 |
commit | 311ab924cacb3353066bf25f23208a315ac06b9d (patch) | |
tree | 4562209dc2dba361da4eb3bb7bea923d892f1a48 /libxcb/doc | |
parent | 0412ee015982ea1ab7cbe353f20b24530d2d8048 (diff) | |
parent | c6539c9f45372fb6518bff17a781effd654bd3f0 (diff) | |
download | vcxsrv-311ab924cacb3353066bf25f23208a315ac06b9d.tar.gz vcxsrv-311ab924cacb3353066bf25f23208a315ac06b9d.tar.bz2 vcxsrv-311ab924cacb3353066bf25f23208a315ac06b9d.zip |
svn merge ^/branches/released .
Diffstat (limited to 'libxcb/doc')
-rw-r--r-- | libxcb/doc/xkb_internals | 49 | ||||
-rw-r--r-- | libxcb/doc/xkb_issues | 38 |
2 files changed, 87 insertions, 0 deletions
diff --git a/libxcb/doc/xkb_internals b/libxcb/doc/xkb_internals new file mode 100644 index 000000000..3e103910c --- /dev/null +++ b/libxcb/doc/xkb_internals @@ -0,0 +1,49 @@ +
+XKB introduces several uncommon data structures:
+ - switch allows conditional inclusion of fields
+ - several complex objects intermix variable and fixed size fields
+ - lists with a variable number of variable size objects
+
+To handle these objects, a number of new functions is generated:
+ - _serialize() turns a structured object into a byte stream,
+ (re)ordering or including fields according to the protocol
+ - _unserialize() rewrites data from a buffer into a structured object
+ - _unpack() expands a buffer representing a switch object into
+ a special structured type, all flags needed to resolve the switch
+ expression have to given as parameters
+ - _sizeof() calculates the size of a serialized object, often by calling
+ _unserialize()/_unpack() internally
+
+The new structured data type for switch is special as it contains fixed
+and variable size fields. Variable size fields can be accessed via pointers.
+
+If switch appears in a request, an additional set of request helpers is
+generated with the suffix _aux or _aux_(un)checked. While the 'common'
+request functions require that switch has been serialized before, the _aux
+variants take the structured data type. They are especially designed to
+replace certain functions in xcb-util/aux.
+
+Accessors for switch members need two parameters, where the first is usually
+a pointer to the respective request or reply structure, while the second
+is a pointer to the unpacked switch data structure.
+
+Functions from the serialize family that take a double pointer can allocate
+memory on their own, which is useful if the size of a buffer has to be
+calculated depending on the data within. These functions call malloc() when
+the double pointer is given as the address of a pointer that has been
+initialized to 0. It is the responsibility of the user to free any allocated
+memory.
+
+Intermixed variable and fixed size fields are an important special case in XKB.
+The current implementation resolves the issue by reordering the fields before
+sending them on the wire as well as before returning a reply. That means that
+these objects look like 'common' XCB data types and they can be accessed as such
+(i.e. fixed size fields directly via the structured type and variable size fields
+via accessors/iterators).
+
+In case a list with variable size elements needs to be accessed, it is necessary
+to use iterators. The iterator functions take care of determining the actual
+object size for each element automatically.
+
+A small and preliminary set of auxiliary functions is available in xkb_util.c
+in the check_xkb module.
diff --git a/libxcb/doc/xkb_issues b/libxcb/doc/xkb_issues new file mode 100644 index 000000000..f10c015e5 --- /dev/null +++ b/libxcb/doc/xkb_issues @@ -0,0 +1,38 @@ +
+There are a number of problematic special cases in XKB. The issues
+mentioned here are at most partly resolved.
+
+1. The are several XxxDoodad structures defined in xkb.xml. They are used
+ in a few lists, but in a rather special way:
+ The struct "CommonDoodad" is supposed to be a rather generic data type,
+ combining the most basic Doodad fields that are common in all these structures.
+ All Doodads are encapsulated in a union type simply called "Doodad".
+ Now this union is used in subsequent list definitions, aiming at a kind of
+ 'polymorphism': From inspection of the protocol and Xlib, the Doodads are to
+ be discriminated based on their type field.
+ However the special meaning of the type field is not encoded in the protocol.
+ Furthermore the TextDoodad and the LogoDoodad are variable size types due to
+ some fields of type CountedString16, thereby turning the union into a
+ possibly variable size type as well.
+ However, for lists with variable size elements, special sizeof functions are
+ required. These cannot be autogenerated as it cannot be referred which
+ Doodad type to use for the union.
+ Therefore, the Doodad type structures are unsupported at the moment.
+
+2. There are still some bugs in xkb.xml: Either certain fields are missing
+ that are required by the protocol, or Xlib simply has another understanding
+ of the protocol.
+
+3. The interface for accessors should be reviewed.
+
+4. Currently some bitcases carry 'name' attributes. These could be avoided if
+ the data within would consist of a singe struct field only.
+
+5. switch could get a 'fixed_size' attribute, so when rewriting valueparam to switch,
+ an uint32_t * pointer could be used instead of void *.
+
+6. The automatic inclusion of padding requires some complicated coding in the
+ generator. This is errorprone and could be avoided if all padding is explicitly
+ given in the protocol definition. For variable size fields that require padding,
+ the pad tag could get a 'fieldref' attribute. That way padding could be handled
+ a lot easier in the autogenerator.
\ No newline at end of file |