Lines Matching +full:i2c +full:- +full:hid
2 HID I/O Transport Drivers
5 The HID subsystem is independent of the underlying transport driver. Initially,
6 only USB was supported, but other specifications adopted the HID design and
8 Bluetooth, I2C and user-space I/O drivers.
10 1) HID Bus
13 The HID subsystem is designed as a bus. Any I/O subsystem may provide HID
14 devices and register them with the HID bus. HID core then loads generic device
16 transport and device setup/management. HID core is responsible for
17 report-parsing, report interpretation and the user-space API. Device specifics
22 +-----------+ +-----------+ +-----------+ +-----------+
24 +-----------+ +-----------+ +-----------+ +-----------+
26 +------------+ +------------+
28 +------------+ +------------+
30 +------------------+ +------------------+
32 +------------------+ +------------------+
35 +----------------+
36 | HID Core |
37 +----------------+
43 +----------------+ +-----------+ +------------------+ +------------------+
45 +----------------+ +-----------+ +------------------+ +------------------+
49 - I/O: USB, I2C, Bluetooth-l2cap
50 - Transport: USB-HID, I2C-HID, BT-HIDP
52 Everything below "HID Core" is simplified in this graph as it is only of
53 interest to HID device drivers. Transport drivers do not need to know the
57 -----------------
60 transport drivers. Transport drivers use this to find any suitable HID device.
61 They allocate HID device objects and register them with HID core. Transport
62 drivers are not required to register themselves with HID core. HID core is never
67 device. Once a device is registered with HID core, the callbacks provided via
68 this struct are used by HID core to communicate with the device.
71 HID core will operate a device as long as it is registered regardless of any
73 must unregister the device from HID core and HID core will stop using the
77 ----------------------------------
82 verifications. Generally, HID calls operating on asynchronous channels must be
83 running in atomic-context just fine.
88 required on asynchronous channels, a transport-driver must implement that via
91 HID core requires transport drivers to follow a given design. A Transport
92 driver must provide two bi-directional I/O channels to each HID device. These
93 channels must not necessarily be bi-directional in the hardware itself. A
94 transport driver might just provide 4 uni-directional channels. Or it might
96 will describe them as two bi-directional channels as they have several
99 - Interrupt Channel (intr): The intr channel is used for asynchronous data
105 - Control Channel (ctrl): The ctrl channel is used for synchronous requests and
109 The control-channel is used for direct blocking queries to the device
110 independent of any events on the intr-channel.
114 Communication between devices and HID core is mostly done via HID reports. A
117 - INPUT Report: Input reports provide data from device to host. This
122 - OUTPUT Report: Output reports change device states. They are sent from host
128 - FEATURE Report: Feature reports are used for specific static device features
130 data like battery-state or device-settings.
139 HID audio speakers make great use of it).
145 - GET_REPORT: A GET_REPORT request has a report ID as payload and is sent
149 is enforced by HID core as several transport drivers don't allow multiple
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
163 - SET_REPORT: A SET_REPORT request has a report ID plus data as payload. It is
168 A device must answer with a synchronous acknowledgement. However, HID core
169 does not require transport drivers to forward this acknowledgement to HID
172 restriction is enforced by HID core as some transport drivers do not support
175 Other ctrl-channel requests are supported by USB-HID but are not available
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.
183 2) HID API
187 -------------------
190 with HID core::
192 struct hid_device *hid;
195 hid = hid_allocate_device();
196 if (IS_ERR(hid)) {
197 ret = PTR_ERR(hid);
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));
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>;
214 ret = hid_add_device(hid);
218 Once hid_add_device() is entered, HID core might use the callbacks provided in
220 transport-drivers if not supported.
224 hid_destroy_device(hid);
226 Once hid_destroy_device() returns, HID core will no longer make use of any
230 -----------------------------
232 The available HID callbacks are:
238 Called from HID device drivers once they want to use the device. Transport
240 devices are already set up before transport drivers register them to HID core
241 so this is mostly only used by USB-HID.
247 Called from HID device drivers once they are done with a device. Transport
249 ->start() might be called again if another HID device driver is loaded on the
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
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.
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
274 ->open() calls have been followed by a ->close() call. However, ->start() may
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
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.
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
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.
309 Used by HID core before calling ->request() again. A transport driver can use
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
328 Send raw output report via intr channel. Used by some HID device drivers
337 Perform SET/GET_IDLE request. Only used by USB-HID, do not implement!
340 --------------
343 handle any I/O-related state-tracking themselves. HID core does not implement
345 given HID transport specification.
347 Every raw data packet read from a device must be fed into HID core via
348 hid_input_report(). You must specify the channel-type (intr or ctrl) and report
352 Responses to GET_REPORT requests via ->request() must also be provided via this
353 API. Responses to ->raw_request() are synchronous and must be intercepted by the
355 Acknowledgements to SET_REPORT requests are not of interest to HID core.
357 ----------------------------------------------------