1 ==============================================
2 Care and feeding of your Human Interface Devic
3 ==============================================
4
5 Introduction
6 ============
7
8 In addition to the normal input type HID devic
9 human interface device protocols for things th
10 interfaces, but have similar sorts of communic
11 examples for this are power devices (especiall
12 supplies) and monitor control on higher end mo
13
14 To support these disparate requirements, the L
15 HID events to two separate interfaces:
16 * the input subsystem, which converts HID even
17 device interfaces (such as keyboard, mouse and
18 normalised event interface - see Documentation
19 * the hiddev interface, which provides fairly
20
21 The data flow for a HID event produced by a de
22 the following::
23
24 usb.c ---> hid-core.c ----> hid-input.c ----
25 |
26 |
27 --> hiddev.c ----> P
28
29 In addition, other subsystems (apart from USB)
30 events into the input subsystem, but these hav
31 device interface.
32
33 Using the HID Device Interface
34 ==============================
35
36 The hiddev interface is a char interface using
37 with the minor numbers starting at 96 and fini
38 you need the following commands::
39
40 mknod /dev/usb/hiddev0 c 180 96
41 mknod /dev/usb/hiddev1 c 180 97
42 mknod /dev/usb/hiddev2 c 180 98
43 mknod /dev/usb/hiddev3 c 180 99
44 mknod /dev/usb/hiddev4 c 180 100
45 mknod /dev/usb/hiddev5 c 180 101
46 mknod /dev/usb/hiddev6 c 180 102
47 mknod /dev/usb/hiddev7 c 180 103
48 mknod /dev/usb/hiddev8 c 180 104
49 mknod /dev/usb/hiddev9 c 180 105
50 mknod /dev/usb/hiddev10 c 180 106
51 mknod /dev/usb/hiddev11 c 180 107
52 mknod /dev/usb/hiddev12 c 180 108
53 mknod /dev/usb/hiddev13 c 180 109
54 mknod /dev/usb/hiddev14 c 180 110
55 mknod /dev/usb/hiddev15 c 180 111
56
57 So you point your hiddev compliant user-space
58 interface for your device, and it all just wor
59
60 Assuming that you have a hiddev compliant user
61 course. If you need to write one, read on.
62
63
64 The HIDDEV API
65 ==============
66
67 This description should be read in conjunction
68 specification, freely available from https://w
69 conveniently linked of http://www.linux-usb.or
70
71 The hiddev API uses a read() interface, and a
72
73 HID devices exchange data with the host comput
74 bundles called "reports". Each report is divi
75 each of which can have one or more "usages".
76 each one of these usages has a single signed 3
77
78 read():
79 -------
80
81 This is the event interface. When the HID dev
82 it performs an interrupt transfer containing a
83 the changed value. The hid-core.c module pars
84 returns to hiddev.c the individual usages that
85 the report. In its basic mode, the hiddev wil
86 usage changes available to the reader using a
87
88 struct hiddev_event {
89 unsigned hid;
90 signed int value;
91 };
92
93 containing the HID usage identifier for the st
94 the value that it was changed to. Note that th
95 within <linux/hiddev.h>, along with some other
96 structures. The HID usage identifier is a com
97 page shifted to the 16 high order bits ORed wi
98 behavior of the read() function can be modifie
99 ioctl() described below.
100
101
102 ioctl():
103 --------
104
105 This is the control interface. There are a num
106
107 HIDIOCGVERSION
108 - int (read)
109
110 Gets the version code out of the hiddev drive
111
112 HIDIOCAPPLICATION
113 - (none)
114
115 This ioctl call returns the HID application us
116 HID device. The third argument to ioctl() spec
117 index to get. This is useful when the device h
118 application collection. If the index is invali
119 the number of application collections this dev
120 returns -1. You can find out beforehand how ma
121 collections the device has from the num_applic
122 hiddev_devinfo structure.
123
124 HIDIOCGCOLLECTIONINFO
125 - struct hiddev_collection_info (read/write)
126
127 This returns a superset of the information abo
128 application collections, but all the collectio
129 also returns the level the collection lives in
130 The user passes in a hiddev_collection_info st
131 field set to the index that should be returned
132 the other fields. If the index is larger than
133 index, the ioctl returns -1 and sets errno to
134
135 HIDIOCGDEVINFO
136 - struct hiddev_devinfo (read)
137
138 Gets a hiddev_devinfo structure which describe
139
140 HIDIOCGSTRING
141 - struct hiddev_string_descriptor (read/writ
142
143 Gets a string descriptor from the device. The
144 "index" field to indicate which descriptor sho
145
146 HIDIOCINITREPORT
147 - (none)
148
149 Instructs the kernel to retrieve all input and
150 from the device. At this point, all the usage
151 current values for the device, and will mainta
152 changes. Note that the use of this ioctl is u
153 since later kernels automatically initialize t
154 device at attach time.
155
156 HIDIOCGNAME
157 - string (variable length)
158
159 Gets the device name
160
161 HIDIOCGREPORT
162 - struct hiddev_report_info (write)
163
164 Instructs the kernel to get a feature or input
165 in order to selectively update the usage struc
166 INITREPORT).
167
168 HIDIOCSREPORT
169 - struct hiddev_report_info (write)
170
171 Instructs the kernel to send a report to the d
172 be filled in by the user through HIDIOCSUSAGE
173 individual usage values in the report before s
174 to the device.
175
176 HIDIOCGREPORTINFO
177 - struct hiddev_report_info (read/write)
178
179 Fills in a hiddev_report_info structure for th
180 looked up by type (input, output or feature) a
181 must be filled in by the user. The ID can be a
182 report id as reported by the device -- or rela
183 HID_REPORT_ID_FIRST for the first report, and
184 report_id) for the next report after report_id
185 information about report ids, the right way to
186 use the relative IDs above to enumerate the va
187 returns non-zero when there is no more next ID
188 filled into the returned hiddev_report_info st
189
190 HIDIOCGFIELDINFO
191 - struct hiddev_field_info (read/write)
192
193 Returns the field information associated with
194 hiddev_field_info structure. The user must fil
195 report_type in this structure, as above. The f
196 be filled in, which should be a number from 0
197 returned from a previous HIDIOCGREPORTINFO cal
198
199 HIDIOCGUCODE
200 - struct hiddev_usage_ref (read/write)
201
202 Returns the usage_code in a hiddev_usage_ref s
203 its report type, report id, field index, and i
204 field have already been filled into the struct
205
206 HIDIOCGUSAGE
207 - struct hiddev_usage_ref (read/write)
208
209 Returns the value of a usage in a hiddev_usage
210 usage to be retrieved can be specified as abov
211 choose to fill in the report_type field and sp
212 HID_REPORT_ID_UNKNOWN. In this case, the hidde
213 filled in with the report and field informatio
214 usage if it is found.
215
216 HIDIOCSUSAGE
217 - struct hiddev_usage_ref (write)
218
219 Sets the value of a usage in an output report.
220 the hiddev_usage_ref structure as above, but a
221 the value field.
222
223 HIDIOGCOLLECTIONINDEX
224 - struct hiddev_usage_ref (write)
225
226 Returns the collection index associated with t
227 indicates where in the collection hierarchy th
228
229 HIDIOCGFLAG
230 - int (read)
231 HIDIOCSFLAG
232 - int (write)
233
234 These operations respectively inspect and repl
235 that influence the read() call above. The fla
236
237 HIDDEV_FLAG_UREF
238 - read() calls will now return
239 struct hiddev_usage_ref instead of str
240 This is a larger structure, but in sit
241 device has more than one usage in its
242 same usage code, this mode serves to r
243 ambiguity.
244
245 HIDDEV_FLAG_REPORT
246 - This flag can only be used in conjunct
247 with HIDDEV_FLAG_UREF. With this flag
248 sends a report, a struct hiddev_usage_
249 to read() filled in with the report_ty
250 with field_index set to FIELD_INDEX_NO
251 additional notification when the devic
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.