1 |
3 |
xianfeng |
Care and feeding of your Human Interface Devices
|
2 |
|
|
|
3 |
|
|
INTRODUCTION
|
4 |
|
|
|
5 |
|
|
In addition to the normal input type HID devices, USB also uses the
|
6 |
|
|
human interface device protocols for things that are not really human
|
7 |
|
|
interfaces, but have similar sorts of communication needs. The two big
|
8 |
|
|
examples for this are power devices (especially uninterruptable power
|
9 |
|
|
supplies) and monitor control on higher end monitors.
|
10 |
|
|
|
11 |
|
|
To support these disparate requirements, the Linux USB system provides
|
12 |
|
|
HID events to two separate interfaces:
|
13 |
|
|
* the input subsystem, which converts HID events into normal input
|
14 |
|
|
device interfaces (such as keyboard, mouse and joystick) and a
|
15 |
|
|
normalised event interface - see Documentation/input/input.txt
|
16 |
|
|
* the hiddev interface, which provides fairly raw HID events
|
17 |
|
|
|
18 |
|
|
The data flow for a HID event produced by a device is something like
|
19 |
|
|
the following :
|
20 |
|
|
|
21 |
|
|
usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event]
|
22 |
|
|
|
|
23 |
|
|
|
|
24 |
|
|
--> hiddev.c ----> POWER / MONITOR CONTROL
|
25 |
|
|
|
26 |
|
|
In addition, other subsystems (apart from USB) can potentially feed
|
27 |
|
|
events into the input subsystem, but these have no effect on the hid
|
28 |
|
|
device interface.
|
29 |
|
|
|
30 |
|
|
USING THE HID DEVICE INTERFACE
|
31 |
|
|
|
32 |
|
|
The hiddev interface is a char interface using the normal USB major,
|
33 |
|
|
with the minor numbers starting at 96 and finishing at 111. Therefore,
|
34 |
|
|
you need the following commands:
|
35 |
|
|
mknod /dev/usb/hiddev0 c 180 96
|
36 |
|
|
mknod /dev/usb/hiddev1 c 180 97
|
37 |
|
|
mknod /dev/usb/hiddev2 c 180 98
|
38 |
|
|
mknod /dev/usb/hiddev3 c 180 99
|
39 |
|
|
mknod /dev/usb/hiddev4 c 180 100
|
40 |
|
|
mknod /dev/usb/hiddev5 c 180 101
|
41 |
|
|
mknod /dev/usb/hiddev6 c 180 102
|
42 |
|
|
mknod /dev/usb/hiddev7 c 180 103
|
43 |
|
|
mknod /dev/usb/hiddev8 c 180 104
|
44 |
|
|
mknod /dev/usb/hiddev9 c 180 105
|
45 |
|
|
mknod /dev/usb/hiddev10 c 180 106
|
46 |
|
|
mknod /dev/usb/hiddev11 c 180 107
|
47 |
|
|
mknod /dev/usb/hiddev12 c 180 108
|
48 |
|
|
mknod /dev/usb/hiddev13 c 180 109
|
49 |
|
|
mknod /dev/usb/hiddev14 c 180 110
|
50 |
|
|
mknod /dev/usb/hiddev15 c 180 111
|
51 |
|
|
|
52 |
|
|
So you point your hiddev compliant user-space program at the correct
|
53 |
|
|
interface for your device, and it all just works.
|
54 |
|
|
|
55 |
|
|
Assuming that you have a hiddev compliant user-space program, of
|
56 |
|
|
course. If you need to write one, read on.
|
57 |
|
|
|
58 |
|
|
|
59 |
|
|
THE HIDDEV API
|
60 |
|
|
This description should be read in conjunction with the HID
|
61 |
|
|
specification, freely available from http://www.usb.org, and
|
62 |
|
|
conveniently linked of http://www.linux-usb.org.
|
63 |
|
|
|
64 |
|
|
The hiddev API uses a read() interface, and a set of ioctl() calls.
|
65 |
|
|
|
66 |
|
|
HID devices exchange data with the host computer using data
|
67 |
|
|
bundles called "reports". Each report is divided into "fields",
|
68 |
|
|
each of which can have one or more "usages". In the hid-core,
|
69 |
|
|
each one of these usages has a single signed 32 bit value.
|
70 |
|
|
|
71 |
|
|
read():
|
72 |
|
|
This is the event interface. When the HID device's state changes,
|
73 |
|
|
it performs an interrupt transfer containing a report which contains
|
74 |
|
|
the changed value. The hid-core.c module parses the report, and
|
75 |
|
|
returns to hiddev.c the individual usages that have changed within
|
76 |
|
|
the report. In its basic mode, the hiddev will make these individual
|
77 |
|
|
usage changes available to the reader using a struct hiddev_event:
|
78 |
|
|
|
79 |
|
|
struct hiddev_event {
|
80 |
|
|
unsigned hid;
|
81 |
|
|
signed int value;
|
82 |
|
|
};
|
83 |
|
|
|
84 |
|
|
containing the HID usage identifier for the status that changed, and
|
85 |
|
|
the value that it was changed to. Note that the structure is defined
|
86 |
|
|
within , along with some other useful #defines and
|
87 |
|
|
structures. The HID usage identifier is a composite of the HID usage
|
88 |
|
|
page shifted to the 16 high order bits ORed with the usage code. The
|
89 |
|
|
behavior of the read() function can be modified using the HIDIOCSFLAG
|
90 |
|
|
ioctl() described below.
|
91 |
|
|
|
92 |
|
|
|
93 |
|
|
ioctl():
|
94 |
|
|
This is the control interface. There are a number of controls:
|
95 |
|
|
|
96 |
|
|
HIDIOCGVERSION - int (read)
|
97 |
|
|
Gets the version code out of the hiddev driver.
|
98 |
|
|
|
99 |
|
|
HIDIOCAPPLICATION - (none)
|
100 |
|
|
This ioctl call returns the HID application usage associated with the
|
101 |
|
|
hid device. The third argument to ioctl() specifies which application
|
102 |
|
|
index to get. This is useful when the device has more than one
|
103 |
|
|
application collection. If the index is invalid (greater or equal to
|
104 |
|
|
the number of application collections this device has) the ioctl
|
105 |
|
|
returns -1. You can find out beforehand how many application
|
106 |
|
|
collections the device has from the num_applications field from the
|
107 |
|
|
hiddev_devinfo structure.
|
108 |
|
|
|
109 |
|
|
HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
|
110 |
|
|
This returns a superset of the information above, providing not only
|
111 |
|
|
application collections, but all the collections the device has. It
|
112 |
|
|
also returns the level the collection lives in the hierarchy.
|
113 |
|
|
The user passes in a hiddev_collection_info struct with the index
|
114 |
|
|
field set to the index that should be returned. The ioctl fills in
|
115 |
|
|
the other fields. If the index is larger than the last collection
|
116 |
|
|
index, the ioctl returns -1 and sets errno to -EINVAL.
|
117 |
|
|
|
118 |
|
|
HIDIOCGDEVINFO - struct hiddev_devinfo (read)
|
119 |
|
|
Gets a hiddev_devinfo structure which describes the device.
|
120 |
|
|
|
121 |
|
|
HIDIOCGSTRING - struct hiddev_string_descriptor (read/write)
|
122 |
|
|
Gets a string descriptor from the device. The caller must fill in the
|
123 |
|
|
"index" field to indicate which descriptor should be returned.
|
124 |
|
|
|
125 |
|
|
HIDIOCINITREPORT - (none)
|
126 |
|
|
Instructs the kernel to retrieve all input and feature report values
|
127 |
|
|
from the device. At this point, all the usage structures will contain
|
128 |
|
|
current values for the device, and will maintain it as the device
|
129 |
|
|
changes. Note that the use of this ioctl is unnecessary in general,
|
130 |
|
|
since later kernels automatically initialize the reports from the
|
131 |
|
|
device at attach time.
|
132 |
|
|
|
133 |
|
|
HIDIOCGNAME - string (variable length)
|
134 |
|
|
Gets the device name
|
135 |
|
|
|
136 |
|
|
HIDIOCGREPORT - struct hiddev_report_info (write)
|
137 |
|
|
Instructs the kernel to get a feature or input report from the device,
|
138 |
|
|
in order to selectively update the usage structures (in contrast to
|
139 |
|
|
INITREPORT).
|
140 |
|
|
|
141 |
|
|
HIDIOCSREPORT - struct hiddev_report_info (write)
|
142 |
|
|
Instructs the kernel to send a report to the device. This report can
|
143 |
|
|
be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
|
144 |
|
|
individual usage values in the report before sending the report in full
|
145 |
|
|
to the device.
|
146 |
|
|
|
147 |
|
|
HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
|
148 |
|
|
Fills in a hiddev_report_info structure for the user. The report is
|
149 |
|
|
looked up by type (input, output or feature) and id, so these fields
|
150 |
|
|
must be filled in by the user. The ID can be absolute -- the actual
|
151 |
|
|
report id as reported by the device -- or relative --
|
152 |
|
|
HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT |
|
153 |
|
|
report_id) for the next report after report_id. Without a-priori
|
154 |
|
|
information about report ids, the right way to use this ioctl is to
|
155 |
|
|
use the relative IDs above to enumerate the valid IDs. The ioctl
|
156 |
|
|
returns non-zero when there is no more next ID. The real report ID is
|
157 |
|
|
filled into the returned hiddev_report_info structure.
|
158 |
|
|
|
159 |
|
|
HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
|
160 |
|
|
Returns the field information associated with a report in a
|
161 |
|
|
hiddev_field_info structure. The user must fill in report_id and
|
162 |
|
|
report_type in this structure, as above. The field_index should also
|
163 |
|
|
be filled in, which should be a number from 0 and maxfield-1, as
|
164 |
|
|
returned from a previous HIDIOCGREPORTINFO call.
|
165 |
|
|
|
166 |
|
|
HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
|
167 |
|
|
Returns the usage_code in a hiddev_usage_ref structure, given that
|
168 |
|
|
given its report type, report id, field index, and index within the
|
169 |
|
|
field have already been filled into the structure.
|
170 |
|
|
|
171 |
|
|
HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
|
172 |
|
|
Returns the value of a usage in a hiddev_usage_ref structure. The
|
173 |
|
|
usage to be retrieved can be specified as above, or the user can
|
174 |
|
|
choose to fill in the report_type field and specify the report_id as
|
175 |
|
|
HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
|
176 |
|
|
filled in with the report and field information associated with this
|
177 |
|
|
usage if it is found.
|
178 |
|
|
|
179 |
|
|
HIDIOCSUSAGE - struct hiddev_usage_ref (write)
|
180 |
|
|
Sets the value of a usage in an output report. The user fills in
|
181 |
|
|
the hiddev_usage_ref structure as above, but additionally fills in
|
182 |
|
|
the value field.
|
183 |
|
|
|
184 |
|
|
HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
|
185 |
|
|
Returns the collection index associated with this usage. This
|
186 |
|
|
indicates where in the collection hierarchy this usage sits.
|
187 |
|
|
|
188 |
|
|
HIDIOCGFLAG - int (read)
|
189 |
|
|
HIDIOCSFLAG - int (write)
|
190 |
|
|
These operations respectively inspect and replace the mode flags
|
191 |
|
|
that influence the read() call above. The flags are as follows:
|
192 |
|
|
|
193 |
|
|
HIDDEV_FLAG_UREF - read() calls will now return
|
194 |
|
|
struct hiddev_usage_ref instead of struct hiddev_event.
|
195 |
|
|
This is a larger structure, but in situations where the
|
196 |
|
|
device has more than one usage in its reports with the
|
197 |
|
|
same usage code, this mode serves to resolve such
|
198 |
|
|
ambiguity.
|
199 |
|
|
|
200 |
|
|
HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
|
201 |
|
|
with HIDDEV_FLAG_UREF. With this flag set, when the device
|
202 |
|
|
sends a report, a struct hiddev_usage_ref will be returned
|
203 |
|
|
to read() filled in with the report_type and report_id, but
|
204 |
|
|
with field_index set to FIELD_INDEX_NONE. This serves as
|
205 |
|
|
additional notification when the device has sent a report.
|