Documentation/hid/hid-transport.rst

8 Bluetooth, I2C and user-space I/O drivers.
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 for raw data
16 transport and device setup/management. HID core is responsible for
17 report-parsing, report interpretation and the user-space API. Device specifics
18 and quirks are handled by all layers depending on the quirk.
22  +-----------+  +-----------+            +-----------+  +-----------+
23  | Device #1 |  | Device #i |            | Device #j |  | Device #k |
24  +-----------+  +-----------+            +-----------+  +-----------+
26         +------------+                          +------------+
28         +------------+                          +------------+
30      +------------------+                    +------------------+
32      +------------------+                    +------------------+
35                           +----------------+
37                           +----------------+
43  +----------------+  +-----------+  +------------------+  +------------------+
45  +----------------+  +-----------+  +------------------+  +------------------+
49   - I/O: USB, I2C, Bluetooth-l2cap
50   - Transport: USB-HID, I2C-HID, BT-HIDP
53 interest to HID device drivers. Transport drivers do not need to know the
56 1.1) Device Setup
57 -----------------
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
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.
70 Transport drivers are responsible for 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
77 ----------------------------------
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
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
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
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
103    send their input events on this channel. Outgoing events are normally
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
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
117  - INPUT Report: Input reports provide data from device to host. This
119    data is generated by the device and sent to the host with or without
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
126    Hosts may choose to send output reports either continuously or only on
128  - FEATURE Report: Feature reports are used for specific static device features
130    data like battery-state or device-settings.
133    on the intr channel as this channel is asynchronous.
135 INPUT and OUTPUT reports can be sent as pure data reports on the intr channel.
141 Plain reports must not be sent on the ctrl channel, though. Instead, the ctrl
143 allowed on the intr channel and are the only means of data there.
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
152    not handled as generic device events. That is, if a device does not operate
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
160    return the current report state of the device. However, OUTPUT reports as
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
168    A device must answer with a synchronous acknowledgement. However, HID core
175 Other ctrl-channel requests are supported by USB-HID but are not available
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.
187 -------------------
189 Transport drivers normally use the following procedure to register a new device
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));
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>;
220 transport-drivers if not supported.
222 To unregister a device, use::
230 -----------------------------
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
241    so this is mostly only used by USB-HID.
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.
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.
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
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.
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
290    analogical to the ->open() and ->close() hints and redundant.
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
302    report following the HID specs and send it via the ->raw_request() callback.
309    Used by HID core before calling ->request() again. A transport driver can use
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
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
331    output report on the intr channel!
337    Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
340 --------------
343 handle any I/O-related state-tracking themselves. HID core does not implement
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
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
357 ----------------------------------------------------