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

Peter Hutterer peter.hutterer at who-t.net
Fri Apr 7 04:04:40 UTC 2017

For the initial patchset, see 
For a high-level description, see

This is a relatively unexciting update, the notable bits are:
* instead of having a per-device type get_seat_* request, we now have just a
  basic get_seat() request that returns all inputfd-capable devices. This
  allows for mice, keyboards, etc as well without having more requests
* the property description has a link to the github repo i started for the
* the fd was split into a read/write fd to allow for pipes, the type was
  extended for an evdev-protocol-carrying pipe. (I'm not convinced this
  is good enough yet, just as a note)

This addresses some of the immediate comments. The big list of TODO is:
* LED control, force feedback, and other write-back channels that don't work
  on the fd but go through sysfs
* battery status and other notifications


diff --git a/Makefile.am b/Makefile.am
index e693afa..e46910a 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -4,6 +4,7 @@ unstable_protocols =								\
 	unstable/linux-dmabuf/linux-dmabuf-unstable-v1.xml			\
 	unstable/text-input/text-input-unstable-v1.xml				\
 	unstable/input-method/input-method-unstable-v1.xml			\
+	unstable/inputfd/inputfd-unstable-v1.xml				\
 	unstable/xdg-shell/xdg-shell-unstable-v5.xml				\
 	unstable/xdg-shell/xdg-shell-unstable-v6.xml				\
 	unstable/relative-pointer/relative-pointer-unstable-v1.xml		\
