[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
https://lists.freedesktop.org/archives/wayland-devel/2017-March/033626.html
For a high-level description, see
http://who-t.blogspot.com.au/2017/04/inputfd-protocol-for-direct-access-to.html
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
dictionary
* 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
Cheers,
Peter
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
+
+Maintainers:
+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.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
+ BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
+ ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 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>
+</protocol>
+
+
More information about the wayland-devel
mailing list