From: Linus Torvalds Date: Wed, 3 May 2017 19:38:20 +0000 (-0700) Subject: Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=16a12fa9aed176444fc795b09e796be41902bb08;p=GitHub%2Fmoto-9609%2Fandroid_kernel_motorola_exynos9610.git Merge branch 'for-linus' of git://git./linux/kernel/git/dtor/input Pull input subsystem updates from Dmitry Torokhov: - a big update from Mauro converting input documentation to ReST format - Synaptics PS/2 is now aware of SMBus companion devices, which means that we can now use native RMI4 protocol to handle touchpads, instead of relying on legacy PS/2 mode. - we removed support from BMA180 accelerometer from input devices as it is now handled properly by IIO - update to TSC2007 to corretcly report pressure - other miscellaneous driver fixes. * 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/dtor/input: (152 commits) Input: ar1021_i2c - use BIT to check for a bit Input: twl4030-pwrbutton - use input_set_capability() helper Input: twl4030-pwrbutton - use correct device for irq request Input: ar1021_i2c - enable touch mode during open Input: add uinput documentation dt-bindings: input: add bindings document for ar1021_i2c driver dt-bindings: input: rotary-encoder: fix typo Input: xen-kbdfront - add module parameter for setting resolution ARM: pxa/raumfeld: fix compile error in rotary controller resources Input: xpad - do not suggest writing to Dominic Input: xpad - don't use literal blocks inside footnotes Input: xpad - note that usb/devices is now at /sys/kernel/debug/ Input: docs - freshen up introduction Input: docs - split input docs into kernel- and user-facing Input: docs - note that MT-A protocol is obsolete Input: docs - update joystick documentation a bit Input: docs - remove disclaimer/GPL notice Input: fix "Game console" heading level in joystick documentation Input: rotary-encoder - remove references to platform data from docs Input: move documentation for Amiga CD32 ... --- 16a12fa9aed176444fc795b09e796be41902bb08 diff --cc Documentation/input/event-codes.rst index 000000000000,00b88f113bda..a8c0873beb95 mode 000000,100644..100644 --- a/Documentation/input/event-codes.rst +++ b/Documentation/input/event-codes.rst @@@ -1,0 -1,406 +1,409 @@@ + .. _input-event-codes: + + ================= + Input event codes + ================= + + + The input protocol uses a map of types and codes to express input device values + to userspace. This document describes the types and codes and how and when they + may be used. + + A single hardware event generates multiple input events. Each input event + contains the new value of a single data item. A special event type, EV_SYN, is + used to separate input events into packets of input data changes occurring at + the same moment in time. In the following, the term "event" refers to a single + input event encompassing a type, code, and value. + + The input protocol is a stateful protocol. Events are emitted only when values + of event codes have changed. However, the state is maintained within the Linux + input subsystem; drivers do not need to maintain the state and may attempt to + emit unchanged values without harm. Userspace may obtain the current state of + event code values using the EVIOCG* ioctls defined in linux/input.h. The event + reports supported by a device are also provided by sysfs in + class/input/event*/device/capabilities/, and the properties of a device are + provided in class/input/event*/device/properties. + + Event types + =========== + + Event types are groupings of codes under a logical input construct. Each + type has a set of applicable codes to be used in generating events. See the + Codes section for details on valid codes for each type. + + * EV_SYN: + + - Used as markers to separate events. Events may be separated in time or in + space, such as with the multitouch protocol. + + * EV_KEY: + + - Used to describe state changes of keyboards, buttons, or other key-like + devices. + + * EV_REL: + + - Used to describe relative axis value changes, e.g. moving the mouse 5 units + to the left. + + * EV_ABS: + + - Used to describe absolute axis value changes, e.g. describing the + coordinates of a touch on a touchscreen. + + * EV_MSC: + + - Used to describe miscellaneous input data that do not fit into other types. + + * EV_SW: + + - Used to describe binary state input switches. + + * EV_LED: + + - Used to turn LEDs on devices on and off. + + * EV_SND: + + - Used to output sound to devices. + + * EV_REP: + + - Used for autorepeating devices. + + * EV_FF: + + - Used to send force feedback commands to an input device. + + * EV_PWR: + + - A special type for power button and switch input. + + * EV_FF_STATUS: + + - Used to receive force feedback device status. + + Event codes + =========== + + Event codes define the precise type of event. + + EV_SYN + ------ + + EV_SYN event values are undefined. Their usage is defined only by when they are + sent in the evdev event stream. + + * SYN_REPORT: + + - Used to synchronize and separate events into packets of input data changes + occurring at the same moment in time. For example, motion of a mouse may set + the REL_X and REL_Y values for one motion, then emit a SYN_REPORT. The next + motion will emit more REL_X and REL_Y values and send another SYN_REPORT. + + * SYN_CONFIG: + + - TBD + + * SYN_MT_REPORT: + + - Used to synchronize and separate touch events. See the + multi-touch-protocol.txt document for more information. + + * SYN_DROPPED: + + - Used to indicate buffer overrun in the evdev client's event queue. + Client should ignore all events up to and including next SYN_REPORT + event and query the device (using EVIOCG* ioctls) to obtain its + current state. + + EV_KEY + ------ + + EV_KEY events take the form KEY_ or BTN_. For example, KEY_A is used + to represent the 'A' key on a keyboard. When a key is depressed, an event with + the key's code is emitted with value 1. When the key is released, an event is + emitted with value 0. Some hardware send events when a key is repeated. These + events have a value of 2. In general, KEY_ is used for keyboard keys, and + BTN_ is used for other types of momentary switch events. + + A few EV_KEY codes have special meanings: + + * BTN_TOOL_: + + - These codes are used in conjunction with input trackpads, tablets, and + touchscreens. These devices may be used with fingers, pens, or other tools. + When an event occurs and a tool is used, the corresponding BTN_TOOL_ + code should be set to a value of 1. When the tool is no longer interacting + with the input device, the BTN_TOOL_ code should be reset to 0. All + trackpads, tablets, and touchscreens should use at least one BTN_TOOL_ + code when events are generated. + + * BTN_TOUCH: + + BTN_TOUCH is used for touch contact. While an input tool is determined to be + within meaningful physical contact, the value of this property must be set + to 1. Meaningful physical contact may mean any contact, or it may mean + contact conditioned by an implementation defined property. For example, a + touchpad may set the value to 1 only when the touch pressure rises above a + certain value. BTN_TOUCH may be combined with BTN_TOOL_ codes. For + example, a pen tablet may set BTN_TOOL_PEN to 1 and BTN_TOUCH to 0 while the + pen is hovering over but not touching the tablet surface. + + Note: For appropriate function of the legacy mousedev emulation driver, + BTN_TOUCH must be the first evdev code emitted in a synchronization frame. + + Note: Historically a touch device with BTN_TOOL_FINGER and BTN_TOUCH was + interpreted as a touchpad by userspace, while a similar device without + BTN_TOOL_FINGER was interpreted as a touchscreen. For backwards compatibility + with current userspace it is recommended to follow this distinction. In the + future, this distinction will be deprecated and the device properties ioctl + EVIOCGPROP, defined in linux/input.h, will be used to convey the device type. + + * BTN_TOOL_FINGER, BTN_TOOL_DOUBLETAP, BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: + + - These codes denote one, two, three, and four finger interaction on a + trackpad or touchscreen. For example, if the user uses two fingers and moves + them on the touchpad in an effort to scroll content on screen, + BTN_TOOL_DOUBLETAP should be set to value 1 for the duration of the motion. + Note that all BTN_TOOL_ codes and the BTN_TOUCH code are orthogonal in + purpose. A trackpad event generated by finger touches should generate events + for one code from each group. At most only one of these BTN_TOOL_ + codes should have a value of 1 during any synchronization frame. + + Note: Historically some drivers emitted multiple of the finger count codes with + a value of 1 in the same synchronization frame. This usage is deprecated. + + Note: In multitouch drivers, the input_mt_report_finger_count() function should + be used to emit these codes. Please see multi-touch-protocol.txt for details. + + EV_REL + ------ + + EV_REL events describe relative changes in a property. For example, a mouse may + move to the left by a certain number of units, but its absolute position in + space is unknown. If the absolute position is known, EV_ABS codes should be used + instead of EV_REL codes. + + A few EV_REL codes have special meanings: + + * REL_WHEEL, REL_HWHEEL: + + - These codes are used for vertical and horizontal scroll wheels, + respectively. + + EV_ABS + ------ + + EV_ABS events describe absolute changes in a property. For example, a touchpad + may emit coordinates for a touch location. + + A few EV_ABS codes have special meanings: + + * ABS_DISTANCE: + + - Used to describe the distance of a tool from an interaction surface. This + event should only be emitted while the tool is hovering, meaning in close + proximity of the device and while the value of the BTN_TOUCH code is 0. If + the input device may be used freely in three dimensions, consider ABS_Z + instead. + - BTN_TOOL_ should be set to 1 when the tool comes into detectable + proximity and set to 0 when the tool leaves detectable proximity. + BTN_TOOL_ signals the type of tool that is currently detected by the + hardware and is otherwise independent of ABS_DISTANCE and/or BTN_TOUCH. + + * ABS_MT_: + + - Used to describe multitouch input events. Please see + multi-touch-protocol.txt for details. + + EV_SW + ----- + + EV_SW events describe stateful binary switches. For example, the SW_LID code is + used to denote when a laptop lid is closed. + + Upon binding to a device or resuming from suspend, a driver must report + the current switch state. This ensures that the device, kernel, and userspace + state is in sync. + + Upon resume, if the switch state is the same as before suspend, then the input + subsystem will filter out the duplicate switch state reports. The driver does + not need to keep the state of the switch at any time. + + EV_MSC + ------ + + EV_MSC events are used for input and output events that do not fall under other + categories. + + A few EV_MSC codes have special meaning: + + * MSC_TIMESTAMP: + + - Used to report the number of microseconds since the last reset. This event + should be coded as an uint32 value, which is allowed to wrap around with + no special consequence. It is assumed that the time difference between two + consecutive events is reliable on a reasonable time scale (hours). + A reset to zero can happen, in which case the time since the last event is + unknown. If the device does not provide this information, the driver must + not provide it to user space. + + EV_LED + ------ + + EV_LED events are used for input and output to set and query the state of + various LEDs on devices. + + EV_REP + ------ + + EV_REP events are used for specifying autorepeating events. + + EV_SND + ------ + + EV_SND events are used for sending sound commands to simple sound output + devices. + + EV_FF + ----- + + EV_FF events are used to initialize a force feedback capable device and to cause + such device to feedback. + + EV_PWR + ------ + + EV_PWR events are a special type of event used specifically for power + management. Its usage is not well defined. To be addressed later. + + Device properties + ================= + + Normally, userspace sets up an input device based on the data it emits, + i.e., the event types. In the case of two devices emitting the same event + types, additional information can be provided in the form of device + properties. + + INPUT_PROP_DIRECT + INPUT_PROP_POINTER + -------------------------------------- + + The INPUT_PROP_DIRECT property indicates that device coordinates should be + directly mapped to screen coordinates (not taking into account trivial + transformations, such as scaling, flipping and rotating). Non-direct input + devices require non-trivial transformation, such as absolute to relative + transformation for touchpads. Typical direct input devices: touchscreens, + drawing tablets; non-direct devices: touchpads, mice. + + The INPUT_PROP_POINTER property indicates that the device is not transposed + on the screen and thus requires use of an on-screen pointer to trace user's + movements. Typical pointer devices: touchpads, tablets, mice; non-pointer + device: touchscreen. + + If neither INPUT_PROP_DIRECT or INPUT_PROP_POINTER are set, the property is + considered undefined and the device type should be deduced in the + traditional way, using emitted event types. + + INPUT_PROP_BUTTONPAD + -------------------- + + For touchpads where the button is placed beneath the surface, such that + pressing down on the pad causes a button click, this property should be + set. Common in clickpad notebooks and macbooks from 2009 and onwards. + + Originally, the buttonpad property was coded into the bcm5974 driver + version field under the name integrated button. For backwards + compatibility, both methods need to be checked in userspace. + + INPUT_PROP_SEMI_MT + ------------------ + + Some touchpads, most common between 2008 and 2011, can detect the presence + of multiple contacts without resolving the individual positions; only the + number of contacts and a rectangular shape is known. For such + touchpads, the semi-mt property should be set. + + Depending on the device, the rectangle may enclose all touches, like a + bounding box, or just some of them, for instance the two most recent + touches. The diversity makes the rectangle of limited use, but some + gestures can normally be extracted from it. + + If INPUT_PROP_SEMI_MT is not set, the device is assumed to be a true MT + device. + + INPUT_PROP_TOPBUTTONPAD + ----------------------- + + Some laptops, most notably the Lenovo 40 series provide a trackstick + device but do not have physical buttons associated with the trackstick + device. Instead, the top area of the touchpad is marked to show + visual/haptic areas for left, middle, right buttons intended to be used + with the trackstick. + + If INPUT_PROP_TOPBUTTONPAD is set, userspace should emulate buttons + accordingly. This property does not affect kernel behavior. + The kernel does not provide button emulation for such devices but treats + them as any other INPUT_PROP_BUTTONPAD device. + + INPUT_PROP_ACCELEROMETER + ------------------------ + + Directional axes on this device (absolute and/or relative x, y, z) represent -accelerometer data. All other axes retain their meaning. A device must not mix ++accelerometer data. Some devices also report gyroscope data, which devices ++can report through the rotational axes (absolute and/or relative rx, ry, rz). ++ ++All other axes retain their meaning. A device must not mix + regular directional axes and accelerometer axes on the same event node. + + Guidelines + ========== + + The guidelines below ensure proper single-touch and multi-finger functionality. + For multi-touch functionality, see the multi-touch-protocol.txt document for + more information. + + Mice + ---- + + REL_{X,Y} must be reported when the mouse moves. BTN_LEFT must be used to report + the primary button press. BTN_{MIDDLE,RIGHT,4,5,etc.} should be used to report + further buttons of the device. REL_WHEEL and REL_HWHEEL should be used to report + scroll wheel events where available. + + Touchscreens + ------------ + + ABS_{X,Y} must be reported with the location of the touch. BTN_TOUCH must be + used to report when a touch is active on the screen. + BTN_{MOUSE,LEFT,MIDDLE,RIGHT} must not be reported as the result of touch + contact. BTN_TOOL_ events should be reported where possible. + + For new hardware, INPUT_PROP_DIRECT should be set. + + Trackpads + --------- + + Legacy trackpads that only provide relative position information must report + events like mice described above. + + Trackpads that provide absolute touch position must report ABS_{X,Y} for the + location of the touch. BTN_TOUCH should be used to report when a touch is active + on the trackpad. Where multi-finger support is available, BTN_TOOL_ should + be used to report the number of touches active on the trackpad. + + For new hardware, INPUT_PROP_POINTER should be set. + + Tablets + ------- + + BTN_TOOL_ events must be reported when a stylus or other tool is active on + the tablet. ABS_{X,Y} must be reported with the location of the tool. BTN_TOUCH + should be used to report when the tool is in contact with the tablet. + BTN_{STYLUS,STYLUS2} should be used to report buttons on the tool itself. Any + button may be used for buttons on the tablet except BTN_{MOUSE,LEFT}. + BTN_{0,1,2,etc} are good generic codes for unlabeled buttons. Do not use + meaningful buttons, like BTN_FORWARD, unless the button is labeled for that + purpose on the device. + + For new hardware, both INPUT_PROP_DIRECT and INPUT_PROP_POINTER should be set. diff --cc Documentation/input/ff.rst index 000000000000,c30f185216a0..6a265a6934e6 mode 000000,100644..100644 --- a/Documentation/input/ff.rst +++ b/Documentation/input/ff.rst @@@ -1,0 -1,264 +1,265 @@@ + ======================== + Force feedback for Linux + ======================== + + :Author: Johann Deneux on 2001/04/22. + :Updated: Anssi Hannula on 2006/04/09. + + You may redistribute this file. Please remember to include shape.svg and + interactive.svg as well. + + Introduction + ~~~~~~~~~~~~ + + This document describes how to use force feedback devices under Linux. The + goal is not to support these devices as if they were simple input-only devices + (as it is already the case), but to really enable the rendering of force + effects. + This document only describes the force feedback part of the Linux input + interface. Please read joystick.txt and input.txt before reading further this + document. + + Instructions to the user + ~~~~~~~~~~~~~~~~~~~~~~~~ + + To enable force feedback, you have to: + + 1. have your kernel configured with evdev and a driver that supports your + device. + 2. make sure evdev module is loaded and /dev/input/event* device files are + created. + + Before you start, let me WARN you that some devices shake violently during the + initialisation phase. This happens for example with my "AVB Top Shot Pegasus". + To stop this annoying behaviour, move you joystick to its limits. Anyway, you + should keep a hand on your device, in order to avoid it to break down if + something goes wrong. + + If you have a serial iforce device, you need to start inputattach. See + joystick.txt for details. + + Does it work ? + -------------- + + There is an utility called fftest that will allow you to test the driver:: + + % fftest /dev/input/eventXX + + Instructions to the developer + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + All interactions are done using the event API. That is, you can use ioctl() + and write() on /dev/input/eventXX. + This information is subject to change. + + Querying device capabilities + ---------------------------- + + :: + + #include + #include + + #define BITS_TO_LONGS(x) \ + (((x) + 8 * sizeof (unsigned long) - 1) / (8 * sizeof (unsigned long))) + unsigned long features[BITS_TO_LONGS(FF_CNT)]; + int ioctl(int file_descriptor, int request, unsigned long *features); + + "request" must be EVIOCGBIT(EV_FF, size of features array in bytes ) + + Returns the features supported by the device. features is a bitfield with the + following bits: + + - FF_CONSTANT can render constant force effects + - FF_PERIODIC can render periodic effects with the following waveforms: + + - FF_SQUARE square waveform + - FF_TRIANGLE triangle waveform + - FF_SINE sine waveform + - FF_SAW_UP sawtooth up waveform + - FF_SAW_DOWN sawtooth down waveform + - FF_CUSTOM custom waveform + + - FF_RAMP can render ramp effects + - FF_SPRING can simulate the presence of a spring + - FF_FRICTION can simulate friction + - FF_DAMPER can simulate damper effects + - FF_RUMBLE rumble effects + - FF_INERTIA can simulate inertia + - FF_GAIN gain is adjustable + - FF_AUTOCENTER autocenter is adjustable + + .. note:: + + - In most cases you should use FF_PERIODIC instead of FF_RUMBLE. All + devices that support FF_RUMBLE support FF_PERIODIC (square, triangle, + sine) and the other way around. + + - The exact syntax FF_CUSTOM is undefined for the time being as no driver + supports it yet. + + :: + + int ioctl(int fd, EVIOCGEFFECTS, int *n); + + Returns the number of effects the device can keep in its memory. + + Uploading effects to the device + ------------------------------- + + :: + + #include + #include + + int ioctl(int file_descriptor, int request, struct ff_effect *effect); + + "request" must be EVIOCSFF. + + "effect" points to a structure describing the effect to upload. The effect is + uploaded, but not played. + The content of effect may be modified. In particular, its field "id" is set + to the unique id assigned by the driver. This data is required for performing + some operations (removing an effect, controlling the playback). + This if field must be set to -1 by the user in order to tell the driver to + allocate a new effect. + + Effects are file descriptor specific. + -See for a description of the ff_effect struct. You should also -find help in a few sketches, contained in files shape.svg and interactive.svg: ++See for a description of the ff_effect struct. You ++should also find help in a few sketches, contained in files shape.svg ++and interactive.svg: + + .. figure:: shape.svg + + Shape + + .. figure:: interactive.svg + + Interactive + + + Removing an effect from the device + ---------------------------------- + + :: + + int ioctl(int fd, EVIOCRMFF, effect.id); + + This makes room for new effects in the device's memory. Note that this also + stops the effect if it was playing. + + Controlling the playback of effects + ----------------------------------- + + Control of playing is done with write(). Below is an example: + + :: + + #include + #include + + struct input_event play; + struct input_event stop; + struct ff_effect effect; + int fd; + ... + fd = open("/dev/input/eventXX", O_RDWR); + ... + /* Play three times */ + play.type = EV_FF; + play.code = effect.id; + play.value = 3; + + write(fd, (const void*) &play, sizeof(play)); + ... + /* Stop an effect */ + stop.type = EV_FF; + stop.code = effect.id; + stop.value = 0; + + write(fd, (const void*) &play, sizeof(stop)); + + Setting the gain + ---------------- + + Not all devices have the same strength. Therefore, users should set a gain + factor depending on how strong they want effects to be. This setting is + persistent across access to the driver. + + :: + + /* Set the gain of the device + int gain; /* between 0 and 100 */ + struct input_event ie; /* structure used to communicate with the driver */ + + ie.type = EV_FF; + ie.code = FF_GAIN; + ie.value = 0xFFFFUL * gain / 100; + + if (write(fd, &ie, sizeof(ie)) == -1) + perror("set gain"); + + Enabling/Disabling autocenter + ----------------------------- + + The autocenter feature quite disturbs the rendering of effects in my opinion, + and I think it should be an effect, which computation depends on the game + type. But you can enable it if you want. + + :: + + int autocenter; /* between 0 and 100 */ + struct input_event ie; + + ie.type = EV_FF; + ie.code = FF_AUTOCENTER; + ie.value = 0xFFFFUL * autocenter / 100; + + if (write(fd, &ie, sizeof(ie)) == -1) + perror("set auto-center"); + + A value of 0 means "no auto-center". + + Dynamic update of an effect + --------------------------- + + Proceed as if you wanted to upload a new effect, except that instead of + setting the id field to -1, you set it to the wanted effect id. + Normally, the effect is not stopped and restarted. However, depending on the + type of device, not all parameters can be dynamically updated. For example, + the direction of an effect cannot be updated with iforce devices. In this + case, the driver stops the effect, up-load it, and restart it. + + Therefore it is recommended to dynamically change direction while the effect + is playing only when it is ok to restart the effect with a replay count of 1. + + Information about the status of effects + --------------------------------------- + + Every time the status of an effect is changed, an event is sent. The values + and meanings of the fields of the event are as follows:: + + struct input_event { + /* When the status of the effect changed */ + struct timeval time; + + /* Set to EV_FF_STATUS */ + unsigned short type; + + /* Contains the id of the effect */ + unsigned short code; + + /* Indicates the status */ + unsigned int value; + }; + + FF_STATUS_STOPPED The effect stopped playing + FF_STATUS_PLAYING The effect started to play + + .. note:: + + - Status feedback is only supported by iforce driver. If you have + a really good reason to use this, please contact + linux-joystick@atrey.karlin.mff.cuni.cz or anssi.hannula@gmail.com + so that support for it can be added to the rest of the drivers. diff --cc Documentation/input/input-programming.rst index 000000000000,57dbab652cfa..45a4c6e05e39 mode 000000,100644..100644 --- a/Documentation/input/input-programming.rst +++ b/Documentation/input/input-programming.rst @@@ -1,0 -1,302 +1,302 @@@ + =============================== + 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 + #include + #include + + #include + #include + + 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 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 ++See uapi/linux/input-event-codes.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.