1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
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.
|
