--- /dev/null
-accelerometer data. All other axes retain their meaning. A device must not mix
+ .. _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_<name> or BTN_<name>. 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_<name> is used for keyboard keys, and
+ BTN_<name> is used for other types of momentary switch events.
+
+ A few EV_KEY codes have special meanings:
+
+ * BTN_TOOL_<name>:
+
+ - 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_<name>
+ code should be set to a value of 1. When the tool is no longer interacting
+ with the input device, the BTN_TOOL_<name> code should be reset to 0. All
+ trackpads, tablets, and touchscreens should use at least one BTN_TOOL_<name>
+ 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_<name> 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_<name> 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_<name>
+ 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_<name> should be set to 1 when the tool comes into detectable
+ proximity and set to 0 when the tool leaves detectable proximity.
+ BTN_TOOL_<name> 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_<name>:
+
+ - 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. 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_<name> 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_<name> 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_<name> 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.
--- /dev/null
-See <linux/input.h> 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:
+ ========================
+ Force feedback for Linux
+ ========================
+
+ :Author: Johann Deneux <johann.deneux@gmail.com> on 2001/04/22.
+ :Updated: Anssi Hannula <anssi.hannula@gmail.com> 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 <linux/input.h>
+ #include <sys/ioctl.h>
+
+ #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 <linux/input.h>
+ #include <sys/ioctl.h>
+
+ 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 <uapi/linux/input.h> 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 <linux/input.h>
+ #include <unistd.h>
+
+ 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.
--- /dev/null
-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
+ ===============================
+ 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 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.
projects / linux-2.6-block.git / commitdiff