Updates against input CVS. Lots of typo fixs and new info. Added in Q40 keyboard controller for m68k platform.

1 files changed, 101 insertions, 86 deletions

diff --git a/Documentation/input/input.txt b/Documentation/input/input.txt
index 6d1ae96dce3a..aa2a2672cfcd 100644
--- a/Documentation/input/input.txt
+++ b/Documentation/input/input.txt
@@ -1,7 +1,7 @@
 			  Linux Input drivers v1.0
-	       (c) 1999-2001 Vojtech Pavlik <vojtech@suse.cz>
+	       (c) 1999-2001 Vojtech Pavlik <vojtech@ucw.cz>
 			     Sponsored by SuSE
-	    $Id: input.txt,v 1.5 2001/06/06 11:05:33 vojtech Exp $
+	    $Id: input.txt,v 1.8 2002/05/29 03:15:01 bradleym Exp $
 ----------------------------------------------------------------------------
 
 0. Disclaimer
@@ -21,7 +21,7 @@ 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,
+- 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
@@ -30,11 +30,12 @@ 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.
+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 center of the input drivers is the input.o module, which must be
+  The centre 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:
 
@@ -59,7 +60,7 @@ kernel):
 	mousedev.o
 	keybdev.o
 	usbcore.o
-	usb-[uo]hci.o
+	usb-uhci.o or usb-ohci.o or uhci.o
 	hid.o
 
   After this, the USB keyboard will work straight away, and the USB mouse
@@ -67,8 +68,8 @@ 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:
+  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
@@ -97,9 +98,9 @@ XFree to this device to use it - GPM should be called like:
 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
+3.1.1 hid.o
 ~~~~~~~~~~~
-  Hid.c is the largest and most complex driver of the whole suite. It
+  hid.o 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.
 
@@ -120,59 +121,62 @@ 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.
+of hid-core.c and send me the syslog traces.
 
-3.1.2 usbmouse.c
+3.1.2 usbmouse.o
 ~~~~~~~~~~~~~~~~
   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
+other use when the big hid.o 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
+all do. If you don't have any strong reason to use this module, use hid.o
 instead.
 
-3.1.3 usbkbd.c
+3.1.3 usbkbd.o
 ~~~~~~~~~~~~~~
-  Much like usbmouse.c, this module talks to keyboards with a simpplified
+  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.
+Use hid.o instead if there isn't any special reason to use this.
 
-3.1.4 wacom.c
+3.1.4 wacom.o
 ~~~~~~~~~~~~~
   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.c
+3.1.5 iforce.o
 ~~~~~~~~~~~~~~~
   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.
+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.c
+3.2.1 keybdev.o
 ~~~~~~~~~~~~~~~
-  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
+  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.o
 ~~~~~~~~~~~~~~~~
-  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 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.o
 
   Mousedev devices in /dev/input (as shown above) are:
 
@@ -185,30 +189,31 @@ programs could use a more reasonable interface, for example evdev.c
 	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.
+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.
+  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. 
+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.c
 ~~~~~~~~~~~~~~
   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:
+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
@@ -218,16 +223,17 @@ any joystick is connected, it can be accessed in /dev/input on:
 
 And so on up to js31.
 
-3.2.4 evdev.c
+3.2.4 evdev.o
 ~~~~~~~~~~~~~
-  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.
+  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.
+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:
 
@@ -237,40 +243,27 @@ independent.
 	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.
+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.
+  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.
+  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 joystick emulation with the 'jstest' utility,
+available in the joystick package (see Documentation/joystick.txt).
 
-  You can test the event devics with the 'evtest' utitily available on the
-input driver homepage (see the URL above).
+  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@suse.cz> will be happy to provide you any help I
+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:
 
@@ -295,3 +288,25 @@ 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/
+