[RFC] X Input Driver specification

[Magnus Vigerlöf]

Hello,

As there doesn't seem to be a specification (or at least an up-to-date one) on 
what the different initialization stages for an Input Device should do I've 
continued on the one on the wiki [1]. My changes are around the calls made 
for set up/removal of the input device, from both the device driver and 
xserver point-of-view.

[1] http://xorg.freedesktop.org/wiki/XOrgInputDriverSpec


PreInit()/UnInit() are both functions defined in the InputDriverRec structure.

DEVICE_* is an argument to the device_control()-function defined in the 
LocalDeviceRec structure.


Adding a device would make the following calls:
 PreInit(), DEVICE_INIT, DEVICE_ON

Going from/to the VT with the X-server would make off/on to be called:
 DEVICE_OFF/DEVICE_ON

Removing a device from the server would make the following calls:
 DEVICE_CLOSE, UnInit()


* PreInit() (called only once for each device)
- Device side
Allocates all the resources for the device the driver needs. Should not access 
the hardware yet. Must call xf86AllocateInput to allocate the device-struct 
that is returned. This is a good place to check/verify parameters and 
initialize structures for the device.
An option with the key/value of "_source"/"client/dbus" will be in the 
provided option list if called as a result of a hot-plug request.

- Server side
if function returns a pointer to an InputInfoRec but haven't set 
XI86_CONFIGURED, UnInit is called if defined. If not, xf86DeleteInput is 
called to make some kind of cleanup. For devices that should be hotpluggable 
the UnInit function is required if there shouldn't be any resource leaks.


* DEVICE_INIT (called once for each device)
- Device side
Additional initialization/resource allocation for the device. Should still not 
access the hardware.

- X-server side
If the function return anything but 'Success' the device *can not* be used. 
DEVICE_ON will never be called. It will however be listed as an extension 
device in X, thus making it visible, but never available.


* DEVICE_ON
- Device side
Opens the underlying device and should restore the device to a known state, 
based on the config, or from the state saved at the lst DEVICE_OFF. Should 
call xf86AddEnabledDevice to add the FD to the ones monitored 
by the event loop. It is called when adding an input device or switching to 
the VT.

- X-server side
Only if the function return 'Success' it can expect a call to DEVICE_OFF at 
VT-switch.


* DEVICE_OFF
- Device side
Called when switching away from the VT. Drivers should save the device state, 
if applicable, and close the device port. Should call xf86RemoveEnabledDevice 
first to stop the event loop from monitoring the FD.

- X-server side
This function will only be called if the DEVICE_ON returned 'Success'.


* DEVICE_CLOSE (called once for each device)
- Device side
Deallocation of the resources allocated in DEVICE_INIT. This is sent when a 
device instance is to be removed from the server. Before this is called, any 
long-term storage of device state information, such as touch-screen 
calibration, should be retrieved by client code (i.e. a HotPlug agent) and 
not by the device driver.

- X-server side
Will be called without prior call to DEVICE_OFF when a remove request is 
received. Not called if DEVICE_INIT returned anything but 'Success'.


* UnInit() (called only once for each device)
- Device side
Deallocates all recources allocated in PreInit. xf86DeleteInput should be 
called to free the device-struct allocated in PreInit.

- Server side
If the function is not defined, xf86DeleteInput will be called instead. But 
that will most likely result in a memory leak as no device-private structures 
will be deallocated.


Cheers
  Magnus V