0001 ================================================
0002 Care and feeding of your Human Interface Devices
0003 ================================================
0004
0005 Introduction
0006 ============
0007
0008 In addition to the normal input type HID devices, USB also uses the
0009 human interface device protocols for things that are not really human
0010 interfaces, but have similar sorts of communication needs. The two big
0011 examples for this are power devices (especially uninterruptable power
0012 supplies) and monitor control on higher end monitors.
0013
0014 To support these disparate requirements, the Linux USB system provides
0015 HID events to two separate interfaces:
0016 * the input subsystem, which converts HID events into normal input
0017 device interfaces (such as keyboard, mouse and joystick) and a
0018 normalised event interface - see Documentation/input/input.rst
0019 * the hiddev interface, which provides fairly raw HID events
0020
0021 The data flow for a HID event produced by a device is something like
0022 the following::
0023
0024 usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event]
0025 |
0026 |
0027 --> hiddev.c ----> POWER / MONITOR CONTROL
0028
0029 In addition, other subsystems (apart from USB) can potentially feed
0030 events into the input subsystem, but these have no effect on the HID
0031 device interface.
0032
0033 Using the HID Device Interface
0034 ==============================
0035
0036 The hiddev interface is a char interface using the normal USB major,
0037 with the minor numbers starting at 96 and finishing at 111. Therefore,
0038 you need the following commands::
0039
0040 mknod /dev/usb/hiddev0 c 180 96
0041 mknod /dev/usb/hiddev1 c 180 97
0042 mknod /dev/usb/hiddev2 c 180 98
0043 mknod /dev/usb/hiddev3 c 180 99
0044 mknod /dev/usb/hiddev4 c 180 100
0045 mknod /dev/usb/hiddev5 c 180 101
0046 mknod /dev/usb/hiddev6 c 180 102
0047 mknod /dev/usb/hiddev7 c 180 103
0048 mknod /dev/usb/hiddev8 c 180 104
0049 mknod /dev/usb/hiddev9 c 180 105
0050 mknod /dev/usb/hiddev10 c 180 106
0051 mknod /dev/usb/hiddev11 c 180 107
0052 mknod /dev/usb/hiddev12 c 180 108
0053 mknod /dev/usb/hiddev13 c 180 109
0054 mknod /dev/usb/hiddev14 c 180 110
0055 mknod /dev/usb/hiddev15 c 180 111
0056
0057 So you point your hiddev compliant user-space program at the correct
0058 interface for your device, and it all just works.
0059
0060 Assuming that you have a hiddev compliant user-space program, of
0061 course. If you need to write one, read on.
0062
0063
0064 The HIDDEV API
0065 ==============
0066
0067 This description should be read in conjunction with the HID
0068 specification, freely available from https://www.usb.org, and
0069 conveniently linked of http://www.linux-usb.org.
0070
0071 The hiddev API uses a read() interface, and a set of ioctl() calls.
0072
0073 HID devices exchange data with the host computer using data
0074 bundles called "reports". Each report is divided into "fields",
0075 each of which can have one or more "usages". In the hid-core,
0076 each one of these usages has a single signed 32-bit value.
0077
0078 read():
0079 -------
0080
0081 This is the event interface. When the HID device's state changes,
0082 it performs an interrupt transfer containing a report which contains
0083 the changed value. The hid-core.c module parses the report, and
0084 returns to hiddev.c the individual usages that have changed within
0085 the report. In its basic mode, the hiddev will make these individual
0086 usage changes available to the reader using a struct hiddev_event::
0087
0088 struct hiddev_event {
0089 unsigned hid;
0090 signed int value;
0091 };
0092
0093 containing the HID usage identifier for the status that changed, and
0094 the value that it was changed to. Note that the structure is defined
0095 within <linux/hiddev.h>, along with some other useful #defines and
0096 structures. The HID usage identifier is a composite of the HID usage
0097 page shifted to the 16 high order bits ORed with the usage code. The
0098 behavior of the read() function can be modified using the HIDIOCSFLAG
0099 ioctl() described below.
0100
0101
0102 ioctl():
0103 --------
0104
0105 This is the control interface. There are a number of controls:
0106
0107 HIDIOCGVERSION
0108 - int (read)
0109
0110 Gets the version code out of the hiddev driver.
0111
0112 HIDIOCAPPLICATION
0113 - (none)
0114
0115 This ioctl call returns the HID application usage associated with the
0116 HID device. The third argument to ioctl() specifies which application
0117 index to get. This is useful when the device has more than one
0118 application collection. If the index is invalid (greater or equal to
0119 the number of application collections this device has) the ioctl
0120 returns -1. You can find out beforehand how many application
0121 collections the device has from the num_applications field from the
0122 hiddev_devinfo structure.
0123
0124 HIDIOCGCOLLECTIONINFO
0125 - struct hiddev_collection_info (read/write)
0126
0127 This returns a superset of the information above, providing not only
0128 application collections, but all the collections the device has. It
0129 also returns the level the collection lives in the hierarchy.
0130 The user passes in a hiddev_collection_info struct with the index
0131 field set to the index that should be returned. The ioctl fills in
0132 the other fields. If the index is larger than the last collection
0133 index, the ioctl returns -1 and sets errno to -EINVAL.
0134
0135 HIDIOCGDEVINFO
0136 - struct hiddev_devinfo (read)
0137
0138 Gets a hiddev_devinfo structure which describes the device.
0139
0140 HIDIOCGSTRING
0141 - struct hiddev_string_descriptor (read/write)
0142
0143 Gets a string descriptor from the device. The caller must fill in the
0144 "index" field to indicate which descriptor should be returned.
0145
0146 HIDIOCINITREPORT
0147 - (none)
0148
0149 Instructs the kernel to retrieve all input and feature report values
0150 from the device. At this point, all the usage structures will contain
0151 current values for the device, and will maintain it as the device
0152 changes. Note that the use of this ioctl is unnecessary in general,
0153 since later kernels automatically initialize the reports from the
0154 device at attach time.
0155
0156 HIDIOCGNAME
0157 - string (variable length)
0158
0159 Gets the device name
0160
0161 HIDIOCGREPORT
0162 - struct hiddev_report_info (write)
0163
0164 Instructs the kernel to get a feature or input report from the device,
0165 in order to selectively update the usage structures (in contrast to
0166 INITREPORT).
0167
0168 HIDIOCSREPORT
0169 - struct hiddev_report_info (write)
0170
0171 Instructs the kernel to send a report to the device. This report can
0172 be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
0173 individual usage values in the report before sending the report in full
0174 to the device.
0175
0176 HIDIOCGREPORTINFO
0177 - struct hiddev_report_info (read/write)
0178
0179 Fills in a hiddev_report_info structure for the user. The report is
0180 looked up by type (input, output or feature) and id, so these fields
0181 must be filled in by the user. The ID can be absolute -- the actual
0182 report id as reported by the device -- or relative --
0183 HID_REPORT_ID_FIRST for the first report, and (HID_REPORT_ID_NEXT |
0184 report_id) for the next report after report_id. Without a priori
0185 information about report ids, the right way to use this ioctl is to
0186 use the relative IDs above to enumerate the valid IDs. The ioctl
0187 returns non-zero when there is no more next ID. The real report ID is
0188 filled into the returned hiddev_report_info structure.
0189
0190 HIDIOCGFIELDINFO
0191 - struct hiddev_field_info (read/write)
0192
0193 Returns the field information associated with a report in a
0194 hiddev_field_info structure. The user must fill in report_id and
0195 report_type in this structure, as above. The field_index should also
0196 be filled in, which should be a number from 0 and maxfield-1, as
0197 returned from a previous HIDIOCGREPORTINFO call.
0198
0199 HIDIOCGUCODE
0200 - struct hiddev_usage_ref (read/write)
0201
0202 Returns the usage_code in a hiddev_usage_ref structure, given that
0203 its report type, report id, field index, and index within the
0204 field have already been filled into the structure.
0205
0206 HIDIOCGUSAGE
0207 - struct hiddev_usage_ref (read/write)
0208
0209 Returns the value of a usage in a hiddev_usage_ref structure. The
0210 usage to be retrieved can be specified as above, or the user can
0211 choose to fill in the report_type field and specify the report_id as
0212 HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
0213 filled in with the report and field information associated with this
0214 usage if it is found.
0215
0216 HIDIOCSUSAGE
0217 - struct hiddev_usage_ref (write)
0218
0219 Sets the value of a usage in an output report. The user fills in
0220 the hiddev_usage_ref structure as above, but additionally fills in
0221 the value field.
0222
0223 HIDIOGCOLLECTIONINDEX
0224 - struct hiddev_usage_ref (write)
0225
0226 Returns the collection index associated with this usage. This
0227 indicates where in the collection hierarchy this usage sits.
0228
0229 HIDIOCGFLAG
0230 - int (read)
0231 HIDIOCSFLAG
0232 - int (write)
0233
0234 These operations respectively inspect and replace the mode flags
0235 that influence the read() call above. The flags are as follows:
0236
0237 HIDDEV_FLAG_UREF
0238 - read() calls will now return
0239 struct hiddev_usage_ref instead of struct hiddev_event.
0240 This is a larger structure, but in situations where the
0241 device has more than one usage in its reports with the
0242 same usage code, this mode serves to resolve such
0243 ambiguity.
0244
0245 HIDDEV_FLAG_REPORT
0246 - This flag can only be used in conjunction
0247 with HIDDEV_FLAG_UREF. With this flag set, when the device
0248 sends a report, a struct hiddev_usage_ref will be returned
0249 to read() filled in with the report_type and report_id, but
0250 with field_index set to FIELD_INDEX_NONE. This serves as
0251 additional notification when the device has sent a report.
