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.