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

Fri Mar 31 09:23:49 UTC 2017

On Fri, 31 Mar 2017 17:29:19 +1000
Peter Hutterer <peter.hutterer at who-t.net> wrote:

> This is the first draft for a protocol to enable direct access to input
> devices. The basic premise is: instead of protocols to handle gaming
> devices, 3D mice, sensors, etc. we just hand you (the client) an fd and hope
> you're happy with it. You get to play with that fd until it's revoked, i.e.
> right now we only provide it for evdev fds where we have EVIOCMUTE.
> 
> Focus management is straightforward and follows compositor policy. The
> protocol is quite simple: 
> 
> clients get a wp_inputfd_device for each device
>   this device sends some static information (name, usb ids, ...)
>   this device sends focus-in with an fd
>   this device sends focus-out, the fd is revoked
>   ... repeat focus in/out as necessary ...
>   this device sends removed on unplug
> 
> The devices are wrapped up into seats and those seats are provided by a
> global manager object - largely because that's what we need for the protocol
> to work.
> 
> The notable bits are:
> * devices are divided into categories, so instead of getting all devices,
>   you say "give me an inputfd-seat for gaming devices". That object then
>   sends you all devices. In the future, we'll have an equivalent "give me
>   the seat for 3D mice", etc., but right now the gaming devices is
>   all that exists
> * there's a generic key/value event called "property". This one is largely
>   so the compositor can tag devices with some capabilities to make it easier
>   for the client to identify what it wants. I'll punt to Bastien for
>   details because he requested that, but I can imagine something like
>   "joystick type" is "gamepad". This big deal with this is that the
>   dictionary of tags is something that compositor and clients will have to
>   agree on, and it's not something defined by the protocol. This enables us
>   to change/extend the tags independent of protocol bumps.
>   It's quite similar to having access to the udev device to get at udev
>   properties, but some devices may not have a udev device, so...
> 
> What is *not* in the protocol is how the compositor decides what is a gaming
> devices. The ID_INPUT_JOYSTICK udev property is too crude with many false
> positives. For tablets, we get around this by having libwacom spit out udev
> rules to tag things correctly. A similar approach is the best solution
> here: have some database that knows about various joystick devices and which
> category they fall into and install the udev rules/hwdb entries
> accordingly. There was talk of a gaming-device-oriented library
> (libgamingdev), this library could provide that information. Such a library
> would also be a prime spot for that property dictionary. Volunteers to start
> working on this, please step forward!
> 
> /me takes a big step back
> 
> Again, this is a draft, so feel free to pick it apart or request changes so
> it matches your use-case. Please do add CC's as required, I am by no means a
> game developer so I'm not aware of use-cases beyond the immediately obvious.

Hi Peter,

the grand idea seems good to me, and the protocol draft is already very
well written. I have a few comments below.

> +    <event name="property">
> +      <description summary="device capability notification">
> +	This event is sent to notify the client of a custom property that
> +	applies to this device. The property is a standard key/value store
> +	in UTF-8 format, interpretation of both strings is left to the
> +	client. The wayland protocol makes no guarantees about the content
> +	of each string beyond its text encoding.
> +
> +	Compositors and clients need to agree on a dictionary of properties.
> +	For example, a compositor may designate the device to be of
> +	'joystick-type' 'gamepad'. This dictionary is out of the scope of
> +	this protocol.
> +      </description>
> +      <arg name="property" type="string" summary="A UTF-8 encoded property name"/>
> +      <arg name="value" type="string" summary="A UTF-8 encoded property value"/>
> +    </event>

While I understand the desire to leave the dictionary for others to
specify, this event is essentially useless without it. The dictionary
really is part of the protocol, even if you didn't want it. I'm not
sure it's helpful to leave the authority on the dictionary unspecified.
As you wrote, they need to be agreed somewhere.

This raises a couple of questions for the protocol itself:

- What should the client do with a property or value it does not
  recognize?

- If the client does not recognize a property or a value, can it still
  use the device? Could this vary per property?

- Should the compositor be sending only properties and values the
  client can understand?

If this protocol does not define a single authority on the dictionary,
should it then carry a dictionary type, id or namespace?

Should properties be namespaced?

> +
> +    <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. The decision what consitutes focus 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.focus_out event. Upon wp_inputfd_device.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.focus_out event or wp_inputfd_device.removed
> +	event are sent before the client encounters an error on the file
> +	descriptor.
> +
> +	A compositor guarantees that the underlying device does not change
> +	until a wp_inputfd_device.removed event. In other words, if the fd
> +	type allows querying capabilities through the fd, a client needs to
> +	do so only once at the first focus_in. Subsequent focus_in events
> +	will provide the same capabilities.
> +
> +	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.removed event.
> +      </description>
> +      <arg name="serial" type="uint"/>

What is 'serial'?

> +      <arg name="fd" type="fd" summary="file descriptor to the device"/>
> +      <arg name="fd_type" type="uint" enum="fd_type" summary="fd type" />
> +      <arg name="surface" type="object" interface="wl_surface" summary="The current surface that has the device's focus" allow-null="true"/>
> +    </event>

This reminded me, we should probably check whether libwayland-client
can handle 'focus_in' racing with 'destroy' without leaking the fd. I
have no recollection if it does. That is, when the client sends
'destroy' at the same time the server sends 'focus_in', the client no
longer has a live proxy (has a zombie instead), does libwayland-client
while dropping the 'focus_in' on the floor also close the received fd.

> +
> +    <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
> +	will fail. The client must close(2) the file descriptor received in

"will fail" seems a bit strong.

> +	the wp_inputfd_device.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.removed.
> +
> +	See wp_inputfd_device.focus_in for more details.
> +      </description>
> +    </event>
> +  </interface>
> +</protocol>
> +
> +

Thanks,
pq
-------------- 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/20170331/b4a7936b/attachment.sig>