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 000000000000..180e0689676c
--- /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.