diff --git a/doc/protocol/_index.md b/doc/protocol/_index.md index 8f565e4..940d3e0 100644 --- a/doc/protocol/_index.md +++ b/doc/protocol/_index.md @@ -14,7 +14,7 @@ server side, typically a Wayland compositor, is called the **"EIS Implementation This documentation details the protocol to communicate between the client side and the EIS implementation. -A typical Compositor setup using the `libei` and `libeis` [C libraries]({{< relref "libraries" >}}) looks like this: +A typical Compositor setup using the `libei` and `libeis` [C libraries]({{% relref "libraries" %}}) looks like this: {{< mermaid >}} flowchart LR; diff --git a/doc/protocol/doc/ei-scanner.md b/doc/protocol/doc/ei-scanner.md index fa623d1..541c5fe 100644 --- a/doc/protocol/doc/ei-scanner.md +++ b/doc/protocol/doc/ei-scanner.md @@ -10,7 +10,7 @@ weight: 5 In the libei repo, we use the [ei-scanner](https://gitlab.freedesktop.org/libinput/libei/-/blob/main/proto/ei-scanner) to generate bindings for C and Python (for tests) as well the [interface -documentation]({{< relref "interfaces/" >}}) in this documentation. +documentation]({{% relref "interfaces/" %}}) in this documentation. Note: these generated protocol bindings are **not** part of libei's API contract. diff --git a/doc/protocol/doc/initial-handshake.md b/doc/protocol/doc/initial-handshake.md index 428a6a7..bd8ac90 100644 --- a/doc/protocol/doc/initial-handshake.md +++ b/doc/protocol/doc/initial-handshake.md @@ -6,12 +6,12 @@ weight: 4 --- The initial connection is a two-step process: -An [ei_handshake]({{< relref "interfaces/ei_handshake" >}}) object with the special ID 0 is guaranteed to +An [ei_handshake]({{% relref "interfaces/ei_handshake" %}}) object with the special ID 0 is guaranteed to exists. The client must send the appropriate requests to set up its connection, followed by the `ei_handshake.finish` request. The EIS -implementation replies by creating the [ei_connection]({{< relref "interfaces/ei_connection" >}}) object with the +implementation replies by creating the [ei_connection]({{% relref "interfaces/ei_connection" %}}) object with the client-requested version (or any lower version) that is the connection for the -remainder of this client (see [version negotiation]({{< relref "doc/specification#version-negotiation" >}}). +remainder of this client (see [version negotiation]({{% relref "doc/specification#version-negotiation" %}}). Immediately after connecting, the EIS implementation must send the `ei_handshake.handshake_version` event. The client replies with the diff --git a/doc/protocol/doc/overview.md b/doc/protocol/doc/overview.md index fe94bdb..2da65e4 100644 --- a/doc/protocol/doc/overview.md +++ b/doc/protocol/doc/overview.md @@ -31,10 +31,10 @@ flowchart LR; {{< /mermaid >}} Objects are identified by a unique object ID, assigned at creation of the object. -The type of an object is defined by its [interface]({{< relref "interfaces" >}}) +The type of an object is defined by its [interface]({{% relref "interfaces" %}}) and agreed on at object creation. Each object has exactly one interface, but there may be multiple objects with that interface. For example, a compositor -may create multiple objects with the [`ei_device`]({{< relref "interfaces/ei_device" >}}) +may create multiple objects with the [`ei_device`]({{% relref "interfaces/ei_device" %}}) interface. All data on the protocol (e.g. object IDs) is private to that client's @@ -57,7 +57,7 @@ content: |object-id |length |opcode |... Where: - `object-id` is one 64-bit unsigned integer that uniquely identifies the object sending the request/event. The `object-id` - 0 is reserved for the special [`ei_handshake`]({{< relref "interfaces/ei_handshake" >}}) object. + 0 is reserved for the special [`ei_handshake`]({{% relref "interfaces/ei_handshake" %}}) object. - `length` is a 32-bit integer that specifies the length of the message in bytes, including the 16 header bytes for `object-id`, `length` and `opcode`. - `opcode` is a 32-bit integer that specifies the event or request-specific diff --git a/doc/protocol/doc/specification.md b/doc/protocol/doc/specification.md index e19ea36..efda14b 100644 --- a/doc/protocol/doc/specification.md +++ b/doc/protocol/doc/specification.md @@ -9,7 +9,7 @@ The current protocol specification is available [in XML format here](https://git In that protocol specification: -- a request or event with the XML attribute `type="destructor"` marks the message as [destructor]({{< relref "#destructors" >}}). +- a request or event with the XML attribute `type="destructor"` marks the message as [destructor]({{% relref "#destructors" %}}). - an argument with an XML attribute `enum` carries a value of the corresponding enum - an argument with an XML attribute `interface` attribute indicates that an object in the same message is of that interface type diff --git a/doc/protocol/doc/types.md b/doc/protocol/doc/types.md index a11f1ed..4d96497 100644 --- a/doc/protocol/doc/types.md +++ b/doc/protocol/doc/types.md @@ -20,9 +20,9 @@ All types are encoded in the EIS implementation's native byte order. | int64 | 64 | signed integer | `int64_t` | | | float | 32 | IEEE-754 float | `float` | | | fd | 0 | file descriptor | `int` | see [^1] | -| string | 32 + N| length + string | `int`, `char[]` | see [String Encoding]({{< ref "#string-encoding" >}}) | -| new_id | 64 | object id allocated by the caller | `uint64_t` | see [Object IDs]({{< ref "#object-ids" >}}) | -| object_id | 64 | previously allocated object id | `uint64_t` | see [Object IDs]({{< ref "#object-ids" >}}) | +| string | 32 + N| length + string | `int`, `char[]` | see [String Encoding]({{% ref "#string-encoding" %}}) | +| new_id | 64 | object id allocated by the caller | `uint64_t` | see [Object IDs]({{% ref "#object-ids" %}}) | +| object_id | 64 | previously allocated object id | `uint64_t` | see [Object IDs]({{% ref "#object-ids" %}}) | [^1]: zero bytes in the message itself, transmitted in the overhead