fdo-mirrors/libei
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/libinput/libei.git synced 2026-04-20 05:00:38 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

proto: add a device ready request

Browse source 
The protocol currently supports a ei_device.done event to notify
the ei client that the initial description of the device is complete.
For some future use-cases the client may need to futher negotiate
properties of the device. For example for tablet tools the client may
narrow down capabilities of the tool.

The sequence with the new request is thus e.g.
     -> ei_seat.device
     -> ei_device.name
     -> ei_device.interface
     -> ei_device.interface
     -> ei_device.done
     <- ei_device.ready
     -> ei_device.resumed

In libei the request is sent automatically on unref of
the DEVICE_ADDED event. This makes clients immediately compatible
and for the typical (future) use-case of device configuration. Said
configuration will likely be handled in response to the DEVICE_ADDED
event anyway.

In libeis, a new EIS_EVENT_DEVICE_READY event that is sent when the client
sends that same event on the protocol, informing the EIS implementation
that this device is ready. For clients that do not support that version
the event is emulated immediately after sending ei_device.done.

This requires a flag bit to be long-term maintainable. The typical
EIS implementation currently calls eis_device_add() immediately
followed by eis_device_resume(). This doesn't leave any room to
wait for the client's ei_device.ready request.

One backwards-compatible solution could be to buffer the
eis_device_resume() until the ei_device.ready has been received but this
is fraught with hairy corner cases, e.g. if the client is a receiver
context we would also have to buffer all events immediately sent to the
client.

So instead, we have a flag in the context and if set by the caller, we
change the internal behavior to match ei_device interface version 3.

Part-of: <https://gitlab.freedesktop.org/libinput/libei/-/merge_requests/346>
This commit is contained in:
Peter Hutterer 2025-07-11 09:47:50 +10:00
parent 7141566924
commit 39a222868f
13 changed files with 226 additions and 5 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

24
proto/protocol.xml
View file

@ -544,7 +544,7 @@
</event>
</interface>
<interface name="ei_device" version="2">
<interface name="ei_device" version="3">
<description summary="logical input device">
An ei_device represents a single logical input device. Like physical input
devices an ei_device may have multiple capabilities and may e.g. function
@ -635,6 +635,28 @@
<arg name="timestamp" type="uint64" summary="timestamp in microseconds"/>
</request>
<!-- ei_device client requests version 2 -->
<!-- space intentionally left blank -->
<!-- ei_device client requests version 3 -->
<request name="ready" since="3" context-type="sender">
<description summary="Device ready notification">
Notification by the client that the device configuration (as seen
by the protocol) is complete and the EIS implementation may
send ei_device.resumed.
This allows for future further negotation of the device behavior and
or device properties before the device is finalized by the EIS implementation.
A client supporting version 3 of the ei_device interface must issue
this request in response to the ei_device.done event.
It is a protocol violation to send this event more than once per device.
</description>
</request>
<!-- ei_device events version 1 -->
<event name="destroyed" type="destructor" since="1">

7
src/libei-event.c
View file