diff --git a/unstable/inputfd/README b/unstable/inputfd/README
new file mode 100644
index 0000000..a24d858
--- /dev/null
+++ b/unstable/inputfd/README
@@ -0,0 +1,4 @@
+Input device fd passing protocol
+Peter Hutterer <peter.hutterer at who-t.net>
diff --git a/unstable/inputfd/inputfd-unstable-v1.xml b/unstable/inputfd/inputfd-unstable-v1.xml
new file mode 100644
index 0000000..e6da5bd
--- /dev/null
+++ b/unstable/inputfd/inputfd-unstable-v1.xml
@@ -0,0 +1,316 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="inputfd_unstable_v1">
+  <copyright>
+    Copyright 2017 © Red Hat, Inc.
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation files
+    (the "Software"), to deal in the Software without restriction,
+    including without limitation the rights to use, copy, modify, merge,
+    publish, distribute, sublicense, and/or sell copies of the Software,
+    and to permit persons to whom the Software is furnished to do so,
+    subject to the following conditions:
+    The above copyright notice and this permission notice (including the
+    next paragraph) shall be included in all copies or substantial
+    portions of the Software.
+  </copyright>
+  <description summary="Wayland protocol for direct fd access to input devices">
+    This description provides a high-level overview of the interfaces
+    in this protocol. For details, see the protocol specification.
+    Some input devices do not interact with the windowing system. Examples
+    of such input devices are gaming controllers or 3D mice. In many cases,
+    a client requires direct access to the device to access or interpret
+    device-specific functionality.
+    This interface provides the ability for a compositor to pass a file
+    descriptor to the client. The compositor may restrict the type of device
+    designated as compatible device and it may restrict specific events from
+    being sent to the client (e.g. by masking the Home button on a gamepad).
+    Otherwise, a client should treat the device as if opened manually.
+    Multiple input devices of the same type may exists and assigned to
+    different seats. The top-level object of this protocol is a
+    wp_inputfd_manager, a client must request the interface for a given seat.
+    This object then provides the list of devices for that category.
+    Once a compositor deems a device to be focused on the client or on a
+    client's surface it sends a wp_inputfd_device.focus_in event with a file
+    descriptor for this device. A compositor may arbitrarily revoke access
+    to the device by sending a wp_inputfd.focus_out. Additionally, a
+    compositor may invoke system functionality to restrict access to the
+    file descriptor, e.g. by using EVIOCMUTE on an evdev fd.
+    Otherwise, a client should treat the file descriptor as direct access to
+    the device for the duration of it having access.
+    Warning! The protocol described in this file is experimental and
+    backward incompatible changes may be made. Backward compatible changes
+    may be added together with the corresponding interface version bump.
+    Backward incompatible changes are done by bumping the version number in
+    the protocol and interface names and resetting the interface version.
+    Once the protocol is to be declared stable, the 'z' prefix and the
+    version number in the protocol and interface names are removed and the
+    interface version number is reset.
+  </description>
+  <interface name="zwp_inputfd_manager_v1" version="1">
+    <description summary="controller object for direct fd access input devices">
+      An object that provides access to the input devices available for
+      direct fd access on this system. All input devices are associated with
+      a seat, to get access to the actual devices, use
+      wp_inputfd_manager.get_seat.
+    </description>
+    <request name="get_seat">
+      <description summary="get the seat for receiving device notifications">
+	Get the wp_inputfd_seat object for the given seat. This object
+	provides access to all exposed devices in this seat.
+	The decision which device is available through this interface is
+	made by the compositor. The protocol makes no guarantees whether a
+	particular device is available through this interface.
+      </description>
+      <arg name="inputfd_seat" type="new_id" interface="zwp_inputfd_seat_v1"/>
+      <arg name="seat" type="object" interface="wl_seat" summary="The wl_seat object to retrieve the input devices for" />
+    </request>
+    <request name="destroy" type="destructor">
+      <description summary="release the memory for the inputfd manager object">
+	Destroy the wp_inputfd_manager object. Objects created from this
+	object are unaffected and should be destroyed separately.
+      </description>
+    </request>
+  </interface>
+  <interface name="zwp_inputfd_seat_v1" version="1">
+    <description summary="controller object for input devices of a seat">
+      An object that provides access to the input devices available on this
+      seat for the requested type of device. After binding to this
+      interface, the compositor sends a set of wp_inputfd_seat.device_added
+      events for currently available devices and whenever a new device
+      becomes available.
+    </description>
+    <request name="destroy" type="destructor">
+      <description summary="release the memory for the inputfd seat object">
+	Destroy the wp_inputfd_seat object. Objects created from this
+	object are unaffected and should be destroyed separately.
+      </description>
+    </request>
+    <event name="device_added">
+      <description summary="new device notification">
+	This event is sent whenever a new device becomes available on
+	this seat. This event only provides the object id of the devices,
+	any static information about the device (device name,
+	vid/pid, etc.) is sent through the wp_inputfd_device interface.
+	Which devices are compatible input devices for this seat is a
+	decision made by the compositor, the protocol makes no guarantee
+	that any specific device becomes available as inputfd device to a
+	client.
+      </description>
+      <arg name="id" type="new_id" interface="zwp_inputfd_device_v1" summary="the newly added device"/>
+    </event>
+  </interface>
+  <interface name="zwp_inputfd_device_v1" version="1">
+    <description summary="input fd device">
+      The wp_inputfd_device interface represents one device accessible
+      directly by an fd passed to the client.
+      A device has a number of static characteristics, e.g. device
+      name and pid/vid. These capabilities are sent in an event sequence
+      immediately after the wp_inputfd_seat.device_added event. This initial
+      event sequence is terminated by a wp_inputfd_device.done event. This
+      sequence is sent only once and always before the first
+      wp_inputfd_device.focus_in event.
+      A device is the representation of a logical device as exposed by the
+      underlying system and may only represent parts of a single physical
+      input device. It is the client's task to identify the device as part
+      of a physical device and to group the logical devices together as
+      appropriate.
+    </description>
+    <request name="destroy" type="destructor">
+      <description summary="destroy the inputfd object">
+	This destroys the client's resource for this inputfd object.
+      </description>
+    </request>
+    <event name="name">
+      <description summary="device name">
+	The name is a UTF-8 encoded string with the device's name, intended
+	for presentation to the user.
+	This event is sent in the initial burst of events before the
+	wp_inputfd_device.done event.
+	This event is optional, if the required information is not available
+	for this device the event is omitted.
+      </description>
+      <arg name="name" type="string" summary="the device name"/>
+    </event>
+    <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.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>
+    <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.
+	The protocol makes no guarantee that a compositor supports a
+	specific dictionary or dictionary version. A client must be able to
+	a) handle properties of unknown name b) handle properties of
+	unknown value, and c) handle multiple events for the same property
+	with different values.
+	While the protocol is in development, the autoritative dictionary is
+	located at: https://github.com/whot/inputfd-property-authority
+	Property events are always optional, a client must assume reasonable
+	defaults if the propety event is not sent. The dictionary of
+	properties may specify the expected default value for a property.
+	Properties describe static capabilities of the device only, a
+	property is valid until the device is removed.
+      </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>
+    <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.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.destroy
+	the object.
+      </description>
+    </event>
+    <enum name="fd_type">
+      <description summary="Input fd device file descriptor types">
+	This enum specifies the format of the file descriptor passed to
+	clients with the wp_inputfd_device.focus_in event.
+      </description>
+      <entry name="evdev" value="0" summary="An evdev file descriptor" />
+      <entry name="pipe_evdev" value="1" summary="A unidirectional pipe talking evdev">
+	<description>
+	  This file descriptor type describes a unidirectional data channel
+	  (e.g. pipe(2)) that sends events using the evdev protocol. Unlike
+	  a normal evdev file descriptor this data channel is a) read- or
+	  write-only but not both and b) any evdev-specific ioctl() will
+	  fail on the file descriptor.
+	  This file descriptor can be used to read or write evdev-style
+	  struct input_events.
+	</description>
+      </entry>
+    </enum>
+    <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 two file descriptors with access to this
+	device, one for read operations, one for write operations. The read
+	and the write file descriptor may be the same fd.  These file
+	descriptors are valid until a subsequent wp_inputfd_device.focus_out
+	event. Upon wp_inputfd_device.focus_out, the compositor may revoke
+	the fds 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 one of the fds, 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="read_type" type="uint" enum="fd_type" summary="fd type for read descriptor" />
+      <arg name="read" type="fd" summary="read-file descriptor to the device"/>
+      <arg name="write_type" type="uint" enum="fd_type" summary="fd type for write descriptor" />
+      <arg name="write" type="fd" summary="write-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 descriptors received in
+	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>

More information about the wayland-devel mailing list