Device properties have landed

After a few more patches, the property support has now landed in what I'd like to call the final version. Unless there's any more changes in the next few weeks, this will be added as the main component of the X Input Extension v1.5.

So here's a short description of what they are, the protocol additions and the driver-side API.

What are device properties?

Input device properties (IDP) are basically the same as Window Properties (Atoms) in the core X protocol, or RandR output properties. They are numerical identifiers with arbitrary names that can be assigned arbitrary values. The big thing about IDP is that we can now add options to drivers that can be triggered at modified by clients without having to bump the protocol or even the server. Likewise, we can add options to the server easier too.

One of the server's weakest parts was run-time configuration of input devices. Options in the xorg.conf (or nowadays in the HAL fdi file) were easy enough, but once the server was running it was difficult to do anything. Synaptics even exposes shared memory to enable run-time configuration for lack of a better mechanism. IDP should fix this lack of a decent method and hopefully unify the configuration mechanisms. In fact, synaptics, evdev and joystick already provide property support.

Your server already uses a lot of properties for various stuff. The "xlsatoms" command lists all properties currently defined and their names. The "xprop" command lists all window properties and their current value(s).

Driver API

The code to use device properties from a driver (or the server) is basically always the same:

#include<X11/Xatom.h>
#define MYPROP_NAME "Example property"

char prop_value = 8;
/* create atom (if it doesn't exist already anyway) */
Atom prop = MakeAtom(MYPROP_NAME, strlen(MYPROP_NAME), TRUE);
rc = XIChangeDeviceProperty(device, prop,
                           XA_INTEGER /* type */,
                           8 /* format */,
                           PropModeReplace,
                           1 /* no of items */,
                           &prop_value /* data */,
                           TRUE /* send event */):

/* don't allow clients to delete our prop */
XISetDevicePropertyDeletable(device, prop, FALSE);
XIRegisterPropertyHandler(device, SetPropertyHandler, 
                                  GetPropertyHandler, 
                                  DeletePropertyHandler);

SetPropertyHandler is called whenever a client changes the property. GetPropertyHandler is called whenever a client retrieves the property value, if you have to get data off the device - do it here. Finally DeletePropertyHandler is called when the property is about to be deleted. Note that if you set the property to be non-deletable, the DeletePropertyHandler can only called if a driver or the server wants to delete the property.

In all cases, do stuff, return Success or an error code otherwise. A NULL handler is allowed. Errors are returned immediately to the client, so make sure your property is properly documented that developers can figure out why a BadValue, BadMatch, etc. error occurs.

Here's some example code for a SetPropertyHandler

int SetPropertyHandler(DeviceIntPtr dev, Atom atom, 
                       XIPropertyValuePtr value, BOOL checkonly)
{
 if (atom == myprop)
 {
    if (val->format != 8 || val->type != XA_INTEGER || ...)
       return BadMatch;
   
    if (*((char*)val->data) > 10)
       return BadValue;

    if (!checkonly) /* do something with the value */
    { ... 
    }
 }
 return Success; /* You MUST return Success, even if you didn't handle it */
}

Important here: if checkonly is TRUE, you must not change any state. Check only for validity of the atom and the given value. Each SetPropertyHandler is called twice, once to check the value, then again to actually apply the data. The assumption is that if the checkonly run succeeds, the state change cannot fail. If you return an error in the checkonly run, this error is returned to the client and the second run is never executed.

A few rules: keep the handler simple. You cannot assume that you're called in any particular order. You cannot assume that the second run is ever executed. Keep the handler as local as possible, instead of having one big handler it may be better having two separate ones (e.g. one in the DIX, one in the DDX).

That's basically it. A call to XIChangeDeviceProperty() causes an event to be sent to the clients, so this is the API that should be used if the property needs changing from within the server/driver.

Protocol requests and events

As just mentioned above, there's one event DevicePropertyNotify which lists the state (NewValue or Deleted), the property affected and of course the device id. This event is sent whenever a property is changed by a client and whenever a driver/the server changes a property with XIChangeDeviceProperty(..., TRUE).

The four new requests are:

ListDeviceProperties
ChangeDeviceProperty
DeleteDeviceProperty
GetDeviceProperty

All four requests are virtually identical to the ListProperties, ChangeProperty, DeleteProperty, and GetProperty requests of the core protocol - except they allow the specification of a device ID instead of a window ID. Just look up the man page for the core protocol requests for more information.

The xinput tool has all the basic code to list, view and delete properties.

As a final gimmick, evdev, synaptics and the xserver each have a name-properties.h file, (e.g. evdev-properties.h gives you all the defines for the property names) and the command "
pkg-config --cflags xorg-evdev" gives you the necessary include paths.