@ -73,12 +73,13 @@ ei_event_type_to_string(enum ei_event_type type)
static void
ei_event_destroy(struct ei_event *event)
{
struct ei *ei = ei_event_get_context(event);
switch (event->type) {
case EI_EVENT_CONNECT:
case EI_EVENT_DISCONNECT:
case EI_EVENT_SEAT_ADDED:
case EI_EVENT_SEAT_REMOVED:
case EI_EVENT_DEVICE_ADDED:
case EI_EVENT_DEVICE_REMOVED:
case EI_EVENT_DEVICE_PAUSED:
case EI_EVENT_DEVICE_RESUMED:
@ -98,6 +99,10 @@ ei_event_destroy(struct ei_event *event)
case EI_EVENT_TOUCH_UP:
case EI_EVENT_TOUCH_MOTION:
break;
case EI_EVENT_DEVICE_ADDED:
if (ei->interface_versions.ei_device >= EI_DEVICE_REQUEST_READY_SINCE_VERSION)
ei_device_request_ready(event->device);
break;
case EI_EVENT_PONG:
ei_ping_unref(event->pong.ping);
break;

2
src/libei.c
View file

@ -127,7 +127,7 @@ ei_create_context(bool is_sender, void *user_data)
.ei_callback = VERSION_V(1),
.ei_pingpong = VERSION_V(1),
.ei_seat = VERSION_V(1),
.ei_device = VERSION_V(2),
.ei_device = VERSION_V(3),
.ei_pointer = VERSION_V(1),
.ei_pointer_absolute = VERSION_V(1),
.ei_scroll = VERSION_V(1),

2
src/libeis-client.c
View file

@ -522,7 +522,7 @@ eis_client_new(struct eis *eis, int fd)
.ei_callback = VERSION_V(1),
.ei_pingpong = VERSION_V(1),
.ei_seat = VERSION_V(1),
.ei_device = VERSION_V(2),
.ei_device = flag_is_set(eis->flags, EIS_FLAG_DEVICE_READY) ? VERSION_V(3) : VERSION_V(2),
.ei_pointer = VERSION_V(1),
.ei_pointer_absolute = VERSION_V(1),
.ei_scroll = VERSION_V(1),

37
src/libeis-device.c
View file

@ -257,6 +257,7 @@ client_msg_start_emulating(struct eis_device *device, uint32_t serial, uint32_t
case EIS_DEVICE_STATE_DEAD:
case EIS_DEVICE_STATE_CLOSED_BY_CLIENT:
case EIS_DEVICE_STATE_NEW:
case EIS_DEVICE_STATE_AWAITING_READY:
case EIS_DEVICE_STATE_EMULATING:
result = brei_result_new(EIS_CONNECTION_DISCONNECT_REASON_PROTOCOL,
"Invalid device state %u for a start_emulating event", device->state);
@ -286,6 +287,7 @@ client_msg_stop_emulating(struct eis_device *device, uint32_t serial)
case EIS_DEVICE_STATE_DEAD:
case EIS_DEVICE_STATE_CLOSED_BY_CLIENT:
case EIS_DEVICE_STATE_NEW:
case EIS_DEVICE_STATE_AWAITING_READY:
case EIS_DEVICE_STATE_RESUMED:
result = brei_result_new(EIS_CONNECTION_DISCONNECT_REASON_PROTOCOL,
"Invalid device state %u for a stop_emulating event", device->state);
@ -321,6 +323,7 @@ maybe_error_on_device_state(struct eis_device *device, const char *event_type)
case EIS_DEVICE_STATE_EMULATING:
return NULL;
case EIS_DEVICE_STATE_NEW:
case EIS_DEVICE_STATE_AWAITING_READY:
case EIS_DEVICE_STATE_CLOSED_BY_CLIENT:
case EIS_DEVICE_STATE_DEAD:
break;
@ -345,12 +348,25 @@ client_msg_frame(struct eis_device *device, uint32_t serial, uint64_t time)
return maybe_error_on_device_state(device, "frame");
}
static struct brei_result *
client_msg_ready(struct eis_device *device)
{
if (device->state != EIS_DEVICE_STATE_AWAITING_READY)
return brei_result_new(EIS_CONNECTION_DISCONNECT_REASON_PROTOCOL,
"Invalid device state %u for a ready event", device->state);
device->state = EIS_DEVICE_STATE_PAUSED;
eis_queue_device_ready_event(device);
return NULL;
}
static const struct eis_device_interface interface = {
.release = client_msg_release,
.start_emulating = client_msg_start_emulating,
.stop_emulating = client_msg_stop_emulating,
.frame = client_msg_frame,
.ready = client_msg_ready,
};
const struct eis_device_interface *
@ -830,7 +846,7 @@ eis_device_add(struct eis_device *device)
"%s: adding device without capabilities", __func__);
}
device->state = EIS_DEVICE_STATE_PAUSED;
device->state = EIS_DEVICE_STATE_AWAITING_READY;
eis_client_register_object(client, &device->proto_object);
eis_seat_event_device(seat, device->proto_object.id, device->proto_object.version);
int rc = eis_device_event_name(device, device->name);
@ -921,6 +937,16 @@ eis_device_add(struct eis_device *device)
}
rc = eis_device_event_done(device);
if (rc < 0)
goto out;
struct eis *eis = eis_device_get_context(device);
if (client->interface_versions.ei_device < EIS_DEVICE_REQUEST_READY_SINCE_VERSION) {
device->state = EIS_DEVICE_STATE_PAUSED;
if (flag_is_set(eis->flags, EIS_FLAG_DEVICE_READY))
eis_queue_device_ready_event(device);
}
out:
if (rc < 0) {
log_error(eis_client_get_context(client), "Failed to add device, disconnecting client");
@ -1394,6 +1420,9 @@ eis_device_closed_by_client(struct eis_device *device)
if (!eis_client_is_sender(eis_device_get_client(device)))
eis_queue_device_stop_emulating_event(device);
_fallthrough_;
case EIS_DEVICE_STATE_AWAITING_READY:
eis_queue_device_ready_event(device);
_fallthrough_;
case EIS_DEVICE_STATE_NEW:
case EIS_DEVICE_STATE_PAUSED:
case EIS_DEVICE_STATE_RESUMED:
@ -1420,6 +1449,12 @@ eis_device_resume(struct eis_device *device)
{
struct eis_client *client = eis_device_get_client(device);
if (device->state == EIS_DEVICE_STATE_AWAITING_READY) {
log_bug_client(eis_client_get_context(client),
"Attempting to resume a device before DEVICE_READY");
return;
}
if (device->state != EIS_DEVICE_STATE_PAUSED)
return;

1
src/libeis-device.h
View file

@ -32,6 +32,7 @@
enum eis_device_state {
EIS_DEVICE_STATE_NEW,
EIS_DEVICE_STATE_AWAITING_READY,
EIS_DEVICE_STATE_PAUSED,
EIS_DEVICE_STATE_RESUMED,
EIS_DEVICE_STATE_EMULATING,

1
src/libeis-event.c
View file

@ -44,6 +44,7 @@ eis_event_destroy(struct eis_event *event)
case EIS_EVENT_DEVICE_CLOSED:
case EIS_EVENT_DEVICE_START_EMULATING:
case EIS_EVENT_DEVICE_STOP_EMULATING:
case EIS_EVENT_DEVICE_READY:
case EIS_EVENT_BUTTON_BUTTON:
case EIS_EVENT_POINTER_MOTION:
case EIS_EVENT_POINTER_MOTION_ABSOLUTE:

5
src/libeis-private.h
View file

@ -63,6 +63,8 @@ struct eis {
struct sink *sink;
struct list clients;
uint32_t flags;
struct eis_backend_interface backend_interface;
void *backend;
struct list event_queue;
@ -104,6 +106,9 @@ eis_queue_seat_bind_event(struct eis_seat *seat, uint32_t capabilities);
void
eis_queue_device_closed_event(struct eis_device *device);
void
eis_queue_device_ready_event(struct eis_device *device);
void
eis_queue_frame_event(struct eis_device *device, uint64_t time);

26
src/libeis.c
View file

@ -29,6 +29,7 @@
#include <stdio.h>
#include <unistd.h>
#include "util-bits.h"
#include "util-macros.h"
#include "util-object.h"
#include "util-sources.h"
@ -95,6 +96,22 @@ eis_new(void *user_data)
return steal(&eis);
}
_public_ int
eis_set_flag(struct eis *eis, enum eis_flag flag)
{
if (eis->backend) {
log_bug_client(eis, "%s must be called before setting up a backend", __func__);
return -EBUSY;
}
if (flag > EIS_FLAG_DEVICE_READY)
return -EINVAL;
flag_set(eis->flags, flag);
return 0;
}
_public_ int
eis_get_fd(struct eis *eis)
{
@ -121,6 +138,7 @@ eis_event_type_to_string(enum eis_event_type type)
CASE_RETURN_STRING(EIS_EVENT_CLIENT_DISCONNECT);
CASE_RETURN_STRING(EIS_EVENT_SEAT_BIND);
CASE_RETURN_STRING(EIS_EVENT_DEVICE_CLOSED);
CASE_RETURN_STRING(EIS_EVENT_DEVICE_READY);
CASE_RETURN_STRING(EIS_EVENT_PONG);
CASE_RETURN_STRING(EIS_EVENT_SYNC);
CASE_RETURN_STRING(EIS_EVENT_DEVICE_START_EMULATING);
@ -256,6 +274,14 @@ eis_queue_device_closed_event(struct eis_device *device)
eis_queue_event(e);
}
void
eis_queue_device_ready_event(struct eis_device *device)
{
struct eis_event *e = eis_event_new_for_device(device);
e->type = EIS_EVENT_DEVICE_READY;
eis_queue_event(e);
}
void
eis_sync_event_send_done(struct eis_event *e)
{

61
src/libeis.h
View file

@ -272,6 +272,20 @@ enum eis_event_type {
*/
EIS_EVENT_DEVICE_CLOSED,
/**
* The client has completed configuration of the device (if any) and
* the caller may call eis_device_resume().
*
* libei guarantees that this event even if the client
* does not support the underlying protocol.
*
* This event is only generated if the caller has called
* eis_set_flag() with the @ref EIS_FLAG_DEVICE_READY flag.
*
* @since 1.6
*/
EIS_EVENT_DEVICE_READY,
/**
* Returned in response to eis_ping().
*/
@ -398,6 +412,53 @@ eis_event_type_to_string(enum eis_event_type);
struct eis *
eis_new(void *user_data);
/**
* Context flags to enable EIS-specific behaviors.
*
* These flags must be set to take advantage of newer versions
* of the ei protocol. See the documentation for each flag
* for details.
*
* @see eis_set_flag
*
* @since 1.6
*/
enum eis_flag {
/**
* If set, libeis will announce ei_device protocol
* version 3 or later. A compatible client will send
* ei_device.ready in response to ei_device.done. See
* the protocol documentation for details.
*
* If set, after eis_device_add() an EIS implementation must wait
* until the @ref EIS_EVENT_DEVICE_READY has been received for
* that device before calling eis_device_resume().
*/
EIS_FLAG_DEVICE_READY = 1,
};
/**
* Change the behavior of the context according to the
* given flag. See @ref eis_flag for documentation on
* each indidividual flag.
*
* This function must be called before any of eis_setup_backend_fd()
* or eis_setup_backend_socket().
*
* This function may be called multiple times with different flags.
* Some flags may be mutually exclusive, consult the documentation
* on each individual flag for details.
*
* @param eis The EIS context
* @param flag **One** flag (not a bitmask) to set on this context
*
* @return 0 on success or a negative errno on failure
*
* @since 1.6
*/
int
eis_set_flag(struct eis *eis, enum eis_flag flag);
/**
* @ingroup libeis-log
*/

24
test/eierpecken.c
View file

@ -582,18 +582,32 @@ new_context(const char *what, va_list args)
struct peck *peck = peck_create(NULL);
enum peck_ei_mode ei_mode = PECK_EI_SENDER;
uint32_t eis_flags = 0;
while (what) {
if (streq(what, "mode"))
ei_mode = va_arg(args, enum peck_ei_mode);
if (streq(what, "eis-flags"))
eis_flags = va_arg(args, uint32_t);
what = va_arg(args, const char *);
}
assert(ei_mode == PECK_EI_RECEIVER || ei_mode == PECK_EI_SENDER);
int rc, fd;
struct eis *eis = eis_new(peck);
if (eis_flags != 0) {
size_t shift = 0;
while (eis_flags) {
if (eis_flags & 0x1)
eis_set_flag(eis, bit(shift));
eis_flags >>= 1;
shift++;
}
}
eis_log_set_handler(eis, peck_eis_log_handler);
eis_log_set_priority(eis, EIS_LOG_PRIORITY_DEBUG);
eis_clock_set_now_func(eis, peck_eis_now_func);
@ -690,6 +704,7 @@ peck_enable_eis_behavior(struct peck *peck, enum peck_eis_behavior behavior)
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_ACCEPT_CLIENT);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_HANDLE_BIND_SEAT);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_RESUME_DEVICE);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_HANDLE_DEVICE_READY);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_HANDLE_CLOSE_DEVICE);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_HANDLE_START_EMULATING);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_HANDLE_STOP_EMULATING);
@ -710,6 +725,7 @@ peck_enable_eis_behavior(struct peck *peck, enum peck_eis_behavior behavior)
case PECK_EIS_BEHAVIOR_ADD_POINTER_ABSOLUTE:
case PECK_EIS_BEHAVIOR_ADD_KEYBOARD:
case PECK_EIS_BEHAVIOR_ADD_TOUCH:
case PECK_EIS_BEHAVIOR_HANDLE_DEVICE_READY:
flag_set(peck->eis_behavior, behavior);
break;
case PECK_EIS_BEHAVIOR_REJECT_CLIENT:
@ -767,6 +783,7 @@ peck_disable_eis_behavior(struct peck *peck, enum peck_eis_behavior behavior)
case PECK_EIS_BEHAVIOR_ADD_POINTER_ABSOLUTE:
case PECK_EIS_BEHAVIOR_ADD_KEYBOARD:
case PECK_EIS_BEHAVIOR_ADD_TOUCH:
case PECK_EIS_BEHAVIOR_HANDLE_DEVICE_READY:
case PECK_EIS_BEHAVIOR_REJECT_CLIENT:
case PECK_EIS_BEHAVIOR_ACCEPT_CLIENT:
case PECK_EIS_BEHAVIOR_RESUME_DEVICE:
@ -1104,6 +1121,12 @@ _peck_dispatch_eis(struct peck *peck, int lineno)
else
process_event = tristate_no;
break;
case EIS_EVENT_DEVICE_READY:
if (flag_is_set(peck->eis_behavior, PECK_EIS_BEHAVIOR_HANDLE_DEVICE_READY))
process_event = tristate_yes;
else
process_event = tristate_no;
break;
case EIS_EVENT_PONG:
break;
case EIS_EVENT_SYNC:
@ -1659,6 +1682,7 @@ peck_eis_event_type_name(enum eis_event_type type)
CASE_STRING(SYNC);
CASE_STRING(DEVICE_START_EMULATING);
CASE_STRING(DEVICE_STOP_EMULATING);
CASE_STRING(DEVICE_READY);
CASE_STRING(POINTER_MOTION);
CASE_STRING(POINTER_MOTION_ABSOLUTE);
CASE_STRING(BUTTON_BUTTON);

