From 95c6014a7f93538f064cafe68d31a5e188809f03 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Tue, 30 Dec 2025 14:59:27 +0200 Subject: [PATCH] doc: document the Wayland XML dialect Document the XML tags used to describe Wayland protocols. Previously we only had the informal specification in the Protocol chapter, and the DTD. Better late than never. I have looked into wayland-scanner and libwayland for various limitations documented here possibly for the first time. I have also forbid things that are not in use or are known broken, including unspecified interface for a new_id in an event, or an object argument with an unspecified interface. I did investigate writing a RELAX NG compact schema for Wayland and documenting everything there, then generating DocBook XML from it. However, it seems generating documentation from schema is actually really complicated. I found these tools: - xs3p stylesheet: website looks dead, though Sourceforge still has it. Produces XHTML, not DocBook. Has an unfamiliar license. - xsddoc: the authors wrote that XSLT is not really sufficient, so they abandoned this approach and went for Java to create xnsdoc. - xnsdoc: seems to be proprietary licensed, although one could ask for a free license for a FLOSS project. All in all, it seems to be much easier to just write the documentation in DocBook, copying the strcture from the DTD manually, than to generate it. It's not doing to change often, anyway. It also allowed me to leverage DocBook syntax in full. Signed-off-by: Pekka Paalanen Signed-off-by: Pekka Paalanen --- doc/publican/Message_XML.xml | 928 +++++++++++++++++++++++++++++++++++ doc/publican/Wayland.xml | 1 + doc/publican/meson.build | 1 + 3 files changed, 930 insertions(+) create mode 100644 doc/publican/Message_XML.xml diff --git a/doc/publican/Message_XML.xml b/doc/publican/Message_XML.xml new file mode 100644 index 00000000..0188eead --- /dev/null +++ b/doc/publican/Message_XML.xml @@ -0,0 +1,928 @@ + + +%BOOK_ENTITIES; + +protocol"> +copyright"> +description"> +interface"> +enum"> +entry"> +request"> +event"> +arg"> + + + +]> + + + Message Definition Language + +
+ Overview + + + The fundamentals of the Wayland protocol are explained in + . This chapter formally defines the + language used to define Wayland protocols. + + + Wayland is an object-oriented protocol. Each object follows exactly + one interface. An interface is a collection of message and enumeration + definitions. A message can be either a request (sent by a client) + or an event (sent by a server). A message can have arguments. + All arguments are typed. + +
+ +
+ XML Elements + +
+ protocol + + protocol ::= (©right;?, &description;? &interface;+) + + + protocol is the root element in a Wayland protocol XML file. + Code generation tools may optionally use the protocol + name in API symbol names. The XML file name should be + similar to the protocol name. + + + The &description; element should be used to document the intended + purpose of the protocol, give an overview, and give any development + stage notices if applicable. + + + The ©right; element should be used to indicate the copyrights and + the license of the XML file. + + + + Required attributes + + + + name="cname" + + + + The name of the protocol (a.k.a protocol extension). + &cname-requirements; + + + The name should be globally unique. Protocols to be included in + wayland-protocols + must follow the naming rules set there. Other protocols should use + a unique prefix for the name, e.g. referring to the owning project's + name. + + + + +
+ + + +
+ description + + + Parent elements: &protocol;, &interface;, &request;, &event;, + &arg;, &enum;, &entry; + + + description ::= #PCDATA + + + Contains human-readable documentation for its parent element. + May contain formatted text, including paragraphs and bulleted + lists. + + + + Optional attributes + + + + summary="summary" + + + + A short (half a line at most) description of the documented + element. + + + When a &description; element is used, it is recommended to + not use the summary attribute of the parent + element. + + + + +
+ +
+ interface + + + Parent elements: &protocol; + + + interface ::= (&description;?, (&request;|&event;|&enum;)+) + + + An interface element contains the &request;s and &event;s that form the + interface. Enumerations can also be defined with &enum; elements. + These all belong into the namespace of the interface. Code generation + tools may use the interface name in API symbol names. + + + Interfaces form an ancestry tree. Aside from + , new protocol objects are + always created through an existing protocol object that may be referred to + as the factory object. + This can happen in one of two ways: the factory object's interface either + defines or does not define the new object's interface. + + + When the factory interface defines the new object's interface, the new + object also inherits the factory object's interface version number. + This number defines the interface version of the new object. + The factory object is referred to as + the parent object and the factory interface is + referred to as the parent interface. This + forms the ancestry tree of interfaces. + + + When the factory interface does not define the new object's interface, + both the interface name and the version must be communicated explicitly. + The foremost example of this is + . + In this case the terms "parent" or "ancestor" are not used. Interfaces + that are advertised through + are called global interfaces, or globals for short. + + + If objects having the interface can cause protocol errors, the protocol + error codes must be defined within the interface with an &enum; + element with its name set to "error". + Protocol error codes are always specific to the interface of the object + referred to in . + + + The &description; element should be used to describe the purpose and + the general usage of the interface. + + + + Required attributes + + + + name="cname" + + + + The name of the interface. &cname-requirements; + The name must be unique in the &protocol;, and preferably it should + also be globally unique to avoid API conflicts in language bindings + of multiple protocols. + + + Protocols to be included in + wayland-protocols + must follow the interface naming rules set there. Other protocols + should use a unique prefix for the name, e.g. referring to the owning + project's name. + + + + + + version="V" + + + + The interface's latest version number V must + be an integer greater than zero. An interface element defines + all versions of the interface from 1 to V + inclusive. The contents of each interface version are defined in each of + the &request;, &event;, &enum; and &entry; elements using the attributes + since and deprecated-since, and + in the specification text. + + + When an interface is extended, the version number must be incremented + on all the interfaces part of the same interface ancestry tree. + The exception to this rule are interfaces which are forever stuck + to version 1, which is usually caused by having multiple parent + interfaces with independent ancestor global interfaces. + + + A protocol object may have any defined version of the interface. + The version of the object is determined at runtime either + by inheritance from another protocol object or explicitly. + + + It is possible for a protocol object to have a version higher than + defined by its interface. This may happen when the interface is + stuck at version 1 as per above. It may also happen when a protocol + XML file has not been thoroughly updated as required. In such cases + the object shall function as with the highest defined interface + version. + + + + +
+ +
+ request + + + Parent elements: &interface; + + + request ::= (&description;?, &arg;*) + + + Defines a request, a message from a client to a server. + Requests are always associated with a specific protocol object. + + + Requests are automatically assigned opcodes in the order they + appear inside the &interface; element. Therefore the only + backwards-compatible way to add requests to an interface is to + add them to the end. Any &event; elements do not interfere + with request opcode assignments. + + + The &arg; elements declare the request's arguments. + There can be 0 to 20 arguments for a request. + The order of &arg; inside the request element defines the order of + the arguments on the wire. All declared arguments are mandatory, + and extra arguments are not allowed on the wire. + + + The &description; element should be used to document the request. + + + + Required attributes + + + + name="cname" + + + + The name of the request. &cname-requirements; + The name must be unique within all requests and &event;s in the + containing &interface;. + + + Code and language binding generators may use the name in the API + they create. The name of the containing + &interface; provides the namespace for requests. + + + + + + + Optional attributes + + + + type="destructor" + + + + When this attribute is present, the request is a destructor: + it shall destroy the protocol object it is sent on. Protocol IPC + libraries may use this for bookkeeping protocol object lifetimes. + + + Libwayland-client uses this information to ignore incoming &event;s + for destroyed protocol objects. Such events may occur due to a + natural race condition between the client destroying a protocol + object and the server sending events before processing the + destroy request. + + + + + + since="S" + + + + S must be an integer greater than zero. + If since is not specified, + since="1" is assumed. + + + This request was added in &interface; version + S. The request does not exist if the + protocol object has a bound version smaller than + S. Attempts to use it in such a case + shall raise the protocol error + wl_display.error.invalid_method. + + + + + + deprecated-since="D" + + + + D must be an integer greater than the + value of since. + If deprecated-since is not specified, then + the request is not deprecated in any version of the containing + &interface;. + + + This request was deprecated in &interface; version + D and above, and should not be sent on + protocol objects of such version. This is informational. + Compositors must still be prepared to handle the + request unless specified otherwise. + + + + +
+ +
+ event + + + Parent elements: &interface; + + + event ::= (&description;?, &arg;*) + + + Defines an event, a message from a server to a client. + Events are always associated with a specific protocol object. + + + Events are automatically assigned opcodes in the order they + appear inside the &interface; element. Therefore the only + backwards-compatible way to add events to an interface is to + add them to the end. Any &request; elements do not interfere + with event opcode assignments. + + + The &arg; elements declare the event's arguments. + There can be 0 to 20 arguments for an event. + The order of &arg; inside the event element defines the order of + the arguments on the wire. All declared arguments are mandatory, + and extra arguments are not allowed on the wire. + + + The &description; element should be used to document the event. + + + + Required attributes + + + + name="cname" + + + + The name of the event. &cname-requirements; + The name must be unique within all &request;s and events in the + containing &interface;. + + + Code and language binding generators may use the name in the API + they create. The name of the containing + &interface; provides the namespace for events. + + + + + + + Optional attributes + + + + type="destructor" + + + + When this attribute is present, the event is a destructor: + it shall destroy the protocol object it is sent on. Protocol IPC + libraries may use this for bookkeeping protocol object lifetimes. + + + + Destructor events are an underdeveloped feature in Wayland. + They can be used only on client-created protocol objects, and + it is the protocol designer's responsibility + to design such a message exchange that race conditions cannot + occur. The main problem would be a client sending a request at the + same time as the server is sending a destructor event. The + server will consider the protocol object to be already invalid + or even recycled when it proceeds to process the request. + This often results in protocol errors, but under specific + conditions it might also result in silently incorrect behavior. + + + Destructor events should not be used in new protocols. + If a destructor event is necessary, the simplest way to avoid + these problems is to have the &interface; not contain any + &request;s. + + + + + + + since="S" + + + + S must be an integer greater than zero. + If since is not specified, + since="1" is assumed. + + + This event was added in &interface; version + S. The event does not exist if the + protocol object has a bound version smaller than + S. + + + + + + deprecated-since="D" + + + + D must be an integer greater than the + value of since. + If deprecated-since is not specified, then + the event is not deprecated in any version of the containing + &interface;. + + + This event was deprecated in &interface; version + D and above, and should not be sent on + protocol objects of such version. This is informational. + Clients must still be prepared to receive this event + unless otherwise specified. + + + + +
+ +
+ arg + + + Parent elements: &request;, &event; + + + arg ::= &description;? + + + This element declares one argument for the request or the event. + + + + Required attributes + + + + name="cname" + + + + The name of the argument. &cname-requirements; + The name must be unique within all the arguments of the parent element. + + + + + + type="T" + + + + The type T of the argument datum must + be one of: + + + + int + + 32-bit signed integer. + + + + uint + + 32-bit unsigned integer. + + + + fixed + + Signed 24.8-bit fixed-point value. + + + + string + + + UTF-8 encoded string value, NUL byte terminated. + Interior NUL bytes are not allowed. + + + + + array + + A byte array of arbitrary data. + + + + fd + + A file descriptor. + + The file descriptor must be open and valid on send. + It is not possible to pass a null value. + + + + + new_id + + + Creates a new protocol object. A &request; or an &event; may + have at most one new_id argument. + + + If interface is specified, the new + protocol object shall have the specified &interface;, + and the new object's (interface) version shall be the + version of the object on which the &request; or &event; + is being sent. + + + If interface is not specified, the + &request; shall implicitly have two additional arguments: + A string for an &interface; name, and + a uint for the new object's version. + Leaving the interface unspecified is reserved for special use, + + for example. + + + + An &event; argument must always specify the + new_id interface. + + + + + + object + + Reference to an existing protocol object. + + The attribute interface should be + specified. Otherwise IPC libraries cannot enforce the + interface, and checking the interface falls on user code + and specification text. + + + + + + + + + + Optional attributes + + + + summary="summary" + + + + A short (half a line at most) description. This attribute + should not be used if a &description; is used. + + + + + + interface="iface" + + + + If given, iface must be the + name of some &interface;, and + type of this argument must be either + "object" or "new_id". + This indicates that the existing or new object must have + the interface iface. + Use for other argument types is forbidden. + + + + If an interface from another protocol is used, then this + creates a dependency between the protocols. If an application + generates code for one protocol, then it must also generate + code for all dependencies. Therefore this would not be a + backwards compatible change. + + + + + + + allow-null="true" | "false" + + + + Whether the argument value can be null on send. + Defaults to "false", meaning it is illegal + to send a null value. + Can be used only when type is + "string" or "object". + + + + Even though this attribute can be used to forbid a compositor + from sending a null object as an event argument, an IPC library + implementation may not protect the client from receiving a null + object. This can happen with libwayland-client when the client + has destroyed the protocol object before dispatching an event + that referred to it in an argument. + + + + + + + enum="enum-cname-suffix" + + + + If specified, indicates that the argument value should come from the + &enum; named enum-cname-suffix. If the + enumeration is a bitfield, then type must be + "uint". Otherwise type must + be either "uint" or "int". + + + The name enum-cname-suffix refers to an &enum; + in the same &interface; by default. If it is necessary to refer to an + enumeration from another interface, the interface name can be + given with a period: + enum="iface.enum-cname-suffix" + + + + This attribute alone does not automatically restrict the legal + values for this argument. + If values from outside of the enumeration need to be forbidden, + that must be specified explicitly in the documentation. + + + A common design pattern is to have the server advertise the + supported enumeration or bit values with &event;s and + explicitly forbid clients from using any other values in + requests. This also requires a protocol error code to be + specified with the error &enum; to be raised if a client + uses an illegal value, see + . + + + + + +
+ +
+ enum + + + Parent elements: &protocol; + + + enum ::= (&description;?, &entry;*) + + + This tag defines an enumeration of integer values. Enumerations are + merely a syntactic construct to give names to arbitrary integer + constants. Each constant is listed as an &entry; with its name. + There are two types of enumerations: regular enumerations and bitfields. + + + Regular enumerations do not use bitfield + attribute, or they set it to "false". + The set of pre-defined values that belong to a regular enumeration is + exactly the set of values listed as &entry; elements after + the protocol object version is taken into account. + See the &entry; attributes since and + deprecated-since. + + + Bitfields set bitfield to + "true". The set of values that belong to a + bitfield enumeration are all the values that can be formed by + the bitwise-or operator from the set of values listed as &entry; + elements like in the regular enumeration. Usually also zero is + implicitly included. + + + All the values in a regular enumeration must be either + signed or unsigned 32-bit integers. All the values in a + bitfield enumeration must be unsigned 32-bit integers. + + + + Required attributes + + + + name="cname-suffix" + + + + The name of the enumeration. &cname-suffix-requirements; + The name must be unique within all enumerations in the containing + &interface;. The name is used as the namespace for all the + contained &entry; elements. + + + + + + + Optional attributes + + + + since="S" + + + + S must be an integer greater than zero. + If since is not specified, + since="1" is assumed. + + + This enumeration was added in &interface; version + S. The enumeration does not exist if the + protocol object has a bound version smaller than + S. + + + + + + bitfield="true" | "false" + + + + Specifies if this enumeration is a bitfield. + Defaults to "false". + + + + +
+ +
+ entry + + + Parent elements: &enum; + + + entry ::= &description;? + + + Defines a name for an integer constant and makes it part of the + set of values of the containing enumeration. + + + + Required attributes + + + + name="cname-suffix" + + + + The name of a value in an enumeration. &cname-suffix-requirements; + The name must be unique within all entry elements in the containing + &enum;. + + + + + + value="V" + + + + An integer value. + The value can be given in decimal, hexadecimal, or octal + representation. + + + + + + + Optional attributes + + + + summary="summary" + + + + A short (half a line at most) description. This attribute + should not be used if a &description; is used. + + + + + + since="S" + + + + S must be an integer greater than zero. + If since is not specified, + since="1" is assumed. + + + This value was added in &interface; version + S. + + + + + + deprecated-since="D" + + + + D must be an integer greater than the + value of since. + If deprecated-since is not specified, then + the value is not deprecated in any version of the containing + &interface;. + + + This value was removed in &interface; version + D. This does not make the value + automatically illegal to use, see + attribute + enum. + + + + +
+
+ diff --git a/doc/publican/Wayland.xml b/doc/publican/Wayland.xml index f02a97fc..049a35f9 100644 --- a/doc/publican/Wayland.xml +++ b/doc/publican/Wayland.xml @@ -10,6 +10,7 @@ + diff --git a/doc/publican/meson.build b/doc/publican/meson.build index fb730f5f..2cb95b96 100644 --- a/doc/publican/meson.build +++ b/doc/publican/meson.build @@ -19,6 +19,7 @@ foreach src : files([ 'Color.xml', 'Client.xml', 'Server.xml', + 'Message_XML.xml', ]) name = fs.name(src) publican_inputs += fs.copyfile(name)