Input: create a book with Linux Input documentation

Now that all files under Documentation/input follows the ReST markup
language, rename them to *.rst and create a book for the Linux Input
subsystem.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Dmitry Torokhov <dmitry.torokhov@gmail.com>

1 files changed, 0 insertions, 305 deletions

diff --git a/Documentation/input/input-programming.txt b/Documentation/input/input-programming.txt
deleted file mode 100644
index 4d3b22222e93..000000000000
--- a/Documentation/input/input-programming.txt
+++ /dev/null
@@ -1,305 +0,0 @@
-~~~~~~~~~~~~~~~~~~~~~~~~~
-Programming input drivers
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Creating an input device driver
-===============================
-
-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 struct input_dev *button_dev;
-
-    static irqreturn_t button_interrupt(int irq, void *dummy)
-    {
-	    input_report_key(button_dev, BTN_0, inb(BUTTON_PORT) & 1);
-	    input_sync(button_dev);
-	    return IRQ_HANDLED;
-    }
-
-    static int __init button_init(void)
-    {
-	    int error;
-
-	    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 = input_allocate_device();
-	    if (!button_dev) {
-		    printk(KERN_ERR "button.c: Not enough memory\n");
-		    error = -ENOMEM;
-		    goto err_free_irq;
-	    }
-
-	    button_dev->evbit[0] = BIT_MASK(EV_KEY);
-	    button_dev->keybit[BIT_WORD(BTN_0)] = BIT_MASK(BTN_0);
-
-	    error = input_register_device(button_dev);
-	    if (error) {
-		    printk(KERN_ERR "button.c: Failed to register device\n");
-		    goto err_free_dev;
-	    }
-
-	    return 0;
-
-    err_free_dev:
-	    input_free_device(button_dev);
-    err_free_irq:
-	    free_irq(BUTTON_IRQ, button_interrupt);
-	    return error;
-    }
-
-    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);
-
-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 allocates a new input device structure with input_allocate_device()
-and sets up 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. input_register_device() may sleep and therefore 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.
-
-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::
-
-    static int button_open(struct input_dev *dev)
-    {
-	    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;
-	    }
-
-	    return 0;
-    }
-
-    static void button_close(struct input_dev *dev)
-    {
-	    free_irq(IRQ_AMIGA_VERTB, button_interrupt);
-    }
-
-    static int __init button_init(void)
-    {
-	    ...
-	    button_dev->open = button_open;
-	    button_dev->close = button_close;
-	    ...
-    }
-
-Note that input core keeps track of number of users for the device and
-makes sure that dev->open() is called only when the first user connects
-to the device and that dev->close() is called when the very last user
-disconnects. Calls to both callbacks are serialized.
-
-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.
-
-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;
-
-Or, you can just say::
-
-	input_set_abs_params(button_dev, ABS_X, 0, 255, 4, 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).
-
-BITS_TO_LONGS(), BIT_WORD(), BIT_MASK()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-These three macros from bitops.h help some bitfield computations::
-
-	BITS_TO_LONGS(x) - returns the length of a bitfield array in longs for
-			   x bits
-	BIT_WORD(x)	 - returns the index in the array in longs for bit x
-	BIT_MASK(x)	 - returns the index in a long for bit x
-
-The id* and name fields
-~~~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-The keycode, keycodemax, keycodesize fields
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-These three fields should be used by input devices that have dense keymaps.
-The keycode is an array used to map from scancodes to input system keycodes.
-The keycode max should contain the size of the array and keycodesize the
-size of each entry in it (in bytes).
-
-Userspace can query and alter current scancode to keycode mappings using
-EVIOCGKEYCODE and EVIOCSKEYCODE ioctls on corresponding evdev interface.
-When a device has all 3 aforementioned fields filled in, the driver may
-rely on kernel's default implementation of setting and querying keycode
-mappings.
-
-dev->getkeycode() and dev->setkeycode()
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-getkeycode() and setkeycode() callbacks allow drivers to override default
-keycode/keycodesize/keycodemax mapping mechanism provided by input core
-and implement sparse keycode maps.
-
-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.
-
-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.