1========================= 2HID I/O Transport Drivers 3========================= 4 5The HID subsystem is independent of the underlying transport driver. Initially, 6only USB was supported, but other specifications adopted the HID design and 7provided new transport drivers. The kernel includes at least support for USB, 8Bluetooth, I2C and user-space I/O drivers. 9 101) HID Bus 11========== 12 13The HID subsystem is designed as a bus. Any I/O subsystem may provide HID 14devices and register them with the HID bus. HID core then loads generic device 15drivers on top of it. The transport drivers are responsible for raw data 16transport and device setup/management. HID core is responsible for 17report-parsing, report interpretation and the user-space API. Device specifics 18and 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 47Example Drivers: 48 49 - I/O: USB, I2C, Bluetooth-l2cap 50 - Transport: USB-HID, I2C-HID, BT-HIDP 51 52Everything below "HID Core" is simplified in this graph as it is only of 53interest to HID device drivers. Transport drivers do not need to know the 54specifics. 55 561.1) Device Setup 57----------------- 58 59I/O drivers normally provide hotplug detection or device enumeration APIs to the 60transport drivers. Transport drivers use this to find any suitable HID device. 61They allocate HID device objects and register them with HID core. Transport 62drivers are not required to register themselves with HID core. HID core is never 63aware of which transport drivers are available and is not interested in it. It 64is only interested in devices. 65 66Transport drivers attach a constant "struct hid_ll_driver" object with each 67device. Once a device is registered with HID core, the callbacks provided via 68this struct are used by HID core to communicate with the device. 69 70Transport drivers are responsible for detecting device failures and unplugging. 71HID core will operate a device as long as it is registered regardless of any 72device failures. Once transport drivers detect unplug or failure events, they 73must unregister the device from HID core and HID core will stop using the 74provided callbacks. 75 761.2) Transport Driver Requirements 77---------------------------------- 78 79The terms "asynchronous" and "synchronous" in this document describe the 80transmission behavior regarding acknowledgements. An asynchronous channel must 81not perform any synchronous operations like waiting for acknowledgements or 82verifications. Generally, HID calls operating on asynchronous channels must be 83running in atomic-context just fine. 84On the other hand, synchronous channels can be implemented by the transport 85driver in whatever way they like. They might just be the same as asynchronous 86channels, but they can also provide acknowledgement reports, automatic 87retransmission on failure, etc. in a blocking manner. If such functionality is 88required on asynchronous channels, a transport-driver must implement that via 89its own worker threads. 90 91HID core requires transport drivers to follow a given design. A Transport 92driver must provide two bi-directional I/O channels to each HID device. These 93channels must not necessarily be bi-directional in the hardware itself. A 94transport driver might just provide 4 uni-directional channels. Or it might 95multiplex all four on a single physical channel. However, in this document we 96will describe them as two bi-directional channels as they have several 97properties 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 sent 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 114Communication between devices and HID core is mostly done via HID reports. A 115report 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 135INPUT and OUTPUT reports can be sent as pure data reports on the intr channel. 136For INPUT reports this is the usual operational mode. But for OUTPUT reports, 137this is rarely done as OUTPUT reports are normally quite scarce. But devices are 138free to make excessive use of asynchronous OUTPUT reports (for instance, custom 139HID audio speakers make great use of it). 140 141Plain reports must not be sent on the ctrl channel, though. Instead, the ctrl 142channel provides synchronous GET/SET_REPORT requests. Plain reports are only 143allowed 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 its 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 175Other 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 1832) HID API 184========== 185 1862.1) Initialization 187------------------- 188 189Transport drivers normally use the following procedure to register a new device 190with 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 218Once 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 220transport-drivers if not supported. 221 222To unregister a device, use:: 223 224 hid_destroy_device(hid); 225 226Once hid_destroy_device() returns, HID core will no longer make use of any 227driver callbacks. 228 2292.2) hid_ll_driver operations 230----------------------------- 231 232The 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 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 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 3392.3) Data Path 340-------------- 341 342Transport drivers are responsible of reading data from I/O devices. They must 343handle any I/O-related state-tracking themselves. HID core does not implement 344protocol handshakes or other management commands which can be required by the 345given HID transport specification. 346 347Every raw data packet read from a device must be fed into HID core via 348hid_input_report(). You must specify the channel-type (intr or ctrl) and report 349type (input/output/feature). Under normal conditions, only input reports are 350provided via this API. 351 352Responses to GET_REPORT requests via ->request() must also be provided via this 353API. Responses to ->raw_request() are synchronous and must be intercepted by the 354transport driver and not passed to hid_input_report(). 355Acknowledgements to SET_REPORT requests are not of interest to HID core. 356 357---------------------------------------------------- 358 359Written 2013, David Herrmann <dh.herrmann@gmail.com> 360