Documentation/hid/hid-transport.rst

8 Bluetooth, I2C and user-space I/O drivers.
17 report-parsing, report interpretation and the user-space API. Device specifics
22  +-----------+  +-----------+            +-----------+  +-----------+
24  +-----------+  +-----------+            +-----------+  +-----------+
26         +------------+                          +------------+
28         +------------+                          +------------+
30      +------------------+                    +------------------+
32      +------------------+                    +------------------+
35                           +----------------+
37                           +----------------+
43  +----------------+  +-----------+  +------------------+  +------------------+
45  +----------------+  +-----------+  +------------------+  +------------------+
49   - I/O: USB, I2C, Bluetooth-l2cap
50   - Transport: USB-HID, I2C-HID, BT-HIDP
57 -----------------
60 transport drivers. Transport drivers use this to find any suitable HID device.
77 ----------------------------------
80 transmission behavior regarding acknowledgements. An asynchronous channel must
83 running in atomic-context just fine.
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
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
105  - Control Channel (ctrl): The ctrl channel is used for synchronous requests and
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
117  - INPUT Report: Input reports provide data from device to host. This
122  - OUTPUT Report: Output reports change device states. They are sent from host
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.
138 free to make excessive use of asynchronous OUTPUT reports (for instance, custom
139 HID audio speakers make great use of it).
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.
145  - GET_REPORT: A GET_REPORT request has a report ID as payload and is sent
147    requested report ID on the ctrl channel as a synchronous acknowledgement.
154    the raw data report on the intr channel on state change.
163  - SET_REPORT: A SET_REPORT request has a report ID plus data as payload. It is
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>;
218 Once hid_add_device() is entered, HID core might use the callbacks provided in
220 transport-drivers if not supported.
222 To unregister a device, use::
226 Once hid_destroy_device() returns, HID core will no longer make use of any
230 -----------------------------
238    Called from HID device drivers once they want to use the device. Transport
241    so this is mostly only used by USB-HID.
249    ->start() might be called again if another HID device driver is loaded on the
260    Usually, while user-space didn't open any input API/etc., device drivers are
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
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
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
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 ----------------------------------------------------