Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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 disparite 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 <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 | |
Paolo Ornati | 670e9f3 | 2006-10-03 22:57:56 +0200 | [diff] [blame] | 121 | HIDIOCGSTRING - struct hiddev_string_descriptor (read/write) |
Linus Torvalds | 1da177e | 2005-04-16 15:20:36 -0700 | [diff] [blame] | 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. |