diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/xkb_internals | 49 | ||||
| -rw-r--r-- | doc/xkb_issues | 38 |
2 files changed, 87 insertions, 0 deletions
diff --git a/doc/xkb_internals b/doc/xkb_internals new file mode 100644 index 0000000..93c6d01 --- /dev/null +++ b/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/doc/xkb_issues b/doc/xkb_issues new file mode 100644 index 0000000..80efcc1 --- /dev/null +++ b/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 |