| ========================= |
| HID I/O Transport Drivers |
| ========================= |
| |
| The HID subsystem is independent of the underlying transport driver. Initially, |
| only USB was supported, but other specifications adopted the HID design and |
| provided new transport drivers. The kernel includes at least support for USB, |
| Bluetooth, I2C and user-space I/O drivers. |
| |
| 1) HID Bus |
| ========== |
| |
| The HID subsystem is designed as a bus. Any I/O subsystem may provide HID |
| devices and register them with the HID bus. HID core then loads generic device |
| drivers on top of it. The transport drivers are responsible of raw data |
| transport and device setup/management. HID core is responsible of |
| report-parsing, report interpretation and the user-space API. Device specifics |
| and quirks are handled by all layers depending on the quirk. |
| |
| :: |
| |
| +-----------+ +-----------+ +-----------+ +-----------+ |
| | Device #1 | | Device #i | | Device #j | | Device #k | |
| +-----------+ +-----------+ +-----------+ +-----------+ |
| \\ // \\ // |
| +------------+ +------------+ |
| | I/O Driver | | I/O Driver | |
| +------------+ +------------+ |
| || || |
| +------------------+ +------------------+ |
| | Transport Driver | | Transport Driver | |
| +------------------+ +------------------+ |
| \___ ___/ |
| \ / |
| +----------------+ |
| | HID Core | |
| +----------------+ |
| / | | \ |
| / | | \ |
| ____________/ | | \_________________ |
| / | | \ |
| / | | \ |
| +----------------+ +-----------+ +------------------+ +------------------+ |
| | Generic Driver | | MT Driver | | Custom Driver #1 | | Custom Driver #2 | |
| +----------------+ +-----------+ +------------------+ +------------------+ |
| |
| Example Drivers: |
| |
| - I/O: USB, I2C, Bluetooth-l2cap |
| - Transport: USB-HID, I2C-HID, BT-HIDP |
| |
| Everything below "HID Core" is simplified in this graph as it is only of |
| interest to HID device drivers. Transport drivers do not need to know the |
| specifics. |
| |
| 1.1) Device Setup |
| ----------------- |
| |
| I/O drivers normally provide hotplug detection or device enumeration APIs to the |
| transport drivers. Transport drivers use this to find any suitable HID device. |
| They allocate HID device objects and register them with HID core. Transport |
| drivers are not required to register themselves with HID core. HID core is never |
| aware of which transport drivers are available and is not interested in it. It |
| is only interested in devices. |
| |
| Transport drivers attach a constant "struct hid_ll_driver" object with each |
| device. Once a device is registered with HID core, the callbacks provided via |
| this struct are used by HID core to communicate with the device. |
| |
| Transport drivers are responsible of detecting device failures and unplugging. |
| HID core will operate a device as long as it is registered regardless of any |
| device failures. Once transport drivers detect unplug or failure events, they |
| must unregister the device from HID core and HID core will stop using the |
| provided callbacks. |
| |
| 1.2) Transport Driver Requirements |
| ---------------------------------- |
| |
| The terms "asynchronous" and "synchronous" in this document describe the |
| transmission behavior regarding acknowledgements. An asynchronous channel must |
| not perform any synchronous operations like waiting for acknowledgements or |
| verifications. Generally, HID calls operating on asynchronous channels must be |
| running in atomic-context just fine. |
| On the other hand, synchronous channels can be implemented by the transport |
| driver in whatever way they like. They might just be the same as asynchronous |
| channels, but they can also provide acknowledgement reports, automatic |
| retransmission on failure, etc. in a blocking manner. If such functionality is |
| required on asynchronous channels, a transport-driver must implement that via |
| its own worker threads. |
| |
| HID core requires transport drivers to follow a given design. A Transport |
| driver must provide two bi-directional I/O channels to each HID device. These |
| channels must not necessarily be bi-directional in the hardware itself. A |
| transport driver might just provide 4 uni-directional channels. Or it might |
| multiplex all four on a single physical channel. However, in this document we |
| will describe them as two bi-directional channels as they have several |
| properties in common. |
| |
| - Interrupt Channel (intr): The intr channel is used for asynchronous data |
| reports. No management commands or data acknowledgements are sent on this |
| channel. Any unrequested incoming or outgoing data report must be sent on |
| this channel and is never acknowledged by the remote side. Devices usually |
| send their input events on this channel. Outgoing events are normally |
| not send via intr, except if high throughput is required. |
| - Control Channel (ctrl): The ctrl channel is used for synchronous requests and |
| device management. Unrequested data input events must not be sent on this |
| channel and are normally ignored. Instead, devices only send management |
| events or answers to host requests on this channel. |
| The control-channel is used for direct blocking queries to the device |
| independent of any events on the intr-channel. |
| Outgoing reports are usually sent on the ctrl channel via synchronous |
| SET_REPORT requests. |
| |
| Communication between devices and HID core is mostly done via HID reports. A |
| report can be of one of three types: |
| |
| - INPUT Report: Input reports provide data from device to host. This |
| data may include button events, axis events, battery status or more. This |
| data is generated by the device and sent to the host with or without |
| requiring explicit requests. Devices can choose to send data continuously or |
| only on change. |
| - OUTPUT Report: Output reports change device states. They are sent from host |
| to device and may include LED requests, rumble requests or more. Output |
| reports are never sent from device to host, but a host can retrieve their |
| current state. |
| Hosts may choose to send output reports either continuously or only on |
| change. |
| - FEATURE Report: Feature reports are used for specific static device features |
| and never reported spontaneously. A host can read and/or write them to access |
| data like battery-state or device-settings. |
| Feature reports are never sent without requests. A host must explicitly set |
| or retrieve a feature report. This also means, feature reports are never sent |
| on the intr channel as this channel is asynchronous. |
| |
| INPUT and OUTPUT reports can be sent as pure data reports on the intr channel. |
| For INPUT reports this is the usual operational mode. But for OUTPUT reports, |
| this is rarely done as OUTPUT reports are normally quite scarce. But devices are |
| free to make excessive use of asynchronous OUTPUT reports (for instance, custom |
| HID audio speakers make great use of it). |
| |
| Plain reports must not be sent on the ctrl channel, though. Instead, the ctrl |
| channel provides synchronous GET/SET_REPORT requests. Plain reports are only |
| allowed on the intr channel and are the only means of data there. |
| |
| - GET_REPORT: A GET_REPORT request has a report ID as payload and is sent |
| from host to device. The device must answer with a data report for the |
| requested report ID on the ctrl channel as a synchronous acknowledgement. |
| Only one GET_REPORT request can be pending for each device. This restriction |
| is enforced by HID core as several transport drivers don't allow multiple |
| simultaneous GET_REPORT requests. |
| Note that data reports which are sent as answer to a GET_REPORT request are |
| not handled as generic device events. That is, if a device does not operate |
| in continuous data reporting mode, an answer to GET_REPORT does not replace |
| the raw data report on the intr channel on state change. |
| GET_REPORT is only used by custom HID device drivers to query device state. |
| Normally, HID core caches any device state so this request is not necessary |
| on devices that follow the HID specs except during device initialization to |
| retrieve the current state. |
| GET_REPORT requests can be sent for any of the 3 report types and shall |
| return the current report state of the device. However, OUTPUT reports as |
| payload may be blocked by the underlying transport driver if the |
| specification does not allow them. |
| - SET_REPORT: A SET_REPORT request has a report ID plus data as payload. It is |
| sent from host to device and a device must update it's current report state |
| according to the given data. Any of the 3 report types can be used. However, |
| INPUT reports as payload might be blocked by the underlying transport driver |
| if the specification does not allow them. |
| A device must answer with a synchronous acknowledgement. However, HID core |
| does not require transport drivers to forward this acknowledgement to HID |
| core. |
| Same as for GET_REPORT, only one SET_REPORT can be pending at a time. This |
| restriction is enforced by HID core as some transport drivers do not support |
| multiple synchronous SET_REPORT requests. |
| |
| Other ctrl-channel requests are supported by USB-HID but are not available |
| (or deprecated) in most other transport level specifications: |
| |
| - GET/SET_IDLE: Only used by USB-HID and I2C-HID. |
| - GET/SET_PROTOCOL: Not used by HID core. |
| - RESET: Used by I2C-HID, not hooked up in HID core. |
| - SET_POWER: Used by I2C-HID, not hooked up in HID core. |
| |
| 2) HID API |
| ========== |
| |
| 2.1) Initialization |
| ------------------- |
| |
| Transport drivers normally use the following procedure to register a new device |
| with HID core:: |
| |
| struct hid_device *hid; |
| int ret; |
| |
| hid = hid_allocate_device(); |
| if (IS_ERR(hid)) { |
| ret = PTR_ERR(hid); |
| goto err_<...>; |
| } |
| |
| strscpy(hid->name, <device-name-src>, sizeof(hid->name)); |
| strscpy(hid->phys, <device-phys-src>, sizeof(hid->phys)); |
| strscpy(hid->uniq, <device-uniq-src>, sizeof(hid->uniq)); |
| |
| hid->ll_driver = &custom_ll_driver; |
| hid->bus = <device-bus>; |
| hid->vendor = <device-vendor>; |
| hid->product = <device-product>; |
| hid->version = <device-version>; |
| hid->country = <device-country>; |
| hid->dev.parent = <pointer-to-parent-device>; |
| hid->driver_data = <transport-driver-data-field>; |
| |
| ret = hid_add_device(hid); |
| if (ret) |
| goto err_<...>; |
| |
| Once hid_add_device() is entered, HID core might use the callbacks provided in |
| "custom_ll_driver". Note that fields like "country" can be ignored by underlying |
| transport-drivers if not supported. |
| |
| To unregister a device, use:: |
| |
| hid_destroy_device(hid); |
| |
| Once hid_destroy_device() returns, HID core will no longer make use of any |
| driver callbacks. |
| |
| 2.2) hid_ll_driver operations |
| ----------------------------- |
| |
| The available HID callbacks are: |
| |
| :: |
| |
| int (*start) (struct hid_device *hdev) |
| |
| Called from HID device drivers once they want to use the device. Transport |
| drivers can choose to setup their device in this callback. However, normally |
| devices are already set up before transport drivers register them to HID core |
| so this is mostly only used by USB-HID. |
| |
| :: |
| |
| void (*stop) (struct hid_device *hdev) |
| |
| Called from HID device drivers once they are done with a device. Transport |
| drivers can free any buffers and deinitialize the device. But note that |
| ->start() might be called again if another HID device driver is loaded on the |
| device. |
| |
| Transport drivers are free to ignore it and deinitialize devices after they |
| destroyed them via hid_destroy_device(). |
| |
| :: |
| |
| int (*open) (struct hid_device *hdev) |
| |
| Called from HID device drivers once they are interested in data reports. |
| Usually, while user-space didn't open any input API/etc., device drivers are |
| not interested in device data and transport drivers can put devices asleep. |
| However, once ->open() is called, transport drivers must be ready for I/O. |
| ->open() calls are nested for each client that opens the HID device. |
| |
| :: |
| |
| void (*close) (struct hid_device *hdev) |
| |
| Called from HID device drivers after ->open() was called but they are no |
| longer interested in device reports. (Usually if user-space closed any input |
| devices of the driver). |
| |
| Transport drivers can put devices asleep and terminate any I/O of all |
| ->open() calls have been followed by a ->close() call. However, ->start() may |
| be called again if the device driver is interested in input reports again. |
| |
| :: |
| |
| int (*parse) (struct hid_device *hdev) |
| |
| Called once during device setup after ->start() has been called. Transport |
| drivers must read the HID report-descriptor from the device and tell HID core |
| about it via hid_parse_report(). |
| |
| :: |
| |
| int (*power) (struct hid_device *hdev, int level) |
| |
| Called by HID core to give PM hints to transport drivers. Usually this is |
| analogical to the ->open() and ->close() hints and redundant. |
| |
| :: |
| |
| void (*request) (struct hid_device *hdev, struct hid_report *report, |
| int reqtype) |
| |
| Send an HID request on the ctrl channel. "report" contains the report that |
| should be sent and "reqtype" the request type. Request-type can be |
| HID_REQ_SET_REPORT or HID_REQ_GET_REPORT. |
| |
| This callback is optional. If not provided, HID core will assemble a raw |
| report following the HID specs and send it via the ->raw_request() callback. |
| The transport driver is free to implement this asynchronously. |
| |
| :: |
| |
| int (*wait) (struct hid_device *hdev) |
| |
| Used by HID core before calling ->request() again. A transport driver can use |
| it to wait for any pending requests to complete if only one request is |
| allowed at a time. |
| |
| :: |
| |
| int (*raw_request) (struct hid_device *hdev, unsigned char reportnum, |
| __u8 *buf, size_t count, unsigned char rtype, |
| int reqtype) |
| |
| Same as ->request() but provides the report as raw buffer. This request shall |
| be synchronous. A transport driver must not use ->wait() to complete such |
| requests. This request is mandatory and hid core will reject the device if |
| it is missing. |
| |
| :: |
| |
| int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len) |
| |
| Send raw output report via intr channel. Used by some HID device drivers |
| which require high throughput for outgoing requests on the intr channel. This |
| must not cause SET_REPORT calls! This must be implemented as asynchronous |
| output report on the intr channel! |
| |
| :: |
| |
| int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype) |
| |
| Perform SET/GET_IDLE request. Only used by USB-HID, do not implement! |
| |
| 2.3) Data Path |
| -------------- |
| |
| Transport drivers are responsible of reading data from I/O devices. They must |
| handle any I/O-related state-tracking themselves. HID core does not implement |
| protocol handshakes or other management commands which can be required by the |
| given HID transport specification. |
| |
| Every raw data packet read from a device must be fed into HID core via |
| hid_input_report(). You must specify the channel-type (intr or ctrl) and report |
| type (input/output/feature). Under normal conditions, only input reports are |
| provided via this API. |
| |
| Responses to GET_REPORT requests via ->request() must also be provided via this |
| API. Responses to ->raw_request() are synchronous and must be intercepted by the |
| transport driver and not passed to hid_input_report(). |
| Acknowledgements to SET_REPORT requests are not of interest to HID core. |
| |
| ---------------------------------------------------- |
| |
| Written 2013, David Herrmann <dh.herrmann@gmail.com> |
