Linux HID driver v0.8 (c) 1999 Vojtech Pavlik (c) 1999 Andreas Gal 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 , 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.