hotplug example?

[Peter Hutterer]

[this message was previously sent off-list but I figured it might be worthy of
archiving]

On Mon, Jun 16, 2008 at 11:14:22PM +0930, Peter Hutterer wrote:
> Just look at xf86-input-evdev. The driver simply needs to clean up after
> itself in UnInit and DeviceProc(..., DEVICE_CLOSE). The actual hotplugging is
> done by the server, the driver doesn't really know if it's hotplugged or
> started on init.
> 
> To get hotplug working, hal needs to send a notification to the xserver when
> the device appears. xserver/config/x11-input.fdi has the magic for that, you
> can change keys for your device to use a different driver.
> 
> If you can't use hal for some reason, you need to compile your server with
> --enable-config-dbus and then send the appropriate commands (documented in
> xserver/config/dbus-api).

what I meant in the above email is that the driver doesn't actually _do_
hotplugging, it just _supports_ it.

All the driver ever sees is its module being loaded, devices added, started
and closed, and the module being unloaded.
How that happens is transparent, so in the driver you don't know whether the
module was loaded in response to an xorg.conf option, or in response to an HAL
event.

In your driver, you need to make sure that whatever you allocated in the
ModuleSetupProc is cleaned up in ModuleTearDownProc (XF86ModuleData rec).
These two are called when the module is loaded or unloaded respectively.

PreInit is called when the device is recognised by the server as a new device
to be added. What the driver should do here is figure out if all options are
correct, if the device you want to open is available, etc. PreInit is the
stage where the driver should fail if the device cannot be used (e.g. wrong
device path).

The pInfo->device_control function is then called when the device is
initialised (DEVICE_INIT), enabled (DEVICE_ON), disabled (DEVICE_OFF) or
removed (DEVICE_CLOSE). What the driver should do is:
DEVICE_INIT: initialise the device by creating it's classes (e.g.
InitValuatorClassDeviceStruct), init driver-internal required stuff.
DEVICE_ON: start listening for events on the fd, note that a device must not
send events before it is enabled through DEVICE_ON.
DEVICE_OFF: stop listening for events, the device must not send events anymore.
DEVICE_CLOSE: remove driver-internal memory for this device, the device can be
considered dead.

Note that DEVICE_INIT and DEVICE_CLOSE are only used once per device, but _ON
and _OFF can be called anytime, multiple times.

This is what you have to do to _support_ hotplugging in the driver.
To actually invoke the hotplugging code, you need to construct the correct hal
events when they are sent to the X server. So you want a merge command that
sets input.x11_driver to your driver, much like it does right now with the
mouse driver (or evdev under Linux). That's pretty much it, just have a look
at x11-input.fdi in the xserver/config directory, this gives you some examples
on how to do that.

Cheers,
  Peter