[RFC wayland-protocols] inputfd - direct input access protocol
Peter Hutterer
peter.hutterer at who-t.net
Tue Apr 4 00:22:24 UTC 2017
On Tue, Apr 04, 2017 at 08:16:03AM +0900, Carsten Haitzler wrote:
> On Fri, 31 Mar 2017 17:29:19 +1000 Peter Hutterer <peter.hutterer at who-t.net>
> said:
>
> If you're going to do this ... why not just do it for keyboards, mice, touch
> panels etc. too?
all these have desktop interactions that the compositor needs. joysticks
generally don't, the compositor doesn't care about the events.
> My point is - the same reasons these other devices don't be lazy and stick
> their heads in the sand with these other devices are the same reasons
> joysticks, gamepads etc. etc. should also be UNDERSTOOD by the compositor
> before passing them on so they compositor can filter out special buttons (eg a
> power button and handle it internally, or a "home" button to go back to the
> home screen etc.).
>
> The "I'll just pass the fd and otherwise have no idea what is going on" is
> sticking your head in the sand and avoiding a solution.
hence the proposal for a libgamedev to be able to share some of that code
where needed, or to get some less device-specific handling on the client
side.
Cheers,
Peter
>
> > 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.
> >
> > 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..3b83378
> > --- /dev/null
> > +++ b/unstable/inputfd/inputfd-unstable-v1.xml
> > @@ -0,0 +1,279 @@
> > +<?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.
> > +
> > + This interface divides devices into type-based categories, clients are
> > + expected to only request access to devices that match the category they
> > + require. As of version 1, this interface provides only a single
> > + category: "gaming devices". Future categories of devices are expected to
> > + re-use the same wp_inputfd_device interface, but may differ in the way
> > + how to request them.
> > +
> > + 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. Dependent on the device type sought after, a client
> > + may request a type-specific seat interface (e.g.
> > + wp_inputfd_manager.get_seat_gamedev). This seat 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_gamedev.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.
> > + </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 one of the get_seat
> > + requests, e.g. wp_inputfd_manager.get_seat_gamedev.
> > + </description>
> > +
> > + <request name="get_seat_gamedev">
> > + <description summary="get the seat for gaming devices">
> > + Get the wp_inputfd_seat object for the given seat. This object
> > + provides access to all gaming devices in this seat.
> > +
> > + The decision which device is a gaming device 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.
> > + </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.
> > + </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" />
> > + </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 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"/>
> > + <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>
> > +
> > + <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
> > + 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