1Programming input drivers 2~~~~~~~~~~~~~~~~~~~~~~~~~ 3 41. Creating an input device driver 5~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 6 71.0 The simplest example 8~~~~~~~~~~~~~~~~~~~~~~~~ 9 10Here comes a very simple example of an input device driver. The device has 11just one button and the button is accessible at i/o port BUTTON_PORT. When 12pressed or released a BUTTON_IRQ happens. The driver could look like: 13 14#include <linux/input.h> 15#include <linux/module.h> 16#include <linux/init.h> 17 18#include <asm/irq.h> 19#include <asm/io.h> 20 21static struct input_dev *button_dev; 22 23static void button_interrupt(int irq, void *dummy, struct pt_regs *fp) 24{ 25 input_report_key(button_dev, BTN_1, inb(BUTTON_PORT) & 1); 26 input_sync(button_dev); 27} 28 29static int __init button_init(void) 30{ 31 int error; 32 33 if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { 34 printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); 35 return -EBUSY; 36 } 37 38 button_dev = input_allocate_device(); 39 if (!button_dev) { 40 printk(KERN_ERR "button.c: Not enough memory\n"); 41 error = -ENOMEM; 42 goto err_free_irq; 43 } 44 45 button_dev->evbit[0] = BIT(EV_KEY); 46 button_dev->keybit[LONG(BTN_0)] = BIT(BTN_0); 47 48 error = input_register_device(button_dev); 49 if (error) { 50 printk(KERN_ERR "button.c: Failed to register device\n"); 51 goto err_free_dev; 52 } 53 54 return 0; 55 56 err_free_dev: 57 input_free_device(button_dev); 58 err_free_irq: 59 free_irq(BUTTON_IRQ, button_interrupt); 60 return error; 61} 62 63static void __exit button_exit(void) 64{ 65 input_unregister_device(button_dev); 66 free_irq(BUTTON_IRQ, button_interrupt); 67} 68 69module_init(button_init); 70module_exit(button_exit); 71 721.1 What the example does 73~~~~~~~~~~~~~~~~~~~~~~~~~ 74 75First it has to include the <linux/input.h> file, which interfaces to the 76input subsystem. This provides all the definitions needed. 77 78In the _init function, which is called either upon module load or when 79booting the kernel, it grabs the required resources (it should also check 80for the presence of the device). 81 82Then it allocates a new input device structure with input_aloocate_device() 83and sets up input bitfields. This way the device driver tells the other 84parts of the input systems what it is - what events can be generated or 85accepted by this input device. Our example device can only generate EV_KEY 86type events, and from those only BTN_0 event code. Thus we only set these 87two bits. We could have used 88 89 set_bit(EV_KEY, button_dev.evbit); 90 set_bit(BTN_0, button_dev.keybit); 91 92as well, but with more than single bits the first approach tends to be 93shorter. 94 95Then the example driver registers the input device structure by calling 96 97 input_register_device(&button_dev); 98 99This adds the button_dev structure to linked lists of the input driver and 100calls device handler modules _connect functions to tell them a new input 101device has appeared. input_register_device() may sleep and therefore must 102not be called from an interrupt or with a spinlock held. 103 104While in use, the only used function of the driver is 105 106 button_interrupt() 107 108which upon every interrupt from the button checks its state and reports it 109via the 110 111 input_report_key() 112 113call to the input system. There is no need to check whether the interrupt 114routine isn't reporting two same value events (press, press for example) to 115the input system, because the input_report_* functions check that 116themselves. 117 118Then there is the 119 120 input_sync() 121 122call to tell those who receive the events that we've sent a complete report. 123This doesn't seem important in the one button case, but is quite important 124for for example mouse movement, where you don't want the X and Y values 125to be interpreted separately, because that'd result in a different movement. 126 1271.2 dev->open() and dev->close() 128~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 129 130In case the driver has to repeatedly poll the device, because it doesn't 131have an interrupt coming from it and the polling is too expensive to be done 132all the time, or if the device uses a valuable resource (eg. interrupt), it 133can use the open and close callback to know when it can stop polling or 134release the interrupt and when it must resume polling or grab the interrupt 135again. To do that, we would add this to our example driver: 136 137static int button_open(struct input_dev *dev) 138{ 139 if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { 140 printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); 141 return -EBUSY; 142 } 143 144 return 0; 145} 146 147static void button_close(struct input_dev *dev) 148{ 149 free_irq(IRQ_AMIGA_VERTB, button_interrupt); 150} 151 152static int __init button_init(void) 153{ 154 ... 155 button_dev->open = button_open; 156 button_dev->close = button_close; 157 ... 158} 159 160Note that input core keeps track of number of users for the device and 161makes sure that dev->open() is called only when the first user connects 162to the device and that dev->close() is called when the very last user 163disconnects. Calls to both callbacks are serialized. 164 165The open() callback should return a 0 in case of success or any nonzero value 166in case of failure. The close() callback (which is void) must always succeed. 167 1681.3 Basic event types 169~~~~~~~~~~~~~~~~~~~~~ 170 171The most simple event type is EV_KEY, which is used for keys and buttons. 172It's reported to the input system via: 173 174 input_report_key(struct input_dev *dev, int code, int value) 175 176See linux/input.h for the allowable values of code (from 0 to KEY_MAX). 177Value is interpreted as a truth value, ie any nonzero value means key 178pressed, zero value means key released. The input code generates events only 179in case the value is different from before. 180 181In addition to EV_KEY, there are two more basic event types: EV_REL and 182EV_ABS. They are used for relative and absolute values supplied by the 183device. A relative value may be for example a mouse movement in the X axis. 184The mouse reports it as a relative difference from the last position, 185because it doesn't have any absolute coordinate system to work in. Absolute 186events are namely for joysticks and digitizers - devices that do work in an 187absolute coordinate systems. 188 189Having the device report EV_REL buttons is as simple as with EV_KEY, simply 190set the corresponding bits and call the 191 192 input_report_rel(struct input_dev *dev, int code, int value) 193 194function. Events are generated only for nonzero value. 195 196However EV_ABS requires a little special care. Before calling 197input_register_device, you have to fill additional fields in the input_dev 198struct for each absolute axis your device has. If our button device had also 199the ABS_X axis: 200 201 button_dev.absmin[ABS_X] = 0; 202 button_dev.absmax[ABS_X] = 255; 203 button_dev.absfuzz[ABS_X] = 4; 204 button_dev.absflat[ABS_X] = 8; 205 206Or, you can just say: 207 208 input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 8); 209 210This setting would be appropriate for a joystick X axis, with the minimum of 2110, maximum of 255 (which the joystick *must* be able to reach, no problem if 212it sometimes reports more, but it must be able to always reach the min and 213max values), with noise in the data up to +- 4, and with a center flat 214position of size 8. 215 216If you don't need absfuzz and absflat, you can set them to zero, which mean 217that the thing is precise and always returns to exactly the center position 218(if it has any). 219 2201.4 NBITS(), LONG(), BIT() 221~~~~~~~~~~~~~~~~~~~~~~~~~~ 222 223These three macros from input.h help some bitfield computations: 224 225 NBITS(x) - returns the length of a bitfield array in longs for x bits 226 LONG(x) - returns the index in the array in longs for bit x 227 BIT(x) - returns the index in a long for bit x 228 2291.5 The id* and name fields 230~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 231 232The dev->name should be set before registering the input device by the input 233device driver. It's a string like 'Generic button device' containing a 234user friendly name of the device. 235 236The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID 237of the device. The bus IDs are defined in input.h. The vendor and device ids 238are defined in pci_ids.h, usb_ids.h and similar include files. These fields 239should be set by the input device driver before registering it. 240 241The idtype field can be used for specific information for the input device 242driver. 243 244The id and name fields can be passed to userland via the evdev interface. 245 2461.6 The keycode, keycodemax, keycodesize fields 247~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 248 249These three fields should be used by input devices that have dense keymaps. 250The keycode is an array used to map from scancodes to input system keycodes. 251The keycode max should contain the size of the array and keycodesize the 252size of each entry in it (in bytes). 253 254Userspace can query and alter current scancode to keycode mappings using 255EVIOCGKEYCODE and EVIOCSKEYCODE ioctls on corresponding evdev interface. 256When a device has all 3 aforementioned fields filled in, the driver may 257rely on kernel's default implementation of setting and querying keycode 258mappings. 259 2601.7 dev->getkeycode() and dev->setkeycode() 261~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 262getkeycode() and setkeycode() callbacks allow drivers to override default 263keycode/keycodesize/keycodemax mapping mechanism provided by input core 264and implement sparse keycode maps. 265 2661.8 Key autorepeat 267~~~~~~~~~~~~~~~~~~ 268 269... is simple. It is handled by the input.c module. Hardware autorepeat is 270not used, because it's not present in many devices and even where it is 271present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable 272autorepeat for your device, just set EV_REP in dev->evbit. All will be 273handled by the input system. 274 2751.9 Other event types, handling output events 276~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 277 278The other event types up to now are: 279 280EV_LED - used for the keyboard LEDs. 281EV_SND - used for keyboard beeps. 282 283They are very similar to for example key events, but they go in the other 284direction - from the system to the input device driver. If your input device 285driver can handle these events, it has to set the respective bits in evbit, 286*and* also the callback routine: 287 288 button_dev->event = button_event; 289 290int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value); 291{ 292 if (type == EV_SND && code == SND_BELL) { 293 outb(value, BUTTON_BELL); 294 return 0; 295 } 296 return -1; 297} 298 299This callback routine can be called from an interrupt or a BH (although that 300isn't a rule), and thus must not sleep, and must not take too long to finish. 301