xcb/proto
Description
===========
xcb/proto is a set of XML files describing the X Window System protocol
It is designed for use with libxcb, the X C binding
<http://xcb.freedesktop.org/>. xcb/proto consists of:
xcb.xsd An XML Schema defining the data format for describing the X
protocol.
*.py Code generator helpers that read the protocol descriptions
into python structures. See libxcb for example usage.
*.xml XML descriptions of the core X protocol and many extensions.
Generating C bindings
=====================
See libxcb <http://cgit.freedesktop.org/xcb/libxcb/>.
Protocol Description Format
===========================
Root element
------------
<xcb header="string" extension-name="string" extension-xname="string">
top-level elements
</xcb>
This is the root element of a protocol description. The attributes are all
various forms of the extension name. header is the basename of the XML
protocol description file, which will be used as the basename for generated
bindings as well. extension-name is the name of the extension in InterCaps,
which will be used in the names of functions. extension-xname is the name
of the extension as passed to QueryExtension.
As an example, the XML-XCB description for the GO-FASTER extension would use
the root element <xcb header="gofaster" extension-name="GoFaster"
extension-xname="GO-FASTER">; as a result, C bindings will be put in
gofaster.h and gofaster.c, extension functions will be named
XCBGoFasterFunctionName, and the extension initialization will call
QueryExtension with the name "GO-FASTER".
This element can contain any number of the elements listed in the section
"Top-Level Elements" below.
Top-Level Elements
------------------
<import>header_name</import>
The import element allows the protocol description to reference types
declared in another extension. The content is be the basename of the
extension XML file, which is also the header attribute of the extension's
root node. Note that types from xproto are automatically available, without
explicitly importing them.
<struct name="identifier">structure contents</struct>
This element represents a data structure. The name attribute gives the name
of the structure. The content represents the fields of the structure, and
consists of one or more of the field, pad, and list elements described in
the section "Structure Contents" below.
<union name="identifier">structure contents</union>
This element represents a union of data types, which can hold one value of
any of those types. The name attribute gives the name of the union. The
content represents the fields of the union, and consists of one or more of
the field and pad elements described in the section "Structure Contents
below".
<xidtype name="identifier" />
This element represents an identifier for a particular type of resource.
The name attribute gives the name of the new type.
<enum name="identifier">
<item name="identifier">[optional expression]</item>
...
</enum>
The enum element represents an enumeration type, which can take on any of
the values given by the contained item elements. The name attribute on the
enum gives the name of the enumerated type.
The item element represents one possible value of an enumerated type. The
name attribute on the item gives the name of that value, and the optional
content is an expression giving the numeric value. If the expression is
omitted, the value will be one more than that of the previous item, or 0 for
the first item.
<typedef oldname="identifier" newname="identifier" />
The typedef element declares the type given by the newname attribute to be
an alias for the type given by the oldname attribute.
<request name="identifier" opcode="integer" [combine-adjacent="true"]>
structure contents
[<reply>structure contents</reply>]
</request>
The request element represents an X protocol request. The name attribute
gives the name of the request, and the opcode attribute gives the numeric
request code. The content of the request element represents the fields in
the request, and consists of one or more of any of the elements listed in
the "Structure Contents" section below. Note that for requests in the core
protocol, the first field in the request goes into the one-byte gap between
the major opcode and the length; if the request does not have any data in
that gap, put a one byte pad as the first element. Extension requests
always have this gap filled with the minor opcode.
The optional reply element is present if the request has a reply. The
content of the reply element represents the fields in the reply, and
consists of zero or more of the field, pad, and list elements listed in the
"Structure Contents" section below. Note that the first field in the reply
always goes into the one-byte gap between the response type and the sequence
number; if the reply does not have any data in that gap, put a one byte pad
as the first element.
If the optional combine-adjacent attribute is true, multiple adjacent
requests of the same type may be combined into a single request without
affecting the semantics of the requests.
<event name="identifier" number="integer" [no-sequence-number="true"]>
structure contents
</event>
This element represents an X protocol event. The name attribute gives the
name of the event, and the number attribute gives the event number. The
content of the event element represents the fields in the event, and
consists of zero or more of the field, pad, and list elements listed in the
"Structure Contents" section below.
If the optional no-sequence-number attribute is true, the event does not
include a sequence number. This is a special-case for the KeymapNotify
event in the core protocol, and should not be used in any other event.
<error name="identifier" number="integer">
structure contents
</error>
This element represents an X protocol error. The name attribute gives the
name of the error, and the number attribute gives the error number. The
content of the error element represents the fields in the error, and
consists of zero or more of the field, pad, and list elements listed in the
"Structure Contents" section below.
<eventcopy name="identifier" number="identifier" ref="identifier" />
This element creates an alias for the event named in the ref attribute, with
the new name given in the name attribute, and the new event number given in
the number attribute.
<errorcopy name="identifier" number="identifier" ref="identifier" />
This element creates an alias for the error named in the ref attribute, with
the new name given in the name attribute, and the new error number given in
the number attribute.
Structure Contents
------------------
Note: "type" attributes below refer to types defined by previous elements,
either in the current extension, xproto, or one of the imported extensions.
The type name must refer to only one possible type; if more than one type
matches, an error occurs. To avoid this, the type may be explicitly prefixed
with a namespace, which should be the value of the header attribute on the
protocol description containing the desired type. The namespace and type are
separated by a single colon. For example, to refer to the PIXMAP type defined
in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
than type="PIXMAP".
Note: Most of the below may optionally contain an enum, altenum, or mask
attribute, which follows the above rules for "type". "enum" is an exhaustive
enum; the value is restricted to one of the constants named in the enum.
"altenum" may be one of the values contained in the enum, but it need not be.
"mask" refers to an enum to be used as a bitmask.
<pad bytes="integer" />
This element declares some padding in a data structure. The bytes
attribute declares the number of bytes of padding.
<field type="identifier" name="identifier" />
This element represents a field in a data structure. The type attribute
declares the data type of the field, and the name attribute gives the name
of the field.
<list type="identifier" name="identifier">expression</list>
This element represents an array or list of fields in a data structure. The
type attribute declares the data type of the field, and the name attribute
gives the name of the field. The content is an expression giving the length
of the list in terms of other fields in the structure. See the section
"Expressions" for details on the expression representation.
<localfield type="identifier" name="identifier" />
This element represents a parameter in a request that is not sent over the
wire. The field can be referenced in the length expressions of lists or in
an exprfield. The type attribute declares the data type of the field, and
the name attribute gives the name of the field.
<exprfield type="identifier" name="identifier">expression</exprfield>
This element represents a field in a request that is calculated rather than
supplied by the caller. The type attribute declares the data type of the
field, and the name attribute gives the name of the field. The content is
the expression giving the value of the field. See the section "Expressions"
for details on the expression representation.
<valueparam value-mask-type="identifier" value-mask-name="identifier"
value-list-name="identifier" />
This element represents a BITMASK/LISTofVALUE parameter pair: a bitmask
defining the set of values included, and a list containing these values.
value-mask-type gives the type of the bitmask; this must be CARD16 or
CARD32. value-mask-name gives the field name of the bitmask, and
value-list-name gives the field name of the list of values. Please use
<switch> instead for new protocol definitions.
<switch name="identifier"> switch expression
<bitcase> bitcase expression, fields </bitcase> </switch>
This element represents conditional inclusion of fields. It can be viewed
as sequence of multiple ifs: if ( switch expression & bitcase expression )
is equal to bitcase expression, bitcase fields are included in structure.
It can be used only as the last field of structure. New protocol definitions
should prefer to use this instead of <valueparam>.
Expressions
-----------
Expressions consist of a tree of <op> elements with leaves consisting of
<fieldref> or <value> elements.
<op op="operator">expression expression</op>
The op element represents an operator, with the op attribute specifying
which operator. The supported operations are +, -, *, /, &, and
<<, and their semantics are identical to the corresponding operators
in C. The two operand expressions may be other expression elements.
<fieldref>identifier</fieldref>
The fieldref element represents a reference to the value of another field in
the structure containing this expression. The identifier is the value of
the "name" attribute on the referenced field.
<value>integer</value>
The value element represents a literal integer value in an expression. The
integer may be expressed in decimal or hexadecimal.
<bit>integer</bit>
The bit element represents a literal bitmask value in an expression.
The integer must be in the range 0..31, expanding to (1<<n) in C.
<enumref ref="identifier">enum item identifier</enumref>
This element represents a reference to item of enum.
<unop op="operator">expression</unop>
This element represents a unary operator, with the op attribute specifying
which operator. The only supported operation so far is ~, and its semantic
is identical to the corresponding operator in C.
<sumof ref="identifier" />
This element represents a sumation of the elements of the referenced list.
<popcount>expression</popcount>
This element represents the number of bits set in the expression.