1=========================
2HID I/O Transport Drivers
3=========================
4
5The HID subsystem is independent of the underlying transport driver. Initially,
6only USB was supported, but other specifications adopted the HID design and
7provided new transport drivers. The kernel includes at least support for USB,
8Bluetooth, I2C and user-space I/O drivers.
9
101) HID Bus
11==========
12
13The HID subsystem is designed as a bus. Any I/O subsystem may provide HID
14devices and register them with the HID bus. HID core then loads generic device
15drivers on top of it. The transport drivers are responsible for raw data
16transport and device setup/management. HID core is responsible for
17report-parsing, report interpretation and the user-space API. Device specifics
18and quirks are handled by all layers depending on the quirk.
19
20::
21
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
47Example Drivers:
48
49  - I/O: USB, I2C, Bluetooth-l2cap
50  - Transport: USB-HID, I2C-HID, BT-HIDP
51
52Everything below "HID Core" is simplified in this graph as it is only of
53interest to HID device drivers. Transport drivers do not need to know the
54specifics.
55
561.1) Device Setup
57-----------------
58
59I/O drivers normally provide hotplug detection or device enumeration APIs to the
60transport drivers. Transport drivers use this to find any suitable HID device.
61They allocate HID device objects and register them with HID core. Transport
62drivers are not required to register themselves with HID core. HID core is never
63aware of which transport drivers are available and is not interested in it. It
64is only interested in devices.
65
66Transport drivers attach a constant "struct hid_ll_driver" object with each
67device. Once a device is registered with HID core, the callbacks provided via
68this struct are used by HID core to communicate with the device.
69
70Transport drivers are responsible for detecting device failures and unplugging.
71HID core will operate a device as long as it is registered regardless of any
72device failures. Once transport drivers detect unplug or failure events, they
73must unregister the device from HID core and HID core will stop using the
74provided callbacks.
75
761.2) Transport Driver Requirements
77----------------------------------
78
79The terms "asynchronous" and "synchronous" in this document describe the
80transmission behavior regarding acknowledgements. An asynchronous channel must
81not perform any synchronous operations like waiting for acknowledgements or
82verifications. Generally, HID calls operating on asynchronous channels must be
83running in atomic-context just fine.
84On the other hand, synchronous channels can be implemented by the transport
85driver in whatever way they like. They might just be the same as asynchronous
86channels, but they can also provide acknowledgement reports, automatic
87retransmission on failure, etc. in a blocking manner. If such functionality is
88required on asynchronous channels, a transport-driver must implement that via
89its own worker threads.
90
91HID core requires transport drivers to follow a given design. A Transport
92driver must provide two bi-directional I/O channels to each HID device. These
93channels must not necessarily be bi-directional in the hardware itself. A
94transport driver might just provide 4 uni-directional channels. Or it might
95multiplex all four on a single physical channel. However, in this document we
96will describe them as two bi-directional channels as they have several
97properties 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 sent 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
114Communication between devices and HID core is mostly done via HID reports. A
115report 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
135INPUT and OUTPUT reports can be sent as pure data reports on the intr channel.
136For INPUT reports this is the usual operational mode. But for OUTPUT reports,
137this is rarely done as OUTPUT reports are normally quite scarce. But devices are
138free to make excessive use of asynchronous OUTPUT reports (for instance, custom
139HID audio speakers make great use of it).
140
141Plain reports must not be sent on the ctrl channel, though. Instead, the ctrl
142channel provides synchronous GET/SET_REPORT requests. Plain reports are only
143allowed 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 its 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
175Other 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
1832) HID API
184==========
185
1862.1) Initialization
187-------------------
188
189Transport drivers normally use the following procedure to register a new device
190with HID core::
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
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));
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
218Once 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
220transport-drivers if not supported.
221
222To unregister a device, use::
223
224	hid_destroy_device(hid);
225
226Once hid_destroy_device() returns, HID core will no longer make use of any
227driver callbacks.
228
2292.2) hid_ll_driver operations
230-----------------------------
231
232The available HID callbacks are:
233
234   ::
235
236      int (*start) (struct hid_device *hdev)
237
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
243   ::
244
245      void (*stop) (struct hid_device *hdev)
246
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.
251
252   Transport drivers are free to ignore it and deinitialize devices after they
253   destroyed them via hid_destroy_device().
254
255   ::
256
257      int (*open) (struct hid_device *hdev)
258
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
265   ::
266
267      void (*close) (struct hid_device *hdev)
268
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).
272
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
277   ::
278
279      int (*parse) (struct hid_device *hdev)
280
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
285   ::
286
287      int (*power) (struct hid_device *hdev, int level)
288
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
292   ::
293
294      void (*request) (struct hid_device *hdev, struct hid_report *report,
295		       int reqtype)
296
297   Send a 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.
300
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
305   ::
306
307      int (*wait) (struct hid_device *hdev)
308
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
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
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
321   requests. This request is mandatory and hid core will reject the device if
322   it is missing.
323
324   ::
325
326      int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
327
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
333   ::
334
335      int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
336
337   Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
338
3392.3) Data Path
340--------------
341
342Transport drivers are responsible of reading data from I/O devices. They must
343handle any I/O-related state-tracking themselves. HID core does not implement
344protocol handshakes or other management commands which can be required by the
345given HID transport specification.
346
347Every raw data packet read from a device must be fed into HID core via
348hid_input_report(). You must specify the channel-type (intr or ctrl) and report
349type (input/output/feature). Under normal conditions, only input reports are
350provided via this API.
351
352Responses to GET_REPORT requests via ->request() must also be provided via this
353API. Responses to ->raw_request() are synchronous and must be intercepted by the
354transport driver and not passed to hid_input_report().
355Acknowledgements to SET_REPORT requests are not of interest to HID core.
356
357----------------------------------------------------
358
359Written 2013, David Herrmann <dh.herrmann@gmail.com>
360