Fix 9efd2ac87b9eca51d07173cf33d48f4d3b77509e field name
[free-sw/xcb/proto] / doc / xml-xcb.txt
1                                   xcb/proto
2
3 Description
4 ===========
5
6 xcb/proto is a set of XML files describing the  X Window System protocol
7 It is designed for use with libxcb, the X C binding
8 <http://xcb.freedesktop.org/>.  xcb/proto consists of:
9
10 xcb.xsd      An XML Schema defining the data format for describing the X
11              protocol.
12
13 *.py         Code generator helpers that read the protocol descriptions
14              into python structures. See libxcb for example usage.
15
16 *.xml        XML descriptions of the core X protocol and many extensions.
17
18
19 Generating C bindings
20 =====================
21
22 See libxcb <http://cgit.freedesktop.org/xcb/libxcb/>.
23
24
25 Protocol Description Format
26 ===========================
27
28 Root element
29 ------------
30
31 <xcb header="string" extension-name="string" extension-xname="string">
32   top-level elements
33 </xcb>
34
35   This is the root element of a protocol description.  The attributes are all
36   various forms of the extension name.  header is the basename of the XML
37   protocol description file, which will be used as the basename for generated
38   bindings as well.  extension-name is the name of the extension in InterCaps,
39   which will be used in the names of functions.  extension-xname is the name
40   of the extension as passed to QueryExtension.
41
42   As an example, the XML-XCB description for the GO-FASTER extension would use
43   the root element <xcb header="gofaster" extension-name="GoFaster"
44   extension-xname="GO-FASTER">; as a result, C bindings will be put in
45   gofaster.h and gofaster.c, extension functions will be named
46   XCBGoFasterFunctionName, and the extension initialization will call
47   QueryExtension with the name "GO-FASTER".
48
49   This element can contain any number of the elements listed in the section
50   "Top-Level Elements" below.
51
52
53 Top-Level Elements
54 ------------------
55
56 <import>header_name</import>
57
58   The import element allows the protocol description to reference types
59   declared in another extension.  The content is be the basename of the
60   extension XML file, which is also the header attribute of the extension's
61   root node.  Note that types from xproto are automatically available, without
62   explicitly importing them.
63
64 <struct name="identifier">structure contents</struct>
65
66   This element represents a data structure.  The name attribute gives the name
67   of the structure.  The content represents the fields of the structure, and
68   consists of one or more of the field, pad, and list elements described in
69   the section "Structure Contents" below.
70
71 <union name="identifier">structure contents</union>
72
73   This element represents a union of data types, which can hold one value of
74   any of those types.  The name attribute gives the name of the union.  The
75   content represents the fields of the union, and consists of one or more of
76   the field and pad elements described in the section "Structure Contents
77   below".
78
79 <xidtype name="identifier" />
80
81   This element represents an identifier for a particular type of resource.
82   The name attribute gives the name of the new type.
83
84 <enum name="identifier">
85   <item name="identifier">[optional expression]</item>
86   ...
87 </enum>
88
89   The enum element represents an enumeration type, which can take on any of
90   the values given by the contained item elements.  The name attribute on the
91   enum gives the name of the enumerated type.
92
93   The item element represents one possible value of an enumerated type.  The
94   name attribute on the item gives the name of that value, and the optional
95   content is an expression giving the numeric value.  If the expression is
96   omitted, the value will be one more than that of the previous item, or 0 for
97   the first item.
98
99 <typedef oldname="identifier" newname="identifier" />
100
101   The typedef element declares the type given by the newname attribute to be
102   an alias for the type given by the oldname attribute.
103
104 <request name="identifier" opcode="integer" [combine-adjacent="true"]>
105   structure contents
106   [<reply>structure contents</reply>]
107 </request>
108
109   The request element represents an X protocol request.  The name attribute
110   gives the name of the request, and the opcode attribute gives the numeric
111   request code.  The content of the request element represents the fields in
112   the request, and consists of one or more of any of the elements listed in
113   the "Structure Contents" section below.  Note that for requests in the core
114   protocol, the first field in the request goes into the one-byte gap between
115   the major opcode and the length; if the request does not have any data in
116   that gap, put a one byte pad as the first element.  Extension requests
117   always have this gap filled with the minor opcode.
118
119   The optional reply element is present if the request has a reply.  The
120   content of the reply element represents the fields in the reply, and
121   consists of zero or more of the field, pad, and list elements listed in the
122   "Structure Contents" section below.  Note that the first field in the reply
123   always goes into the one-byte gap between the response type and the sequence
124   number; if the reply does not have any data in that gap, put a one byte pad
125   as the first element.
126
127   If the optional combine-adjacent attribute is true, multiple adjacent
128   requests of the same type may be combined into a single request without
129   affecting the semantics of the requests.
130
131 <event name="identifier" number="integer" [no-sequence-number="true"]>
132   structure contents
133 </event>
134
135   This element represents an X protocol event.  The name attribute gives the
136   name of the event, and the number attribute gives the event number.  The
137   content of the event element represents the fields in the event, and
138   consists of zero or more of the field, pad, and list elements listed in the
139   "Structure Contents" section below.
140
141   If the optional no-sequence-number attribute is true, the event does not
142   include a sequence number.  This is a special-case for the KeymapNotify
143   event in the core protocol, and should not be used in any other event.
144
145 <error name="identifier" number="integer">
146   structure contents
147 </error>
148
149   This element represents an X protocol error.  The name attribute gives the
150   name of the error, and the number attribute gives the error number.  The
151   content of the error element represents the fields in the error, and
152   consists of zero or more of the field, pad, and list elements listed in the
153   "Structure Contents" section below.
154
155 <eventcopy name="identifier" number="identifier" ref="identifier" />
156
157   This element creates an alias for the event named in the ref attribute, with
158   the new name given in the name attribute, and the new event number given in
159   the number attribute.
160
161 <errorcopy name="identifier" number="identifier" ref="identifier" />
162
163   This element creates an alias for the error named in the ref attribute, with
164   the new name given in the name attribute, and the new error number given in
165   the number attribute.
166
167
168 Structure Contents
169 ------------------
170
171 Note: "type" attributes below refer to types defined by previous elements,
172 either in the current extension, xproto, or one of the imported extensions.
173 The type name must refer to only one possible type; if more than one type
174 matches, an error occurs.  To avoid this, the type may be explicitly prefixed
175 with a namespace, which should be the value of the header attribute on the
176 protocol description containing the desired type.  The namespace and type are
177 separated by a single colon.  For example, to refer to the PIXMAP type defined
178 in glx rather than the one defined in xproto, use type="glx:PIXMAP" rather
179 than type="PIXMAP".
180
181 Note: Most of the below may optionally contain an enum, altenum, or mask
182 attribute, which follows the above rules for "type". "enum" is an exhaustive
183 enum; the value is restricted to one of the constants named in the enum.
184 "altenum" may be one of the values contained in the enum, but it need not be.
185 "mask" refers to an enum to be used as a bitmask.
186
187 <pad bytes="integer" />
188
189   This element declares some padding in a data structure.  The bytes
190   attribute declares the number of bytes of padding.
191
192 <field type="identifier" name="identifier" />
193
194   This element represents a field in a data structure.  The type attribute
195   declares the data type of the field, and the name attribute gives the name
196   of the field.
197
198 <list type="identifier" name="identifier">expression</list>
199
200   This element represents an array or list of fields in a data structure.  The
201   type attribute declares the data type of the field, and the name attribute
202   gives the name of the field.  The content is an expression giving the length
203   of the list in terms of other fields in the structure.  See the section
204   "Expressions" for details on the expression representation.
205
206 <localfield type="identifier" name="identifier" />
207
208   This element represents a parameter in a request that is not sent over the
209   wire.  The field can be referenced in the length expressions of lists or in
210   an exprfield.  The type attribute declares the data type of the field, and
211   the name attribute gives the name of the field.
212
213 <exprfield type="identifier" name="identifier">expression</exprfield>
214
215   This element represents a field in a request that is calculated rather than
216   supplied by the caller.  The type attribute declares the data type of the
217   field, and the name attribute gives the name of the field.  The content is
218   the expression giving the value of the field.  See the section "Expressions"
219   for details on the expression representation.
220
221 <valueparam value-mask-type="identifier" value-mask-name="identifier"
222             value-list-name="identifier" />
223
224   This element represents a BITMASK/LISTofVALUE parameter pair: a bitmask
225   defining the set of values included, and a list containing these values.
226   value-mask-type gives the type of the bitmask; this must be CARD16 or
227   CARD32.  value-mask-name gives the field name of the bitmask, and
228   value-list-name gives the field name of the list of values. Please use
229   <switch> instead for new protocol definitions.
230
231 <switch name="identifier"> switch expression
232     <bitcase> bitcase expression, fields </bitcase> </switch>
233
234   This element represents conditional inclusion of fields. It can be viewed
235   as sequence of multiple ifs: if ( switch expression & bitcase expression )
236   is equal to bitcase expression, bitcase fields are included in structure.
237   It can be used only as the last field of structure. New protocol definitions
238   should prefer to use this instead of <valueparam>.
239
240 Expressions
241 -----------
242
243   Expressions consist of a tree of <op> elements with leaves consisting of
244   <fieldref> or <value> elements.
245
246 <op op="operator">expression expression</op>
247
248   The op element represents an operator, with the op attribute specifying
249   which operator.  The supported operations are +, -, *, /, &amp;, and
250   &lt;&lt;, and their semantics are identical to the corresponding operators
251   in C.  The two operand expressions may be other expression elements.
252
253 <fieldref>identifier</fieldref>
254
255   The fieldref element represents a reference to the value of another field in
256   the structure containing this expression.  The identifier is the value of
257   the "name" attribute on the referenced field.
258
259 <value>integer</value>
260
261   The value element represents a literal integer value in an expression.  The
262   integer may be expressed in decimal or hexadecimal.
263
264 <bit>integer</bit>
265
266   The bit element represents a literal bitmask value in an expression.
267   The integer must be in the range 0..31, expanding to (1<<n) in C.
268
269 <enumref ref="identifier">enum item identifier</enumref>
270
271   This element represents a reference to item of enum.
272
273 <unop op="operator">expression</unop>
274
275   This element represents a unary operator, with the op attribute specifying
276   which operator. The only supported operation so far is ~, and its semantic
277   is identical to the corresponding operator in C.
278
279 <sumof ref="identifier" />
280
281   This element represents a sumation of the elements of the referenced list.
282
283 <popcount>expression</popcount>
284
285   This element represents the number of bits set in the expression.
286