diff options
Diffstat (limited to 'Documentation/input/input-programming.txt')
| -rw-r--r-- | Documentation/input/input-programming.txt | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt new file mode 100644 index 00000000000..180e0689676 --- /dev/null +++ b/Documentation/input/input-programming.txt @@ -0,0 +1,281 @@ +$Id: input-programming.txt,v 1.4 2001/05/04 09:47:14 vojtech Exp $ + +Programming input drivers +~~~~~~~~~~~~~~~~~~~~~~~~~ + +1. Creating an input device driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +1.0 The simplest example +~~~~~~~~~~~~~~~~~~~~~~~~ + +Here comes a very simple example of an input device driver. The device has +just one button and the button is accessible at i/o port BUTTON_PORT. When +pressed or released a BUTTON_IRQ happens. The driver could look like: + +#include <linux/input.h> +#include <linux/module.h> +#include <linux/init.h> + +#include <asm/irq.h> +#include <asm/io.h> + +static void button_interrupt(int irq, void *dummy, struct pt_regs *fp) +{ + input_report_key(&button_dev, BTN_1, inb(BUTTON_PORT) & 1); + input_sync(&button_dev); +} + +static int __init button_init(void) +{ + if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { + printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); + return -EBUSY; + } + + button_dev.evbit[0] = BIT(EV_KEY); + button_dev.keybit[LONG(BTN_0)] = BIT(BTN_0); + + input_register_device(&button_dev); +} + +static void __exit button_exit(void) +{ + input_unregister_device(&button_dev); + free_irq(BUTTON_IRQ, button_interrupt); +} + +module_init(button_init); +module_exit(button_exit); + +1.1 What the example does +~~~~~~~~~~~~~~~~~~~~~~~~~ + +First it has to include the <linux/input.h> file, which interfaces to the +input subsystem. This provides all the definitions needed. + +In the _init function, which is called either upon module load or when +booting the kernel, it grabs the required resources (it should also check +for the presence of the device). + +Then it sets the input bitfields. This way the device driver tells the other +parts of the input systems what it is - what events can be generated or +accepted by this input device. Our example device can only generate EV_KEY type +events, and from those only BTN_0 event code. Thus we only set these two +bits. We could have used + + set_bit(EV_KEY, button_dev.evbit); + set_bit(BTN_0, button_dev.keybit); + +as well, but with more than single bits the first approach tends to be +shorter. + +Then the example driver registers the input device structure by calling + + input_register_device(&button_dev); + +This adds the button_dev structure to linked lists of the input driver and +calls device handler modules _connect functions to tell them a new input +device has appeared. Because the _connect functions may call kmalloc(, +GFP_KERNEL), which can sleep, input_register_device() must not be called +from an interrupt or with a spinlock held. + +While in use, the only used function of the driver is + + button_interrupt() + +which upon every interrupt from the button checks its state and reports it +via the + + input_report_key() + +call to the input system. There is no need to check whether the interrupt +routine isn't reporting two same value events (press, press for example) to +the input system, because the input_report_* functions check that +themselves. + +Then there is the + + input_sync() + +call to tell those who receive the events that we've sent a complete report. +This doesn't seem important in the one button case, but is quite important +for for example mouse movement, where you don't want the X and Y values +to be interpreted separately, because that'd result in a different movement. + +1.2 dev->open() and dev->close() +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In case the driver has to repeatedly poll the device, because it doesn't +have an interrupt coming from it and the polling is too expensive to be done +all the time, or if the device uses a valuable resource (eg. interrupt), it +can use the open and close callback to know when it can stop polling or +release the interrupt and when it must resume polling or grab the interrupt +again. To do that, we would add this to our example driver: + +int button_used = 0; + +static int button_open(struct input_dev *dev) +{ + if (button_used++) + return 0; + + if (request_irq(BUTTON_IRQ, button_interrupt, 0, "button", NULL)) { + printk(KERN_ERR "button.c: Can't allocate irq %d\n", button_irq); + button_used--; + return -EBUSY; + } + + return 0; +} + +static void button_close(struct input_dev *dev) +{ + if (!--button_used) + free_irq(IRQ_AMIGA_VERTB, button_interrupt); +} + +static int __init button_init(void) +{ + ... + button_dev.open = button_open; + button_dev.close = button_close; + ... +} + +Note the button_used variable - we have to track how many times the open +function was called to know when exactly our device stops being used. + +The open() callback should return a 0 in case of success or any nonzero value +in case of failure. The close() callback (which is void) must always succeed. + +1.3 Basic event types +~~~~~~~~~~~~~~~~~~~~~ + +The most simple event type is EV_KEY, which is used for keys and buttons. +It's reported to the input system via: + + input_report_key(struct input_dev *dev, int code, int value) + +See linux/input.h for the allowable values of code (from 0 to KEY_MAX). +Value is interpreted as a truth value, ie any nonzero value means key +pressed, zero value means key released. The input code generates events only +in case the value is different from before. + +In addition to EV_KEY, there are two more basic event types: EV_REL and +EV_ABS. They are used for relative and absolute values supplied by the +device. A relative value may be for example a mouse movement in the X axis. +The mouse reports it as a relative difference from the last position, +because it doesn't have any absolute coordinate system to work in. Absolute +events are namely for joysticks and digitizers - devices that do work in an +absolute coordinate systems. + +Having the device report EV_REL buttons is as simple as with EV_KEY, simply +set the corresponding bits and call the + + input_report_rel(struct input_dev *dev, int code, int value) + +function. Events are generated only for nonzero value. + +However EV_ABS requires a little special care. Before calling +input_register_device, you have to fill additional fields in the input_dev +struct for each absolute axis your device has. If our button device had also +the ABS_X axis: + + button_dev.absmin[ABS_X] = 0; + button_dev.absmax[ABS_X] = 255; + button_dev.absfuzz[ABS_X] = 4; + button_dev.absflat[ABS_X] = 8; + +This setting would be appropriate for a joystick X axis, with the minimum of +0, maximum of 255 (which the joystick *must* be able to reach, no problem if +it sometimes reports more, but it must be able to always reach the min and +max values), with noise in the data up to +- 4, and with a center flat +position of size 8. + +If you don't need absfuzz and absflat, you can set them to zero, which mean +that the thing is precise and always returns to exactly the center position +(if it has any). + +1.4 The void *private field +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This field in the input structure can be used to point to any private data +structures in the input device driver, in case the driver handles more than +one device. You'll need it in the open and close callbacks. + +1.5 NBITS(), LONG(), BIT() +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These three macros from input.h help some bitfield computations: + + NBITS(x) - returns the length of a bitfield array in longs for x bits + LONG(x) - returns the index in the array in longs for bit x + BIT(x) - returns the index in a long for bit x + +1.6 The number, id* and name fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The dev->number is assigned by the input system to the input device when it +is registered. It has no use except for identifying the device to the user +in system messages. + +The dev->name should be set before registering the input device by the input +device driver. It's a string like 'Generic button device' containing a +user friendly name of the device. + +The id* fields contain the bus ID (PCI, USB, ...), vendor ID and device ID +of the device. The bus IDs are defined in input.h. The vendor and device ids +are defined in pci_ids.h, usb_ids.h and similar include files. These fields +should be set by the input device driver before registering it. + +The idtype field can be used for specific information for the input device +driver. + +The id and name fields can be passed to userland via the evdev interface. + +1.7 The keycode, keycodemax, keycodesize fields +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +These two fields will be used for any input devices that report their data +as scancodes. If not all scancodes can be known by autodetection, they may +need to be set by userland utilities. The keycode array then is an array +used to map from scancodes to input system keycodes. The keycode max will +contain the size of the array and keycodesize the size of each entry in it +(in bytes). + +1.8 Key autorepeat +~~~~~~~~~~~~~~~~~~ + +... is simple. It is handled by the input.c module. Hardware autorepeat is +not used, because it's not present in many devices and even where it is +present, it is broken sometimes (at keyboards: Toshiba notebooks). To enable +autorepeat for your device, just set EV_REP in dev->evbit. All will be +handled by the input system. + +1.9 Other event types, handling output events +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The other event types up to now are: + +EV_LED - used for the keyboard LEDs. +EV_SND - used for keyboard beeps. + +They are very similar to for example key events, but they go in the other +direction - from the system to the input device driver. If your input device +driver can handle these events, it has to set the respective bits in evbit, +*and* also the callback routine: + + button_dev.event = button_event; + +int button_event(struct input_dev *dev, unsigned int type, unsigned int code, int value); +{ + if (type == EV_SND && code == SND_BELL) { + outb(value, BUTTON_BELL); + return 0; + } + return -1; +} + +This callback routine can be called from an interrupt or a BH (although that +isn't a rule), and thus must not sleep, and must not take too long to finish. |