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