Commit | Line | Data |
---|---|---|
cca47861 MCC |
1 | ========================= |
2 | HID I/O Transport Drivers | |
3 | ========================= | |
6fad42d5 BT |
4 | |
5 | The HID subsystem is independent of the underlying transport driver. Initially, | |
6 | only USB was supported, but other specifications adopted the HID design and | |
7 | provided new transport drivers. The kernel includes at least support for USB, | |
8 | Bluetooth, I2C and user-space I/O drivers. | |
9 | ||
10 | 1) HID Bus | |
11 | ========== | |
12 | ||
13 | The HID subsystem is designed as a bus. Any I/O subsystem may provide HID | |
14 | devices and register them with the HID bus. HID core then loads generic device | |
15 | drivers on top of it. The transport drivers are responsible of raw data | |
16 | transport and device setup/management. HID core is responsible of | |
17 | report-parsing, report interpretation and the user-space API. Device specifics | |
18 | and quirks are handled by all layers depending on the quirk. | |
19 | ||
cca47861 MCC |
20 | :: |
21 | ||
6fad42d5 BT |
22 | +-----------+ +-----------+ +-----------+ +-----------+ |
23 | | Device #1 | | Device #i | | Device #j | | Device #k | | |
24 | +-----------+ +-----------+ +-----------+ +-----------+ | |
25 | \\ // \\ // | |
26 | +------------+ +------------+ | |
27 | | I/O Driver | | I/O Driver | | |
28 | +------------+ +------------+ | |
29 | || || | |
30 | +------------------+ +------------------+ | |
31 | | Transport Driver | | Transport Driver | | |
32 | +------------------+ +------------------+ | |
33 | \___ ___/ | |
34 | \ / | |
35 | +----------------+ | |
36 | | HID Core | | |
37 | +----------------+ | |
38 | / | | \ | |
39 | / | | \ | |
40 | ____________/ | | \_________________ | |
41 | / | | \ | |
42 | / | | \ | |
43 | +----------------+ +-----------+ +------------------+ +------------------+ | |
44 | | Generic Driver | | MT Driver | | Custom Driver #1 | | Custom Driver #2 | | |
45 | +----------------+ +-----------+ +------------------+ +------------------+ | |
46 | ||
47 | Example Drivers: | |
cca47861 MCC |
48 | |
49 | - I/O: USB, I2C, Bluetooth-l2cap | |
50 | - Transport: USB-HID, I2C-HID, BT-HIDP | |
6fad42d5 BT |
51 | |
52 | Everything below "HID Core" is simplified in this graph as it is only of | |
53 | interest to HID device drivers. Transport drivers do not need to know the | |
54 | specifics. | |
55 | ||
56 | 1.1) Device Setup | |
57 | ----------------- | |
58 | ||
59 | I/O drivers normally provide hotplug detection or device enumeration APIs to the | |
60 | transport drivers. Transport drivers use this to find any suitable HID device. | |
61 | They allocate HID device objects and register them with HID core. Transport | |
62 | drivers are not required to register themselves with HID core. HID core is never | |
63 | aware of which transport drivers are available and is not interested in it. It | |
64 | is only interested in devices. | |
65 | ||
66 | Transport drivers attach a constant "struct hid_ll_driver" object with each | |
67 | device. Once a device is registered with HID core, the callbacks provided via | |
68 | this struct are used by HID core to communicate with the device. | |
69 | ||
70 | Transport drivers are responsible of detecting device failures and unplugging. | |
71 | HID core will operate a device as long as it is registered regardless of any | |
72 | device failures. Once transport drivers detect unplug or failure events, they | |
73 | must unregister the device from HID core and HID core will stop using the | |
74 | provided callbacks. | |
75 | ||
76 | 1.2) Transport Driver Requirements | |
77 | ---------------------------------- | |
78 | ||
79 | The terms "asynchronous" and "synchronous" in this document describe the | |
80 | transmission behavior regarding acknowledgements. An asynchronous channel must | |
81 | not perform any synchronous operations like waiting for acknowledgements or | |
82 | verifications. Generally, HID calls operating on asynchronous channels must be | |
83 | running in atomic-context just fine. | |
84 | On the other hand, synchronous channels can be implemented by the transport | |
85 | driver in whatever way they like. They might just be the same as asynchronous | |
86 | channels, but they can also provide acknowledgement reports, automatic | |
87 | retransmission on failure, etc. in a blocking manner. If such functionality is | |
88 | required on asynchronous channels, a transport-driver must implement that via | |
89 | its own worker threads. | |
90 | ||
91 | HID core requires transport drivers to follow a given design. A Transport | |
92 | driver must provide two bi-directional I/O channels to each HID device. These | |
93 | channels must not necessarily be bi-directional in the hardware itself. A | |
94 | transport driver might just provide 4 uni-directional channels. Or it might | |
95 | multiplex all four on a single physical channel. However, in this document we | |
96 | will describe them as two bi-directional channels as they have several | |
97 | properties in common. | |
98 | ||
99 | - Interrupt Channel (intr): The intr channel is used for asynchronous data | |
100 | reports. No management commands or data acknowledgements are sent on this | |
101 | channel. Any unrequested incoming or outgoing data report must be sent on | |
102 | this channel and is never acknowledged by the remote side. Devices usually | |
103 | send their input events on this channel. Outgoing events are normally | |
104 | not send via intr, except if high throughput is required. | |
105 | - Control Channel (ctrl): The ctrl channel is used for synchronous requests and | |
106 | device management. Unrequested data input events must not be sent on this | |
107 | channel and are normally ignored. Instead, devices only send management | |
108 | events or answers to host requests on this channel. | |
109 | The control-channel is used for direct blocking queries to the device | |
110 | independent of any events on the intr-channel. | |
111 | Outgoing reports are usually sent on the ctrl channel via synchronous | |
112 | SET_REPORT requests. | |
113 | ||
114 | Communication between devices and HID core is mostly done via HID reports. A | |
115 | report can be of one of three types: | |
116 | ||
117 | - INPUT Report: Input reports provide data from device to host. This | |
118 | data may include button events, axis events, battery status or more. This | |
119 | data is generated by the device and sent to the host with or without | |
120 | requiring explicit requests. Devices can choose to send data continuously or | |
121 | only on change. | |
122 | - OUTPUT Report: Output reports change device states. They are sent from host | |
123 | to device and may include LED requests, rumble requests or more. Output | |
124 | reports are never sent from device to host, but a host can retrieve their | |
125 | current state. | |
126 | Hosts may choose to send output reports either continuously or only on | |
127 | change. | |
128 | - FEATURE Report: Feature reports are used for specific static device features | |
129 | and never reported spontaneously. A host can read and/or write them to access | |
130 | data like battery-state or device-settings. | |
131 | Feature reports are never sent without requests. A host must explicitly set | |
132 | or retrieve a feature report. This also means, feature reports are never sent | |
133 | on the intr channel as this channel is asynchronous. | |
134 | ||
135 | INPUT and OUTPUT reports can be sent as pure data reports on the intr channel. | |
136 | For INPUT reports this is the usual operational mode. But for OUTPUT reports, | |
137 | this is rarely done as OUTPUT reports are normally quite scarce. But devices are | |
138 | free to make excessive use of asynchronous OUTPUT reports (for instance, custom | |
139 | HID audio speakers make great use of it). | |
140 | ||
141 | Plain reports must not be sent on the ctrl channel, though. Instead, the ctrl | |
142 | channel provides synchronous GET/SET_REPORT requests. Plain reports are only | |
143 | allowed on the intr channel and are the only means of data there. | |
144 | ||
145 | - GET_REPORT: A GET_REPORT request has a report ID as payload and is sent | |
146 | from host to device. The device must answer with a data report for the | |
147 | requested report ID on the ctrl channel as a synchronous acknowledgement. | |
148 | Only one GET_REPORT request can be pending for each device. This restriction | |
149 | is enforced by HID core as several transport drivers don't allow multiple | |
150 | simultaneous GET_REPORT requests. | |
151 | Note that data reports which are sent as answer to a GET_REPORT request are | |
152 | not handled as generic device events. That is, if a device does not operate | |
153 | in continuous data reporting mode, an answer to GET_REPORT does not replace | |
154 | the raw data report on the intr channel on state change. | |
155 | GET_REPORT is only used by custom HID device drivers to query device state. | |
156 | Normally, HID core caches any device state so this request is not necessary | |
157 | on devices that follow the HID specs except during device initialization to | |
158 | retrieve the current state. | |
159 | GET_REPORT requests can be sent for any of the 3 report types and shall | |
160 | return the current report state of the device. However, OUTPUT reports as | |
161 | payload may be blocked by the underlying transport driver if the | |
162 | specification does not allow them. | |
163 | - SET_REPORT: A SET_REPORT request has a report ID plus data as payload. It is | |
164 | sent from host to device and a device must update it's current report state | |
165 | according to the given data. Any of the 3 report types can be used. However, | |
166 | INPUT reports as payload might be blocked by the underlying transport driver | |
167 | if the specification does not allow them. | |
168 | A device must answer with a synchronous acknowledgement. However, HID core | |
169 | does not require transport drivers to forward this acknowledgement to HID | |
170 | core. | |
171 | Same as for GET_REPORT, only one SET_REPORT can be pending at a time. This | |
172 | restriction is enforced by HID core as some transport drivers do not support | |
173 | multiple synchronous SET_REPORT requests. | |
174 | ||
175 | Other ctrl-channel requests are supported by USB-HID but are not available | |
176 | (or deprecated) in most other transport level specifications: | |
177 | ||
178 | - GET/SET_IDLE: Only used by USB-HID and I2C-HID. | |
179 | - GET/SET_PROTOCOL: Not used by HID core. | |
180 | - RESET: Used by I2C-HID, not hooked up in HID core. | |
181 | - SET_POWER: Used by I2C-HID, not hooked up in HID core. | |
182 | ||
183 | 2) HID API | |
184 | ========== | |
185 | ||
186 | 2.1) Initialization | |
187 | ------------------- | |
188 | ||
189 | Transport drivers normally use the following procedure to register a new device | |
cca47861 | 190 | with HID core:: |
6fad42d5 BT |
191 | |
192 | struct hid_device *hid; | |
193 | int ret; | |
194 | ||
195 | hid = hid_allocate_device(); | |
196 | if (IS_ERR(hid)) { | |
197 | ret = PTR_ERR(hid); | |
198 | goto err_<...>; | |
199 | } | |
200 | ||
220ee02a SK |
201 | strscpy(hid->name, <device-name-src>, sizeof(hid->name)); |
202 | strscpy(hid->phys, <device-phys-src>, sizeof(hid->phys)); | |
203 | strscpy(hid->uniq, <device-uniq-src>, sizeof(hid->uniq)); | |
6fad42d5 BT |
204 | |
205 | hid->ll_driver = &custom_ll_driver; | |
206 | hid->bus = <device-bus>; | |
207 | hid->vendor = <device-vendor>; | |
208 | hid->product = <device-product>; | |
209 | hid->version = <device-version>; | |
210 | hid->country = <device-country>; | |
211 | hid->dev.parent = <pointer-to-parent-device>; | |
212 | hid->driver_data = <transport-driver-data-field>; | |
213 | ||
214 | ret = hid_add_device(hid); | |
215 | if (ret) | |
216 | goto err_<...>; | |
217 | ||
218 | Once hid_add_device() is entered, HID core might use the callbacks provided in | |
219 | "custom_ll_driver". Note that fields like "country" can be ignored by underlying | |
220 | transport-drivers if not supported. | |
221 | ||
cca47861 | 222 | To unregister a device, use:: |
6fad42d5 BT |
223 | |
224 | hid_destroy_device(hid); | |
225 | ||
226 | Once hid_destroy_device() returns, HID core will no longer make use of any | |
227 | driver callbacks. | |
228 | ||
229 | 2.2) hid_ll_driver operations | |
230 | ----------------------------- | |
231 | ||
232 | The available HID callbacks are: | |
cca47861 MCC |
233 | |
234 | :: | |
235 | ||
236 | int (*start) (struct hid_device *hdev) | |
237 | ||
6fad42d5 BT |
238 | Called from HID device drivers once they want to use the device. Transport |
239 | drivers can choose to setup their device in this callback. However, normally | |
240 | devices are already set up before transport drivers register them to HID core | |
241 | so this is mostly only used by USB-HID. | |
242 | ||
cca47861 MCC |
243 | :: |
244 | ||
245 | void (*stop) (struct hid_device *hdev) | |
246 | ||
6fad42d5 BT |
247 | Called from HID device drivers once they are done with a device. Transport |
248 | drivers can free any buffers and deinitialize the device. But note that | |
249 | ->start() might be called again if another HID device driver is loaded on the | |
250 | device. | |
cca47861 | 251 | |
6fad42d5 BT |
252 | Transport drivers are free to ignore it and deinitialize devices after they |
253 | destroyed them via hid_destroy_device(). | |
254 | ||
cca47861 MCC |
255 | :: |
256 | ||
257 | int (*open) (struct hid_device *hdev) | |
258 | ||
6fad42d5 BT |
259 | Called from HID device drivers once they are interested in data reports. |
260 | Usually, while user-space didn't open any input API/etc., device drivers are | |
261 | not interested in device data and transport drivers can put devices asleep. | |
262 | However, once ->open() is called, transport drivers must be ready for I/O. | |
263 | ->open() calls are nested for each client that opens the HID device. | |
264 | ||
cca47861 MCC |
265 | :: |
266 | ||
267 | void (*close) (struct hid_device *hdev) | |
268 | ||
6fad42d5 BT |
269 | Called from HID device drivers after ->open() was called but they are no |
270 | longer interested in device reports. (Usually if user-space closed any input | |
271 | devices of the driver). | |
cca47861 | 272 | |
6fad42d5 BT |
273 | Transport drivers can put devices asleep and terminate any I/O of all |
274 | ->open() calls have been followed by a ->close() call. However, ->start() may | |
275 | be called again if the device driver is interested in input reports again. | |
276 | ||
cca47861 MCC |
277 | :: |
278 | ||
279 | int (*parse) (struct hid_device *hdev) | |
280 | ||
6fad42d5 BT |
281 | Called once during device setup after ->start() has been called. Transport |
282 | drivers must read the HID report-descriptor from the device and tell HID core | |
283 | about it via hid_parse_report(). | |
284 | ||
cca47861 MCC |
285 | :: |
286 | ||
287 | int (*power) (struct hid_device *hdev, int level) | |
288 | ||
6fad42d5 BT |
289 | Called by HID core to give PM hints to transport drivers. Usually this is |
290 | analogical to the ->open() and ->close() hints and redundant. | |
291 | ||
cca47861 MCC |
292 | :: |
293 | ||
294 | void (*request) (struct hid_device *hdev, struct hid_report *report, | |
295 | int reqtype) | |
296 | ||
6fad42d5 BT |
297 | Send an HID request on the ctrl channel. "report" contains the report that |
298 | should be sent and "reqtype" the request type. Request-type can be | |
299 | HID_REQ_SET_REPORT or HID_REQ_GET_REPORT. | |
cca47861 | 300 | |
6fad42d5 BT |
301 | This callback is optional. If not provided, HID core will assemble a raw |
302 | report following the HID specs and send it via the ->raw_request() callback. | |
303 | The transport driver is free to implement this asynchronously. | |
304 | ||
cca47861 MCC |
305 | :: |
306 | ||
307 | int (*wait) (struct hid_device *hdev) | |
308 | ||
6fad42d5 BT |
309 | Used by HID core before calling ->request() again. A transport driver can use |
310 | it to wait for any pending requests to complete if only one request is | |
311 | allowed at a time. | |
312 | ||
cca47861 MCC |
313 | :: |
314 | ||
315 | int (*raw_request) (struct hid_device *hdev, unsigned char reportnum, | |
316 | __u8 *buf, size_t count, unsigned char rtype, | |
317 | int reqtype) | |
318 | ||
6fad42d5 BT |
319 | Same as ->request() but provides the report as raw buffer. This request shall |
320 | be synchronous. A transport driver must not use ->wait() to complete such | |
3c86726c BT |
321 | requests. This request is mandatory and hid core will reject the device if |
322 | it is missing. | |
6fad42d5 | 323 | |
cca47861 MCC |
324 | :: |
325 | ||
326 | int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len) | |
327 | ||
6fad42d5 BT |
328 | Send raw output report via intr channel. Used by some HID device drivers |
329 | which require high throughput for outgoing requests on the intr channel. This | |
330 | must not cause SET_REPORT calls! This must be implemented as asynchronous | |
331 | output report on the intr channel! | |
332 | ||
cca47861 MCC |
333 | :: |
334 | ||
335 | int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype) | |
336 | ||
6fad42d5 BT |
337 | Perform SET/GET_IDLE request. Only used by USB-HID, do not implement! |
338 | ||
339 | 2.3) Data Path | |
340 | -------------- | |
341 | ||
342 | Transport drivers are responsible of reading data from I/O devices. They must | |
343 | handle any I/O-related state-tracking themselves. HID core does not implement | |
344 | protocol handshakes or other management commands which can be required by the | |
345 | given HID transport specification. | |
346 | ||
347 | Every raw data packet read from a device must be fed into HID core via | |
348 | hid_input_report(). You must specify the channel-type (intr or ctrl) and report | |
349 | type (input/output/feature). Under normal conditions, only input reports are | |
350 | provided via this API. | |
351 | ||
352 | Responses to GET_REPORT requests via ->request() must also be provided via this | |
353 | API. Responses to ->raw_request() are synchronous and must be intercepted by the | |
354 | transport driver and not passed to hid_input_report(). | |
355 | Acknowledgements to SET_REPORT requests are not of interest to HID core. | |
356 | ||
357 | ---------------------------------------------------- | |
cca47861 | 358 | |
6fad42d5 | 359 | Written 2013, David Herrmann <dh.herrmann@gmail.com> |