blob: 3dcba9fd4a3aaae1be0b60d132fca31914a4c02e [file] [log] [blame]
Benjamin Tissoires6fad42d2014-02-05 16:33:24 -05001 HID I/O Transport Drivers
2 ===========================
3
4The HID subsystem is independent of the underlying transport driver. Initially,
5only USB was supported, but other specifications adopted the HID design and
6provided new transport drivers. The kernel includes at least support for USB,
7Bluetooth, I2C and user-space I/O drivers.
8
91) HID Bus
10==========
11
12The HID subsystem is designed as a bus. Any I/O subsystem may provide HID
13devices and register them with the HID bus. HID core then loads generic device
14drivers on top of it. The transport drivers are responsible of raw data
15transport and device setup/management. HID core is responsible of
16report-parsing, report interpretation and the user-space API. Device specifics
17and 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
44Example Drivers:
45 I/O: USB, I2C, Bluetooth-l2cap
46 Transport: USB-HID, I2C-HID, BT-HIDP
47
48Everything below "HID Core" is simplified in this graph as it is only of
49interest to HID device drivers. Transport drivers do not need to know the
50specifics.
51
521.1) Device Setup
53-----------------
54
55I/O drivers normally provide hotplug detection or device enumeration APIs to the
56transport drivers. Transport drivers use this to find any suitable HID device.
57They allocate HID device objects and register them with HID core. Transport
58drivers are not required to register themselves with HID core. HID core is never
59aware of which transport drivers are available and is not interested in it. It
60is only interested in devices.
61
62Transport drivers attach a constant "struct hid_ll_driver" object with each
63device. Once a device is registered with HID core, the callbacks provided via
64this struct are used by HID core to communicate with the device.
65
66Transport drivers are responsible of detecting device failures and unplugging.
67HID core will operate a device as long as it is registered regardless of any
68device failures. Once transport drivers detect unplug or failure events, they
69must unregister the device from HID core and HID core will stop using the
70provided callbacks.
71
721.2) Transport Driver Requirements
73----------------------------------
74
75The terms "asynchronous" and "synchronous" in this document describe the
76transmission behavior regarding acknowledgements. An asynchronous channel must
77not perform any synchronous operations like waiting for acknowledgements or
78verifications. Generally, HID calls operating on asynchronous channels must be
79running in atomic-context just fine.
80On the other hand, synchronous channels can be implemented by the transport
81driver in whatever way they like. They might just be the same as asynchronous
82channels, but they can also provide acknowledgement reports, automatic
83retransmission on failure, etc. in a blocking manner. If such functionality is
84required on asynchronous channels, a transport-driver must implement that via
85its own worker threads.
86
87HID core requires transport drivers to follow a given design. A Transport
88driver must provide two bi-directional I/O channels to each HID device. These
89channels must not necessarily be bi-directional in the hardware itself. A
90transport driver might just provide 4 uni-directional channels. Or it might
91multiplex all four on a single physical channel. However, in this document we
92will describe them as two bi-directional channels as they have several
93properties 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
110Communication between devices and HID core is mostly done via HID reports. A
111report 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
131INPUT and OUTPUT reports can be sent as pure data reports on the intr channel.
132For INPUT reports this is the usual operational mode. But for OUTPUT reports,
133this is rarely done as OUTPUT reports are normally quite scarce. But devices are
134free to make excessive use of asynchronous OUTPUT reports (for instance, custom
135HID audio speakers make great use of it).
136
137Plain reports must not be sent on the ctrl channel, though. Instead, the ctrl
138channel provides synchronous GET/SET_REPORT requests. Plain reports are only
139allowed 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
171Other 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
1792) HID API
180==========
181
1822.1) Initialization
183-------------------
184
185Transport drivers normally use the following procedure to register a new device
186with 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
214Once 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
216transport-drivers if not supported.
217
218To unregister a device, use:
219
220 hid_destroy_device(hid);
221
222Once hid_destroy_device() returns, HID core will no longer make use of any
223driver callbacks.
224
2252.2) hid_ll_driver operations
226-----------------------------
227
228The 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
Benjamin Tissoires3c867262014-02-20 15:24:49 -0500286 requests. This request is mandatory and hid core will reject the device if
287 it is missing.
Benjamin Tissoires6fad42d2014-02-05 16:33:24 -0500288
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
2982.3) Data Path
299--------------
300
301Transport drivers are responsible of reading data from I/O devices. They must
302handle any I/O-related state-tracking themselves. HID core does not implement
303protocol handshakes or other management commands which can be required by the
304given HID transport specification.
305
306Every raw data packet read from a device must be fed into HID core via
307hid_input_report(). You must specify the channel-type (intr or ctrl) and report
308type (input/output/feature). Under normal conditions, only input reports are
309provided via this API.
310
311Responses to GET_REPORT requests via ->request() must also be provided via this
312API. Responses to ->raw_request() are synchronous and must be intercepted by the
313transport driver and not passed to hid_input_report().
314Acknowledgements to SET_REPORT requests are not of interest to HID core.
315
316----------------------------------------------------
317Written 2013, David Herrmann <dh.herrmann@gmail.com>