Documentation/hid/hid-transport.rst

2 HID I/O Transport Drivers
5 The HID subsystem is independent of the underlying transport driver. Initially,
6 only USB was supported, but other specifications adopted the HID design and
10 1) HID Bus
13 The HID subsystem is designed as a bus. Any I/O subsystem may provide HID
14 devices and register them with the HID bus. HID core then loads generic device
16 transport and device setup/management. HID core is responsible for
36                           |    HID Core    |
50   - Transport: USB-HID, I2C-HID, BT-HIDP
52 Everything below "HID Core" is simplified in this graph as it is only of
53 interest to HID device drivers. Transport drivers do not need to know 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
62 drivers are not required to register themselves with HID core. HID core is never
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.
71 HID core will operate a device as long as it is registered regardless of any
73 must unregister the device from HID core and HID core will stop using the
82 verifications. Generally, HID calls operating on asynchronous channels must be
91 HID core requires transport drivers to follow a given design. A Transport
92 driver must provide two bi-directional I/O channels to each HID device. These
114 Communication between devices and HID core is mostly done via HID reports. A
139 HID audio speakers make great use of it).
149    is enforced by HID core as several transport drivers don't allow multiple
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
168    A device must answer with a synchronous acknowledgement. However, HID core
169    does not require transport drivers to forward this acknowledgement to HID
172    restriction is enforced by HID core as some transport drivers do not support
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.
183 2) HID API
190 with HID core::
218 Once hid_add_device() is entered, HID core might use the callbacks provided in
226 Once hid_destroy_device() returns, HID core will no longer make use of any
232 The available HID callbacks are:
238    Called from HID device drivers once they want to use the device. Transport
240    devices are already set up before transport drivers register them to HID core
241    so this is mostly only used by USB-HID.
247    Called from HID device drivers once they are done with a device. Transport
249    ->start() might be called again if another HID device driver is loaded on the
259    Called from HID device drivers once they are interested in data reports.
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
282    drivers must read the HID report-descriptor from the device and tell HID core
289    Called by HID core to give PM hints to transport drivers. Usually this is
297    Send a HID request on the ctrl channel. "report" contains the report that
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.
309    Used by HID core before calling ->request() again. A transport driver can use
328    Send raw output report via intr channel. Used by some HID device drivers
337    Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
343 handle any I/O-related state-tracking themselves. HID core does not implement
345 given HID transport specification.
347 Every raw data packet read from a device must be fed into HID core via
355 Acknowledgements to SET_REPORT requests are not of interest to HID core.