1cca47861SMauro Carvalho Chehab========================= 2cca47861SMauro Carvalho ChehabHID I/O Transport Drivers 3cca47861SMauro Carvalho Chehab========================= 4cca47861SMauro Carvalho Chehab 5cca47861SMauro Carvalho ChehabThe HID subsystem is independent of the underlying transport driver. Initially, 6cca47861SMauro Carvalho Chehabonly USB was supported, but other specifications adopted the HID design and 7cca47861SMauro Carvalho Chehabprovided new transport drivers. The kernel includes at least support for USB, 8cca47861SMauro Carvalho ChehabBluetooth, I2C and user-space I/O drivers. 9cca47861SMauro Carvalho Chehab 10cca47861SMauro Carvalho Chehab1) HID Bus 11cca47861SMauro Carvalho Chehab========== 12cca47861SMauro Carvalho Chehab 13cca47861SMauro Carvalho ChehabThe HID subsystem is designed as a bus. Any I/O subsystem may provide HID 14cca47861SMauro Carvalho Chehabdevices and register them with the HID bus. HID core then loads generic device 15cca47861SMauro Carvalho Chehabdrivers on top of it. The transport drivers are responsible of raw data 16cca47861SMauro Carvalho Chehabtransport and device setup/management. HID core is responsible of 17cca47861SMauro Carvalho Chehabreport-parsing, report interpretation and the user-space API. Device specifics 18cca47861SMauro Carvalho Chehaband quirks are handled by all layers depending on the quirk. 19cca47861SMauro Carvalho Chehab 20cca47861SMauro Carvalho Chehab:: 21cca47861SMauro Carvalho Chehab 22cca47861SMauro Carvalho Chehab +-----------+ +-----------+ +-----------+ +-----------+ 23cca47861SMauro Carvalho Chehab | Device #1 | | Device #i | | Device #j | | Device #k | 24cca47861SMauro Carvalho Chehab +-----------+ +-----------+ +-----------+ +-----------+ 25cca47861SMauro Carvalho Chehab \\ // \\ // 26cca47861SMauro Carvalho Chehab +------------+ +------------+ 27cca47861SMauro Carvalho Chehab | I/O Driver | | I/O Driver | 28cca47861SMauro Carvalho Chehab +------------+ +------------+ 29cca47861SMauro Carvalho Chehab || || 30cca47861SMauro Carvalho Chehab +------------------+ +------------------+ 31cca47861SMauro Carvalho Chehab | Transport Driver | | Transport Driver | 32cca47861SMauro Carvalho Chehab +------------------+ +------------------+ 33cca47861SMauro Carvalho Chehab \___ ___/ 34cca47861SMauro Carvalho Chehab \ / 35cca47861SMauro Carvalho Chehab +----------------+ 36cca47861SMauro Carvalho Chehab | HID Core | 37cca47861SMauro Carvalho Chehab +----------------+ 38cca47861SMauro Carvalho Chehab / | | \ 39cca47861SMauro Carvalho Chehab / | | \ 40cca47861SMauro Carvalho Chehab ____________/ | | \_________________ 41cca47861SMauro Carvalho Chehab / | | \ 42cca47861SMauro Carvalho Chehab / | | \ 43cca47861SMauro Carvalho Chehab +----------------+ +-----------+ +------------------+ +------------------+ 44cca47861SMauro Carvalho Chehab | Generic Driver | | MT Driver | | Custom Driver #1 | | Custom Driver #2 | 45cca47861SMauro Carvalho Chehab +----------------+ +-----------+ +------------------+ +------------------+ 46cca47861SMauro Carvalho Chehab 47cca47861SMauro Carvalho ChehabExample Drivers: 48cca47861SMauro Carvalho Chehab 49cca47861SMauro Carvalho Chehab - I/O: USB, I2C, Bluetooth-l2cap 50cca47861SMauro Carvalho Chehab - Transport: USB-HID, I2C-HID, BT-HIDP 51cca47861SMauro Carvalho Chehab 52cca47861SMauro Carvalho ChehabEverything below "HID Core" is simplified in this graph as it is only of 53cca47861SMauro Carvalho Chehabinterest to HID device drivers. Transport drivers do not need to know the 54cca47861SMauro Carvalho Chehabspecifics. 55cca47861SMauro Carvalho Chehab 56cca47861SMauro Carvalho Chehab1.1) Device Setup 57cca47861SMauro Carvalho Chehab----------------- 58cca47861SMauro Carvalho Chehab 59cca47861SMauro Carvalho ChehabI/O drivers normally provide hotplug detection or device enumeration APIs to the 60cca47861SMauro Carvalho Chehabtransport drivers. Transport drivers use this to find any suitable HID device. 61cca47861SMauro Carvalho ChehabThey allocate HID device objects and register them with HID core. Transport 62cca47861SMauro Carvalho Chehabdrivers are not required to register themselves with HID core. HID core is never 63cca47861SMauro Carvalho Chehabaware of which transport drivers are available and is not interested in it. It 64cca47861SMauro Carvalho Chehabis only interested in devices. 65cca47861SMauro Carvalho Chehab 66cca47861SMauro Carvalho ChehabTransport drivers attach a constant "struct hid_ll_driver" object with each 67cca47861SMauro Carvalho Chehabdevice. Once a device is registered with HID core, the callbacks provided via 68cca47861SMauro Carvalho Chehabthis struct are used by HID core to communicate with the device. 69cca47861SMauro Carvalho Chehab 70cca47861SMauro Carvalho ChehabTransport drivers are responsible of detecting device failures and unplugging. 71cca47861SMauro Carvalho ChehabHID core will operate a device as long as it is registered regardless of any 72cca47861SMauro Carvalho Chehabdevice failures. Once transport drivers detect unplug or failure events, they 73cca47861SMauro Carvalho Chehabmust unregister the device from HID core and HID core will stop using the 74cca47861SMauro Carvalho Chehabprovided callbacks. 75cca47861SMauro Carvalho Chehab 76cca47861SMauro Carvalho Chehab1.2) Transport Driver Requirements 77cca47861SMauro Carvalho Chehab---------------------------------- 78cca47861SMauro Carvalho Chehab 79cca47861SMauro Carvalho ChehabThe terms "asynchronous" and "synchronous" in this document describe the 80cca47861SMauro Carvalho Chehabtransmission behavior regarding acknowledgements. An asynchronous channel must 81cca47861SMauro Carvalho Chehabnot perform any synchronous operations like waiting for acknowledgements or 82cca47861SMauro Carvalho Chehabverifications. Generally, HID calls operating on asynchronous channels must be 83cca47861SMauro Carvalho Chehabrunning in atomic-context just fine. 84cca47861SMauro Carvalho ChehabOn the other hand, synchronous channels can be implemented by the transport 85cca47861SMauro Carvalho Chehabdriver in whatever way they like. They might just be the same as asynchronous 86cca47861SMauro Carvalho Chehabchannels, but they can also provide acknowledgement reports, automatic 87cca47861SMauro Carvalho Chehabretransmission on failure, etc. in a blocking manner. If such functionality is 88cca47861SMauro Carvalho Chehabrequired on asynchronous channels, a transport-driver must implement that via 89cca47861SMauro Carvalho Chehabits own worker threads. 90cca47861SMauro Carvalho Chehab 91cca47861SMauro Carvalho ChehabHID core requires transport drivers to follow a given design. A Transport 92cca47861SMauro Carvalho Chehabdriver must provide two bi-directional I/O channels to each HID device. These 93cca47861SMauro Carvalho Chehabchannels must not necessarily be bi-directional in the hardware itself. A 94cca47861SMauro Carvalho Chehabtransport driver might just provide 4 uni-directional channels. Or it might 95cca47861SMauro Carvalho Chehabmultiplex all four on a single physical channel. However, in this document we 96cca47861SMauro Carvalho Chehabwill describe them as two bi-directional channels as they have several 97cca47861SMauro Carvalho Chehabproperties in common. 98cca47861SMauro Carvalho Chehab 99cca47861SMauro Carvalho Chehab - Interrupt Channel (intr): The intr channel is used for asynchronous data 100cca47861SMauro Carvalho Chehab reports. No management commands or data acknowledgements are sent on this 101cca47861SMauro Carvalho Chehab channel. Any unrequested incoming or outgoing data report must be sent on 102cca47861SMauro Carvalho Chehab this channel and is never acknowledged by the remote side. Devices usually 103cca47861SMauro Carvalho Chehab send their input events on this channel. Outgoing events are normally 104cca47861SMauro Carvalho Chehab not send via intr, except if high throughput is required. 105cca47861SMauro Carvalho Chehab - Control Channel (ctrl): The ctrl channel is used for synchronous requests and 106cca47861SMauro Carvalho Chehab device management. Unrequested data input events must not be sent on this 107cca47861SMauro Carvalho Chehab channel and are normally ignored. Instead, devices only send management 108cca47861SMauro Carvalho Chehab events or answers to host requests on this channel. 109cca47861SMauro Carvalho Chehab The control-channel is used for direct blocking queries to the device 110cca47861SMauro Carvalho Chehab independent of any events on the intr-channel. 111cca47861SMauro Carvalho Chehab Outgoing reports are usually sent on the ctrl channel via synchronous 112cca47861SMauro Carvalho Chehab SET_REPORT requests. 113cca47861SMauro Carvalho Chehab 114cca47861SMauro Carvalho ChehabCommunication between devices and HID core is mostly done via HID reports. A 115cca47861SMauro Carvalho Chehabreport can be of one of three types: 116cca47861SMauro Carvalho Chehab 117cca47861SMauro Carvalho Chehab - INPUT Report: Input reports provide data from device to host. This 118cca47861SMauro Carvalho Chehab data may include button events, axis events, battery status or more. This 119cca47861SMauro Carvalho Chehab data is generated by the device and sent to the host with or without 120cca47861SMauro Carvalho Chehab requiring explicit requests. Devices can choose to send data continuously or 121cca47861SMauro Carvalho Chehab only on change. 122cca47861SMauro Carvalho Chehab - OUTPUT Report: Output reports change device states. They are sent from host 123cca47861SMauro Carvalho Chehab to device and may include LED requests, rumble requests or more. Output 124cca47861SMauro Carvalho Chehab reports are never sent from device to host, but a host can retrieve their 125cca47861SMauro Carvalho Chehab current state. 126cca47861SMauro Carvalho Chehab Hosts may choose to send output reports either continuously or only on 127cca47861SMauro Carvalho Chehab change. 128cca47861SMauro Carvalho Chehab - FEATURE Report: Feature reports are used for specific static device features 129cca47861SMauro Carvalho Chehab and never reported spontaneously. A host can read and/or write them to access 130cca47861SMauro Carvalho Chehab data like battery-state or device-settings. 131cca47861SMauro Carvalho Chehab Feature reports are never sent without requests. A host must explicitly set 132cca47861SMauro Carvalho Chehab or retrieve a feature report. This also means, feature reports are never sent 133cca47861SMauro Carvalho Chehab on the intr channel as this channel is asynchronous. 134cca47861SMauro Carvalho Chehab 135cca47861SMauro Carvalho ChehabINPUT and OUTPUT reports can be sent as pure data reports on the intr channel. 136cca47861SMauro Carvalho ChehabFor INPUT reports this is the usual operational mode. But for OUTPUT reports, 137cca47861SMauro Carvalho Chehabthis is rarely done as OUTPUT reports are normally quite scarce. But devices are 138cca47861SMauro Carvalho Chehabfree to make excessive use of asynchronous OUTPUT reports (for instance, custom 139cca47861SMauro Carvalho ChehabHID audio speakers make great use of it). 140cca47861SMauro Carvalho Chehab 141cca47861SMauro Carvalho ChehabPlain reports must not be sent on the ctrl channel, though. Instead, the ctrl 142cca47861SMauro Carvalho Chehabchannel provides synchronous GET/SET_REPORT requests. Plain reports are only 143cca47861SMauro Carvalho Chehaballowed on the intr channel and are the only means of data there. 144cca47861SMauro Carvalho Chehab 145cca47861SMauro Carvalho Chehab - GET_REPORT: A GET_REPORT request has a report ID as payload and is sent 146cca47861SMauro Carvalho Chehab from host to device. The device must answer with a data report for the 147cca47861SMauro Carvalho Chehab requested report ID on the ctrl channel as a synchronous acknowledgement. 148cca47861SMauro Carvalho Chehab Only one GET_REPORT request can be pending for each device. This restriction 149cca47861SMauro Carvalho Chehab is enforced by HID core as several transport drivers don't allow multiple 150cca47861SMauro Carvalho Chehab simultaneous GET_REPORT requests. 151cca47861SMauro Carvalho Chehab Note that data reports which are sent as answer to a GET_REPORT request are 152cca47861SMauro Carvalho Chehab not handled as generic device events. That is, if a device does not operate 153cca47861SMauro Carvalho Chehab in continuous data reporting mode, an answer to GET_REPORT does not replace 154cca47861SMauro Carvalho Chehab the raw data report on the intr channel on state change. 155cca47861SMauro Carvalho Chehab GET_REPORT is only used by custom HID device drivers to query device state. 156cca47861SMauro Carvalho Chehab Normally, HID core caches any device state so this request is not necessary 157cca47861SMauro Carvalho Chehab on devices that follow the HID specs except during device initialization to 158cca47861SMauro Carvalho Chehab retrieve the current state. 159cca47861SMauro Carvalho Chehab GET_REPORT requests can be sent for any of the 3 report types and shall 160cca47861SMauro Carvalho Chehab return the current report state of the device. However, OUTPUT reports as 161cca47861SMauro Carvalho Chehab payload may be blocked by the underlying transport driver if the 162cca47861SMauro Carvalho Chehab specification does not allow them. 163cca47861SMauro Carvalho Chehab - SET_REPORT: A SET_REPORT request has a report ID plus data as payload. It is 164cca47861SMauro Carvalho Chehab sent from host to device and a device must update it's current report state 165cca47861SMauro Carvalho Chehab according to the given data. Any of the 3 report types can be used. However, 166cca47861SMauro Carvalho Chehab INPUT reports as payload might be blocked by the underlying transport driver 167cca47861SMauro Carvalho Chehab if the specification does not allow them. 168cca47861SMauro Carvalho Chehab A device must answer with a synchronous acknowledgement. However, HID core 169cca47861SMauro Carvalho Chehab does not require transport drivers to forward this acknowledgement to HID 170cca47861SMauro Carvalho Chehab core. 171cca47861SMauro Carvalho Chehab Same as for GET_REPORT, only one SET_REPORT can be pending at a time. This 172cca47861SMauro Carvalho Chehab restriction is enforced by HID core as some transport drivers do not support 173cca47861SMauro Carvalho Chehab multiple synchronous SET_REPORT requests. 174cca47861SMauro Carvalho Chehab 175cca47861SMauro Carvalho ChehabOther ctrl-channel requests are supported by USB-HID but are not available 176cca47861SMauro Carvalho Chehab(or deprecated) in most other transport level specifications: 177cca47861SMauro Carvalho Chehab 178cca47861SMauro Carvalho Chehab - GET/SET_IDLE: Only used by USB-HID and I2C-HID. 179cca47861SMauro Carvalho Chehab - GET/SET_PROTOCOL: Not used by HID core. 180cca47861SMauro Carvalho Chehab - RESET: Used by I2C-HID, not hooked up in HID core. 181cca47861SMauro Carvalho Chehab - SET_POWER: Used by I2C-HID, not hooked up in HID core. 182cca47861SMauro Carvalho Chehab 183cca47861SMauro Carvalho Chehab2) HID API 184cca47861SMauro Carvalho Chehab========== 185cca47861SMauro Carvalho Chehab 186cca47861SMauro Carvalho Chehab2.1) Initialization 187cca47861SMauro Carvalho Chehab------------------- 188cca47861SMauro Carvalho Chehab 189cca47861SMauro Carvalho ChehabTransport drivers normally use the following procedure to register a new device 190cca47861SMauro Carvalho Chehabwith HID core:: 191cca47861SMauro Carvalho Chehab 192cca47861SMauro Carvalho Chehab struct hid_device *hid; 193cca47861SMauro Carvalho Chehab int ret; 194cca47861SMauro Carvalho Chehab 195cca47861SMauro Carvalho Chehab hid = hid_allocate_device(); 196cca47861SMauro Carvalho Chehab if (IS_ERR(hid)) { 197cca47861SMauro Carvalho Chehab ret = PTR_ERR(hid); 198cca47861SMauro Carvalho Chehab goto err_<...>; 199cca47861SMauro Carvalho Chehab } 200cca47861SMauro Carvalho Chehab 2014832a4daSLinus Torvalds strscpy(hid->name, <device-name-src>, sizeof(hid->name)); 2024832a4daSLinus Torvalds strscpy(hid->phys, <device-phys-src>, sizeof(hid->phys)); 2034832a4daSLinus Torvalds strscpy(hid->uniq, <device-uniq-src>, sizeof(hid->uniq)); 204cca47861SMauro Carvalho Chehab 205cca47861SMauro Carvalho Chehab hid->ll_driver = &custom_ll_driver; 206cca47861SMauro Carvalho Chehab hid->bus = <device-bus>; 207cca47861SMauro Carvalho Chehab hid->vendor = <device-vendor>; 208cca47861SMauro Carvalho Chehab hid->product = <device-product>; 209cca47861SMauro Carvalho Chehab hid->version = <device-version>; 210cca47861SMauro Carvalho Chehab hid->country = <device-country>; 211cca47861SMauro Carvalho Chehab hid->dev.parent = <pointer-to-parent-device>; 212cca47861SMauro Carvalho Chehab hid->driver_data = <transport-driver-data-field>; 213cca47861SMauro Carvalho Chehab 214cca47861SMauro Carvalho Chehab ret = hid_add_device(hid); 215cca47861SMauro Carvalho Chehab if (ret) 216cca47861SMauro Carvalho Chehab goto err_<...>; 217cca47861SMauro Carvalho Chehab 218cca47861SMauro Carvalho ChehabOnce hid_add_device() is entered, HID core might use the callbacks provided in 219cca47861SMauro Carvalho Chehab"custom_ll_driver". Note that fields like "country" can be ignored by underlying 220cca47861SMauro Carvalho Chehabtransport-drivers if not supported. 221cca47861SMauro Carvalho Chehab 222cca47861SMauro Carvalho ChehabTo unregister a device, use:: 223cca47861SMauro Carvalho Chehab 224cca47861SMauro Carvalho Chehab hid_destroy_device(hid); 225cca47861SMauro Carvalho Chehab 226cca47861SMauro Carvalho ChehabOnce hid_destroy_device() returns, HID core will no longer make use of any 227cca47861SMauro Carvalho Chehabdriver callbacks. 228cca47861SMauro Carvalho Chehab 229cca47861SMauro Carvalho Chehab2.2) hid_ll_driver operations 230cca47861SMauro Carvalho Chehab----------------------------- 231cca47861SMauro Carvalho Chehab 232cca47861SMauro Carvalho ChehabThe available HID callbacks are: 233cca47861SMauro Carvalho Chehab 234cca47861SMauro Carvalho Chehab :: 235cca47861SMauro Carvalho Chehab 236cca47861SMauro Carvalho Chehab int (*start) (struct hid_device *hdev) 237cca47861SMauro Carvalho Chehab 238cca47861SMauro Carvalho Chehab Called from HID device drivers once they want to use the device. Transport 239cca47861SMauro Carvalho Chehab drivers can choose to setup their device in this callback. However, normally 240cca47861SMauro Carvalho Chehab devices are already set up before transport drivers register them to HID core 241cca47861SMauro Carvalho Chehab so this is mostly only used by USB-HID. 242cca47861SMauro Carvalho Chehab 243cca47861SMauro Carvalho Chehab :: 244cca47861SMauro Carvalho Chehab 245cca47861SMauro Carvalho Chehab void (*stop) (struct hid_device *hdev) 246cca47861SMauro Carvalho Chehab 247cca47861SMauro Carvalho Chehab Called from HID device drivers once they are done with a device. Transport 248cca47861SMauro Carvalho Chehab drivers can free any buffers and deinitialize the device. But note that 249cca47861SMauro Carvalho Chehab ->start() might be called again if another HID device driver is loaded on the 250cca47861SMauro Carvalho Chehab device. 251cca47861SMauro Carvalho Chehab 252cca47861SMauro Carvalho Chehab Transport drivers are free to ignore it and deinitialize devices after they 253cca47861SMauro Carvalho Chehab destroyed them via hid_destroy_device(). 254cca47861SMauro Carvalho Chehab 255cca47861SMauro Carvalho Chehab :: 256cca47861SMauro Carvalho Chehab 257cca47861SMauro Carvalho Chehab int (*open) (struct hid_device *hdev) 258cca47861SMauro Carvalho Chehab 259cca47861SMauro Carvalho Chehab Called from HID device drivers once they are interested in data reports. 260cca47861SMauro Carvalho Chehab Usually, while user-space didn't open any input API/etc., device drivers are 261cca47861SMauro Carvalho Chehab not interested in device data and transport drivers can put devices asleep. 262cca47861SMauro Carvalho Chehab However, once ->open() is called, transport drivers must be ready for I/O. 263cca47861SMauro Carvalho Chehab ->open() calls are nested for each client that opens the HID device. 264cca47861SMauro Carvalho Chehab 265cca47861SMauro Carvalho Chehab :: 266cca47861SMauro Carvalho Chehab 267cca47861SMauro Carvalho Chehab void (*close) (struct hid_device *hdev) 268cca47861SMauro Carvalho Chehab 269cca47861SMauro Carvalho Chehab Called from HID device drivers after ->open() was called but they are no 270cca47861SMauro Carvalho Chehab longer interested in device reports. (Usually if user-space closed any input 271cca47861SMauro Carvalho Chehab devices of the driver). 272cca47861SMauro Carvalho Chehab 273cca47861SMauro Carvalho Chehab Transport drivers can put devices asleep and terminate any I/O of all 274cca47861SMauro Carvalho Chehab ->open() calls have been followed by a ->close() call. However, ->start() may 275cca47861SMauro Carvalho Chehab be called again if the device driver is interested in input reports again. 276cca47861SMauro Carvalho Chehab 277cca47861SMauro Carvalho Chehab :: 278cca47861SMauro Carvalho Chehab 279cca47861SMauro Carvalho Chehab int (*parse) (struct hid_device *hdev) 280cca47861SMauro Carvalho Chehab 281cca47861SMauro Carvalho Chehab Called once during device setup after ->start() has been called. Transport 282cca47861SMauro Carvalho Chehab drivers must read the HID report-descriptor from the device and tell HID core 283cca47861SMauro Carvalho Chehab about it via hid_parse_report(). 284cca47861SMauro Carvalho Chehab 285cca47861SMauro Carvalho Chehab :: 286cca47861SMauro Carvalho Chehab 287cca47861SMauro Carvalho Chehab int (*power) (struct hid_device *hdev, int level) 288cca47861SMauro Carvalho Chehab 289cca47861SMauro Carvalho Chehab Called by HID core to give PM hints to transport drivers. Usually this is 290cca47861SMauro Carvalho Chehab analogical to the ->open() and ->close() hints and redundant. 291cca47861SMauro Carvalho Chehab 292cca47861SMauro Carvalho Chehab :: 293cca47861SMauro Carvalho Chehab 294cca47861SMauro Carvalho Chehab void (*request) (struct hid_device *hdev, struct hid_report *report, 295cca47861SMauro Carvalho Chehab int reqtype) 296cca47861SMauro Carvalho Chehab 297cca47861SMauro Carvalho Chehab Send an HID request on the ctrl channel. "report" contains the report that 298cca47861SMauro Carvalho Chehab should be sent and "reqtype" the request type. Request-type can be 299cca47861SMauro Carvalho Chehab HID_REQ_SET_REPORT or HID_REQ_GET_REPORT. 300cca47861SMauro Carvalho Chehab 301cca47861SMauro Carvalho Chehab This callback is optional. If not provided, HID core will assemble a raw 302cca47861SMauro Carvalho Chehab report following the HID specs and send it via the ->raw_request() callback. 303cca47861SMauro Carvalho Chehab The transport driver is free to implement this asynchronously. 304cca47861SMauro Carvalho Chehab 305cca47861SMauro Carvalho Chehab :: 306cca47861SMauro Carvalho Chehab 307cca47861SMauro Carvalho Chehab int (*wait) (struct hid_device *hdev) 308cca47861SMauro Carvalho Chehab 309cca47861SMauro Carvalho Chehab Used by HID core before calling ->request() again. A transport driver can use 310cca47861SMauro Carvalho Chehab it to wait for any pending requests to complete if only one request is 311cca47861SMauro Carvalho Chehab allowed at a time. 312cca47861SMauro Carvalho Chehab 313cca47861SMauro Carvalho Chehab :: 314cca47861SMauro Carvalho Chehab 315cca47861SMauro Carvalho Chehab int (*raw_request) (struct hid_device *hdev, unsigned char reportnum, 316cca47861SMauro Carvalho Chehab __u8 *buf, size_t count, unsigned char rtype, 317cca47861SMauro Carvalho Chehab int reqtype) 318cca47861SMauro Carvalho Chehab 319cca47861SMauro Carvalho Chehab Same as ->request() but provides the report as raw buffer. This request shall 320cca47861SMauro Carvalho Chehab be synchronous. A transport driver must not use ->wait() to complete such 321cca47861SMauro Carvalho Chehab requests. This request is mandatory and hid core will reject the device if 322cca47861SMauro Carvalho Chehab it is missing. 323cca47861SMauro Carvalho Chehab 324cca47861SMauro Carvalho Chehab :: 325cca47861SMauro Carvalho Chehab 326cca47861SMauro Carvalho Chehab int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len) 327cca47861SMauro Carvalho Chehab 328cca47861SMauro Carvalho Chehab Send raw output report via intr channel. Used by some HID device drivers 329cca47861SMauro Carvalho Chehab which require high throughput for outgoing requests on the intr channel. This 330cca47861SMauro Carvalho Chehab must not cause SET_REPORT calls! This must be implemented as asynchronous 331cca47861SMauro Carvalho Chehab output report on the intr channel! 332cca47861SMauro Carvalho Chehab 333cca47861SMauro Carvalho Chehab :: 334cca47861SMauro Carvalho Chehab 335cca47861SMauro Carvalho Chehab int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype) 336cca47861SMauro Carvalho Chehab 337cca47861SMauro Carvalho Chehab Perform SET/GET_IDLE request. Only used by USB-HID, do not implement! 338cca47861SMauro Carvalho Chehab 339cca47861SMauro Carvalho Chehab2.3) Data Path 340cca47861SMauro Carvalho Chehab-------------- 341cca47861SMauro Carvalho Chehab 342cca47861SMauro Carvalho ChehabTransport drivers are responsible of reading data from I/O devices. They must 343cca47861SMauro Carvalho Chehabhandle any I/O-related state-tracking themselves. HID core does not implement 344cca47861SMauro Carvalho Chehabprotocol handshakes or other management commands which can be required by the 345cca47861SMauro Carvalho Chehabgiven HID transport specification. 346cca47861SMauro Carvalho Chehab 347cca47861SMauro Carvalho ChehabEvery raw data packet read from a device must be fed into HID core via 348cca47861SMauro Carvalho Chehabhid_input_report(). You must specify the channel-type (intr or ctrl) and report 349cca47861SMauro Carvalho Chehabtype (input/output/feature). Under normal conditions, only input reports are 350cca47861SMauro Carvalho Chehabprovided via this API. 351cca47861SMauro Carvalho Chehab 352cca47861SMauro Carvalho ChehabResponses to GET_REPORT requests via ->request() must also be provided via this 353cca47861SMauro Carvalho ChehabAPI. Responses to ->raw_request() are synchronous and must be intercepted by the 354cca47861SMauro Carvalho Chehabtransport driver and not passed to hid_input_report(). 355cca47861SMauro Carvalho ChehabAcknowledgements to SET_REPORT requests are not of interest to HID core. 356cca47861SMauro Carvalho Chehab 357cca47861SMauro Carvalho Chehab---------------------------------------------------- 358cca47861SMauro Carvalho Chehab 359cca47861SMauro Carvalho ChehabWritten 2013, David Herrmann <dh.herrmann@gmail.com> 360