5
test/eierpecken.h
View file

@ -108,6 +108,11 @@ enum peck_eis_behavior {
PECK_EIS_BEHAVIOR_RESUME_DEVICE,
PECK_EIS_BEHAVIOR_SUSPEND_DEVICE,
/**
* Handle device ready events. This behavior is enabled by default.
*/
PECK_EIS_BEHAVIOR_HANDLE_DEVICE_READY,
};
enum peck_ei_behavior {

36
test/test-eis.c
View file

@ -505,6 +505,42 @@ MUNIT_TEST(eistest_socket_overflow)
return MUNIT_OK;
}
MUNIT_TEST(test_device_ready)
{
_unref_(peck) *peck = peck_new_context("eis-flags", EIS_FLAG_DEVICE_READY);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_NONE);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_DEFAULT_SEAT);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_HANDLE_SYNC);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_HANDLE_BIND_SEAT);
peck_enable_eis_behavior(peck, PECK_EIS_BEHAVIOR_ACCEPT_CLIENT);
peck_enable_ei_behavior(peck, PECK_EI_BEHAVIOR_AUTODEVICES);
peck_enable_ei_behavior(peck, PECK_EI_BEHAVIOR_AUTOSTART);
peck_dispatch_until_stable(peck);
with_server(peck) {
struct eis_seat *seat = peck_eis_get_default_seat(peck);
_unref_(eis_device) *ptr = eis_seat_new_device(seat);
eis_device_configure_capability(ptr, EIS_DEVICE_CAP_POINTER);
eis_device_configure_capability(ptr, EIS_DEVICE_CAP_BUTTON);
eis_device_configure_capability(ptr, EIS_DEVICE_CAP_SCROLL);
eis_device_configure_name(ptr, "ready device");
eis_device_add(ptr);
}
peck_dispatch_until_stable(peck);
with_server(peck) {
_unref_(eis_event) *ready = peck_eis_next_event(eis, EIS_EVENT_DEVICE_READY);
struct eis_device *dev = eis_event_get_device(ready);
eis_device_resume(dev);
}
return MUNIT_OK;
}
MUNIT_TEST(test_eis_ping)
{
_unref_(peck) *peck = peck_new();