About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / input / input.txt


Based on kernel version 4.10.8. Page generated on 2017-04-01 14:43 EST.

1				  Linux Input drivers v1.0
2		       (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>
3				     Sponsored by SuSE
4	----------------------------------------------------------------------------
5	
6	0. Disclaimer
7	~~~~~~~~~~~~~
8	  This program is free software; you can redistribute it and/or modify it
9	under the terms of the GNU General Public License as published by the Free
10	Software Foundation; either version 2 of the License, or (at your option)
11	any later version.
12	
13	  This program is distributed in the hope that it will be useful, but
14	WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
15	or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
16	more details.
17	
18	  You should have received a copy of the GNU General Public License along
19	with this program; if not, write to the Free Software Foundation, Inc., 59
20	Temple Place, Suite 330, Boston, MA 02111-1307 USA
21	
22	  Should you need to contact me, the author, you can do so either by e-mail
23	- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
24	Simunkova 1594, Prague 8, 182 00 Czech Republic
25	
26	  For your convenience, the GNU General Public License version 2 is included
27	in the package: See the file COPYING.
28	
29	1. Introduction
30	~~~~~~~~~~~~~~~
31	  This is a collection of drivers that is designed to support all input
32	devices under Linux. While it is currently used only on for USB input
33	devices, future use (say 2.5/2.6) is expected to expand to replace
34	most of the existing input system, which is why it lives in
35	drivers/input/ instead of drivers/usb/.
36	
37	  The centre of the input drivers is the input module, which must be
38	loaded before any other of the input modules - it serves as a way of
39	communication between two groups of modules:
40	
41	1.1 Device drivers
42	~~~~~~~~~~~~~~~~~~
43	  These modules talk to the hardware (for example via USB), and provide
44	events (keystrokes, mouse movements) to the input module.
45	
46	1.2 Event handlers
47	~~~~~~~~~~~~~~~~~~
48	  These modules get events from input and pass them where needed via
49	various interfaces - keystrokes to the kernel, mouse movements via a
50	simulated PS/2 interface to GPM and X and so on.
51	
52	2. Simple Usage
53	~~~~~~~~~~~~~~~
54	  For the most usual configuration, with one USB mouse and one USB keyboard,
55	you'll have to load the following modules (or have them built in to the
56	kernel):
57	
58		input
59		mousedev
60		keybdev
61		usbcore
62		uhci_hcd or ohci_hcd or ehci_hcd
63		usbhid
64	
65	  After this, the USB keyboard will work straight away, and the USB mouse
66	will be available as a character device on major 13, minor 63:
67	
68		crw-r--r--   1 root     root      13,  63 Mar 28 22:45 mice
69	
70	  This device has to be created.
71	  The commands to create it by hand are:
72	
73		cd /dev
74		mkdir input
75		mknod input/mice c 13 63
76	
77	  After that you have to point GPM (the textmode mouse cut&paste tool) and
78	XFree to this device to use it - GPM should be called like:
79	
80		gpm -t ps2 -m /dev/input/mice
81	
82	  And in X:
83	
84		Section "Pointer"
85		    Protocol    "ImPS/2"
86		    Device      "/dev/input/mice"
87		    ZAxisMapping 4 5
88		EndSection
89	
90	  When you do all of the above, you can use your USB mouse and keyboard.
91	
92	3. Detailed Description
93	~~~~~~~~~~~~~~~~~~~~~~~
94	3.1 Device drivers
95	~~~~~~~~~~~~~~~~~~
96	  Device drivers are the modules that generate events. The events are
97	however not useful without being handled, so you also will need to use some
98	of the modules from section 3.2.
99	
100	3.1.1 usbhid
101	~~~~~~~~~~~~
102	  usbhid is the largest and most complex driver of the whole suite. It
103	handles all HID devices, and because there is a very wide variety of them,
104	and because the USB HID specification isn't simple, it needs to be this big.
105	
106	  Currently, it handles USB mice, joysticks, gamepads, steering wheels
107	keyboards, trackballs and digitizers.
108	
109	 However, USB uses HID also for monitor controls, speaker controls, UPSs,
110	LCDs and many other purposes.
111	
112	 The monitor and speaker controls should be easy to add to the hid/input
113	interface, but for the UPSs and LCDs it doesn't make much sense. For this,
114	the hiddev interface was designed. See Documentation/hid/hiddev.txt
115	for more information about it.
116	
117	  The usage of the usbhid module is very simple, it takes no parameters,
118	detects everything automatically and when a HID device is inserted, it
119	detects it appropriately.
120	
121	  However, because the devices vary wildly, you might happen to have a
122	device that doesn't work well. In that case #define DEBUG at the beginning
123	of hid-core.c and send me the syslog traces.
124	
125	3.1.2 usbmouse
126	~~~~~~~~~~~~~~
127	  For embedded systems, for mice with broken HID descriptors and just any
128	other use when the big usbhid wouldn't be a good choice, there is the
129	usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
130	protocol. This also means the mice must support this simpler protocol. Not
131	all do. If you don't have any strong reason to use this module, use usbhid
132	instead.
133	
134	3.1.3 usbkbd
135	~~~~~~~~~~~~
136	  Much like usbmouse, this module talks to keyboards with a simplified
137	HIDBP protocol. It's smaller, but doesn't support any extra special keys.
138	Use usbhid instead if there isn't any special reason to use this.
139	
140	3.1.4 wacom
141	~~~~~~~~~~~
142	  This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
143	PenPartner, that one is handled by the HID driver. Although the Intuos and
144	Graphire tablets claim that they are HID tablets as well, they are not and
145	thus need this specific driver.
146	
147	3.1.5 iforce
148	~~~~~~~~~~~~
149	  A driver for I-Force joysticks and wheels, both over USB and RS232. 
150	It includes ForceFeedback support now, even though Immersion
151	Corp. considers the protocol a trade secret and won't disclose a word
152	about it. 
153	
154	3.2 Event handlers
155	~~~~~~~~~~~~~~~~~~
156	  Event handlers distribute the events from the devices to userland and
157	kernel, as needed.
158	
159	3.2.1 keybdev
160	~~~~~~~~~~~~~
161	  keybdev is currently a rather ugly hack that translates the input
162	events into architecture-specific keyboard raw mode (Xlated AT Set2 on
163	x86), and passes them into the handle_scancode function of the
164	keyboard.c module. This works well enough on all architectures that
165	keybdev can generate rawmode on, other architectures can be added to
166	it.
167	
168	  The right way would be to pass the events to keyboard.c directly,
169	best if keyboard.c would itself be an event handler. This is done in
170	the input patch, available on the webpage mentioned below. 
171	
172	3.2.2 mousedev
173	~~~~~~~~~~~~~~
174	  mousedev is also a hack to make programs that use mouse input
175	work. It takes events from either mice or digitizers/tablets and makes
176	a PS/2-style (a la /dev/psaux) mouse device available to the
177	userland. Ideally, the programs could use a more reasonable interface,
178	for example evdev
179	
180	  Mousedev devices in /dev/input (as shown above) are:
181	
182		crw-r--r--   1 root     root      13,  32 Mar 28 22:45 mouse0
183		crw-r--r--   1 root     root      13,  33 Mar 29 00:41 mouse1
184		crw-r--r--   1 root     root      13,  34 Mar 29 00:41 mouse2
185		crw-r--r--   1 root     root      13,  35 Apr  1 10:50 mouse3
186		...
187		...
188		crw-r--r--   1 root     root      13,  62 Apr  1 10:50 mouse30
189		crw-r--r--   1 root     root      13,  63 Apr  1 10:50 mice
190	
191	Each 'mouse' device is assigned to a single mouse or digitizer, except
192	the last one - 'mice'. This single character device is shared by all
193	mice and digitizers, and even if none are connected, the device is
194	present.  This is useful for hotplugging USB mice, so that programs
195	can open the device even when no mice are present.
196	
197	  CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
198	the size of your screen (in pixels) in XFree86. This is needed if you
199	want to use your digitizer in X, because its movement is sent to X
200	via a virtual PS/2 mouse and thus needs to be scaled
201	accordingly. These values won't be used if you use a mouse only.
202	
203	  Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
204	ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
205	program reading the data wishes. You can set GPM and X to any of
206	these. You'll need ImPS/2 if you want to make use of a wheel on a USB
207	mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons. 
208	
209	3.2.3 joydev
210	~~~~~~~~~~~~
211	  Joydev implements v0.x and v1.x Linux joystick api, much like
212	drivers/char/joystick/joystick.c used to in earlier versions. See
213	joystick-api.txt in the Documentation subdirectory for details.  As
214	soon as any joystick is connected, it can be accessed in /dev/input
215	on: 
216	
217		crw-r--r--   1 root     root      13,   0 Apr  1 10:50 js0
218		crw-r--r--   1 root     root      13,   1 Apr  1 10:50 js1
219		crw-r--r--   1 root     root      13,   2 Apr  1 10:50 js2
220		crw-r--r--   1 root     root      13,   3 Apr  1 10:50 js3
221		...
222	
223	And so on up to js31.
224	
225	3.2.4 evdev
226	~~~~~~~~~~~
227	  evdev is the generic input event interface. It passes the events
228	generated in the kernel straight to the program, with timestamps. The
229	API is still evolving, but should be usable now. It's described in
230	section 5. 
231	
232	  This should be the way for GPM and X to get keyboard and mouse
233	events. It allows for multihead in X without any specific multihead
234	kernel support. The event codes are the same on all architectures and
235	are hardware independent.
236	
237	  The devices are in /dev/input:
238	
239		crw-r--r--   1 root     root      13,  64 Apr  1 10:49 event0
240		crw-r--r--   1 root     root      13,  65 Apr  1 10:50 event1
241		crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2
242		crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3
243		...
244	
245	And so on up to event31.
246	
247	4. Verifying if it works
248	~~~~~~~~~~~~~~~~~~~~~~~~
249	  Typing a couple keys on the keyboard should be enough to check that
250	a USB keyboard works and is correctly connected to the kernel keyboard
251	driver. 
252	
253	  Doing a "cat /dev/input/mouse0" (c, 13, 32) will verify that a mouse
254	is also emulated; characters should appear if you move it.
255	
256	  You can test the joystick emulation with the 'jstest' utility,
257	available in the joystick package (see Documentation/input/joystick.txt).
258	
259	  You can test the event devices with the 'evtest' utility available
260	in the LinuxConsole project CVS archive (see the URL below).
261	
262	5. Event interface
263	~~~~~~~~~~~~~~~~~~
264	  Should you want to add event device support into any application (X, gpm,
265	svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I
266	can. Here goes a description of the current state of things, which is going
267	to be extended, but not changed incompatibly as time goes:
268	
269	  You can use blocking and nonblocking reads, also select() on the
270	/dev/input/eventX devices, and you'll always get a whole number of input
271	events on a read. Their layout is:
272	
273	struct input_event {
274		struct timeval time;
275		unsigned short type;
276		unsigned short code;
277		unsigned int value;
278	};
279	
280	  'time' is the timestamp, it returns the time at which the event happened.
281	Type is for example EV_REL for relative moment, EV_KEY for a keypress or
282	release. More types are defined in include/linux/input.h.
283	
284	  'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
285	list is in include/linux/input.h.
286	
287	  'value' is the value the event carries. Either a relative change for
288	EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
289	release, 1 for keypress and 2 for autorepeat.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog