0001 =========================
0002 HID I/O Transport Drivers
0003 =========================
0004
0005 The HID subsystem is independent of the underlying transport driver. Initially,
0006 only USB was supported, but other specifications adopted the HID design and
0007 provided new transport drivers. The kernel includes at least support for USB,
0008 Bluetooth, I2C and user-space I/O drivers.
0009
0010 1) HID Bus
0011 ==========
0012
0013 The HID subsystem is designed as a bus. Any I/O subsystem may provide HID
0014 devices and register them with the HID bus. HID core then loads generic device
0015 drivers on top of it. The transport drivers are responsible for raw data
0016 transport and device setup/management. HID core is responsible for
0017 report-parsing, report interpretation and the user-space API. Device specifics
0018 and quirks are handled by all layers depending on the quirk.
0019
0020 ::
0021
0022 +-----------+ +-----------+ +-----------+ +-----------+
0023 | Device #1 | | Device #i | | Device #j | | Device #k |
0024 +-----------+ +-----------+ +-----------+ +-----------+
0025 \\ // \\ //
0026 +------------+ +------------+
0027 | I/O Driver | | I/O Driver |
0028 +------------+ +------------+
0029 || ||
0030 +------------------+ +------------------+
0031 | Transport Driver | | Transport Driver |
0032 +------------------+ +------------------+
0033 \___ ___/
0034 \ /
0035 +----------------+
0036 | HID Core |
0037 +----------------+
0038 / | | \
0039 / | | \
0040 ____________/ | | \_________________
0041 / | | \
0042 / | | \
0043 +----------------+ +-----------+ +------------------+ +------------------+
0044 | Generic Driver | | MT Driver | | Custom Driver #1 | | Custom Driver #2 |
0045 +----------------+ +-----------+ +------------------+ +------------------+
0046
0047 Example Drivers:
0048
0049 - I/O: USB, I2C, Bluetooth-l2cap
0050 - Transport: USB-HID, I2C-HID, BT-HIDP
0051
0052 Everything below "HID Core" is simplified in this graph as it is only of
0053 interest to HID device drivers. Transport drivers do not need to know the
0054 specifics.
0055
0056 1.1) Device Setup
0057 -----------------
0058
0059 I/O drivers normally provide hotplug detection or device enumeration APIs to the
0060 transport drivers. Transport drivers use this to find any suitable HID device.
0061 They allocate HID device objects and register them with HID core. Transport
0062 drivers are not required to register themselves with HID core. HID core is never
0063 aware of which transport drivers are available and is not interested in it. It
0064 is only interested in devices.
0065
0066 Transport drivers attach a constant "struct hid_ll_driver" object with each
0067 device. Once a device is registered with HID core, the callbacks provided via
0068 this struct are used by HID core to communicate with the device.
0069
0070 Transport drivers are responsible for detecting device failures and unplugging.
0071 HID core will operate a device as long as it is registered regardless of any
0072 device failures. Once transport drivers detect unplug or failure events, they
0073 must unregister the device from HID core and HID core will stop using the
0074 provided callbacks.
0075
0076 1.2) Transport Driver Requirements
0077 ----------------------------------
0078
0079 The terms "asynchronous" and "synchronous" in this document describe the
0080 transmission behavior regarding acknowledgements. An asynchronous channel must
0081 not perform any synchronous operations like waiting for acknowledgements or
0082 verifications. Generally, HID calls operating on asynchronous channels must be
0083 running in atomic-context just fine.
0084 On the other hand, synchronous channels can be implemented by the transport
0085 driver in whatever way they like. They might just be the same as asynchronous
0086 channels, but they can also provide acknowledgement reports, automatic
0087 retransmission on failure, etc. in a blocking manner. If such functionality is
0088 required on asynchronous channels, a transport-driver must implement that via
0089 its own worker threads.
0090
0091 HID core requires transport drivers to follow a given design. A Transport
0092 driver must provide two bi-directional I/O channels to each HID device. These
0093 channels must not necessarily be bi-directional in the hardware itself. A
0094 transport driver might just provide 4 uni-directional channels. Or it might
0095 multiplex all four on a single physical channel. However, in this document we
0096 will describe them as two bi-directional channels as they have several
0097 properties in common.
0098
0099 - Interrupt Channel (intr): The intr channel is used for asynchronous data
0100 reports. No management commands or data acknowledgements are sent on this
0101 channel. Any unrequested incoming or outgoing data report must be sent on
0102 this channel and is never acknowledged by the remote side. Devices usually
0103 send their input events on this channel. Outgoing events are normally
0104 not sent via intr, except if high throughput is required.
0105 - Control Channel (ctrl): The ctrl channel is used for synchronous requests and
0106 device management. Unrequested data input events must not be sent on this
0107 channel and are normally ignored. Instead, devices only send management
0108 events or answers to host requests on this channel.
0109 The control-channel is used for direct blocking queries to the device
0110 independent of any events on the intr-channel.
0111 Outgoing reports are usually sent on the ctrl channel via synchronous
0112 SET_REPORT requests.
0113
0114 Communication between devices and HID core is mostly done via HID reports. A
0115 report can be of one of three types:
0116
0117 - INPUT Report: Input reports provide data from device to host. This
0118 data may include button events, axis events, battery status or more. This
0119 data is generated by the device and sent to the host with or without
0120 requiring explicit requests. Devices can choose to send data continuously or
0121 only on change.
0122 - OUTPUT Report: Output reports change device states. They are sent from host
0123 to device and may include LED requests, rumble requests or more. Output
0124 reports are never sent from device to host, but a host can retrieve their
0125 current state.
0126 Hosts may choose to send output reports either continuously or only on
0127 change.
0128 - FEATURE Report: Feature reports are used for specific static device features
0129 and never reported spontaneously. A host can read and/or write them to access
0130 data like battery-state or device-settings.
0131 Feature reports are never sent without requests. A host must explicitly set
0132 or retrieve a feature report. This also means, feature reports are never sent
0133 on the intr channel as this channel is asynchronous.
0134
0135 INPUT and OUTPUT reports can be sent as pure data reports on the intr channel.
0136 For INPUT reports this is the usual operational mode. But for OUTPUT reports,
0137 this is rarely done as OUTPUT reports are normally quite scarce. But devices are
0138 free to make excessive use of asynchronous OUTPUT reports (for instance, custom
0139 HID audio speakers make great use of it).
0140
0141 Plain reports must not be sent on the ctrl channel, though. Instead, the ctrl
0142 channel provides synchronous GET/SET_REPORT requests. Plain reports are only
0143 allowed on the intr channel and are the only means of data there.
0144
0145 - GET_REPORT: A GET_REPORT request has a report ID as payload and is sent
0146 from host to device. The device must answer with a data report for the
0147 requested report ID on the ctrl channel as a synchronous acknowledgement.
0148 Only one GET_REPORT request can be pending for each device. This restriction
0149 is enforced by HID core as several transport drivers don't allow multiple
0150 simultaneous GET_REPORT requests.
0151 Note that data reports which are sent as answer to a GET_REPORT request are
0152 not handled as generic device events. That is, if a device does not operate
0153 in continuous data reporting mode, an answer to GET_REPORT does not replace
0154 the raw data report on the intr channel on state change.
0155 GET_REPORT is only used by custom HID device drivers to query device state.
0156 Normally, HID core caches any device state so this request is not necessary
0157 on devices that follow the HID specs except during device initialization to
0158 retrieve the current state.
0159 GET_REPORT requests can be sent for any of the 3 report types and shall
0160 return the current report state of the device. However, OUTPUT reports as
0161 payload may be blocked by the underlying transport driver if the
0162 specification does not allow them.
0163 - SET_REPORT: A SET_REPORT request has a report ID plus data as payload. It is
0164 sent from host to device and a device must update its current report state
0165 according to the given data. Any of the 3 report types can be used. However,
0166 INPUT reports as payload might be blocked by the underlying transport driver
0167 if the specification does not allow them.
0168 A device must answer with a synchronous acknowledgement. However, HID core
0169 does not require transport drivers to forward this acknowledgement to HID
0170 core.
0171 Same as for GET_REPORT, only one SET_REPORT can be pending at a time. This
0172 restriction is enforced by HID core as some transport drivers do not support
0173 multiple synchronous SET_REPORT requests.
0174
0175 Other ctrl-channel requests are supported by USB-HID but are not available
0176 (or deprecated) in most other transport level specifications:
0177
0178 - GET/SET_IDLE: Only used by USB-HID and I2C-HID.
0179 - GET/SET_PROTOCOL: Not used by HID core.
0180 - RESET: Used by I2C-HID, not hooked up in HID core.
0181 - SET_POWER: Used by I2C-HID, not hooked up in HID core.
0182
0183 2) HID API
0184 ==========
0185
0186 2.1) Initialization
0187 -------------------
0188
0189 Transport drivers normally use the following procedure to register a new device
0190 with HID core::
0191
0192 struct hid_device *hid;
0193 int ret;
0194
0195 hid = hid_allocate_device();
0196 if (IS_ERR(hid)) {
0197 ret = PTR_ERR(hid);
0198 goto err_<...>;
0199 }
0200
0201 strscpy(hid->name, <device-name-src>, sizeof(hid->name));
0202 strscpy(hid->phys, <device-phys-src>, sizeof(hid->phys));
0203 strscpy(hid->uniq, <device-uniq-src>, sizeof(hid->uniq));
0204
0205 hid->ll_driver = &custom_ll_driver;
0206 hid->bus = <device-bus>;
0207 hid->vendor = <device-vendor>;
0208 hid->product = <device-product>;
0209 hid->version = <device-version>;
0210 hid->country = <device-country>;
0211 hid->dev.parent = <pointer-to-parent-device>;
0212 hid->driver_data = <transport-driver-data-field>;
0213
0214 ret = hid_add_device(hid);
0215 if (ret)
0216 goto err_<...>;
0217
0218 Once hid_add_device() is entered, HID core might use the callbacks provided in
0219 "custom_ll_driver". Note that fields like "country" can be ignored by underlying
0220 transport-drivers if not supported.
0221
0222 To unregister a device, use::
0223
0224 hid_destroy_device(hid);
0225
0226 Once hid_destroy_device() returns, HID core will no longer make use of any
0227 driver callbacks.
0228
0229 2.2) hid_ll_driver operations
0230 -----------------------------
0231
0232 The available HID callbacks are:
0233
0234 ::
0235
0236 int (*start) (struct hid_device *hdev)
0237
0238 Called from HID device drivers once they want to use the device. Transport
0239 drivers can choose to setup their device in this callback. However, normally
0240 devices are already set up before transport drivers register them to HID core
0241 so this is mostly only used by USB-HID.
0242
0243 ::
0244
0245 void (*stop) (struct hid_device *hdev)
0246
0247 Called from HID device drivers once they are done with a device. Transport
0248 drivers can free any buffers and deinitialize the device. But note that
0249 ->start() might be called again if another HID device driver is loaded on the
0250 device.
0251
0252 Transport drivers are free to ignore it and deinitialize devices after they
0253 destroyed them via hid_destroy_device().
0254
0255 ::
0256
0257 int (*open) (struct hid_device *hdev)
0258
0259 Called from HID device drivers once they are interested in data reports.
0260 Usually, while user-space didn't open any input API/etc., device drivers are
0261 not interested in device data and transport drivers can put devices asleep.
0262 However, once ->open() is called, transport drivers must be ready for I/O.
0263 ->open() calls are nested for each client that opens the HID device.
0264
0265 ::
0266
0267 void (*close) (struct hid_device *hdev)
0268
0269 Called from HID device drivers after ->open() was called but they are no
0270 longer interested in device reports. (Usually if user-space closed any input
0271 devices of the driver).
0272
0273 Transport drivers can put devices asleep and terminate any I/O of all
0274 ->open() calls have been followed by a ->close() call. However, ->start() may
0275 be called again if the device driver is interested in input reports again.
0276
0277 ::
0278
0279 int (*parse) (struct hid_device *hdev)
0280
0281 Called once during device setup after ->start() has been called. Transport
0282 drivers must read the HID report-descriptor from the device and tell HID core
0283 about it via hid_parse_report().
0284
0285 ::
0286
0287 int (*power) (struct hid_device *hdev, int level)
0288
0289 Called by HID core to give PM hints to transport drivers. Usually this is
0290 analogical to the ->open() and ->close() hints and redundant.
0291
0292 ::
0293
0294 void (*request) (struct hid_device *hdev, struct hid_report *report,
0295 int reqtype)
0296
0297 Send a HID request on the ctrl channel. "report" contains the report that
0298 should be sent and "reqtype" the request type. Request-type can be
0299 HID_REQ_SET_REPORT or HID_REQ_GET_REPORT.
0300
0301 This callback is optional. If not provided, HID core will assemble a raw
0302 report following the HID specs and send it via the ->raw_request() callback.
0303 The transport driver is free to implement this asynchronously.
0304
0305 ::
0306
0307 int (*wait) (struct hid_device *hdev)
0308
0309 Used by HID core before calling ->request() again. A transport driver can use
0310 it to wait for any pending requests to complete if only one request is
0311 allowed at a time.
0312
0313 ::
0314
0315 int (*raw_request) (struct hid_device *hdev, unsigned char reportnum,
0316 __u8 *buf, size_t count, unsigned char rtype,
0317 int reqtype)
0318
0319 Same as ->request() but provides the report as raw buffer. This request shall
0320 be synchronous. A transport driver must not use ->wait() to complete such
0321 requests. This request is mandatory and hid core will reject the device if
0322 it is missing.
0323
0324 ::
0325
0326 int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len)
0327
0328 Send raw output report via intr channel. Used by some HID device drivers
0329 which require high throughput for outgoing requests on the intr channel. This
0330 must not cause SET_REPORT calls! This must be implemented as asynchronous
0331 output report on the intr channel!
0332
0333 ::
0334
0335 int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype)
0336
0337 Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
0338
0339 2.3) Data Path
0340 --------------
0341
0342 Transport drivers are responsible of reading data from I/O devices. They must
0343 handle any I/O-related state-tracking themselves. HID core does not implement
0344 protocol handshakes or other management commands which can be required by the
0345 given HID transport specification.
0346
0347 Every raw data packet read from a device must be fed into HID core via
0348 hid_input_report(). You must specify the channel-type (intr or ctrl) and report
0349 type (input/output/feature). Under normal conditions, only input reports are
0350 provided via this API.
0351
0352 Responses to GET_REPORT requests via ->request() must also be provided via this
0353 API. Responses to ->raw_request() are synchronous and must be intercepted by the
0354 transport driver and not passed to hid_input_report().
0355 Acknowledgements to SET_REPORT requests are not of interest to HID core.
0356
0357 ----------------------------------------------------
0358
0359 Written 2013, David Herrmann <dh.herrmann@gmail.com>
