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