Documentation/hid/hid-transport.rst

   1 =========================
   2 HID I/O Transport Drivers
   3 =========================
   4
   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
   7 provided new transport drivers. The kernel includes at least support for USB,
   8 Bluetooth, I2C and user-space I/O drivers.
   9
  10 1) HID Bus
  11 ==========
  12
  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
  15 drivers on top of it. The transport drivers are responsible of raw data
  16 transport and device setup/management. HID core is responsible of
  17 report-parsing, report interpretation and the user-space API. Device specifics
  18 and quirks are handled by all layers depending on the quirk.
  19
  20 ::
  21
  22  +-----------+  +-----------+            +-----------+  +-----------+
  23  | Device #1 |  | Device #i |            | Device #j |  | Device #k |
  24  +-----------+  +-----------+            +-----------+  +-----------+
  25           \\      //                              \\      //
  26         +------------+                          +------------+
  27         | I/O Driver |                          | I/O Driver |
  28         +------------+                          +------------+
  29               ||                                      ||
  30      +------------------+                    +------------------+
  31      | Transport Driver |                    | Transport Driver |
  32      +------------------+                    +------------------+
  33                        \___                ___/
  34                            \              /
  35                           +----------------+
  36                           |    HID Core    |
  37                           +----------------+
  38                            /  |        |  \
  39                           /   |        |   \
  40              ____________/    |        |    \_________________
  41             /                 |        |                      \
  42            /                  |        |                       \
  43  +----------------+  +-----------+  +------------------+  +------------------+
  44  | Generic Driver |  | MT Driver |  | Custom Driver #1 |  | Custom Driver #2 |
  45  +----------------+  +-----------+  +------------------+  +------------------+
  46
  47 Example Drivers:
  48
  49   - I/O: USB, I2C, Bluetooth-l2cap
  50   - Transport: USB-HID, I2C-HID, BT-HIDP
  51
  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
  54 specifics.
  55
  56 1.1) Device Setup
  57 -----------------
  58
  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
  62 drivers are not required to register themselves with HID core. HID core is never
  63 aware of which transport drivers are available and is not interested in it. It
  64 is only interested in devices.
  65
  66 Transport drivers attach a constant "struct hid_ll_driver" object with each
  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.
  69
  70 Transport drivers are responsible of 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
  74 provided callbacks.
  75
  76 1.2) Transport Driver Requirements
  77 ----------------------------------
  78
  79 The terms "asynchronous" and "synchronous" in this document describe the
  80 transmission behavior regarding acknowledgements. An asynchronous channel must
  81 not perform any synchronous operations like waiting for acknowledgements or
  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
  85 driver in whatever way they like. They might just be the same as asynchronous
  86 channels, but they can also provide acknowledgement reports, automatic
  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
  89 its own worker threads.
  90
  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
  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
  97 properties in common.
  98
  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
 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
 104    not send via intr, except if high throughput is required.
 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
 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
 112    SET_REPORT requests.
 113
 114 Communication between devices and HID core is mostly done via HID reports. A
 115 report can be of one of three types:
 116
 117  - INPUT Report: Input reports provide data from device to host. This
 118    data may include button events, axis events, battery status or more. This
 119    data is generated by the device and sent to the host with or without
 120    requiring explicit requests. Devices can choose to send data continuously or
 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
 125    current state.
 126    Hosts may choose to send output reports either continuously or only on
 127    change.
 128  - FEATURE Report: Feature reports are used for specific static device features
 129    and never reported spontaneously. A host can read and/or write them to access
 130    data like battery-state or device-settings.
 131    Feature reports are never sent without requests. A host must explicitly set
 132    or retrieve a feature report. This also means, feature reports are never sent
 133    on the intr channel as this channel is asynchronous.
 134
 135 INPUT and OUTPUT reports can be sent as pure data reports on the intr channel.
 136 For INPUT reports this is the usual operational mode. But for OUTPUT reports,
 137 this is rarely done as OUTPUT reports are normally quite scarce. But devices are
 138 free to make excessive use of asynchronous OUTPUT reports (for instance, custom
 139 HID audio speakers make great use of it).
 140
 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.
 144
 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
 149    is enforced by HID core as several transport drivers don't allow multiple
 150    simultaneous GET_REPORT requests.
 151    Note that data reports which are sent as answer to a GET_REPORT request are
 152    not handled as generic device events. That is, if a device does not operate
 153    in continuous data reporting mode, an answer to GET_REPORT does not replace
 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
 158    retrieve the current state.
 159    GET_REPORT requests can be sent for any of the 3 report types and shall
 160    return the current report state of the device. However, OUTPUT reports as
 161    payload may be blocked by the underlying transport driver if the
 162    specification does not allow them.
 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 it's current report state
 165    according to the given data. Any of the 3 report types can be used. However,
 166    INPUT reports as payload might be blocked by the underlying transport driver
 167    if the specification does not allow them.
 168    A device must answer with a synchronous acknowledgement. However, HID core
 169    does not require transport drivers to forward this acknowledgement to HID
 170    core.
 171    Same as for GET_REPORT, only one SET_REPORT can be pending at a time. This
 172    restriction is enforced by HID core as some transport drivers do not support
 173    multiple synchronous SET_REPORT requests.
 174
 175 Other ctrl-channel requests are supported by USB-HID but are not available
 176 (or deprecated) in most other transport level specifications:
 177
 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.
 182
 183 2) HID API
 184 ==========
 185
 186 2.1) Initialization
 187 -------------------
 188
 189 Transport drivers normally use the following procedure to register a new device
 190 with HID core::
 191
 192         struct hid_device *hid;
 193         int ret;
 194
 195         hid = hid_allocate_device();
 196         if (IS_ERR(hid)) {
 197                 ret = PTR_ERR(hid);
 198                 goto err_<...>;
 199         }
 200
 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));
 204
 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>;
 213
 214         ret = hid_add_device(hid);
 215         if (ret)
 216                 goto err_<...>;
 217
 218 Once hid_add_device() is entered, HID core might use the callbacks provided in
 219 "custom_ll_driver". Note that fields like "country" can be ignored by underlying
 220 transport-drivers if not supported.
 221
 222 To unregister a device, use::
 223
 224         hid_destroy_device(hid);
 225
 226 Once hid_destroy_device() returns, HID core will no longer make use of any
 227 driver callbacks.
 228
 229 2.2) hid_ll_driver operations
 230 -----------------------------
 231
 232 The available HID callbacks are:
 233
 234    ::
 235
 236       int (*start) (struct hid_device *hdev)
 237
 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
 240    devices are already set up before transport drivers register them to HID core
 241    so this is mostly only used by USB-HID.
 242
 243    ::
 244
 245       void (*stop) (struct hid_device *hdev)
 246
 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.
 251
 252    Transport drivers are free to ignore it and deinitialize devices after they
 253    destroyed them via hid_destroy_device().
 254
 255    ::
 256
 257       int (*open) (struct hid_device *hdev)
 258
 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.
 264
 265    ::
 266
 267       void (*close) (struct hid_device *hdev)
 268
 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
 271    devices of the driver).
 272
 273    Transport drivers can put devices asleep and terminate any I/O of all
 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.
 276
 277    ::
 278
 279       int (*parse) (struct hid_device *hdev)
 280
 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
 283    about it via hid_parse_report().
 284
 285    ::
 286
 287       int (*power) (struct hid_device *hdev, int level)
 288
 289    Called by HID core to give PM hints to transport drivers. Usually this is
 290    analogical to the ->open() and ->close() hints and redundant.
 291
 292    ::
 293
 294       void (*request) (struct hid_device *hdev, struct hid_report *report,
 295                        int reqtype)
 296
 297    Send an HID request on the ctrl channel. "report" contains the report that
 298    should be sent and "reqtype" the request type. Request-type can be
 299    HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.
 300
 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.
 303    The transport driver is free to implement this asynchronously.
 304
 305    ::
 306
 307       int (*wait) (struct hid_device *hdev)
 308
 309    Used by HID core before calling ->request() again. A transport driver can use
 310    it to wait for any pending requests to complete if only one request is
 311    allowed at a time.
 312
 313    ::
 314
 315       int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
 316                           __u8 *buf, size_t count, unsigned char rtype,
 317                           int reqtype)
 318
 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
 322    it is missing.
 323
 324    ::
 325
 326       int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
 327
 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
 330    must not cause SET_REPORT calls! This must be implemented as asynchronous
 331    output report on the intr channel!
 332
 333    ::
 334
 335       int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
 336
 337    Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
 338
 339 2.3) Data Path
 340 --------------
 341
 342 Transport drivers are responsible of reading data from I/O devices. They must
 343 handle any I/O-related state-tracking themselves. HID core does not implement
 344 protocol handshakes or other management commands which can be required by the
 345 given HID transport specification.
 346
 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
 349 type (input/output/feature). Under normal conditions, only input reports are
 350 provided via this API.
 351
 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
 354 transport driver and not passed to hid_input_report().
 355 Acknowledgements to SET_REPORT requests are not of interest to HID core.
 356
 357 ----------------------------------------------------
 358
 359 Written 2013, David Herrmann <dh.herrmann@gmail.com>