xorg-server libx11 libxcb git update 24/12/2010

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