Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid
authorLinus Torvalds <torvalds@linux-foundation.org>
Thu, 11 Jul 2019 22:32:11 +0000 (15:32 -0700)
committerLinus Torvalds <torvalds@linux-foundation.org>
Thu, 11 Jul 2019 22:32:11 +0000 (15:32 -0700)
Pull HID updates from Jiri Kosina:

 - Documentation conversion to ReST, from Mauro Carvalho Chehab

 - Wacom MobileStudio Pro support, from Ping Cheng

 - Wacom 2nd Gen Intuos Pro Small support, from Aaron Armstrong Skomra

 - assorted small fixes and device ID additions

* 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid:
  HID: Add another Primax PIXART OEM mouse quirk
  HID: wacom: generic: add touchring adjustment for 2nd Gen Pro Small
  docs: hid: convert to ReST
  HID: remove NO_D3 flag when remove driver
  HID: wacom: add new MobileStudio Pro support
  HID: wacom: generic: read the number of expected touches on a per collection basis
  HID: wacom: generic: support the 'report valid' usage for touch
  HID: wacom: generic: read HID_DG_CONTACTMAX from any feature report
  HID: wacom: Add 2nd gen Intuos Pro Small support
  HID: uclogic: Add support for Ugee Rainbow CV720
  HID: logitech-dj: fix return value of logi_dj_recv_query_hidpp_devices
  HID: logitech-hidpp: HID: make const array consumer_rdesc_start static
  HID: logitech-dj: make const array template static
  HID: wacom: correct touch resolution x/y typo
  HID: wacom: generic: Correct pad syncing
  HID: wacom: generic: only switch the mode on devices with LEDs
  HID: logitech-dj: Add usb-id for the 27MHz MX3000 receiver

1  2 
Documentation/hid/hid-transport.rst
MAINTAINERS

index 0000000000000000000000000000000000000000,6f3aaa86ce7b8d06315e2c8ba5d5b398736c6feb..0fe526f36db64313aa88754dde5e8202f8f3035c
mode 000000,100644..100644
--- /dev/null
@@@ -1,0 -1,359 +1,359 @@@
 -      strlcpy(hid->name, <device-name-src>, 127);
 -      strlcpy(hid->phys, <device-phys-src>, 63);
 -      strlcpy(hid->uniq, <device-uniq-src>, 63);
+ =========================
+ 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>
diff --cc MAINTAINERS
Simple merge