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