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