0001 .. include:: <isonum.txt>
0002
0003 ============
0004 Introduction
0005 ============
0006
0007 :Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
0008
0009 Architecture
0010 ============
0011
0012 Input subsystem is a collection of drivers that is designed to support
0013 all input devices under Linux. Most of the drivers reside in
0014 drivers/input, although quite a few live in drivers/hid and
0015 drivers/platform.
0016
0017 The core of the input subsystem is the input module, which must be
0018 loaded before any other of the input modules - it serves as a way of
0019 communication between two groups of modules:
0020
0021 Device drivers
0022 --------------
0023
0024 These modules talk to the hardware (for example via USB), and provide
0025 events (keystrokes, mouse movements) to the input module.
0026
0027 Event handlers
0028 --------------
0029
0030 These modules get events from input core and pass them where needed
0031 via various interfaces - keystrokes to the kernel, mouse movements via
0032 a simulated PS/2 interface to GPM and X, and so on.
0033
0034 Simple Usage
0035 ============
0036
0037 For the most usual configuration, with one USB mouse and one USB keyboard,
0038 you'll have to load the following modules (or have them built in to the
0039 kernel)::
0040
0041 input
0042 mousedev
0043 usbcore
0044 uhci_hcd or ohci_hcd or ehci_hcd
0045 usbhid
0046 hid_generic
0047
0048 After this, the USB keyboard will work straight away, and the USB mouse
0049 will be available as a character device on major 13, minor 63::
0050
0051 crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice
0052
0053 This device is usually created automatically by the system. The commands
0054 to create it by hand are::
0055
0056 cd /dev
0057 mkdir input
0058 mknod input/mice c 13 63
0059
0060 After that you have to point GPM (the textmode mouse cut&paste tool) and
0061 XFree to this device to use it - GPM should be called like::
0062
0063 gpm -t ps2 -m /dev/input/mice
0064
0065 And in X::
0066
0067 Section "Pointer"
0068 Protocol "ImPS/2"
0069 Device "/dev/input/mice"
0070 ZAxisMapping 4 5
0071 EndSection
0072
0073 When you do all of the above, you can use your USB mouse and keyboard.
0074
0075 Detailed Description
0076 ====================
0077
0078 Event handlers
0079 --------------
0080
0081 Event handlers distribute the events from the devices to userspace and
0082 in-kernel consumers, as needed.
0083
0084 evdev
0085 ~~~~~
0086
0087 ``evdev`` is the generic input event interface. It passes the events
0088 generated in the kernel straight to the program, with timestamps. The
0089 event codes are the same on all architectures and are hardware
0090 independent.
0091
0092 This is the preferred interface for userspace to consume user
0093 input, and all clients are encouraged to use it.
0094
0095 See :ref:`event-interface` for notes on API.
0096
0097 The devices are in /dev/input::
0098
0099 crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0
0100 crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1
0101 crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2
0102 crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3
0103 ...
0104
0105 There are two ranges of minors: 64 through 95 is the static legacy
0106 range. If there are more than 32 input devices in a system, additional
0107 evdev nodes are created with minors starting with 256.
0108
0109 keyboard
0110 ~~~~~~~~
0111
0112 ``keyboard`` is in-kernel input handler and is a part of VT code. It
0113 consumes keyboard keystrokes and handles user input for VT consoles.
0114
0115 mousedev
0116 ~~~~~~~~
0117
0118 ``mousedev`` is a hack to make legacy programs that use mouse input
0119 work. It takes events from either mice or digitizers/tablets and makes
0120 a PS/2-style (a la /dev/psaux) mouse device available to the
0121 userland.
0122
0123 Mousedev devices in /dev/input (as shown above) are::
0124
0125 crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0
0126 crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1
0127 crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2
0128 crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3
0129 ...
0130 ...
0131 crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30
0132 crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice
0133
0134 Each ``mouse`` device is assigned to a single mouse or digitizer, except
0135 the last one - ``mice``. This single character device is shared by all
0136 mice and digitizers, and even if none are connected, the device is
0137 present. This is useful for hotplugging USB mice, so that older programs
0138 that do not handle hotplug can open the device even when no mice are
0139 present.
0140
0141 CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
0142 the size of your screen (in pixels) in XFree86. This is needed if you
0143 want to use your digitizer in X, because its movement is sent to X
0144 via a virtual PS/2 mouse and thus needs to be scaled
0145 accordingly. These values won't be used if you use a mouse only.
0146
0147 Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
0148 ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
0149 program reading the data wishes. You can set GPM and X to any of
0150 these. You'll need ImPS/2 if you want to make use of a wheel on a USB
0151 mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
0152
0153 joydev
0154 ~~~~~~
0155
0156 ``joydev`` implements v0.x and v1.x Linux joystick API. See
0157 :ref:`joystick-api` for details.
0158
0159 As soon as any joystick is connected, it can be accessed in /dev/input on::
0160
0161 crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0
0162 crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1
0163 crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2
0164 crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3
0165 ...
0166
0167 And so on up to js31 in legacy range, and additional nodes with minors
0168 above 256 if there are more joystick devices.
0169
0170 Device drivers
0171 --------------
0172
0173 Device drivers are the modules that generate events.
0174
0175 hid-generic
0176 ~~~~~~~~~~~
0177
0178 ``hid-generic`` is one of the largest and most complex driver of the
0179 whole suite. It handles all HID devices, and because there is a very
0180 wide variety of them, and because the USB HID specification isn't
0181 simple, it needs to be this big.
0182
0183 Currently, it handles USB mice, joysticks, gamepads, steering wheels,
0184 keyboards, trackballs and digitizers.
0185
0186 However, USB uses HID also for monitor controls, speaker controls, UPSs,
0187 LCDs and many other purposes.
0188
0189 The monitor and speaker controls should be easy to add to the hid/input
0190 interface, but for the UPSs and LCDs it doesn't make much sense. For this,
0191 the hiddev interface was designed. See Documentation/hid/hiddev.rst
0192 for more information about it.
0193
0194 The usage of the usbhid module is very simple, it takes no parameters,
0195 detects everything automatically and when a HID device is inserted, it
0196 detects it appropriately.
0197
0198 However, because the devices vary wildly, you might happen to have a
0199 device that doesn't work well. In that case #define DEBUG at the beginning
0200 of hid-core.c and send me the syslog traces.
0201
0202 usbmouse
0203 ~~~~~~~~
0204
0205 For embedded systems, for mice with broken HID descriptors and just any
0206 other use when the big usbhid wouldn't be a good choice, there is the
0207 usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
0208 protocol. This also means the mice must support this simpler protocol. Not
0209 all do. If you don't have any strong reason to use this module, use usbhid
0210 instead.
0211
0212 usbkbd
0213 ~~~~~~
0214
0215 Much like usbmouse, this module talks to keyboards with a simplified
0216 HIDBP protocol. It's smaller, but doesn't support any extra special keys.
0217 Use usbhid instead if there isn't any special reason to use this.
0218
0219 psmouse
0220 ~~~~~~~
0221
0222 This is driver for all flavors of pointing devices using PS/2
0223 protocol, including Synaptics and ALPS touchpads, Intellimouse
0224 Explorer devices, Logitech PS/2 mice and so on.
0225
0226 atkbd
0227 ~~~~~
0228
0229 This is driver for PS/2 (AT) keyboards.
0230
0231 iforce
0232 ~~~~~~
0233
0234 A driver for I-Force joysticks and wheels, both over USB and RS232.
0235 It includes Force Feedback support now, even though Immersion
0236 Corp. considers the protocol a trade secret and won't disclose a word
0237 about it.
0238
0239 Verifying if it works
0240 =====================
0241
0242 Typing a couple keys on the keyboard should be enough to check that
0243 a keyboard works and is correctly connected to the kernel keyboard
0244 driver.
0245
0246 Doing a ``cat /dev/input/mouse0`` (c, 13, 32) will verify that a mouse
0247 is also emulated; characters should appear if you move it.
0248
0249 You can test the joystick emulation with the ``jstest`` utility,
0250 available in the joystick package (see :ref:`joystick-doc`).
0251
0252 You can test the event devices with the ``evtest`` utility.
0253
0254 .. _event-interface:
0255
0256 Event interface
0257 ===============
0258
0259 You can use blocking and nonblocking reads, and also select() on the
0260 /dev/input/eventX devices, and you'll always get a whole number of input
0261 events on a read. Their layout is::
0262
0263 struct input_event {
0264 struct timeval time;
0265 unsigned short type;
0266 unsigned short code;
0267 unsigned int value;
0268 };
0269
0270 ``time`` is the timestamp, it returns the time at which the event happened.
0271 Type is for example EV_REL for relative movement, EV_KEY for a keypress or
0272 release. More types are defined in include/uapi/linux/input-event-codes.h.
0273
0274 ``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete
0275 list is in include/uapi/linux/input-event-codes.h.
0276
0277 ``value`` is the value the event carries. Either a relative change for
0278 EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
0279 release, 1 for keypress and 2 for autorepeat.
0280
0281 See :ref:`input-event-codes` for more information about various even codes.
