[RFC v3 wayland-protocols] inputfd - direct input access protocol

Mon Aug 28 09:29:55 UTC 2017

On Wed, 23 Aug 2017 11:48:59 +1000
Peter Hutterer <peter.hutterer at who-t.net> wrote:

> For previous versions, see:
> v1: https://lists.freedesktop.org/archives/wayland-devel/2017-March/033626.html
> v2: https://lists.freedesktop.org/archives/wayland-devel/2017-April/033819.html
> 
> This update is closer to v1 again than v2. Biggest change is: instead of a
> get_seat we have a get_seat_evdev request. Anything evdev is then hanging
> off that seat, basically in how it was before. The hierarchy of objects is
> thus something like this:
> 
>     manager
>       seat_evdev
>          device_evdev
>          device_evdev
>          device_evdev
> 
> and in the future we could have other interfaces like this:
> 
>     manager
>       seat_evdev
>          device_evdev
>          device_evdev
>          device_evdev
>          device_evdev
>       seat_hidraw
>          device_hidraw
>          device_hidraw
>          device_hidraw
>       seat_w3c
>          device_w3c
>          device_w3c
> 
> Having it split at the seat level means we don't have to pollute each
> interface with the different needs of the other interfaces. evdev is the
> easiest case, so that's done first. I dropped the extra properties, Bastien
> and I discussed this at GUADEC and we agreed it's better to implement the
> minimal version first and then see what we need before trying to come up
> with a generic solution.
> 
> Cheers,
>    Peter

Hi Peter,

on a quick read-through, this looks good to me. I have only two
comments to give at this time.

Acked-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>

> diff --git a/unstable/inputfd/inputfd-unstable-v1.xml b/unstable/inputfd/inputfd-unstable-v1.xml
> new file mode 100644
> index 0000000..c8a0380
> --- /dev/null
> +++ b/unstable/inputfd/inputfd-unstable-v1.xml
> @@ -0,0 +1,268 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="inputfd_unstable_v1">

...

> +    <event name="usb_id">
> +      <description summary="device USB vendor/product id">
> +	This event is sent in the initial burst of events before the
> +	wp_inputfd_device_evdev.done event.
> +
> +	This event is optional, if the required information is not available
> +	for this device the event is omitted.
> +      </description>
> +      <arg name="vid" type="uint" summary="USB vendor id"/>
> +      <arg name="pid" type="uint" summary="USB product id"/>
> +    </event>

Roderick mentioned there are other busses than USB. While true, I'm not
sure if adding a third argument for bus type gains anything compared to
keeping the event bus-specific and adding new events for each bus type.

Adding new events for new bus types would allow the compositor to avoid
advertising devices where the client does not understand the bus.
Whether that would be good or bad, I cannot say. If a device can be
used even without understanding the bus and identity, then it would be
bad. If there could be different sets of identity arguments between
busses, then it would be good.

> +
> +    <event name="done">
> +      <description summary="device description events sequence complete">
> +	This event is sent immediately to signal the end of the initial
> +	burst of descriptive events. A client may consider the static
> +	description of the device to be complete and finalize
> +	initialization of the device.
> +      </description>
> +    </event>
> +
> +    <event name="removed">
> +      <description summary="device removed event">
> +	Sent when the device has been removed from the system.
> +
> +	If the client currently has the device focus, a
> +	wp_inputfd_device_evdev.focus_out event is sent before the removed
> +	event. See wp_inputfd_device.focus_in for more details.
> +
> +	When this event is received, the client must
> +	wp_inputfd_device_evdev.destroy the object.
> +      </description>
> +    </event>
> +
> +    <event name="focus_in">
> +      <description summary="input fd device focus in event">
> +	Notification that this client now has the focus and/or access to
> +	this device. How focus is set is left to the
> +	compositor. For example, a compositor may tie joystick focus to the
> +	wl_pointer focus of this seat. The protocol does not guarantee that
> +	any specific client ever receives the focus for a device.
> +
> +	The client is passed a file descriptor with access to this
> +	device. This file descriptor is valid until a subsequent
> +	wp_inputfd_device_evdev.focus_out event. Upon
> +	wp_inputfd_device_evdev.focus_out, the compositor may revoke the fd
> +	and further operations will fail.
> +
> +	However, due to potential race conditions a client must be able to
> +	handle errors as if it opened the fd itself. No guarantee is given
> +	that the wp_inputfd_device_evdev.focus_out event or
> +	wp_inputfd_device_evdev.removed event are sent before the client
> +	encounters an error on the file descriptor.
> +
> +	A compositor guarantees the file descriptor for a
> +	wp_inputfd_device_evdev refers to the same kernel device after each
> +	focus_in event. In other words, any constant information about the
> +	device obtained through the fd (e.g. the EVIOCGPROP ioctl) is
> +	the same after each focus in event. Thus, a client needs to do so
> +	only once at the first focus_in. This guarantee does not extend to
> +	information that the kernel may change at runtime (e.g. the
> +	EVIOCGABS ioctl).
> +
> +	If applicable, this event contains the surface that has the focus.
> +	In some cases, the focus may not be tied to a specific client surface
> +	but is given to the client independent of any surface. In that case,
> +	the surface is null.
> +
> +	The protocol guarantees that focus_in and focus_out always come in
> +	pairs. If the client currently has the focus and the device is
> +	removed, a focus_out event is sent to the client before the
> +	wp_inputfd_device_evdev.removed event.
> +      </description>
> +      <arg name="serial" type="uint"/>

Serial in unexplained.

Thanks,
pq

> +      <arg name="fd" type="fd" summary="file descriptor to the device"/>
> +      <arg name="surface" type="object" interface="wl_surface"
> +	summary="The current surface that has the device's focus" allow-null="true"/>
> +    </event>
> +
> +    <event name="focus_out">
> +      <description summary="input fd device focus out event">
> +	Notification that this client no longer has focus and/or access to
> +	this device. Further reads from this device's file descriptor
> +	may fail. The client must close(2) the file descriptor received in
> +	the wp_inputfd_device_evdev.focus_in event.
> +
> +	This event does not mean the device was removed, merely that the
> +	device is focused elsewhere. For device removal, see
> +	wp_inputfd_device_evdev.removed.
> +
> +	See wp_inputfd_device_evdev.focus_in for more details.
> +      </description>
> +    </event>
> +  </interface>
> +</protocol>

-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 833 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20170828/5c2471ae/attachment.sig>