Ergot vs Wayland

[titaniumtraveler]

A Short Wayland Into

Messages

(See Wire Format)

Messages have a header of

struct Message {
  header: struct {
    sender_object_id: u32,
    message_len:      u16, // includes the header
    operation_code:   u16,
  },
  arguments: [u8; message_len - size_of(header)],
}

Arguments are 32bit padded bytes which types are defined implicitly by the object id.

Messages from server (compositor) to client are called events.
Messages from client to server are called requests.

Datatypes

(Copied here from the spec as reference)

Type	Description
int, uint	The value is the 32-bit value of the signed/unsigned int.
fixed	Signed 24.8 decimal numbers. It is a signed decimal type which offers a sign bit, 23 bits of integer precision and 8 bits of decimal precision. This is exposed as an opaque struct with conversion helpers to and from double and int on the C API side.
string	Starts with an unsigned 32-bit length (including null terminator), followed by the UTF-8 encoded string contents, including terminating null byte, then padding to a 32-bit boundary. A null value is represented with a length of 0. Interior null bytes are not permitted.
object	32-bit object ID. A null value is represented with an ID of 0.
new_id	The 32-bit object ID. Generally, the interface used for the new object is inferred from the xml, but in the case where it's not specified, a new_id is preceded by a string specifying the interface name, and a uint specifying the version.
array	Starts with 32-bit array size in bytes, followed by the array contents verbatim, and finally padding to a 32-bit boundary.
fd	The file descriptor is not stored in the message buffer, but in the ancillary data of the UNIX domain socket message (msg_control).

Interfaces

Interfaces are defined as xml grouped into a "protocol", with the bindings
usually being generated by tools.
As an example, here the interface definition of wl_display from the core
wayland protocol:

(Human readable version, Source XML)

<?xml version="1.0" encoding="UTF-8"?>
<protocol name="wayland">
  <interface name="wl_display" version="1">
    <description summary="core global object">
      The core global object.  This is a special singleton object.  It
      is used for internal Wayland protocol features.
    </description>

    <request name="sync">
      <description summary="asynchronous roundtrip">
	The sync request asks the server to emit the 'done' event
	on the returned wl_callback object.  Since requests are
	handled in-order and events are delivered in-order, this can
	be used as a barrier to ensure all previous requests and the
	resulting events have been handled.

	The object returned by this request will be destroyed by the
	compositor after the callback is fired and as such the client must not
	attempt to use it after that point.

	The callback_data passed in the callback is undefined and should be ignored.
      </description>
      <arg name="callback" type="new_id" interface="wl_callback"
	   summary="callback object for the sync request"/>
    </request>

    <request name="get_registry">
      <description summary="get global registry object">
	This request creates a registry object that allows the client
	to list and bind the global objects available from the
	compositor.

	It should be noted that the server side resources consumed in
	response to a get_registry request can only be released when the
	client disconnects, not when the client side proxy is destroyed.
	Therefore, clients should invoke get_registry as infrequently as
	possible to avoid wasting memory.
      </description>
      <arg name="registry" type="new_id" interface="wl_registry"
	   summary="global registry object"/>
    </request>

    <event name="error">
      <description summary="fatal error event">
	The error event is sent out when a fatal (non-recoverable)
	error has occurred.  The object_id argument is the object
	where the error occurred, most often in response to a request
	to that object.  The code identifies the error and is defined
	by the object interface.  As such, each interface defines its
	own set of error codes.  The message is a brief description
	of the error, for (debugging) convenience.
      </description>
      <arg name="object_id" type="object" summary="object where the error occurred"/>
      <arg name="code" type="uint" summary="error code"/>
      <arg name="message" type="string" summary="error description"/>
    </event>

    <enum name="error">
      <description summary="global error values">
	These errors are global and can be emitted in response to any
	server request.
      </description>
      <entry name="invalid_object" value="0"
	     summary="server couldn't find object"/>
      <entry name="invalid_method" value="1"
	     summary="method doesn't exist on the specified interface or malformed request"/>
      <entry name="no_memory" value="2"
	     summary="server is out of memory"/>
      <entry name="implementation" value="3"
	     summary="implementation error in compositor"/>
    </enum>

    <event name="delete_id">
      <description summary="acknowledge object ID deletion">
	This event is used internally by the object ID management
	logic. When a client deletes an object that it had created,
	the server will send this event to acknowledge that it has
	seen the delete request. When the client receives this event,
	it will know that it can safely reuse the object ID.
      </description>
      <arg name="id" type="uint" summary="deleted object ID"/>
    </event>
  </interface>
  ...
</protocol>

Message flow/Main Protocol concepts

A session usually consist of:

• client connects to socket
• client sends a <object_id(1) as wl_display>::get_registry(registry: new_id<wl_registry>(2)) request to the server
• the server starts sending wl_registry::global events with the globals of the interfaces it supports (for example wl_compositor to create new wl_surfaces that then later can be rendered to)
• the client does its rendering and stuff from here ...

If the client needs synchronize until a certain message is processed,
it can just create a wl_callback via wl_display::callback() and wait on the wl_callback::done event.

Note that in almost all cases the client is responsible to create all
resources that the server should manage and that those resource are often local
to the client.
For example:

• The object IDs are allocated by the client and are only valid for that specific
  connection. So a nested compositor that is a client in the outer compositor,
  has completely independent IDs, so the nested compositor has to translate the
  inner IDs to the outer IDs.
• Any rendering buffers are allocated by the client.

Comparison to ergot/Ideas that might be worth stealing

Addressing

Waylands object ids are capability-based, while ergot are device-based.
For a protocol for multi-device networks like ergot is, being explicitly
device-based is probably the better decision, but for highly dynamic networks it
might be useful to allocate a address (or maybe even a whole segment_id?) to
some "capability".

Lets say we have a standard interface that lets you open a TCP connection to the
outer internet, and have a smartphone and a normal internet router in the
ergot network. It would be useful to just make a call to that address and a
"capability router" then decides through which device the request actually goes.

Codegen

It might be useful to (in the future) have some "external" format that defines the interface of a
endpoint, which then also could be used to generate bindings in other languages.

In wayland the C bindings are generated with a program called wayland-scanner
and the wayland-rs implementation uses its own implementation using proc-macros.

Address translation

When a network segment leader temporarily looses connection needs to manage the network/a subnetwork, and flushing + reassigning the device addresses isn't an option at that point;
It might be useful to translate the inner and outer addresses of messages
going through the router.

That would basically be done in the way wayland does the translation with a
simple lookup table. Or I guess in IP where a router might translate MAC
addresses.

A potential problem with that, that could come up if a device is connected via
multiple sockets to the network, is that the local addresses the device has
might vary.

Possible resolutions to that would be to either have the addresses be scoped to
the socket inside the device, or to have a request that it can send to ask the
network leader what its address is. When there are different answers, the device
should have a clear resolution strategy of who the real leader is and also send
that information to the device that thinks it is the leader.

[titaniumtraveler]

Wow. That got longer than I expected. I hope it is useful. (In any case thinking about this topic definitely was useful for me)