Remove xcl and CVSROOT.

[free-sw/xcb/proto] / doc / xml-xcb.txt

                                   XML-XCB

Description
===========

XML-XCB generates C bindings to the X Window System protocol based on XML
descriptions of the protocol.  It is designed for use with XCB, the X C
binding <http://xcb.freedesktop.org>.  XML-XCB consists of:

xcb.xsd      An XML Schema defining the data format for describing the X
             protocol.  Included in xcb-proto.

c-client.xsl An XSLT code generator that transforms the protocol descriptions
             into C bindings.  Included in xcb.

*.xml        XML descriptions of the core X protocol and many extensions.
             Included in xcb-proto.


Dependencies
============

c-client.xsl requires an XSLT processor that supports XSLT 1.0
<http://www.w3.org/TR/1999/REC-xslt-19991116> and the EXSLT node-set extension
<http://www.exslt.org/exsl/functions/node-set/index.html>.  The XCB build
system currently uses xsltproc.  You can get xsltproc through your
distribution's packaging system, or from <http://xmlsoft.org/XSLT/>.


Generating C bindings
=====================

The C bindings for the core protocol and all the currently supported
extensions are built as part of the xcb build system.  However, for the
purposes of creating and debugging new protocol descriptions, it can be useful
to generate the bindings directly by invoking c-client.xsl to the XML protocol
description.

You must provide several parameters to c-client.xsl:

mode: header or source; specifies which part of the C bindings to generate.
base-path: path to the core X protocol descriptions.
extension-path: path to the extension descriptions.

For example, using xsltproc, you can generate the header for a protocol
description "protocol.xml" with the command:

xsltproc --stringparam base-path /path/to/xcb-proto/src \
         --stringparam extension-path /path/to/xcb-proto/src/extensions \
         --stringparam mode header /path/to/xcb/src/c-client.xsl protocol.xml


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 xcb_types and 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.

<eventcopy 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, xcb_types, 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 xcb_types, use
type="glx:PIXMAP" rather than type="PIXMAP".

<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.


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 *, /, &amp;, and &lt;&lt;, and
  their semantics are identical to the corresponding operators in C.  The two
  operand expressions may be fieldref, value, or op 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.