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