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 -----------------
77 ----------------------------------
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
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
105  - Control Channel (ctrl): The ctrl channel is used for synchronous requests and
109    The control-channel is used for direct blocking queries to the device
110    independent of any events on the intr-channel.
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.
145  - GET_REPORT: A GET_REPORT request has a report ID as payload and is sent
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 -------------------
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.
230 -----------------------------
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.
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
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 ----------------------------------------------------