patch-2.4.10 linux/Documentation/usb/input.txt

Next file: linux/Documentation/watchdog.txt
Previous file: linux/Documentation/usb/hiddev.txt
Back to the patch index
Back to the overall index

diff -u --recursive --new-file v2.4.9/linux/Documentation/usb/input.txt linux/Documentation/usb/input.txt
@@ -1,306 +0,0 @@
-			  Linux Input drivers v1.0
-	       (c) 1999-2000 Vojtech Pavlik <vojtech@suse.cz>
-			     Sponsored by SuSE
-	    $Id: input.txt,v 1.4 2000/05/28 17:57:22 vojtech 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@suse.cz>, or by paper mail: Vojtech Pavlik,
-Ucitelska 1576, 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. However, in the current kernels, although it's
-possibilities are much bigger, it's limited to USB devices only. This is
-also why it resides in the drivers/usb subdirectory.
-
-  The center of the input drivers is the input.o 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.o module.
-
-1.2 Event handlers
-~~~~~~~~~~~~~~~~~~
-  These modules get events from input.o 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.o
-	mousedev.o
-	keybdev.o
-	usbcore.o
-	usb-[uo]hci.o
-	hid.o
-
-  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 that 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 hid.c
-~~~~~~~~~~~
-  Hid.c 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. The driver
-doesn't support these yet, and a new, non-event interface should be designed
-for them. If you have any of these devices (I don't), feel free to design
-something and if it's good, it'll get into the driver.
-
-  The usage of the hid.o 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.c and send me the syslog traces.
-
-3.1.2 usbmouse.c
-~~~~~~~~~~~~~~~~
-  For embedded systems, for mice with broken HID descriptors and just any
-other use when the big hid.c wouldn't be a good choice, there is the
-usbmouse.c 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 hid.c
-instead.
-
-3.1.3 usbkbd.c
-~~~~~~~~~~~~~~
-  Much like usbmouse.c, this module talks to keyboards with a simplified
-HIDBP protocol. It's smaller, but doesn't support any extra special keys.
-Use hid.c instead if there isn't any special reason to use this.
-
-3.1.4 wacom.c
-~~~~~~~~~~~~~
-  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 wmforce.c
-~~~~~~~~~~~~~~~
-  A driver for the Logitech WingMan Force joysticks, when connected via the
-USB port. It works quite well, but there is no force feedback support yet,
-because the interface to do that is a trade secret of Immersion Corp, and
-even Logitech can't disclose it.
-
-  Support for Logitech WingMan Force Wheel isn't present in this driver, but
-if someone has the device, and is willing to cooperate, it should be a
-matter of a couple days to add it.
-
-3.2 Event handlers
-~~~~~~~~~~~~~~~~~~
-  Event handlers distribute the events from the devices to userland and
-kernel, as needed.
-
-3.2.1 keybdev.c
-~~~~~~~~~~~~~~~
-  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.c
-~~~~~~~~~~~~~~~~
-  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.c
-
-  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 it's 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
-GenPS/2 (Genius NetMouse/NetScroll) 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 GenPS/2 if you
-want to use extra (up to 5) buttons. I'm not sure how much is GenPS/2 supported
-in X, though.
-
-3.2.3 joydev.c
-~~~~~~~~~~~~~~
-  Joydev implements v0.x and v1.x Linux joystick api, much like
-drivers/char/joystick/joystick.c. See joystick-api.txt in the Documentation
-subdirectory for details. Joydev does it on top of the input subsystem,
-though. As soon as any USB 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.c
-~~~~~~~~~~~~~
-  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 usable 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
-	...
-
-3. Contacts
-~~~~~~~~~~~
-  This effort has it's 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.
-
-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/joystick.txt).
-
-  You can test the event devics with the 'evtest' utility available on the
-input driver homepage (see the URL above).
-
-5. Event interface
-~~~~~~~~~~~~~~~~~~
-  Should you want to add event device support into any application (X, gpm,
-svgalib ...) I <vojtech@suse.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 movement, 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.
FUNET's LINUX-ADM group, linux-adm@nic.funet.fi
TCL-scripts by Sam Shen (who was at: slshen@lbl.gov)