From 999225c17a6ee23d5b5171b80b5158f93beb7abc Mon Sep 17 00:00:00 2001 From: Auke Booij Date: Mon, 26 Oct 2015 12:16:31 +0000 Subject: [PATCH] doc: document the enum and bitfield attributes Introduce the enum and bitfield attributes, which allow you to refer to the enum you are expecting in an argument, and specify which enums are to be thought of as bitfields. Changes since v3: - Fix typo ("description" -> "descriptive") Signed-off-by: Auke Booij Reviewed-by: Nils Chr. Brause Reviewed-by: Bryce Harrington --- doc/publican/sources/Protocol.xml | 41 ++++++++++++++++++++++++++----- 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/doc/publican/sources/Protocol.xml b/doc/publican/sources/Protocol.xml index 477063be..66cebfb6 100644 --- a/doc/publican/sources/Protocol.xml +++ b/doc/publican/sources/Protocol.xml @@ -14,6 +14,38 @@ object implements an interface and the requests include an opcode that identifies which method in the interface to invoke. + + The protocol is message-based. A message sent by a client to the server + is called request. A message from the server to a client is called event. + A message has a number of arguments, each of which has a certain type (see + for a list of argument types). + + + Additionally, the protocol can specify enums which associate + names to specific numeric enumeration values. These are primarily just + descriptive in nature: at the wire format level enums are just integers. + But they also serve a secondary purpose to enhance type safety or + otherwise add context for use in language bindings or other such code. + This latter usage is only supported so long as code written before these + attributes were introduced still works after; in other words, adding an + enum should not break API, otherwise it puts backwards compatibility at + risk. + + + enums can be defined as just a set of integers, or as + bitfields. This is specified via the bitfield boolean + attribute in the enum definition. If this attribute is true, + the enum is intended to be accessed primarily using bitwise operations, + for example when arbitrarily many choices of the enum can be ORed + together; if it is false, or the attribute is omitted, then the enum + arguments are a just a sequence of numerical values. + + + The enum attribute can be used on either uint + or int arguments, however if the enum is + defined as a bitfield, it can only be used on + uint args. + The server sends back events to the client, each event is emitted from an object. Events can be error conditions. The event includes the @@ -62,14 +94,11 @@ The protocol is sent over a UNIX domain stream socket, where the endpoint usually is named wayland-0 (although it can be changed via WAYLAND_DISPLAY - in the environment). The protocol is message-based. A - message sent by a client to the server is called request. A message - from the server to a client is called event. Every message is - structured as 32-bit words, values are represented in the host's - byte-order. + in the environment). - The message header has 2 words in it: + Every message is structured as 32-bit words; values are represented in the + host's byte-order. The message header has 2 words in it: