397 lines
16 KiB
Plaintext
397 lines
16 KiB
Plaintext
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"] | [xge="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.
|
|
|
|
If the optional xge attribute is true, the event is an X Generic Event and
|
|
will be treated as such.
|
|
|
|
The no-sequence-number and xge attribute can not be combined.
|
|
|
|
<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, mask or altmask
|
|
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 exhaustive enum to be used as a bitmask.
|
|
"altmask" may be a mask from the referred enum, but it need not be.
|
|
|
|
<pad bytes="integer" serialize="bool" />
|
|
|
|
This element declares some padding in a data structure. The bytes
|
|
attribute declares the number of bytes of padding.
|
|
|
|
If serialize="true", then the pad will be serialized/deserialized.
|
|
This is only needed for ABI compatibility with legacy.
|
|
Newly added pads should not be defined with serialize="true".
|
|
|
|
The serialize attribute may be omitted.
|
|
Default is serialize="false".
|
|
|
|
<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.
|
|
|
|
<fd name="identifier" />
|
|
|
|
This element represents a file descriptor field passed with the request. The
|
|
name attribute gives the name of the field.
|
|
|
|
While ordinary fields are encoded as part of the request, file descriptor
|
|
fields are generally passed via an out-of-band mechanism.
|
|
|
|
<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.
|
|
|
|
<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 [name="identifier"]> bitcase expression(s), fields </bitcase>
|
|
<case [name="identifier"]> case expression(s), fields </case>
|
|
</switch>
|
|
|
|
This element represents conditional inclusion of fields. It can be viewed
|
|
as sequence of multiple ifs:
|
|
|
|
<bitcase>:
|
|
if ( switch expression & bitcase expression ) is non-zero,
|
|
bitcase fields are included in structure.
|
|
|
|
<case>:
|
|
if ( switch expression == case expression ) is true,
|
|
then case fields are included in structure.
|
|
|
|
It can be used only as the last field of a structure.
|
|
|
|
When a bitcase or case includes multiple <enumref> clauses, the contents
|
|
of the bitcase or case are only present once regardless of the number of
|
|
bitcase or case expressions that match.
|
|
|
|
<enumref> inside <bitcase> can only refer to an enum's <bit> members.
|
|
<enumref> inside <case> can only refer to an enum's <value> members.
|
|
|
|
A switch may contain multiple <bitcase> or <case> elements.
|
|
Usually it will only contain <bitcase> elements
|
|
or only contain <case> elements.
|
|
That is, mixing of <case> and <bitcase> usually doesn't make any sense.
|
|
|
|
The same value may appear in multiple <case> or <bitcase> elements.
|
|
|
|
New protocol definitions should prefer to use this instead of <valueparam>
|
|
and instead of <union>.
|
|
|
|
|
|
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.
|
|
|
|
<paramref type="type">identifier</paramref>
|
|
|
|
A paramref is similar to a fieldref, but it refers to the value of
|
|
a field in the context which refers to the struct which contains the paramref.
|
|
|
|
So, it refers to a field outside of the structure where it is defined.
|
|
This has the following consequences:
|
|
* The generator cannot deduce its type.
|
|
So, it is mandatory to specify its type.
|
|
* The identifier-name must not be used as a field in the structure
|
|
which contaons the paramref.
|
|
|
|
For an example, see struct "DeviceTimeCoord" and request/reply
|
|
"GetDeviceMotionEvents" in xinput.xml, where paramref "num_axes"
|
|
in struct DeviceTimeCoord refers to field "num_axes" in
|
|
the DeviceTimeCoord reply.
|
|
|
|
<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.
|
|
|
|
<sumof ref="identifier" >expression</sumof>
|
|
|
|
The expression is evaluated for each element of the referenced list,
|
|
in the context of this element.
|
|
This sumof element then represents a sumation of the results of these
|
|
evaluations.
|
|
|
|
expression will usually be a fieldref which references a field of
|
|
a list-element or an expression containing a fieldref,
|
|
such as popcount of a fieldref.
|
|
|
|
<popcount>expression</popcount>
|
|
|
|
This element represents the number of bits set in the expression.
|
|
|
|
<listelement-ref/>
|
|
|
|
This element represents the current list-element when used inside
|
|
a list-iteration expression such as <sumof>.
|
|
|
|
Documentation
|
|
-------------
|
|
|
|
Documentation for each request, reply or event is stored in the appropriate
|
|
element using a <doc> element. The <doc> element can contain the following
|
|
elements:
|
|
|
|
<brief>brief description</brief>
|
|
|
|
A short description of the request, reply or event. For example "makes a
|
|
window visible" for MapWindow. This will end up in the manpage NAME section
|
|
and in the doxygen @brief description.
|
|
|
|
<description><![CDATA[longer description]]></description>
|
|
|
|
The full description. Use `` to highlight words, such as "Draws
|
|
`points_len`-1 lines between each pair of points…"
|
|
|
|
<example><![CDATA[example code]]</description>
|
|
|
|
Example C code illustrating the usage of the particular request, reply or
|
|
event.
|
|
|
|
<field name="name">field description</field>
|
|
|
|
The full description for the specified field. Depending on the context, this
|
|
is either a request parameter or a reply/event datastructure field.
|
|
|
|
<error type="type">error description</field>
|
|
|
|
The full description for an error which can occur due to this request.
|
|
|
|
<see type="request" name="name" />
|
|
|
|
A reference to another relevant program, function, request or event.
|