blob: 2c67fa904adcf902cebf8e7137c0a1609d879a50 [file] [log] [blame]
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -07001.. include:: <isonum.txt>
Linus Torvalds1da177e2005-04-16 15:20:36 -07002
Dmitry Torokhovad649382017-04-15 15:16:50 -07003============
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -07004Introduction
5============
6
Dmitry Torokhovad649382017-04-15 15:16:50 -07007:Copyright: |copy| 1999-2001 Vojtech Pavlik <vojtech@ucw.cz> - Sponsored by SuSE
Linus Torvalds1da177e2005-04-16 15:20:36 -07008
Dmitry Torokhovad649382017-04-15 15:16:50 -07009Architecture
10============
11
Randy Dunlapd1c34bb2021-03-02 14:35:16 -080012Input subsystem is a collection of drivers that is designed to support
Dmitry Torokhovad649382017-04-15 15:16:50 -070013all input devices under Linux. Most of the drivers reside in
14drivers/input, although quite a few live in drivers/hid and
15drivers/platform.
16
17The core of the input subsystem is the input module, which must be
Linus Torvalds1da177e2005-04-16 15:20:36 -070018loaded before any other of the input modules - it serves as a way of
19communication between two groups of modules:
20
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070021Device drivers
22--------------
23
24These modules talk to the hardware (for example via USB), and provide
Linus Torvalds1da177e2005-04-16 15:20:36 -070025events (keystrokes, mouse movements) to the input module.
26
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070027Event handlers
28--------------
29
Dmitry Torokhovad649382017-04-15 15:16:50 -070030These modules get events from input core and pass them where needed
31via various interfaces - keystrokes to the kernel, mouse movements via
32a simulated PS/2 interface to GPM and X, and so on.
Linus Torvalds1da177e2005-04-16 15:20:36 -070033
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070034Simple Usage
35============
36
37For the most usual configuration, with one USB mouse and one USB keyboard,
Linus Torvalds1da177e2005-04-16 15:20:36 -070038you'll have to load the following modules (or have them built in to the
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070039kernel)::
Linus Torvalds1da177e2005-04-16 15:20:36 -070040
41 input
42 mousedev
Linus Torvalds1da177e2005-04-16 15:20:36 -070043 usbcore
44 uhci_hcd or ohci_hcd or ehci_hcd
45 usbhid
Dmitry Torokhovad649382017-04-15 15:16:50 -070046 hid_generic
Linus Torvalds1da177e2005-04-16 15:20:36 -070047
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070048After this, the USB keyboard will work straight away, and the USB mouse
49will be available as a character device on major 13, minor 63::
Linus Torvalds1da177e2005-04-16 15:20:36 -070050
51 crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice
52
Randy Dunlapd1c34bb2021-03-02 14:35:16 -080053This device is usually created automatically by the system. The commands
Dmitry Torokhovad649382017-04-15 15:16:50 -070054to create it by hand are::
Linus Torvalds1da177e2005-04-16 15:20:36 -070055
56 cd /dev
57 mkdir input
58 mknod input/mice c 13 63
59
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070060After that you have to point GPM (the textmode mouse cut&paste tool) and
61XFree to this device to use it - GPM should be called like::
Linus Torvalds1da177e2005-04-16 15:20:36 -070062
63 gpm -t ps2 -m /dev/input/mice
64
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070065And in X::
Linus Torvalds1da177e2005-04-16 15:20:36 -070066
67 Section "Pointer"
68 Protocol "ImPS/2"
69 Device "/dev/input/mice"
70 ZAxisMapping 4 5
71 EndSection
72
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070073When you do all of the above, you can use your USB mouse and keyboard.
Linus Torvalds1da177e2005-04-16 15:20:36 -070074
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -070075Detailed Description
76====================
77
Dmitry Torokhovad649382017-04-15 15:16:50 -070078Event handlers
79--------------
80
81Event handlers distribute the events from the devices to userspace and
82in-kernel consumers, as needed.
83
84evdev
85~~~~~
86
87``evdev`` is the generic input event interface. It passes the events
88generated in the kernel straight to the program, with timestamps. The
89event codes are the same on all architectures and are hardware
90independent.
91
92This is the preferred interface for userspace to consume user
93input, and all clients are encouraged to use it.
94
95See :ref:`event-interface` for notes on API.
96
97The devices are in /dev/input::
98
99 crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0
100 crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1
101 crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2
102 crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3
103 ...
104
105There are two ranges of minors: 64 through 95 is the static legacy
106range. If there are more than 32 input devices in a system, additional
107evdev nodes are created with minors starting with 256.
108
109keyboard
110~~~~~~~~
111
John de la Garza7dfedba2017-08-29 18:48:54 -0700112``keyboard`` is in-kernel input handler and is a part of VT code. It
Dmitry Torokhovad649382017-04-15 15:16:50 -0700113consumes keyboard keystrokes and handles user input for VT consoles.
114
115mousedev
116~~~~~~~~
117
118``mousedev`` is a hack to make legacy programs that use mouse input
119work. It takes events from either mice or digitizers/tablets and makes
120a PS/2-style (a la /dev/psaux) mouse device available to the
121userland.
122
123Mousedev devices in /dev/input (as shown above) are::
124
125 crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0
126 crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1
127 crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2
128 crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3
129 ...
130 ...
131 crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30
132 crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice
133
134Each ``mouse`` device is assigned to a single mouse or digitizer, except
135the last one - ``mice``. This single character device is shared by all
136mice and digitizers, and even if none are connected, the device is
137present. This is useful for hotplugging USB mice, so that older programs
138that do not handle hotplug can open the device even when no mice are
139present.
140
141CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
142the size of your screen (in pixels) in XFree86. This is needed if you
143want to use your digitizer in X, because its movement is sent to X
144via a virtual PS/2 mouse and thus needs to be scaled
145accordingly. These values won't be used if you use a mouse only.
146
147Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
148ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
149program reading the data wishes. You can set GPM and X to any of
150these. You'll need ImPS/2 if you want to make use of a wheel on a USB
151mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.
152
153joydev
154~~~~~~
155
156``joydev`` implements v0.x and v1.x Linux joystick API. See
157:ref:`joystick-api` for details.
158
159As soon as any joystick is connected, it can be accessed in /dev/input on::
160
161 crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0
162 crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1
163 crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2
164 crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3
165 ...
166
167And so on up to js31 in legacy range, and additional nodes with minors
168above 256 if there are more joystick devices.
169
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700170Device drivers
171--------------
172
Dmitry Torokhovad649382017-04-15 15:16:50 -0700173Device drivers are the modules that generate events.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700174
Dmitry Torokhovad649382017-04-15 15:16:50 -0700175hid-generic
176~~~~~~~~~~~
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700177
Dmitry Torokhovad649382017-04-15 15:16:50 -0700178``hid-generic`` is one of the largest and most complex driver of the
179whole suite. It handles all HID devices, and because there is a very
180wide variety of them, and because the USB HID specification isn't
181simple, it needs to be this big.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700182
Randy Dunlapd1c34bb2021-03-02 14:35:16 -0800183Currently, it handles USB mice, joysticks, gamepads, steering wheels,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700184keyboards, trackballs and digitizers.
185
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700186However, USB uses HID also for monitor controls, speaker controls, UPSs,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700187LCDs and many other purposes.
188
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700189The monitor and speaker controls should be easy to add to the hid/input
Linus Torvalds1da177e2005-04-16 15:20:36 -0700190interface, but for the UPSs and LCDs it doesn't make much sense. For this,
Mauro Carvalho Chehabcca47862019-06-28 09:19:59 -0300191the hiddev interface was designed. See Documentation/hid/hiddev.rst
Linus Torvalds1da177e2005-04-16 15:20:36 -0700192for more information about it.
193
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700194The usage of the usbhid module is very simple, it takes no parameters,
Linus Torvalds1da177e2005-04-16 15:20:36 -0700195detects everything automatically and when a HID device is inserted, it
196detects it appropriately.
197
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700198However, because the devices vary wildly, you might happen to have a
Linus Torvalds1da177e2005-04-16 15:20:36 -0700199device that doesn't work well. In that case #define DEBUG at the beginning
200of hid-core.c and send me the syslog traces.
201
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700202usbmouse
203~~~~~~~~
204
205For embedded systems, for mice with broken HID descriptors and just any
Linus Torvalds1da177e2005-04-16 15:20:36 -0700206other use when the big usbhid wouldn't be a good choice, there is the
207usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
208protocol. This also means the mice must support this simpler protocol. Not
209all do. If you don't have any strong reason to use this module, use usbhid
210instead.
211
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700212usbkbd
213~~~~~~
214
215Much like usbmouse, this module talks to keyboards with a simplified
Linus Torvalds1da177e2005-04-16 15:20:36 -0700216HIDBP protocol. It's smaller, but doesn't support any extra special keys.
217Use usbhid instead if there isn't any special reason to use this.
218
Dmitry Torokhovad649382017-04-15 15:16:50 -0700219psmouse
220~~~~~~~
221
222This is driver for all flavors of pointing devices using PS/2
223protocol, including Synaptics and ALPS touchpads, Intellimouse
224Explorer devices, Logitech PS/2 mice and so on.
225
226atkbd
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700227~~~~~
228
Dmitry Torokhovad649382017-04-15 15:16:50 -0700229This is driver for PS/2 (AT) keyboards.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700230
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700231iforce
232~~~~~~
233
234A driver for I-Force joysticks and wheels, both over USB and RS232.
Dmitry Torokhovad649382017-04-15 15:16:50 -0700235It includes Force Feedback support now, even though Immersion
Linus Torvalds1da177e2005-04-16 15:20:36 -0700236Corp. considers the protocol a trade secret and won't disclose a word
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700237about it.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700238
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700239Verifying if it works
240=====================
Linus Torvalds1da177e2005-04-16 15:20:36 -0700241
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700242Typing a couple keys on the keyboard should be enough to check that
Dmitry Torokhovad649382017-04-15 15:16:50 -0700243a keyboard works and is correctly connected to the kernel keyboard
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700244driver.
245
246Doing a ``cat /dev/input/mouse0`` (c, 13, 32) will verify that a mouse
Randy Dunlap09601522012-03-30 13:37:13 -0700247is also emulated; characters should appear if you move it.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700248
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700249You can test the joystick emulation with the ``jstest`` utility,
Dmitry Torokhovad649382017-04-15 15:16:50 -0700250available in the joystick package (see :ref:`joystick-doc`).
Linus Torvalds1da177e2005-04-16 15:20:36 -0700251
Dmitry Torokhovad649382017-04-15 15:16:50 -0700252You can test the event devices with the ``evtest`` utility.
253
254.. _event-interface:
Linus Torvalds1da177e2005-04-16 15:20:36 -0700255
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700256Event interface
257===============
258
Dmitry Torokhovad649382017-04-15 15:16:50 -0700259You can use blocking and nonblocking reads, and also select() on the
Linus Torvalds1da177e2005-04-16 15:20:36 -0700260/dev/input/eventX devices, and you'll always get a whole number of input
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700261events on a read. Their layout is::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700262
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700263 struct input_event {
264 struct timeval time;
265 unsigned short type;
266 unsigned short code;
267 unsigned int value;
268 };
Linus Torvalds1da177e2005-04-16 15:20:36 -0700269
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700270``time`` is the timestamp, it returns the time at which the event happened.
Randy Dunlapd1c34bb2021-03-02 14:35:16 -0800271Type is for example EV_REL for relative movement, EV_KEY for a keypress or
Martin Kepplingerda23e4d2017-02-09 07:53:29 +0100272release. More types are defined in include/uapi/linux/input-event-codes.h.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700273
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700274``code`` is event code, for example REL_X or KEY_BACKSPACE, again a complete
Martin Kepplingerda23e4d2017-02-09 07:53:29 +0100275list is in include/uapi/linux/input-event-codes.h.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700276
Mauro Carvalho Chehabb0f355f2017-04-04 17:29:06 -0700277``value`` is the value the event carries. Either a relative change for
Linus Torvalds1da177e2005-04-16 15:20:36 -0700278EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
279release, 1 for keypress and 2 for autorepeat.
Dmitry Torokhovad649382017-04-15 15:16:50 -0700280
281See :ref:`input-event-codes` for more information about various even codes.