Documentation/input/input.txt - linux - Git at Google


            
            			  Linux Input drivers v1.0

            
            	       (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>

            
            			     Sponsored by SuSE

            
            	    $Id: input.txt,v 1.8 2002/05/29 03:15:01 bradleym Exp $

            
            ----------------------------------------------------------------------------


            0. Disclaimer

            
            ~~~~~~~~~~~~~

            
              This program is free software; you can redistribute it and/or modify it

            
            under the terms of the GNU General Public License as published by the Free

            
            Software Foundation; either version 2 of the License, or (at your option)

            
            any later version.


              This program is distributed in the hope that it will be useful, but

            
            WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY

            
            or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for

            
            more details.


              You should have received a copy of the GNU General Public License along

            
            with this program; if not, write to the Free Software Foundation, Inc., 59

            
            Temple Place, Suite 330, Boston, MA 02111-1307 USA


              Should you need to contact me, the author, you can do so either by e-mail

            
            - mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,

            
            Simunkova 1594, Prague 8, 182 00 Czech Republic


              For your convenience, the GNU General Public License version 2 is included

            
            in the package: See the file COPYING.


            1. Introduction

            
            ~~~~~~~~~~~~~~~

            
              This is a collection of drivers that is designed to support all input

            
            devices under Linux. While it is currently used only on for USB input

            
            devices, future use (say 2.5/2.6) is expected to expand to replace

            
            most of the existing input system, which is why it lives in

            
            drivers/input/ instead of drivers/usb/.


              The centre of the input drivers is the input module, which must be

            
            loaded before any other of the input modules - it serves as a way of

            
            communication between two groups of modules:


            1.1 Device drivers

            
            ~~~~~~~~~~~~~~~~~~

            
              These modules talk to the hardware (for example via USB), and provide

            
            events (keystrokes, mouse movements) to the input module.


            1.2 Event handlers

            
            ~~~~~~~~~~~~~~~~~~

            
              These modules get events from input and pass them where needed via

            
            various interfaces - keystrokes to the kernel, mouse movements via a

            
            simulated PS/2 interface to GPM and X and so on.


            2. Simple Usage

            
            ~~~~~~~~~~~~~~~

            
              For the most usual configuration, with one USB mouse and one USB keyboard,

            
            you'll have to load the following modules (or have them built in to the

            
            kernel):


            	input

            
            	mousedev

            
            	keybdev

            
            	usbcore

            
            	uhci_hcd or ohci_hcd or ehci_hcd

            
            	usbhid


              After this, the USB keyboard will work straight away, and the USB mouse

            
            will be available as a character device on major 13, minor 63:


            	crw-r--r--   1 root     root      13,  63 Mar 28 22:45 mice


              This device has to be created, unless you use devfs, in which case it's

            
            created automatically. The commands to do create it by hand are:


            	cd /dev

            
            	mkdir input

            
            	mknod input/mice c 13 63


              After that you have to point GPM (the textmode mouse cut&paste tool) and

            
            XFree to this device to use it - GPM should be called like:


            	gpm -t ps2 -m /dev/input/mice


              And in X:


            	Section "Pointer"

            
            	    Protocol    "ImPS/2"

            
            	    Device      "/dev/input/mice"

            
            	    ZAxisMapping 4 5

            
            	EndSection


              When you do all of the above, you can use your USB mouse and keyboard.


            3. Detailed Description

            
            ~~~~~~~~~~~~~~~~~~~~~~~

            
            3.1 Device drivers

            
            ~~~~~~~~~~~~~~~~~~

            
              Device drivers are the modules that generate events. The events are

            
            however not useful without being handled, so you also will need to use some

            
            of the modules from section 3.2.


            3.1.1 usbhid

            
            ~~~~~~~~~~~~

            
              usbhid is the largest and most complex driver of the whole suite. It

            
            handles all HID devices, and because there is a very wide variety of them,

            
            and because the USB HID specification isn't simple, it needs to be this big.


              Currently, it handles USB mice, joysticks, gamepads, steering wheels

            
            keyboards, trackballs and digitizers.


             However, USB uses HID also for monitor controls, speaker controls, UPSs,

            
            LCDs and many other purposes.


             The monitor and speaker controls should be easy to add to the hid/input

            
            interface, but for the UPSs and LCDs it doesn't make much sense. For this,

            
            the hiddev interface was designed. See Documentation/usb/hiddev.txt

            
            for more information about it.


              The usage of the usbhid module is very simple, it takes no parameters,

            
            detects everything automatically and when a HID device is inserted, it

            
            detects it appropriately.


              However, because the devices vary wildly, you might happen to have a

            
            device that doesn't work well. In that case #define DEBUG at the beginning

            
            of hid-core.c and send me the syslog traces.


            3.1.2 usbmouse

            
            ~~~~~~~~~~~~~~

            
              For embedded systems, for mice with broken HID descriptors and just any

            
            other use when the big usbhid wouldn't be a good choice, there is the

            
            usbmouse driver. It handles USB mice only. It uses a simpler HIDBP

            
            protocol. This also means the mice must support this simpler protocol. Not

            
            all do. If you don't have any strong reason to use this module, use usbhid

            
            instead.


            3.1.3 usbkbd

            
            ~~~~~~~~~~~~

            
              Much like usbmouse, this module talks to keyboards with a simplified

            
            HIDBP protocol. It's smaller, but doesn't support any extra special keys.

            
            Use usbhid instead if there isn't any special reason to use this.


            3.1.4 wacom

            
            ~~~~~~~~~~~

            
              This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom

            
            PenPartner, that one is handled by the HID driver. Although the Intuos and

            
            Graphire tablets claim that they are HID tablets as well, they are not and

            
            thus need this specific driver.


            3.1.5 iforce

            
            ~~~~~~~~~~~~

            
              A driver for I-Force joysticks and wheels, both over USB and RS232.

            
            It includes ForceFeedback support now, even though Immersion

            
            Corp. considers the protocol a trade secret and won't disclose a word

            
            about it.


            3.2 Event handlers

            
            ~~~~~~~~~~~~~~~~~~

            
              Event handlers distrubite the events from the devices to userland and

            
            kernel, as needed.


            3.2.1 keybdev

            
            ~~~~~~~~~~~~~

            
              keybdev is currently a rather ugly hack that translates the input

            
            events into architecture-specific keyboard raw mode (Xlated AT Set2 on

            
            x86), and passes them into the handle_scancode function of the

            
            keyboard.c module. This works well enough on all architectures that

            
            keybdev can generate rawmode on, other architectures can be added to

            
            it.


              The right way would be to pass the events to keyboard.c directly,

            
            best if keyboard.c would itself be an event handler. This is done in

            
            the input patch, available on the webpage mentioned below.


            3.2.2 mousedev

            
            ~~~~~~~~~~~~~~

            
              mousedev is also a hack to make programs that use mouse input

            
            work. It takes events from either mice or digitizers/tablets and makes

            
            a PS/2-style (a la /dev/psaux) mouse device available to the

            
            userland. Ideally, the programs could use a more reasonable interface,

            
            for example evdev


              Mousedev devices in /dev/input (as shown above) are:


            	crw-r--r--   1 root     root      13,  32 Mar 28 22:45 mouse0

            
            	crw-r--r--   1 root     root      13,  33 Mar 29 00:41 mouse1

            
            	crw-r--r--   1 root     root      13,  34 Mar 29 00:41 mouse2

            
            	crw-r--r--   1 root     root      13,  35 Apr  1 10:50 mouse3

            
            	...

            
            	...

            
            	crw-r--r--   1 root     root      13,  62 Apr  1 10:50 mouse30

            
            	crw-r--r--   1 root     root      13,  63 Apr  1 10:50 mice


            Each 'mouse' device is assigned to a single mouse or digitizer, except

            
            the last one - 'mice'. This single character device is shared by all

            
            mice and digitizers, and even if none are connected, the device is

            
            present.  This is useful for hotplugging USB mice, so that programs

            
            can open the device even when no mice are present.


              CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are

            
            the size of your screen (in pixels) in XFree86. This is needed if you

            
            want to use your digitizer in X, because its movement is sent to X

            
            via a virtual PS/2 mouse and thus needs to be scaled

            
            accordingly. These values won't be used if you use a mouse only.


              Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or

            
            ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the

            
            program reading the data wishes. You can set GPM and X to any of

            
            these. You'll need ImPS/2 if you want to make use of a wheel on a USB

            
            mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.


            3.2.3 joydev

            
            ~~~~~~~~~~~~

            
              Joydev implements v0.x and v1.x Linux joystick api, much like

            
            drivers/char/joystick/joystick.c used to in earlier versions. See

            
            joystick-api.txt in the Documentation subdirectory for details.  As

            
            soon as any joystick is connected, it can be accessed in /dev/input

            
            on:


            	crw-r--r--   1 root     root      13,   0 Apr  1 10:50 js0

            
            	crw-r--r--   1 root     root      13,   1 Apr  1 10:50 js1

            
            	crw-r--r--   1 root     root      13,   2 Apr  1 10:50 js2

            
            	crw-r--r--   1 root     root      13,   3 Apr  1 10:50 js3

            
            	...


            And so on up to js31.


            3.2.4 evdev

            
            ~~~~~~~~~~~

            
              evdev is the generic input event interface. It passes the events

            
            generated in the kernel straight to the program, with timestamps. The

            
            API is still evolving, but should be useable now. It's described in

            
            section 5.


              This should be the way for GPM and X to get keyboard and mouse mouse

            
            events. It allows for multihead in X without any specific multihead

            
            kernel support. The event codes are the same on all architectures and

            
            are hardware independent.


              The devices are in /dev/input:


            	crw-r--r--   1 root     root      13,  64 Apr  1 10:49 event0

            
            	crw-r--r--   1 root     root      13,  65 Apr  1 10:50 event1

            
            	crw-r--r--   1 root     root      13,  66 Apr  1 10:50 event2

            
            	crw-r--r--   1 root     root      13,  67 Apr  1 10:50 event3

            
            	...


            And so on up to event31.


            4. Verifying if it works

            
            ~~~~~~~~~~~~~~~~~~~~~~~~

            
              Typing a couple keys on the keyboard should be enough to check that

            
            a USB keyboard works and is correctly connected to the kernel keyboard

            
            driver.


              Doing a cat /dev/input/mouse0 (c, 13, 32) will verify that a mouse

            
            is also emulated, characters should appear if you move it.


              You can test the joystick emulation with the 'jstest' utility,

            
            available in the joystick package (see Documentation/input/joystick.txt).


              You can test the event devices with the 'evtest' utility available

            
            in the LinuxConsole project CVS archive (see the URL below).


            5. Event interface

            
            ~~~~~~~~~~~~~~~~~~

            
              Should you want to add event device support into any application (X, gpm,

            
            svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I

            
            can. Here goes a description of the current state of things, which is going

            
            to be extended, but not changed incompatibly as time goes:


              You can use blocking and nonblocking reads, also select() on the

            
            /dev/input/eventX devices, and you'll always get a whole number of input

            
            events on a read. Their layout is:


            struct input_event {

            
            	struct timeval time;

            
            	unsigned short type;

            
            	unsigned short code;

            
            	unsigned int value;

            
            };


              'time' is the timestamp, it returns the time at which the event happened.

            
            Type is for example EV_REL for relative momement, REL_KEY for a keypress or

            
            release. More types are defined in include/linux/input.h.


              'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete

            
            list is in include/linux/input.h.


              'value' is the value the event carries. Either a relative change for

            
            EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for

            
            release, 1 for keypress and 2 for autorepeat.


            6. Contacts

            
            ~~~~~~~~~~~

            
              This effort has its home page at:


            	http://www.suse.cz/development/input/


            You'll find both the latest HID driver and the complete Input driver

            
            there as well as information how to access the CVS repository for

            
            latest revisions of the drivers.


              There is also a mailing list for this:


            	majordomo@atrey.karlin.mff.cuni.cz


            Send "subscribe linux-input" to subscribe to it.


            The input changes are also being worked on as part of the LinuxConsole

            
            project, see:


            	 http://sourceforge.net/projects/linuxconsole/
	Linux Input drivers v1.0
	(c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>
	Sponsored by SuSE
	$Id: input.txt,v 1.8 2002/05/29 03:15:01 bradleym Exp $
	----------------------------------------------------------------------------

	0. Disclaimer
	~~~~~~~~~~~~~
	This program is free software; you can redistribute it and/or modify it
	under the terms of the GNU General Public License as published by the Free
	Software Foundation; either version 2 of the License, or (at your option)
	any later version.

	This program is distributed in the hope that it will be useful, but
	WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
	or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
	more details.

	You should have received a copy of the GNU General Public License along
	with this program; if not, write to the Free Software Foundation, Inc., 59
	Temple Place, Suite 330, Boston, MA 02111-1307 USA

	Should you need to contact me, the author, you can do so either by e-mail
	- mail your message to <vojtech@ucw.cz>, or by paper mail: Vojtech Pavlik,
	Simunkova 1594, Prague 8, 182 00 Czech Republic

	For your convenience, the GNU General Public License version 2 is included
	in the package: See the file COPYING.

	1. Introduction
	~~~~~~~~~~~~~~~
	This is a collection of drivers that is designed to support all input
	devices under Linux. While it is currently used only on for USB input
	devices, future use (say 2.5/2.6) is expected to expand to replace
	most of the existing input system, which is why it lives in
	drivers/input/ instead of drivers/usb/.

	The centre of the input drivers is the input module, which must be
	loaded before any other of the input modules - it serves as a way of
	communication between two groups of modules:

	1.1 Device drivers
	~~~~~~~~~~~~~~~~~~
	These modules talk to the hardware (for example via USB), and provide
	events (keystrokes, mouse movements) to the input module.

	1.2 Event handlers
	~~~~~~~~~~~~~~~~~~
	These modules get events from input and pass them where needed via
	various interfaces - keystrokes to the kernel, mouse movements via a
	simulated PS/2 interface to GPM and X and so on.

	2. Simple Usage
	~~~~~~~~~~~~~~~
	For the most usual configuration, with one USB mouse and one USB keyboard,
	you'll have to load the following modules (or have them built in to the
	kernel):

	input
	mousedev
	keybdev
	usbcore
	uhci_hcd or ohci_hcd or ehci_hcd
	usbhid

	After this, the USB keyboard will work straight away, and the USB mouse
	will be available as a character device on major 13, minor 63:

	crw-r--r-- 1 root root 13, 63 Mar 28 22:45 mice

	This device has to be created, unless you use devfs, in which case it's
	created automatically. The commands to do create it by hand are:

	cd /dev
	mkdir input
	mknod input/mice c 13 63

	After that you have to point GPM (the textmode mouse cut&paste tool) and
	XFree to this device to use it - GPM should be called like:

	gpm -t ps2 -m /dev/input/mice

	And in X:

	Section "Pointer"
	Protocol "ImPS/2"
	Device "/dev/input/mice"
	ZAxisMapping 4 5
	EndSection

	When you do all of the above, you can use your USB mouse and keyboard.

	3. Detailed Description
	~~~~~~~~~~~~~~~~~~~~~~~
	3.1 Device drivers
	~~~~~~~~~~~~~~~~~~
	Device drivers are the modules that generate events. The events are
	however not useful without being handled, so you also will need to use some
	of the modules from section 3.2.

	3.1.1 usbhid
	~~~~~~~~~~~~
	usbhid is the largest and most complex driver of the whole suite. It
	handles all HID devices, and because there is a very wide variety of them,
	and because the USB HID specification isn't simple, it needs to be this big.

	Currently, it handles USB mice, joysticks, gamepads, steering wheels
	keyboards, trackballs and digitizers.

	However, USB uses HID also for monitor controls, speaker controls, UPSs,
	LCDs and many other purposes.

	The monitor and speaker controls should be easy to add to the hid/input
	interface, but for the UPSs and LCDs it doesn't make much sense. For this,
	the hiddev interface was designed. See Documentation/usb/hiddev.txt
	for more information about it.

	The usage of the usbhid module is very simple, it takes no parameters,
	detects everything automatically and when a HID device is inserted, it
	detects it appropriately.

	However, because the devices vary wildly, you might happen to have a
	device that doesn't work well. In that case #define DEBUG at the beginning
	of hid-core.c and send me the syslog traces.

	3.1.2 usbmouse
	~~~~~~~~~~~~~~
	For embedded systems, for mice with broken HID descriptors and just any
	other use when the big usbhid wouldn't be a good choice, there is the
	usbmouse driver. It handles USB mice only. It uses a simpler HIDBP
	protocol. This also means the mice must support this simpler protocol. Not
	all do. If you don't have any strong reason to use this module, use usbhid
	instead.

	3.1.3 usbkbd
	~~~~~~~~~~~~
	Much like usbmouse, this module talks to keyboards with a simplified
	HIDBP protocol. It's smaller, but doesn't support any extra special keys.
	Use usbhid instead if there isn't any special reason to use this.

	3.1.4 wacom
	~~~~~~~~~~~
	This is a driver for Wacom Graphire and Intuos tablets. Not for Wacom
	PenPartner, that one is handled by the HID driver. Although the Intuos and
	Graphire tablets claim that they are HID tablets as well, they are not and
	thus need this specific driver.

	3.1.5 iforce
	~~~~~~~~~~~~
	A driver for I-Force joysticks and wheels, both over USB and RS232.
	It includes ForceFeedback support now, even though Immersion
	Corp. considers the protocol a trade secret and won't disclose a word
	about it.

	3.2 Event handlers
	~~~~~~~~~~~~~~~~~~
	Event handlers distrubite the events from the devices to userland and
	kernel, as needed.

	3.2.1 keybdev
	~~~~~~~~~~~~~
	keybdev is currently a rather ugly hack that translates the input
	events into architecture-specific keyboard raw mode (Xlated AT Set2 on
	x86), and passes them into the handle_scancode function of the
	keyboard.c module. This works well enough on all architectures that
	keybdev can generate rawmode on, other architectures can be added to
	it.

	The right way would be to pass the events to keyboard.c directly,
	best if keyboard.c would itself be an event handler. This is done in
	the input patch, available on the webpage mentioned below.

	3.2.2 mousedev
	~~~~~~~~~~~~~~
	mousedev is also a hack to make programs that use mouse input
	work. It takes events from either mice or digitizers/tablets and makes
	a PS/2-style (a la /dev/psaux) mouse device available to the
	userland. Ideally, the programs could use a more reasonable interface,
	for example evdev

	Mousedev devices in /dev/input (as shown above) are:

	crw-r--r-- 1 root root 13, 32 Mar 28 22:45 mouse0
	crw-r--r-- 1 root root 13, 33 Mar 29 00:41 mouse1
	crw-r--r-- 1 root root 13, 34 Mar 29 00:41 mouse2
	crw-r--r-- 1 root root 13, 35 Apr 1 10:50 mouse3
	...
	...
	crw-r--r-- 1 root root 13, 62 Apr 1 10:50 mouse30
	crw-r--r-- 1 root root 13, 63 Apr 1 10:50 mice

	Each 'mouse' device is assigned to a single mouse or digitizer, except
	the last one - 'mice'. This single character device is shared by all
	mice and digitizers, and even if none are connected, the device is
	present. This is useful for hotplugging USB mice, so that programs
	can open the device even when no mice are present.

	CONFIG_INPUT_MOUSEDEV_SCREEN_[XY] in the kernel configuration are
	the size of your screen (in pixels) in XFree86. This is needed if you
	want to use your digitizer in X, because its movement is sent to X
	via a virtual PS/2 mouse and thus needs to be scaled
	accordingly. These values won't be used if you use a mouse only.

	Mousedev will generate either PS/2, ImPS/2 (Microsoft IntelliMouse) or
	ExplorerPS/2 (IntelliMouse Explorer) protocols, depending on what the
	program reading the data wishes. You can set GPM and X to any of
	these. You'll need ImPS/2 if you want to make use of a wheel on a USB
	mouse and ExplorerPS/2 if you want to use extra (up to 5) buttons.

	3.2.3 joydev
	~~~~~~~~~~~~
	Joydev implements v0.x and v1.x Linux joystick api, much like
	drivers/char/joystick/joystick.c used to in earlier versions. See
	joystick-api.txt in the Documentation subdirectory for details. As
	soon as any joystick is connected, it can be accessed in /dev/input
	on:

	crw-r--r-- 1 root root 13, 0 Apr 1 10:50 js0
	crw-r--r-- 1 root root 13, 1 Apr 1 10:50 js1
	crw-r--r-- 1 root root 13, 2 Apr 1 10:50 js2
	crw-r--r-- 1 root root 13, 3 Apr 1 10:50 js3
	...

	And so on up to js31.

	3.2.4 evdev
	~~~~~~~~~~~
	evdev is the generic input event interface. It passes the events
	generated in the kernel straight to the program, with timestamps. The
	API is still evolving, but should be useable now. It's described in
	section 5.

	This should be the way for GPM and X to get keyboard and mouse mouse
	events. It allows for multihead in X without any specific multihead
	kernel support. The event codes are the same on all architectures and
	are hardware independent.

	The devices are in /dev/input:

	crw-r--r-- 1 root root 13, 64 Apr 1 10:49 event0
	crw-r--r-- 1 root root 13, 65 Apr 1 10:50 event1
	crw-r--r-- 1 root root 13, 66 Apr 1 10:50 event2
	crw-r--r-- 1 root root 13, 67 Apr 1 10:50 event3
	...

	And so on up to event31.

	4. Verifying if it works
	~~~~~~~~~~~~~~~~~~~~~~~~
	Typing a couple keys on the keyboard should be enough to check that
	a USB keyboard works and is correctly connected to the kernel keyboard
	driver.

	Doing a cat /dev/input/mouse0 (c, 13, 32) will verify that a mouse
	is also emulated, characters should appear if you move it.

	You can test the joystick emulation with the 'jstest' utility,
	available in the joystick package (see Documentation/input/joystick.txt).

	You can test the event devices with the 'evtest' utility available
	in the LinuxConsole project CVS archive (see the URL below).

	5. Event interface
	~~~~~~~~~~~~~~~~~~
	Should you want to add event device support into any application (X, gpm,
	svgalib ...) I <vojtech@ucw.cz> will be happy to provide you any help I
	can. Here goes a description of the current state of things, which is going
	to be extended, but not changed incompatibly as time goes:

	You can use blocking and nonblocking reads, also select() on the
	/dev/input/eventX devices, and you'll always get a whole number of input
	events on a read. Their layout is:

	struct input_event {
	struct timeval time;
	unsigned short type;
	unsigned short code;
	unsigned int value;
	};

	'time' is the timestamp, it returns the time at which the event happened.
	Type is for example EV_REL for relative momement, REL_KEY for a keypress or
	release. More types are defined in include/linux/input.h.

	'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
	list is in include/linux/input.h.

	'value' is the value the event carries. Either a relative change for
	EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
	release, 1 for keypress and 2 for autorepeat.

	6. Contacts
	~~~~~~~~~~~
	This effort has its home page at:

	http://www.suse.cz/development/input/

	You'll find both the latest HID driver and the complete Input driver
	there as well as information how to access the CVS repository for
	latest revisions of the drivers.

	There is also a mailing list for this:

	majordomo@atrey.karlin.mff.cuni.cz

	Send "subscribe linux-input" to subscribe to it.

	The input changes are also being worked on as part of the LinuxConsole
	project, see:

	http://sourceforge.net/projects/linuxconsole/