Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.
1 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.rst 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 <linux/hiddev.h>, 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.