patch-2.3.37 linux/Documentation/usb/hid.txt

• Lines: 163
• Date: Tue Jan 4 16:12:59 2000
• Orig file: v2.3.36/linux/Documentation/usb/hid.txt
• Orig date: Wed Dec 31 16:00:00 1969

diff -u --recursive --new-file v2.3.36/linux/Documentation/usb/hid.txt linux/Documentation/usb/hid.txt
@@ -0,0 +1,162 @@
+			   Linux HID driver v0.8
+		 (c) 1999 Vojtech Pavlik <vojtech@suse.cz>
+		    (c) 1999 Andreas Gal <agal@uwsp.edu>
+			     Sponsored by SuSE
+----------------------------------------------------------------------------
+
+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 driver for USB devices conforming to the USB HID (Human Input
+Device) standard. These devices include namely keyboards, mice and
+joysticks.
+
+  However many other devices (monitors, speakers, UPSs ...) also communicate
+through the same protocol, which makes its specification somewhat bloated.
+This isn't a problem, though, because the driver doesn't need to know about
+all the possible devices it can control, and can just parse the protocol and
+leave the rest of the job (for example understanding what the UPS wants to
+say) to the userland.
+
+  Because of this, the USB HID driver has two interfaces. One is via the
+proc filesystem, allowing userland applications send and read arbitrary
+reports to and from a connected USB device. The other is via a very simple
+yet generic input device driver, which dispatches input events (keystrokes,
+mouse or joystick movements) to specific, backward compatible userland
+interfaces. This way a PS/2 mouse, an AT keyboard or a Linux joystick driver
+interface are emulated, and allow applications to immediately work with USB
+mice, USB keyboards and USB joysticks without any changes.
+
+  The input driver is aimed for a little more than USB device handling in
+the future, though. It's generic enough so that it can be used for any
+mouse, keyboard or joystick (and more, of course). A PS/2 mouse driver, a
+serial mouse, Sun mouse, and most of the busmouse drivers were rewritten to
+use this as well as the AT keyboard and Sun keyboard drivers. This will
+hopefully allow conversion of all Linux keyboard and mouse and joystick
+drivers to this scheme.
+
+  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.
+There is also a mailing list for this:
+
+	listproc@atrey.karlin.mff.cuni.cz
+
+Send "subscribe linux-joystick Your Name" to subscribe to it.
+
+2. Usage
+~~~~~~~~
+  Since the driver comes with recent 2.3 kernels, all that's needed to use
+it is to enable it either as a module or compiled-in into the kernel. 
+
+  After that, after reboot (and possibly also inserting the USB and HID
+modules) the following will happen:
+
+* If you selected keyboard support, all USB keystrokes will be also routed
+  to the Linux keyboard driver as if being input through the ordinary system
+  keyboard.
+
+* If you selected mouse support, there will be (one or more) simulated PS/2
+  mouse devices on major 10, minor 32, 33 and more. These simulated mice can
+  in addition to a standard 3-button PS/2 mouse behave like MS Intellimice,
+  with a wheel. If you want to use the wheel, just specify '-t imps2' to gpm
+  and 'Protocol "ImPS/2"' to X, and it will work. A single emulated mouse
+  device can be open by any number of processes (unlike the /dev/psaux), and
+  for each of them the emulation is separate, each can use a different mode.
+  The mousedev driver, which emulates the mice, can also emulate a Genius
+  NewScroll 5 buttons-and-a-wheel mouse, if you set it to a Genius PS/2
+  mode ('-t netmouse' 'Protocol "NetMousePS/2"'). However, not gpm, nor X
+  can decode the 5 buttons yet, so this isn't very useful right now.
+
+* If you selected joystick support, the driver will take over major 15, the
+  joystick major number, and will emulate joysticks on it. This means the
+  normal joystick driver can't be used together with it (now, after the
+  normal joystick drivers are converted to the input scheme, all will work
+  nicely together). Also, you'll probably need to calibrate your joystick
+  manually ('man jscal') to be able to use it, because the USB
+  autocalibration is far from perfect yet.
+
+* If you selected event device support, there will be devices on major 10,
+  minors 64, 65 and more for each input device connected through this
+  driver. These devices output raw events the input driver dispatches. Each
+  has a timestamp. This hopefully will be THE way X will talk to keyboard
+  and mice, because it's hardware independent, and not limited by existing
+  de-facto standards.
+
+3. 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/hidmouse (c, 10, 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' utitily available on the
+input driver homepage (see the URL above).
+
+4. FAQ
+~~~~~~
+Q: Why aren't any questions here yet?
+A: Because none were frequent enough yet.
+
+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/inputX 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. Proc interface
+~~~~~~~~~~~~~~~~~
+  For HID-specific devices there is also the /proc interface. It isn't
+present in this release yet, though, so it's description will appear here
+together with the code in the driver.