lkml.org 
[lkml]   [2019]   [Jun]   [13]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    From
    Date
    SubjectRe: [PATCH v1 20/31] docs: hid: convert to ReST
    On Wed, Jun 12, 2019 at 8:39 PM Mauro Carvalho Chehab
    <mchehab+samsung@kernel.org> wrote:
    >
    > Rename the HID documentation files to ReST, add an
    > index for them and adjust in order to produce a nice html
    > output via the Sphinx build system.
    >
    > While here, fix the sysfs example from hid-sensor.txt, that
    > has a lot of "?" instead of the proper UTF-8 characters that
    > are produced by the tree command.
    >
    > At its new index.rst, let's add a :orphan: while this is not linked to
    > the main index.rst file, in order to avoid build warnings.
    >
    > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
    > ---

    Acked-by: Benjamin Tissoires <benjamin.tissoires@redhat.com>

    Do you need to take this patch through the doc tree or should we carry
    it in the HID one?

    Cheers,
    Benjamin

    > .../hid/{hid-alps.txt => hid-alps.rst} | 85 ++-
    > .../hid/{hid-sensor.txt => hid-sensor.rst} | 192 +++----
    > .../{hid-transport.txt => hid-transport.rst} | 82 ++-
    > Documentation/hid/{hiddev.txt => hiddev.rst} | 154 ++++--
    > Documentation/hid/{hidraw.txt => hidraw.rst} | 53 +-
    > Documentation/hid/index.rst | 18 +
    > Documentation/hid/intel-ish-hid.rst | 485 ++++++++++++++++++
    > Documentation/hid/intel-ish-hid.txt | 454 ----------------
    > Documentation/hid/{uhid.txt => uhid.rst} | 46 +-
    > Documentation/input/input.rst | 2 +-
    > MAINTAINERS | 2 +-
    > 11 files changed, 897 insertions(+), 676 deletions(-)
    > rename Documentation/hid/{hid-alps.txt => hid-alps.rst} (64%)
    > rename Documentation/hid/{hid-sensor.txt => hid-sensor.rst} (61%)
    > rename Documentation/hid/{hid-transport.txt => hid-transport.rst} (93%)
    > rename Documentation/hid/{hiddev.txt => hiddev.rst} (77%)
    > rename Documentation/hid/{hidraw.txt => hidraw.rst} (89%)
    > create mode 100644 Documentation/hid/index.rst
    > create mode 100644 Documentation/hid/intel-ish-hid.rst
    > delete mode 100644 Documentation/hid/intel-ish-hid.txt
    > rename Documentation/hid/{uhid.txt => uhid.rst} (94%)
    >
    > diff --git a/Documentation/hid/hid-alps.txt b/Documentation/hid/hid-alps.rst
    > similarity index 64%
    > rename from Documentation/hid/hid-alps.txt
    > rename to Documentation/hid/hid-alps.rst
    > index 6b02a2447c77..e2f4c4c11e3f 100644
    > --- a/Documentation/hid/hid-alps.txt
    > +++ b/Documentation/hid/hid-alps.rst
    > @@ -1,19 +1,26 @@
    > +==========================
    > ALPS HID Touchpad Protocol
    > -----------------------
    > +==========================
    >
    > Introduction
    > ------------
    > Currently ALPS HID driver supports U1 Touchpad device.
    >
    > -U1 devuce basic information.
    > +U1 device basic information.
    > +
    > +========== ======
    > Vender ID 0x044E
    > Product ID 0x120B
    > Version ID 0x0121
    > +========== ======
    >
    >
    > HID Descriptor
    > -------------
    > +--------------
    > +
    > +======= ==================== ===== =======================================
    > Byte Field Value Notes
    > +======= ==================== ===== =======================================
    > 0 wHIDDescLength 001E Length of HID Descriptor : 30 bytes
    > 2 bcdVersion 0100 Compliant with Version 1.00
    > 4 wReportDescLength 00B2 Report Descriptor is 178 Bytes (0x00B2)
    > @@ -28,32 +35,42 @@ Byte Field Value Notes
    > 22 wProductID 120B Product ID 0x120B
    > 24 wVersionID 0121 Version 01.21
    > 26 RESERVED 0000 RESERVED
    > +======= ==================== ===== =======================================
    >
    >
    > Report ID
    > -------------
    > -ReportID-1 (Input Reports) (HIDUsage-Mouse) for TP&SP
    > -ReportID-2 (Input Reports) (HIDUsage-keyboard) for TP
    > -ReportID-3 (Input Reports) (Vendor Usage: Max 10 finger data) for TP
    > -ReportID-4 (Input Reports) (Vendor Usage: ON bit data) for GP
    > -ReportID-5 (Feature Reports) Feature Reports
    > -ReportID-6 (Input Reports) (Vendor Usage: StickPointer data) for SP
    > -ReportID-7 (Feature Reports) Flash update (Bootloader)
    > +---------
    > +
    > +========== ================= =========================================
    > +ReportID-1 (Input Reports) (HIDUsage-Mouse) for TP&SP
    > +ReportID-2 (Input Reports) (HIDUsage-keyboard) for TP
    > +ReportID-3 (Input Reports) (Vendor Usage: Max 10 finger data) for TP
    > +ReportID-4 (Input Reports) (Vendor Usage: ON bit data) for GP
    > +ReportID-5 (Feature Reports) Feature Reports
    > +ReportID-6 (Input Reports) (Vendor Usage: StickPointer data) for SP
    > +ReportID-7 (Feature Reports) Flash update (Bootloader)
    > +========== ================= =========================================
    >
    >
    > Data pattern
    > ------------
    > +
    > +===== ========== ===== =================
    > Case1 ReportID_1 TP/SP Relative/Relative
    > Case2 ReportID_3 TP Absolute
    > ReportID_6 SP Absolute
    > +===== ========== ===== =================
    >
    >
    > Command Read/Write
    > ------------------
    > To read/write to RAM, need to send a commands to the device.
    > +
    > The command format is as below.
    >
    > DataByte(SET_REPORT)
    > +
    > +===== ======================
    > Byte1 Command Byte
    > Byte2 Address - Byte 0 (LSB)
    > Byte3 Address - Byte 1
    > @@ -61,13 +78,19 @@ Byte4 Address - Byte 2
    > Byte5 Address - Byte 3 (MSB)
    > Byte6 Value Byte
    > Byte7 Checksum
    > +===== ======================
    >
    > Command Byte is read=0xD1/write=0xD2 .
    > +
    > Address is read/write RAM address.
    > +
    > Value Byte is writing data when you send the write commands.
    > +
    > When you read RAM, there is no meaning.
    >
    > DataByte(GET_REPORT)
    > +
    > +===== ======================
    > Byte1 Response Byte
    > Byte2 Address - Byte 0 (LSB)
    > Byte3 Address - Byte 1
    > @@ -75,6 +98,7 @@ Byte4 Address - Byte 2
    > Byte5 Address - Byte 3 (MSB)
    > Byte6 Value Byte
    > Byte7 Checksum
    > +===== ======================
    >
    > Read value is stored in Value Byte.
    >
    > @@ -82,7 +106,11 @@ Read value is stored in Value Byte.
    > Packet Format
    > Touchpad data byte
    > ------------------
    > - b7 b6 b5 b4 b3 b2 b1 b0
    > +
    > +
    > +======= ======= ======= ======= ======= ======= ======= ======= =====
    > +- b7 b6 b5 b4 b3 b2 b1 b0
    > +======= ======= ======= ======= ======= ======= ======= ======= =====
    > 1 0 0 SW6 SW5 SW4 SW3 SW2 SW1
    > 2 0 0 0 Fcv Fn3 Fn2 Fn1 Fn0
    > 3 Xa0_7 Xa0_6 Xa0_5 Xa0_4 Xa0_3 Xa0_2 Xa0_1 Xa0_0
    > @@ -114,17 +142,25 @@ Touchpad data byte
    > 25 Ya4_7 Ya4_6 Ya4_5 Ya4_4 Ya4_3 Ya4_2 Ya4_1 Ya4_0
    > 26 Ya4_15 Ya4_14 Ya4_13 Ya4_12 Ya4_11 Ya4_10 Ya4_9 Ya4_8
    > 27 LFB4 Zs4_6 Zs4_5 Zs4_4 Zs4_3 Zs4_2 Zs4_1 Zs4_0
    > +======= ======= ======= ======= ======= ======= ======= ======= =====
    >
    >
    > -SW1-SW6: SW ON/OFF status
    > -Xan_15-0(16bit):X Absolute data of the "n"th finger
    > -Yan_15-0(16bit):Y Absolute data of the "n"th finger
    > -Zsn_6-0(7bit): Operation area of the "n"th finger
    > +SW1-SW6:
    > + SW ON/OFF status
    > +Xan_15-0(16bit):
    > + X Absolute data of the "n"th finger
    > +Yan_15-0(16bit):
    > + Y Absolute data of the "n"th finger
    > +Zsn_6-0(7bit):
    > + Operation area of the "n"th finger
    >
    >
    > StickPointer data byte
    > -------------------
    > - b7 b6 b5 b4 b3 b2 b1 b0
    > +----------------------
    > +
    > +======= ======= ======= ======= ======= ======= ======= ======= =====
    > +- b7 b6 b5 b4 b3 b2 b1 b0
    > +======= ======= ======= ======= ======= ======= ======= ======= =====
    > Byte1 1 1 1 0 1 SW3 SW2 SW1
    > Byte2 X7 X6 X5 X4 X3 X2 X1 X0
    > Byte3 X15 X14 X13 X12 X11 X10 X9 X8
    > @@ -132,8 +168,13 @@ Byte4 Y7 Y6 Y5 Y4 Y3 Y2 Y1 Y0
    > Byte5 Y15 Y14 Y13 Y12 Y11 Y10 Y9 Y8
    > Byte6 Z7 Z6 Z5 Z4 Z3 Z2 Z1 Z0
    > Byte7 T&P Z14 Z13 Z12 Z11 Z10 Z9 Z8
    > +======= ======= ======= ======= ======= ======= ======= ======= =====
    >
    > -SW1-SW3: SW ON/OFF status
    > -Xn_15-0(16bit):X Absolute data
    > -Yn_15-0(16bit):Y Absolute data
    > -Zn_14-0(15bit):Z
    > +SW1-SW3:
    > + SW ON/OFF status
    > +Xn_15-0(16bit):
    > + X Absolute data
    > +Yn_15-0(16bit):
    > + Y Absolute data
    > +Zn_14-0(15bit):
    > + Z
    > diff --git a/Documentation/hid/hid-sensor.txt b/Documentation/hid/hid-sensor.rst
    > similarity index 61%
    > rename from Documentation/hid/hid-sensor.txt
    > rename to Documentation/hid/hid-sensor.rst
    > index b287752a31cd..758972e34971 100644
    > --- a/Documentation/hid/hid-sensor.txt
    > +++ b/Documentation/hid/hid-sensor.rst
    > @@ -1,6 +1,6 @@
    > -
    > +=====================
    > HID Sensors Framework
    > -======================
    > +=====================
    > HID sensor framework provides necessary interfaces to implement sensor drivers,
    > which are connected to a sensor hub. The sensor hub is a HID device and it provides
    > a report descriptor conforming to HID 1.12 sensor usage tables.
    > @@ -15,22 +15,22 @@ the drivers themselves."
    > This specification describes many usage IDs, which describe the type of sensor
    > and also the individual data fields. Each sensor can have variable number of
    > data fields. The length and order is specified in the report descriptor. For
    > -example a part of report descriptor can look like:
    > +example a part of report descriptor can look like::
    >
    > - INPUT(1)[INPUT]
    > - ..
    > - Field(2)
    > - Physical(0020.0073)
    > - Usage(1)
    > - 0020.045f
    > - Logical Minimum(-32767)
    > - Logical Maximum(32767)
    > - Report Size(8)
    > - Report Count(1)
    > - Report Offset(16)
    > - Flags(Variable Absolute)
    > -..
    > -..
    > + INPUT(1)[INPUT]
    > + ..
    > + Field(2)
    > + Physical(0020.0073)
    > + Usage(1)
    > + 0020.045f
    > + Logical Minimum(-32767)
    > + Logical Maximum(32767)
    > + Report Size(8)
    > + Report Count(1)
    > + Report Offset(16)
    > + Flags(Variable Absolute)
    > + ..
    > + ..
    >
    > The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
    > This accelerometer-3D has some fields. Here for example field 2 is motion intensity
    > @@ -40,13 +40,14 @@ data will use this format.
    >
    >
    > Implementation
    > -=================
    > +==============
    >
    > This specification defines many different types of sensors with different sets of
    > data fields. It is difficult to have a common input event to user space applications,
    > for different sensors. For example an accelerometer can send X,Y and Z data, whereas
    > an ambient light sensor can send illumination data.
    > So the implementation has two parts:
    > +
    > - Core hid driver
    > - Individual sensor processing part (sensor drivers)
    >
    > @@ -55,8 +56,11 @@ Core driver
    > The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
    > report descriptors and identifies all the sensors present. It adds an MFD device
    > with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
    > -For example
    > +
    > +For example:
    > +
    > HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
    > +
    > So if any driver with this name is inserted, then the probe routine for that
    > function will be called. So an accelerometer processing driver can register
    > with this name and will be probed if there is an accelerometer-3D detected.
    > @@ -66,7 +70,8 @@ drivers to register and get events for that usage id. Also it provides parsing
    > functions, which get and set each input/feature/output report.
    >
    > Individual sensor processing part (sensor drivers)
    > ------------
    > +--------------------------------------------------
    > +
    > The processing driver will use an interface provided by the core driver to parse
    > the report and get the indexes of the fields and also can get events. This driver
    > can use IIO interface to use the standard ABI defined for a type of sensor.
    > @@ -75,31 +80,34 @@ can use IIO interface to use the standard ABI defined for a type of sensor.
    > Core driver Interface
    > =====================
    >
    > -Callback structure:
    > -Each processing driver can use this structure to set some callbacks.
    > +Callback structure::
    > +
    > + Each processing driver can use this structure to set some callbacks.
    > int (*suspend)(..): Callback when HID suspend is received
    > int (*resume)(..): Callback when HID resume is received
    > int (*capture_sample)(..): Capture a sample for one of its data fields
    > int (*send_event)(..): One complete event is received which can have
    > multiple data fields.
    >
    > -Registration functions:
    > -int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
    > +Registration functions::
    > +
    > + int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
    > u32 usage_id,
    > struct hid_sensor_hub_callbacks *usage_callback):
    >
    > Registers callbacks for an usage id. The callback functions are not allowed
    > -to sleep.
    > +to sleep::
    >
    >
    > -int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
    > + int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
    > u32 usage_id):
    >
    > Removes callbacks for an usage id.
    >
    >
    > -Parsing function:
    > -int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
    > +Parsing function::
    > +
    > + int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
    > u8 type,
    > u32 usage_id, u32 attr_usage_id,
    > struct hid_sensor_hub_attribute_info *info);
    > @@ -110,26 +118,27 @@ so that fields can be set or get individually.
    > These indexes avoid searching every time and getting field index to get or set.
    >
    >
    > -Set Feature report
    > -int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
    > +Set Feature report::
    > +
    > + int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
    > u32 field_index, s32 value);
    >
    > This interface is used to set a value for a field in feature report. For example
    > if there is a field report_interval, which is parsed by a call to
    > -sensor_hub_input_get_attribute_info before, then it can directly set that individual
    > -field.
    > +sensor_hub_input_get_attribute_info before, then it can directly set that
    > +individual field::
    >
    >
    > -int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
    > + int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
    > u32 field_index, s32 *value);
    >
    > This interface is used to get a value for a field in input report. For example
    > if there is a field report_interval, which is parsed by a call to
    > -sensor_hub_input_get_attribute_info before, then it can directly get that individual
    > -field value.
    > +sensor_hub_input_get_attribute_info before, then it can directly get that
    > +individual field value::
    >
    >
    > -int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
    > + int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
    > u32 usage_id,
    > u32 attr_usage_id, u32 report_id);
    >
    > @@ -143,6 +152,8 @@ registered callback function to process the sample.
    > ----------
    >
    > HID Custom and generic Sensors
    > +------------------------------
    > +
    >
    > HID Sensor specification defines two special sensor usage types. Since they
    > don't represent a standard sensor, it is not possible to define using Linux IIO
    > @@ -158,66 +169,73 @@ keyboard attached/detached or lid open/close.
    > To allow application to utilize these sensors, here they are exported uses sysfs
    > attribute groups, attributes and misc device interface.
    >
    > -An example of this representation on sysfs:
    > -/sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
    > -.
    > -????????? enable_sensor
    > -????????? feature-0-200316
    > -??????? ????????? feature-0-200316-maximum
    > -??????? ????????? feature-0-200316-minimum
    > -??????? ????????? feature-0-200316-name
    > -??????? ????????? feature-0-200316-size
    > -??????? ????????? feature-0-200316-unit-expo
    > -??????? ????????? feature-0-200316-units
    > -??????? ????????? feature-0-200316-value
    > -????????? feature-1-200201
    > -??????? ????????? feature-1-200201-maximum
    > -??????? ????????? feature-1-200201-minimum
    > -??????? ????????? feature-1-200201-name
    > -??????? ????????? feature-1-200201-size
    > -??????? ????????? feature-1-200201-unit-expo
    > -??????? ????????? feature-1-200201-units
    > -??????? ????????? feature-1-200201-value
    > -????????? input-0-200201
    > -??????? ????????? input-0-200201-maximum
    > -??????? ????????? input-0-200201-minimum
    > -??????? ????????? input-0-200201-name
    > -??????? ????????? input-0-200201-size
    > -??????? ????????? input-0-200201-unit-expo
    > -??????? ????????? input-0-200201-units
    > -??????? ????????? input-0-200201-value
    > -????????? input-1-200202
    > -??????? ????????? input-1-200202-maximum
    > -??????? ????????? input-1-200202-minimum
    > -??????? ????????? input-1-200202-name
    > -??????? ????????? input-1-200202-size
    > -??????? ????????? input-1-200202-unit-expo
    > -??????? ????????? input-1-200202-units
    > -??????? ????????? input-1-200202-value
    > +An example of this representation on sysfs::
    > +
    > + /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
    > + .
    > + │ ├── enable_sensor
    > + │ │ ├── feature-0-200316
    > + │ │ │ ├── feature-0-200316-maximum
    > + │ │ │ ├── feature-0-200316-minimum
    > + │ │ │ ├── feature-0-200316-name
    > + │ │ │ ├── feature-0-200316-size
    > + │ │ │ ├── feature-0-200316-unit-expo
    > + │ │ │ ├── feature-0-200316-units
    > + │ │ │ ├── feature-0-200316-value
    > + │ │ ├── feature-1-200201
    > + │ │ │ ├── feature-1-200201-maximum
    > + │ │ │ ├── feature-1-200201-minimum
    > + │ │ │ ├── feature-1-200201-name
    > + │ │ │ ├── feature-1-200201-size
    > + │ │ │ ├── feature-1-200201-unit-expo
    > + │ │ │ ├── feature-1-200201-units
    > + │ │ │ ├── feature-1-200201-value
    > + │ │ ├── input-0-200201
    > + │ │ │ ├── input-0-200201-maximum
    > + │ │ │ ├── input-0-200201-minimum
    > + │ │ │ ├── input-0-200201-name
    > + │ │ │ ├── input-0-200201-size
    > + │ │ │ ├── input-0-200201-unit-expo
    > + │ │ │ ├── input-0-200201-units
    > + │ │ │ ├── input-0-200201-value
    > + │ │ ├── input-1-200202
    > + │ │ │ ├── input-1-200202-maximum
    > + │ │ │ ├── input-1-200202-minimum
    > + │ │ │ ├── input-1-200202-name
    > + │ │ │ ├── input-1-200202-size
    > + │ │ │ ├── input-1-200202-unit-expo
    > + │ │ │ ├── input-1-200202-units
    > + │ │ │ ├── input-1-200202-value
    >
    > Here there is a custom sensors with four fields, two feature and two inputs.
    > Each field is represented by a set of attributes. All fields except the "value"
    > are read only. The value field is a RW field.
    > -Example
    > -/sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
    > -feature-0-200316-maximum:6
    > -feature-0-200316-minimum:0
    > -feature-0-200316-name:property-reporting-state
    > -feature-0-200316-size:1
    > -feature-0-200316-unit-expo:0
    > -feature-0-200316-units:25
    > -feature-0-200316-value:1
    > +
    > +Example::
    > +
    > + /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
    > + feature-0-200316-maximum:6
    > + feature-0-200316-minimum:0
    > + feature-0-200316-name:property-reporting-state
    > + feature-0-200316-size:1
    > + feature-0-200316-unit-expo:0
    > + feature-0-200316-units:25
    > + feature-0-200316-value:1
    >
    > How to enable such sensor?
    > +^^^^^^^^^^^^^^^^^^^^^^^^^^
    > +
    > By default sensor can be power gated. To enable sysfs attribute "enable" can be
    > -used.
    > -$ echo 1 > enable_sensor
    > +used::
    > +
    > + $ echo 1 > enable_sensor
    >
    > Once enabled and powered on, sensor can report value using HID reports.
    > -These reports are pushed using misc device interface in a FIFO order.
    > -/dev$ tree | grep HID-SENSOR-2000e1.6.auto
    > -??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto
    > -????????? HID-SENSOR-2000e1.6.auto
    > +These reports are pushed using misc device interface in a FIFO order::
    > +
    > + /dev$ tree | grep HID-SENSOR-2000e1.6.auto
    > + │ │ │ ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
    > + │ ├── HID-SENSOR-2000e1.6.auto
    >
    > Each reports can be of variable length preceded by a header. This header
    > consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
    > diff --git a/Documentation/hid/hid-transport.txt b/Documentation/hid/hid-transport.rst
    > similarity index 93%
    > rename from Documentation/hid/hid-transport.txt
    > rename to Documentation/hid/hid-transport.rst
    > index 3dcba9fd4a3a..6f3aaa86ce7b 100644
    > --- a/Documentation/hid/hid-transport.txt
    > +++ b/Documentation/hid/hid-transport.rst
    > @@ -1,5 +1,6 @@
    > - HID I/O Transport Drivers
    > - ===========================
    > +=========================
    > +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
    > @@ -16,6 +17,8 @@ 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 |
    > +-----------+ +-----------+ +-----------+ +-----------+
    > @@ -42,8 +45,9 @@ and quirks are handled by all layers depending on the quirk.
    > +----------------+ +-----------+ +------------------+ +------------------+
    >
    > Example Drivers:
    > - I/O: USB, I2C, Bluetooth-l2cap
    > - Transport: USB-HID, I2C-HID, BT-HIDP
    > +
    > + - 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
    > @@ -183,7 +187,7 @@ Other ctrl-channel requests are supported by USB-HID but are not available
    > -------------------
    >
    > Transport drivers normally use the following procedure to register a new device
    > -with HID core:
    > +with HID core::
    >
    > struct hid_device *hid;
    > int ret;
    > @@ -215,7 +219,7 @@ 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:
    > +To unregister a device, use::
    >
    > hid_destroy_device(hid);
    >
    > @@ -226,73 +230,110 @@ driver callbacks.
    > -----------------------------
    >
    > The available HID callbacks are:
    > - - int (*start) (struct hid_device *hdev)
    > +
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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)
    > + ::
    > +
    > + 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
    > @@ -314,4 +355,5 @@ 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 --git a/Documentation/hid/hiddev.txt b/Documentation/hid/hiddev.rst
    > similarity index 77%
    > rename from Documentation/hid/hiddev.txt
    > rename to Documentation/hid/hiddev.rst
    > index 638448707aa2..209e6ba4e019 100644
    > --- a/Documentation/hid/hiddev.txt
    > +++ b/Documentation/hid/hiddev.rst
    > @@ -1,6 +1,9 @@
    > +================================================
    > Care and feeding of your Human Interface Devices
    > +================================================
    >
    > -INTRODUCTION
    > +Introduction
    > +============
    >
    > In addition to the normal input type HID devices, USB also uses the
    > human interface device protocols for things that are not really human
    > @@ -16,38 +19,40 @@ normalised event interface - see Documentation/input/input.rst
    > * the hiddev interface, which provides fairly raw HID events
    >
    > The data flow for a HID event produced by a device is something like
    > -the following :
    > +the following::
    >
    > usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event]
    > |
    > |
    > - --> hiddev.c ----> POWER / MONITOR CONTROL
    > + --> hiddev.c ----> POWER / MONITOR CONTROL
    >
    > In addition, other subsystems (apart from USB) can potentially feed
    > events into the input subsystem, but these have no effect on the hid
    > device interface.
    >
    > -USING THE HID DEVICE INTERFACE
    > +Using the HID Device Interface
    > +==============================
    >
    > The hiddev interface is a char interface using the normal USB major,
    > with the minor numbers starting at 96 and finishing at 111. Therefore,
    > -you need the following commands:
    > -mknod /dev/usb/hiddev0 c 180 96
    > -mknod /dev/usb/hiddev1 c 180 97
    > -mknod /dev/usb/hiddev2 c 180 98
    > -mknod /dev/usb/hiddev3 c 180 99
    > -mknod /dev/usb/hiddev4 c 180 100
    > -mknod /dev/usb/hiddev5 c 180 101
    > -mknod /dev/usb/hiddev6 c 180 102
    > -mknod /dev/usb/hiddev7 c 180 103
    > -mknod /dev/usb/hiddev8 c 180 104
    > -mknod /dev/usb/hiddev9 c 180 105
    > -mknod /dev/usb/hiddev10 c 180 106
    > -mknod /dev/usb/hiddev11 c 180 107
    > -mknod /dev/usb/hiddev12 c 180 108
    > -mknod /dev/usb/hiddev13 c 180 109
    > -mknod /dev/usb/hiddev14 c 180 110
    > -mknod /dev/usb/hiddev15 c 180 111
    > +you need the following commands::
    > +
    > + mknod /dev/usb/hiddev0 c 180 96
    > + mknod /dev/usb/hiddev1 c 180 97
    > + mknod /dev/usb/hiddev2 c 180 98
    > + mknod /dev/usb/hiddev3 c 180 99
    > + mknod /dev/usb/hiddev4 c 180 100
    > + mknod /dev/usb/hiddev5 c 180 101
    > + mknod /dev/usb/hiddev6 c 180 102
    > + mknod /dev/usb/hiddev7 c 180 103
    > + mknod /dev/usb/hiddev8 c 180 104
    > + mknod /dev/usb/hiddev9 c 180 105
    > + mknod /dev/usb/hiddev10 c 180 106
    > + mknod /dev/usb/hiddev11 c 180 107
    > + mknod /dev/usb/hiddev12 c 180 108
    > + mknod /dev/usb/hiddev13 c 180 109
    > + mknod /dev/usb/hiddev14 c 180 110
    > + mknod /dev/usb/hiddev15 c 180 111
    >
    > So you point your hiddev compliant user-space program at the correct
    > interface for your device, and it all just works.
    > @@ -56,7 +61,9 @@ Assuming that you have a hiddev compliant user-space program, of
    > course. If you need to write one, read on.
    >
    >
    > -THE HIDDEV API
    > +The HIDDEV API
    > +==============
    > +
    > This description should be read in conjunction with the HID
    > specification, freely available from http://www.usb.org, and
    > conveniently linked of http://www.linux-usb.org.
    > @@ -69,12 +76,14 @@ each of which can have one or more "usages". In the hid-core,
    > each one of these usages has a single signed 32 bit value.
    >
    > read():
    > +-------
    > +
    > This is the event interface. When the HID device's state changes,
    > it performs an interrupt transfer containing a report which contains
    > the changed value. The hid-core.c module parses the report, and
    > returns to hiddev.c the individual usages that have changed within
    > the report. In its basic mode, the hiddev will make these individual
    > -usage changes available to the reader using a struct hiddev_event:
    > +usage changes available to the reader using a struct hiddev_event::
    >
    > struct hiddev_event {
    > unsigned hid;
    > @@ -90,13 +99,19 @@ behavior of the read() function can be modified using the HIDIOCSFLAG
    > ioctl() described below.
    >
    >
    > -ioctl():
    > -This is the control interface. There are a number of controls:
    > +ioctl():
    > +--------
    >
    > -HIDIOCGVERSION - int (read)
    > -Gets the version code out of the hiddev driver.
    > +This is the control interface. There are a number of controls:
    > +
    > +HIDIOCGVERSION
    > + - int (read)
    > +
    > + Gets the version code out of the hiddev driver.
    > +
    > +HIDIOCAPPLICATION
    > + - (none)
    >
    > -HIDIOCAPPLICATION - (none)
    > This ioctl call returns the HID application usage associated with the
    > hid device. The third argument to ioctl() specifies which application
    > index to get. This is useful when the device has more than one
    > @@ -104,25 +119,33 @@ application collection. If the index is invalid (greater or equal to
    > the number of application collections this device has) the ioctl
    > returns -1. You can find out beforehand how many application
    > collections the device has from the num_applications field from the
    > -hiddev_devinfo structure.
    > +hiddev_devinfo structure.
    > +
    > +HIDIOCGCOLLECTIONINFO
    > + - struct hiddev_collection_info (read/write)
    >
    > -HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write)
    > This returns a superset of the information above, providing not only
    > application collections, but all the collections the device has. It
    > also returns the level the collection lives in the hierarchy.
    > -The user passes in a hiddev_collection_info struct with the index
    > -field set to the index that should be returned. The ioctl fills in
    > -the other fields. If the index is larger than the last collection
    > +The user passes in a hiddev_collection_info struct with the index
    > +field set to the index that should be returned. The ioctl fills in
    > +the other fields. If the index is larger than the last collection
    > index, the ioctl returns -1 and sets errno to -EINVAL.
    >
    > -HIDIOCGDEVINFO - struct hiddev_devinfo (read)
    > +HIDIOCGDEVINFO
    > + - struct hiddev_devinfo (read)
    > +
    > Gets a hiddev_devinfo structure which describes the device.
    >
    > -HIDIOCGSTRING - struct hiddev_string_descriptor (read/write)
    > +HIDIOCGSTRING
    > + - struct hiddev_string_descriptor (read/write)
    > +
    > Gets a string descriptor from the device. The caller must fill in the
    > "index" field to indicate which descriptor should be returned.
    >
    > -HIDIOCINITREPORT - (none)
    > +HIDIOCINITREPORT
    > + - (none)
    > +
    > Instructs the kernel to retrieve all input and feature report values
    > from the device. At this point, all the usage structures will contain
    > current values for the device, and will maintain it as the device
    > @@ -130,21 +153,29 @@ changes. Note that the use of this ioctl is unnecessary in general,
    > since later kernels automatically initialize the reports from the
    > device at attach time.
    >
    > -HIDIOCGNAME - string (variable length)
    > +HIDIOCGNAME
    > + - string (variable length)
    > +
    > Gets the device name
    >
    > -HIDIOCGREPORT - struct hiddev_report_info (write)
    > +HIDIOCGREPORT
    > + - struct hiddev_report_info (write)
    > +
    > Instructs the kernel to get a feature or input report from the device,
    > in order to selectively update the usage structures (in contrast to
    > INITREPORT).
    >
    > -HIDIOCSREPORT - struct hiddev_report_info (write)
    > +HIDIOCSREPORT
    > + - struct hiddev_report_info (write)
    > +
    > Instructs the kernel to send a report to the device. This report can
    > be filled in by the user through HIDIOCSUSAGE calls (below) to fill in
    > individual usage values in the report before sending the report in full
    > -to the device.
    > +to the device.
    > +
    > +HIDIOCGREPORTINFO
    > + - struct hiddev_report_info (read/write)
    >
    > -HIDIOCGREPORTINFO - struct hiddev_report_info (read/write)
    > Fills in a hiddev_report_info structure for the user. The report is
    > looked up by type (input, output or feature) and id, so these fields
    > must be filled in by the user. The ID can be absolute -- the actual
    > @@ -154,52 +185,67 @@ report_id) for the next report after report_id. Without a-priori
    > information about report ids, the right way to use this ioctl is to
    > use the relative IDs above to enumerate the valid IDs. The ioctl
    > returns non-zero when there is no more next ID. The real report ID is
    > -filled into the returned hiddev_report_info structure.
    > +filled into the returned hiddev_report_info structure.
    > +
    > +HIDIOCGFIELDINFO
    > + - struct hiddev_field_info (read/write)
    >
    > -HIDIOCGFIELDINFO - struct hiddev_field_info (read/write)
    > Returns the field information associated with a report in a
    > hiddev_field_info structure. The user must fill in report_id and
    > report_type in this structure, as above. The field_index should also
    > be filled in, which should be a number from 0 and maxfield-1, as
    > -returned from a previous HIDIOCGREPORTINFO call.
    > +returned from a previous HIDIOCGREPORTINFO call.
    > +
    > +HIDIOCGUCODE
    > + - struct hiddev_usage_ref (read/write)
    >
    > -HIDIOCGUCODE - struct hiddev_usage_ref (read/write)
    > Returns the usage_code in a hiddev_usage_ref structure, given that
    > given its report type, report id, field index, and index within the
    > field have already been filled into the structure.
    >
    > -HIDIOCGUSAGE - struct hiddev_usage_ref (read/write)
    > +HIDIOCGUSAGE
    > + - struct hiddev_usage_ref (read/write)
    > +
    > Returns the value of a usage in a hiddev_usage_ref structure. The
    > usage to be retrieved can be specified as above, or the user can
    > choose to fill in the report_type field and specify the report_id as
    > HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be
    > filled in with the report and field information associated with this
    > -usage if it is found.
    > +usage if it is found.
    > +
    > +HIDIOCSUSAGE
    > + - struct hiddev_usage_ref (write)
    >
    > -HIDIOCSUSAGE - struct hiddev_usage_ref (write)
    > Sets the value of a usage in an output report. The user fills in
    > the hiddev_usage_ref structure as above, but additionally fills in
    > the value field.
    >
    > -HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write)
    > +HIDIOGCOLLECTIONINDEX
    > + - struct hiddev_usage_ref (write)
    > +
    > Returns the collection index associated with this usage. This
    > indicates where in the collection hierarchy this usage sits.
    >
    > -HIDIOCGFLAG - int (read)
    > -HIDIOCSFLAG - int (write)
    > +HIDIOCGFLAG
    > + - int (read)
    > +HIDIOCSFLAG
    > + - int (write)
    > +
    > These operations respectively inspect and replace the mode flags
    > that influence the read() call above. The flags are as follows:
    >
    > - HIDDEV_FLAG_UREF - read() calls will now return
    > + HIDDEV_FLAG_UREF
    > + - read() calls will now return
    > struct hiddev_usage_ref instead of struct hiddev_event.
    > This is a larger structure, but in situations where the
    > device has more than one usage in its reports with the
    > same usage code, this mode serves to resolve such
    > ambiguity.
    >
    > - HIDDEV_FLAG_REPORT - This flag can only be used in conjunction
    > + HIDDEV_FLAG_REPORT
    > + - This flag can only be used in conjunction
    > with HIDDEV_FLAG_UREF. With this flag set, when the device
    > sends a report, a struct hiddev_usage_ref will be returned
    > - to read() filled in with the report_type and report_id, but
    > + to read() filled in with the report_type and report_id, but
    > with field_index set to FIELD_INDEX_NONE. This serves as
    > additional notification when the device has sent a report.
    > diff --git a/Documentation/hid/hidraw.txt b/Documentation/hid/hidraw.rst
    > similarity index 89%
    > rename from Documentation/hid/hidraw.txt
    > rename to Documentation/hid/hidraw.rst
    > index c8436e354f44..4a4a0ba1f362 100644
    > --- a/Documentation/hid/hidraw.txt
    > +++ b/Documentation/hid/hidraw.rst
    > @@ -1,5 +1,6 @@
    > - HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
    > - ==================================================================
    > +================================================================
    > +HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices
    > +================================================================
    >
    > The hidraw driver provides a raw interface to USB and Bluetooth Human
    > Interface Devices (HIDs). It differs from hiddev in that reports sent and
    > @@ -31,6 +32,7 @@ directly under /dev (eg: /dev/hidraw0). As this location is distribution-
    > and udev rule-dependent, applications should use libudev to locate hidraw
    > devices attached to the system. There is a tutorial on libudev with a
    > working example at:
    > +
    > http://www.signal11.us/oss/udev/
    >
    > The HIDRAW API
    > @@ -51,7 +53,7 @@ byte. For devices which do not use numbered reports, the report data
    > will begin at the first byte.
    >
    > write()
    > ---------
    > +-------
    > The write() function will write a report to the device. For USB devices, if
    > the device has an INTERRUPT OUT endpoint, the report will be sent on that
    > endpoint. If it does not, the report will be sent over the control endpoint,
    > @@ -62,38 +64,52 @@ number. If the device does not use numbered reports, the first byte should
    > be set to 0. The report data itself should begin at the second byte.
    >
    > ioctl()
    > ---------
    > +-------
    > Hidraw supports the following ioctls:
    >
    > -HIDIOCGRDESCSIZE: Get Report Descriptor Size
    > +HIDIOCGRDESCSIZE:
    > + Get Report Descriptor Size
    > +
    > This ioctl will get the size of the device's report descriptor.
    >
    > -HIDIOCGRDESC: Get Report Descriptor
    > +HIDIOCGRDESC:
    > + Get Report Descriptor
    > +
    > This ioctl returns the device's report descriptor using a
    > hidraw_report_descriptor struct. Make sure to set the size field of the
    > hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE.
    >
    > -HIDIOCGRAWINFO: Get Raw Info
    > +HIDIOCGRAWINFO:
    > + Get Raw Info
    > +
    > This ioctl will return a hidraw_devinfo struct containing the bus type, the
    > vendor ID (VID), and product ID (PID) of the device. The bus type can be one
    > -of:
    > - BUS_USB
    > - BUS_HIL
    > - BUS_BLUETOOTH
    > - BUS_VIRTUAL
    > +of::
    > +
    > + - BUS_USB
    > + - BUS_HIL
    > + - BUS_BLUETOOTH
    > + - BUS_VIRTUAL
    > +
    > which are defined in uapi/linux/input.h.
    >
    > -HIDIOCGRAWNAME(len): Get Raw Name
    > +HIDIOCGRAWNAME(len):
    > + Get Raw Name
    > +
    > This ioctl returns a string containing the vendor and product strings of
    > the device. The returned string is Unicode, UTF-8 encoded.
    >
    > -HIDIOCGRAWPHYS(len): Get Physical Address
    > +HIDIOCGRAWPHYS(len):
    > + Get Physical Address
    > +
    > This ioctl returns a string representing the physical address of the device.
    > For USB devices, the string contains the physical path to the device (the
    > USB controller, hubs, ports, etc). For Bluetooth devices, the string
    > contains the hardware (MAC) address of the device.
    >
    > -HIDIOCSFEATURE(len): Send a Feature Report
    > +HIDIOCSFEATURE(len):
    > + Send a Feature Report
    > +
    > This ioctl will send a feature report to the device. Per the HID
    > specification, feature reports are always sent using the control endpoint.
    > Set the first byte of the supplied buffer to the report number. For devices
    > @@ -101,7 +117,9 @@ which do not use numbered reports, set the first byte to 0. The report data
    > begins in the second byte. Make sure to set len accordingly, to one more
    > than the length of the report (to account for the report number).
    >
    > -HIDIOCGFEATURE(len): Get a Feature Report
    > +HIDIOCGFEATURE(len):
    > + Get a Feature Report
    > +
    > This ioctl will request a feature report from the device using the control
    > endpoint. The first byte of the supplied buffer should be set to the report
    > number of the requested report. For devices which do not use numbered
    > @@ -109,11 +127,12 @@ reports, set the first byte to 0. The report will be returned starting at
    > the first byte of the buffer (ie: the report number is not returned).
    >
    > Example
    > ----------
    > +-------
    > In samples/, find hid-example.c, which shows examples of read(), write(),
    > and all the ioctls for hidraw. The code may be used by anyone for any
    > purpose, and can serve as a starting point for developing applications using
    > hidraw.
    >
    > Document by:
    > +
    > Alan Ott <alan@signal11.us>, Signal 11 Software
    > diff --git a/Documentation/hid/index.rst b/Documentation/hid/index.rst
    > new file mode 100644
    > index 000000000000..af4324902622
    > --- /dev/null
    > +++ b/Documentation/hid/index.rst
    > @@ -0,0 +1,18 @@
    > +:orphan:
    > +
    > +=============================
    > +Human Interface Devices (HID)
    > +=============================
    > +
    > +.. toctree::
    > + :maxdepth: 1
    > +
    > + hiddev
    > + hidraw
    > + hid-sensor
    > + hid-transport
    > +
    > + uhid
    > +
    > + hid-alps
    > + intel-ish-hid
    > diff --git a/Documentation/hid/intel-ish-hid.rst b/Documentation/hid/intel-ish-hid.rst
    > new file mode 100644
    > index 000000000000..cccbf4be17d7
    > --- /dev/null
    > +++ b/Documentation/hid/intel-ish-hid.rst
    > @@ -0,0 +1,485 @@
    > +=================================
    > +Intel Integrated Sensor Hub (ISH)
    > +=================================
    > +
    > +A sensor hub enables the ability to offload sensor polling and algorithm
    > +processing to a dedicated low power co-processor. This allows the core
    > +processor to go into low power modes more often, resulting in the increased
    > +battery life.
    > +
    > +There are many vendors providing external sensor hubs confirming to HID
    > +Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
    > +and embedded products. Linux had this support since Linux 3.9.
    > +
    > +Intel® introduced integrated sensor hubs as a part of the SoC starting from
    > +Cherry Trail and now supported on multiple generations of CPU packages. There
    > +are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
    > +These ISH also comply to HID sensor specification, but the difference is the
    > +transport protocol used for communication. The current external sensor hubs
    > +mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
    > +
    > +1. Overview
    > +===========
    > +
    > +Using a analogy with a usbhid implementation, the ISH follows a similar model
    > +for a very high speed communication::
    > +
    > + ----------------- ----------------------
    > + | USB HID | --> | ISH HID |
    > + ----------------- ----------------------
    > + ----------------- ----------------------
    > + | USB protocol | --> | ISH Transport |
    > + ----------------- ----------------------
    > + ----------------- ----------------------
    > + | EHCI/XHCI | --> | ISH IPC |
    > + ----------------- ----------------------
    > + PCI PCI
    > + ----------------- ----------------------
    > + |Host controller| --> | ISH processor |
    > + ----------------- ----------------------
    > + USB Link
    > + ----------------- ----------------------
    > + | USB End points| --> | ISH Clients |
    > + ----------------- ----------------------
    > +
    > +Like USB protocol provides a method for device enumeration, link management
    > +and user data encapsulation, the ISH also provides similar services. But it is
    > +very light weight tailored to manage and communicate with ISH client
    > +applications implemented in the firmware.
    > +
    > +The ISH allows multiple sensor management applications executing in the
    > +firmware. Like USB endpoints the messaging can be to/from a client. As part of
    > +enumeration process, these clients are identified. These clients can be simple
    > +HID sensor applications, sensor calibration application or senor firmware
    > +update application.
    > +
    > +The implementation model is similar, like USB bus, ISH transport is also
    > +implemented as a bus. Each client application executing in the ISH processor
    > +is registered as a device on this bus. The driver, which binds each device
    > +(ISH HID driver) identifies the device type and registers with the hid core.
    > +
    > +2. ISH Implementation: Block Diagram
    > +====================================
    > +
    > +::
    > +
    > + ---------------------------
    > + | User Space Applications |
    > + ---------------------------
    > +
    > + ----------------IIO ABI----------------
    > + --------------------------
    > + | IIO Sensor Drivers |
    > + --------------------------
    > + --------------------------
    > + | IIO core |
    > + --------------------------
    > + --------------------------
    > + | HID Sensor Hub MFD |
    > + --------------------------
    > + --------------------------
    > + | HID Core |
    > + --------------------------
    > + --------------------------
    > + | HID over ISH Client |
    > + --------------------------
    > + --------------------------
    > + | ISH Transport (ISHTP) |
    > + --------------------------
    > + --------------------------
    > + | IPC Drivers |
    > + --------------------------
    > + OS
    > + ---------------- PCI -----------------
    > + Hardware + Firmware
    > + ----------------------------
    > + | ISH Hardware/Firmware(FW) |
    > + ----------------------------
    > +
    > +3. High level processing in above blocks
    > +========================================
    > +
    > +3.1 Hardware Interface
    > +----------------------
    > +
    > +The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
    > +product and vendor IDs are changed from different generations of processors. So
    > +the source code which enumerate drivers needs to update from generation to
    > +generation.
    > +
    > +3.2 Inter Processor Communication (IPC) driver
    > +----------------------------------------------
    > +
    > +Location: drivers/hid/intel-ish-hid/ipc
    > +
    > +The IPC message used memory mapped I/O. The registers are defined in
    > +hw-ish-regs.h.
    > +
    > +3.2.1 IPC/FW message types
    > +^^^^^^^^^^^^^^^^^^^^^^^^^^
    > +
    > +There are two types of messages, one for management of link and other messages
    > +are to and from transport layers.
    > +
    > +TX and RX of Transport messages
    > +...............................
    > +
    > +A set of memory mapped register offers support of multi byte messages TX and
    > +RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
    > +internal queues to sequence messages and send them in order to the FW.
    > +Optionally the caller can register handler to get notification of completion.
    > +A door bell mechanism is used in messaging to trigger processing in host and
    > +client firmware side. When ISH interrupt handler is called, the ISH2HOST
    > +doorbell register is used by host drivers to determine that the interrupt
    > +is for ISH.
    > +
    > +Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
    > +register has the following format:
    > +Bits 0..6: fragment length (7 bits are used)
    > +Bits 10..13: encapsulated protocol
    > +Bits 16..19: management command (for IPC management protocol)
    > +Bit 31: doorbell trigger (signal H/W interrupt to the other side)
    > +Other bits are reserved, should be 0.
    > +
    > +3.2.2 Transport layer interface
    > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    > +
    > +To abstract HW level IPC communication, a set of callbacks are registered.
    > +The transport layer uses them to send and receive messages.
    > +Refer to struct ishtp_hw_ops for callbacks.
    > +
    > +3.3 ISH Transport layer
    > +-----------------------
    > +
    > +Location: drivers/hid/intel-ish-hid/ishtp/
    > +
    > +3.3.1 A Generic Transport Layer
    > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    > +
    > +The transport layer is a bi-directional protocol, which defines:
    > +- Set of commands to start, stop, connect, disconnect and flow control
    > +(ishtp/hbm.h) for details
    > +- A flow control mechanism to avoid buffer overflows
    > +
    > +This protocol resembles bus messages described in the following document:
    > +http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
    > +specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
    > +
    > +3.3.2 Connection and Flow Control Mechanism
    > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    > +
    > +Each FW client and a protocol is identified by an UUID. In order to communicate
    > +to a FW client, a connection must be established using connect request and
    > +response bus messages. If successful, a pair (host_client_id and fw_client_id)
    > +will identify the connection.
    > +
    > +Once connection is established, peers send each other flow control bus messages
    > +independently. Every peer may send a message only if it has received a
    > +flow-control credit before. Once it sent a message, it may not send another one
    > +before receiving the next flow control credit.
    > +Either side can send disconnect request bus message to end communication. Also
    > +the link will be dropped if major FW reset occurs.
    > +
    > +3.3.3 Peer to Peer data transfer
    > +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    > +
    > +Peer to Peer data transfer can happen with or without using DMA. Depending on
    > +the sensor bandwidth requirement DMA can be enabled by using module parameter
    > +ishtp_use_dma under intel_ishtp.
    > +
    > +Each side (host and FW) manages its DMA transfer memory independently. When an
    > +ISHTP client from either host or FW side wants to send something, it decides
    > +whether to send over IPC or over DMA; for each transfer the decision is
    > +independent. The sending side sends DMA_XFER message when the message is in
    > +the respective host buffer (TX when host client sends, RX when FW client
    > +sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
    > +the sender that the memory region for that message may be reused.
    > +
    > +DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
    > +(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
    > +Additionally to DMA address communication, this sequence checks capabilities:
    > +if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
    > +send DMA; if FW doesn't support DMA then it won't respond with
    > +DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
    > +Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
    > +it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
    > +that it already did DMA and the message resides at host. Thus, DMA_XFER
    > +and DMA_XFER_ACK act as ownership indicators.
    > +
    > +At initial state all outgoing memory belongs to the sender (TX to host, RX to
    > +FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
    > +the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
    > +needs not wait for previous DMA_XFER to be ack'ed, and may send another message
    > +as long as remaining continuous memory in its ownership is enough.
    > +In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
    > +(up to IPC MTU), thus allowing for interrupt throttling.
    > +Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
    > +fragments and via IPC otherwise.
    > +
    > +3.3.4 Ring Buffers
    > +^^^^^^^^^^^^^^^^^^
    > +
    > +When a client initiate a connection, a ring or RX and TX buffers are allocated.
    > +The size of ring can be specified by the client. HID client set 16 and 32 for
    > +TX and RX buffers respectively. On send request from client, the data to be
    > +sent is copied to one of the send ring buffer and scheduled to be sent using
    > +bus message protocol. These buffers are required because the FW may have not
    > +have processed the last message and may not have enough flow control credits
    > +to send. Same thing holds true on receive side and flow control is required.
    > +
    > +3.3.5 Host Enumeration
    > +^^^^^^^^^^^^^^^^^^^^^^
    > +
    > +The host enumeration bus command allow discovery of clients present in the FW.
    > +There can be multiple sensor clients and clients for calibration function.
    > +
    > +To ease in implantation and allow independent driver handle each client
    > +this transport layer takes advantage of Linux Bus driver model. Each
    > +client is registered as device on the the transport bus (ishtp bus).
    > +
    > +Enumeration sequence of messages:
    > +
    > +- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
    > +- FW responds with HOST_START_RES_CMD
    > +- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
    > +- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
    > + client IDs
    > +- For each FW ID found in that bitmap host sends
    > + HOST_CLIENT_PROPERTIES_REQ_CMD
    > +- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
    > + max ISHTP message size, etc.
    > +- Once host received properties for that last discovered client, it considers
    > + ISHTP device fully functional (and allocates DMA buffers)
    > +
    > +3.4 HID over ISH Client
    > +-----------------------
    > +
    > +Location: drivers/hid/intel-ish-hid
    > +
    > +The ISHTP client driver is responsible for:
    > +
    > +- enumerate HID devices under FW ISH client
    > +- Get Report descriptor
    > +- Register with HID core as a LL driver
    > +- Process Get/Set feature request
    > +- Get input reports
    > +
    > +3.5 HID Sensor Hub MFD and IIO sensor drivers
    > +---------------------------------------------
    > +
    > +The functionality in these drivers is the same as an external sensor hub.
    > +Refer to
    > +Documentation/hid/hid-sensor.rst for HID sensor
    > +Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
    > +
    > +3.6 End to End HID transport Sequence Diagram
    > +---------------------------------------------
    > +
    > +::
    > +
    > + HID-ISH-CLN ISHTP IPC HW
    > + | | | |
    > + | | |-----WAKE UP------------------>|
    > + | | | |
    > + | | |-----HOST READY--------------->|
    > + | | | |
    > + | | |<----MNG_RESET_NOTIFY_ACK----- |
    > + | | | |
    > + | |<----ISHTP_START------ | |
    > + | | | |
    > + | |<-----------------HOST_START_RES_CMD-------------------|
    > + | | | |
    > + | |------------------QUERY_SUBSCRIBER-------------------->|
    > + | | | |
    > + | |------------------HOST_ENUM_REQ_CMD------------------->|
    > + | | | |
    > + | |<-----------------HOST_ENUM_RES_CMD--------------------|
    > + | | | |
    > + | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
    > + | | | |
    > + | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
    > + | Create new device on in ishtp bus | |
    > + | | | |
    > + | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
    > + | | | |
    > + | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
    > + | Create new device on in ishtp bus | |
    > + | | | |
    > + | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
    > + | | | |
    > + probed()
    > + |----ishtp_cl_connect--->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
    > + | | | |
    > + | |<----------------CLIENT_CONNECT_RES_CMD----------------|
    > + | | | |
    > + |register event callback | | |
    > + | | | |
    > + |ishtp_cl_send(
    > + HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >|
    > + | | | |
    > + | | |<-----IRQ(IPC_PROTOCOL_ISHTP---|
    > + | | | |
    > + |<--ENUM_DEVICE RSP------| | |
    > + | | | |
    > + for each enumerated device
    > + |ishtp_cl_send(
    > + HOSTIF_GET_HID_DESCRIPTOR|----------fill ishtp_msg_hdr struct write to HW----- >|
    > + | | | |
    > + ...Response
    > + | | | |
    > + for each enumerated device
    > + |ishtp_cl_send(
    > + HOSTIF_GET_REPORT_DESCRIPTOR|--------------fill ishtp_msg_hdr struct write to HW-- >|
    > + | | | |
    > + | | | |
    > + hid_allocate_device
    > + | | | |
    > + hid_add_device | | |
    > + | | | |
    > +
    > +
    > +3.7 ISH Debugging
    > +-----------------
    > +
    > +To debug ISH, event tracing mechanism is used. To enable debug logs
    > +echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
    > +cat sys/kernel/debug/tracing/trace
    > +
    > +3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
    > +-----------------------------------------------------
    > +
    > +::
    > +
    > + root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
    > + /sys/bus/iio/devices/
    > + ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
    > + │ ├── buffer
    > + │ │ ├── enable
    > + │ │ ├── length
    > + │ │ └── watermark
    > + ...
    > + │ ├── in_accel_hysteresis
    > + │ ├── in_accel_offset
    > + │ ├── in_accel_sampling_frequency
    > + │ ├── in_accel_scale
    > + │ ├── in_accel_x_raw
    > + │ ├── in_accel_y_raw
    > + │ ├── in_accel_z_raw
    > + │ ├── name
    > + │ ├── scan_elements
    > + │ │ ├── in_accel_x_en
    > + │ │ ├── in_accel_x_index
    > + │ │ ├── in_accel_x_type
    > + │ │ ├── in_accel_y_en
    > + │ │ ├── in_accel_y_index
    > + │ │ ├── in_accel_y_type
    > + │ │ ├── in_accel_z_en
    > + │ │ ├── in_accel_z_index
    > + │ │ └── in_accel_z_type
    > + ...
    > + │ │ ├── devices
    > + │ │ │ │ ├── buffer
    > + │ │ │ │ │ ├── enable
    > + │ │ │ │ │ ├── length
    > + │ │ │ │ │ └── watermark
    > + │ │ │ │ ├── dev
    > + │ │ │ │ ├── in_intensity_both_raw
    > + │ │ │ │ ├── in_intensity_hysteresis
    > + │ │ │ │ ├── in_intensity_offset
    > + │ │ │ │ ├── in_intensity_sampling_frequency
    > + │ │ │ │ ├── in_intensity_scale
    > + │ │ │ │ ├── name
    > + │ │ │ │ ├── scan_elements
    > + │ │ │ │ │ ├── in_intensity_both_en
    > + │ │ │ │ │ ├── in_intensity_both_index
    > + │ │ │ │ │ └── in_intensity_both_type
    > + │ │ │ │ ├── trigger
    > + │ │ │ │ │ └── current_trigger
    > + ...
    > + │ │ │ │ ├── buffer
    > + │ │ │ │ │ ├── enable
    > + │ │ │ │ │ ├── length
    > + │ │ │ │ │ └── watermark
    > + │ │ │ │ ├── dev
    > + │ │ │ │ ├── in_magn_hysteresis
    > + │ │ │ │ ├── in_magn_offset
    > + │ │ │ │ ├── in_magn_sampling_frequency
    > + │ │ │ │ ├── in_magn_scale
    > + │ │ │ │ ├── in_magn_x_raw
    > + │ │ │ │ ├── in_magn_y_raw
    > + │ │ │ │ ├── in_magn_z_raw
    > + │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw
    > + │ │ │ │ ├── in_rot_hysteresis
    > + │ │ │ │ ├── in_rot_offset
    > + │ │ │ │ ├── in_rot_sampling_frequency
    > + │ │ │ │ ├── in_rot_scale
    > + │ │ │ │ ├── name
    > + ...
    > + │ │ │ │ ├── scan_elements
    > + │ │ │ │ │ ├── in_magn_x_en
    > + │ │ │ │ │ ├── in_magn_x_index
    > + │ │ │ │ │ ├── in_magn_x_type
    > + │ │ │ │ │ ├── in_magn_y_en
    > + │ │ │ │ │ ├── in_magn_y_index
    > + │ │ │ │ │ ├── in_magn_y_type
    > + │ │ │ │ │ ├── in_magn_z_en
    > + │ │ │ │ │ ├── in_magn_z_index
    > + │ │ │ │ │ ├── in_magn_z_type
    > + │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en
    > + │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index
    > + │ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type
    > + │ │ │ │ ├── trigger
    > + │ │ │ │ │ └── current_trigger
    > + ...
    > + │ │ │ │ ├── buffer
    > + │ │ │ │ │ ├── enable
    > + │ │ │ │ │ ├── length
    > + │ │ │ │ │ └── watermark
    > + │ │ │ │ ├── dev
    > + │ │ │ │ ├── in_anglvel_hysteresis
    > + │ │ │ │ ├── in_anglvel_offset
    > + │ │ │ │ ├── in_anglvel_sampling_frequency
    > + │ │ │ │ ├── in_anglvel_scale
    > + │ │ │ │ ├── in_anglvel_x_raw
    > + │ │ │ │ ├── in_anglvel_y_raw
    > + │ │ │ │ ├── in_anglvel_z_raw
    > + │ │ │ │ ├── name
    > + │ │ │ │ ├── scan_elements
    > + │ │ │ │ │ ├── in_anglvel_x_en
    > + │ │ │ │ │ ├── in_anglvel_x_index
    > + │ │ │ │ │ ├── in_anglvel_x_type
    > + │ │ │ │ │ ├── in_anglvel_y_en
    > + │ │ │ │ │ ├── in_anglvel_y_index
    > + │ │ │ │ │ ├── in_anglvel_y_type
    > + │ │ │ │ │ ├── in_anglvel_z_en
    > + │ │ │ │ │ ├── in_anglvel_z_index
    > + │ │ │ │ │ └── in_anglvel_z_type
    > + │ │ │ │ ├── trigger
    > + │ │ │ │ │ └── current_trigger
    > + ...
    > + │ │ │ │ ├── buffer
    > + │ │ │ │ │ ├── enable
    > + │ │ │ │ │ ├── length
    > + │ │ │ │ │ └── watermark
    > + │ │ │ │ ├── dev
    > + │ │ │ │ ├── in_anglvel_hysteresis
    > + │ │ │ │ ├── in_anglvel_offset
    > + │ │ │ │ ├── in_anglvel_sampling_frequency
    > + │ │ │ │ ├── in_anglvel_scale
    > + │ │ │ │ ├── in_anglvel_x_raw
    > + │ │ │ │ ├── in_anglvel_y_raw
    > + │ │ │ │ ├── in_anglvel_z_raw
    > + │ │ │ │ ├── name
    > + │ │ │ │ ├── scan_elements
    > + │ │ │ │ │ ├── in_anglvel_x_en
    > + │ │ │ │ │ ├── in_anglvel_x_index
    > + │ │ │ │ │ ├── in_anglvel_x_type
    > + │ │ │ │ │ ├── in_anglvel_y_en
    > + │ │ │ │ │ ├── in_anglvel_y_index
    > + │ │ │ │ │ ├── in_anglvel_y_type
    > + │ │ │ │ │ ├── in_anglvel_z_en
    > + │ │ │ │ │ ├── in_anglvel_z_index
    > + │ │ │ │ │ └── in_anglvel_z_type
    > + │ │ │ │ ├── trigger
    > + │ │ │ │ │ └── current_trigger
    > + ...
    > diff --git a/Documentation/hid/intel-ish-hid.txt b/Documentation/hid/intel-ish-hid.txt
    > deleted file mode 100644
    > index d48b21c71ddd..000000000000
    > --- a/Documentation/hid/intel-ish-hid.txt
    > +++ /dev/null
    > @@ -1,454 +0,0 @@
    > -Intel Integrated Sensor Hub (ISH)
    > -===============================
    > -
    > -A sensor hub enables the ability to offload sensor polling and algorithm
    > -processing to a dedicated low power co-processor. This allows the core
    > -processor to go into low power modes more often, resulting in the increased
    > -battery life.
    > -
    > -There are many vendors providing external sensor hubs confirming to HID
    > -Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops
    > -and embedded products. Linux had this support since Linux 3.9.
    > -
    > -Intel® introduced integrated sensor hubs as a part of the SoC starting from
    > -Cherry Trail and now supported on multiple generations of CPU packages. There
    > -are many commercial devices already shipped with Integrated Sensor Hubs (ISH).
    > -These ISH also comply to HID sensor specification, but the difference is the
    > -transport protocol used for communication. The current external sensor hubs
    > -mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB.
    > -
    > -1. Overview
    > -
    > -Using a analogy with a usbhid implementation, the ISH follows a similar model
    > -for a very high speed communication:
    > -
    > - ----------------- ----------------------
    > - | USB HID | --> | ISH HID |
    > - ----------------- ----------------------
    > - ----------------- ----------------------
    > - | USB protocol | --> | ISH Transport |
    > - ----------------- ----------------------
    > - ----------------- ----------------------
    > - | EHCI/XHCI | --> | ISH IPC |
    > - ----------------- ----------------------
    > - PCI PCI
    > - ----------------- ----------------------
    > - |Host controller| --> | ISH processor |
    > - ----------------- ----------------------
    > - USB Link
    > - ----------------- ----------------------
    > - | USB End points| --> | ISH Clients |
    > - ----------------- ----------------------
    > -
    > -Like USB protocol provides a method for device enumeration, link management
    > -and user data encapsulation, the ISH also provides similar services. But it is
    > -very light weight tailored to manage and communicate with ISH client
    > -applications implemented in the firmware.
    > -
    > -The ISH allows multiple sensor management applications executing in the
    > -firmware. Like USB endpoints the messaging can be to/from a client. As part of
    > -enumeration process, these clients are identified. These clients can be simple
    > -HID sensor applications, sensor calibration application or senor firmware
    > -update application.
    > -
    > -The implementation model is similar, like USB bus, ISH transport is also
    > -implemented as a bus. Each client application executing in the ISH processor
    > -is registered as a device on this bus. The driver, which binds each device
    > -(ISH HID driver) identifies the device type and registers with the hid core.
    > -
    > -2. ISH Implementation: Block Diagram
    > -
    > - ---------------------------
    > - | User Space Applications |
    > - ---------------------------
    > -
    > -----------------IIO ABI----------------
    > - --------------------------
    > - | IIO Sensor Drivers |
    > - --------------------------
    > - --------------------------
    > - | IIO core |
    > - --------------------------
    > - --------------------------
    > - | HID Sensor Hub MFD |
    > - --------------------------
    > - --------------------------
    > - | HID Core |
    > - --------------------------
    > - --------------------------
    > - | HID over ISH Client |
    > - --------------------------
    > - --------------------------
    > - | ISH Transport (ISHTP) |
    > - --------------------------
    > - --------------------------
    > - | IPC Drivers |
    > - --------------------------
    > -OS
    > ----------------- PCI -----------------
    > -Hardware + Firmware
    > - ----------------------------
    > - | ISH Hardware/Firmware(FW) |
    > - ----------------------------
    > -
    > -3. High level processing in above blocks
    > -
    > -3.1 Hardware Interface
    > -
    > -The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI
    > -product and vendor IDs are changed from different generations of processors. So
    > -the source code which enumerate drivers needs to update from generation to
    > -generation.
    > -
    > -3.2 Inter Processor Communication (IPC) driver
    > -Location: drivers/hid/intel-ish-hid/ipc
    > -
    > -The IPC message used memory mapped I/O. The registers are defined in
    > -hw-ish-regs.h.
    > -
    > -3.2.1 IPC/FW message types
    > -
    > -There are two types of messages, one for management of link and other messages
    > -are to and from transport layers.
    > -
    > -TX and RX of Transport messages
    > -
    > -A set of memory mapped register offers support of multi byte messages TX and
    > -RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains
    > -internal queues to sequence messages and send them in order to the FW.
    > -Optionally the caller can register handler to get notification of completion.
    > -A door bell mechanism is used in messaging to trigger processing in host and
    > -client firmware side. When ISH interrupt handler is called, the ISH2HOST
    > -doorbell register is used by host drivers to determine that the interrupt
    > -is for ISH.
    > -
    > -Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell
    > -register has the following format:
    > -Bits 0..6: fragment length (7 bits are used)
    > -Bits 10..13: encapsulated protocol
    > -Bits 16..19: management command (for IPC management protocol)
    > -Bit 31: doorbell trigger (signal H/W interrupt to the other side)
    > -Other bits are reserved, should be 0.
    > -
    > -3.2.2 Transport layer interface
    > -
    > -To abstract HW level IPC communication, a set of callbacks are registered.
    > -The transport layer uses them to send and receive messages.
    > -Refer to struct ishtp_hw_ops for callbacks.
    > -
    > -3.3 ISH Transport layer
    > -Location: drivers/hid/intel-ish-hid/ishtp/
    > -
    > -3.3.1 A Generic Transport Layer
    > -
    > -The transport layer is a bi-directional protocol, which defines:
    > -- Set of commands to start, stop, connect, disconnect and flow control
    > -(ishtp/hbm.h) for details
    > -- A flow control mechanism to avoid buffer overflows
    > -
    > -This protocol resembles bus messages described in the following document:
    > -http://www.intel.com/content/dam/www/public/us/en/documents/technical-\
    > -specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer"
    > -
    > -3.3.2 Connection and Flow Control Mechanism
    > -
    > -Each FW client and a protocol is identified by an UUID. In order to communicate
    > -to a FW client, a connection must be established using connect request and
    > -response bus messages. If successful, a pair (host_client_id and fw_client_id)
    > -will identify the connection.
    > -
    > -Once connection is established, peers send each other flow control bus messages
    > -independently. Every peer may send a message only if it has received a
    > -flow-control credit before. Once it sent a message, it may not send another one
    > -before receiving the next flow control credit.
    > -Either side can send disconnect request bus message to end communication. Also
    > -the link will be dropped if major FW reset occurs.
    > -
    > -3.3.3 Peer to Peer data transfer
    > -
    > -Peer to Peer data transfer can happen with or without using DMA. Depending on
    > -the sensor bandwidth requirement DMA can be enabled by using module parameter
    > -ishtp_use_dma under intel_ishtp.
    > -
    > -Each side (host and FW) manages its DMA transfer memory independently. When an
    > -ISHTP client from either host or FW side wants to send something, it decides
    > -whether to send over IPC or over DMA; for each transfer the decision is
    > -independent. The sending side sends DMA_XFER message when the message is in
    > -the respective host buffer (TX when host client sends, RX when FW client
    > -sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating
    > -the sender that the memory region for that message may be reused.
    > -
    > -DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message
    > -(that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK.
    > -Additionally to DMA address communication, this sequence checks capabilities:
    > -if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't
    > -send DMA; if FW doesn't support DMA then it won't respond with
    > -DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers.
    > -Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER,
    > -it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means
    > -that it already did DMA and the message resides at host. Thus, DMA_XFER
    > -and DMA_XFER_ACK act as ownership indicators.
    > -
    > -At initial state all outgoing memory belongs to the sender (TX to host, RX to
    > -FW), DMA_XFER transfers ownership on the region that contains ISHTP message to
    > -the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender
    > -needs not wait for previous DMA_XFER to be ack'ed, and may send another message
    > -as long as remaining continuous memory in its ownership is enough.
    > -In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once
    > -(up to IPC MTU), thus allowing for interrupt throttling.
    > -Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC
    > -fragments and via IPC otherwise.
    > -
    > -3.3.4 Ring Buffers
    > -
    > -When a client initiate a connection, a ring or RX and TX buffers are allocated.
    > -The size of ring can be specified by the client. HID client set 16 and 32 for
    > -TX and RX buffers respectively. On send request from client, the data to be
    > -sent is copied to one of the send ring buffer and scheduled to be sent using
    > -bus message protocol. These buffers are required because the FW may have not
    > -have processed the last message and may not have enough flow control credits
    > -to send. Same thing holds true on receive side and flow control is required.
    > -
    > -3.3.5 Host Enumeration
    > -
    > -The host enumeration bus command allow discovery of clients present in the FW.
    > -There can be multiple sensor clients and clients for calibration function.
    > -
    > -To ease in implantation and allow independent driver handle each client
    > -this transport layer takes advantage of Linux Bus driver model. Each
    > -client is registered as device on the the transport bus (ishtp bus).
    > -
    > -Enumeration sequence of messages:
    > -- Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up.
    > -- FW responds with HOST_START_RES_CMD
    > -- Host sends HOST_ENUM_REQ_CMD (enumerate FW clients)
    > -- FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW
    > -client IDs
    > -- For each FW ID found in that bitmap host sends
    > -HOST_CLIENT_PROPERTIES_REQ_CMD
    > -- FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID,
    > -max ISHTP message size, etc.
    > -- Once host received properties for that last discovered client, it considers
    > -ISHTP device fully functional (and allocates DMA buffers)
    > -
    > -3.4 HID over ISH Client
    > -Location: drivers/hid/intel-ish-hid
    > -
    > -The ISHTP client driver is responsible for:
    > -- enumerate HID devices under FW ISH client
    > -- Get Report descriptor
    > -- Register with HID core as a LL driver
    > -- Process Get/Set feature request
    > -- Get input reports
    > -
    > -3.5 HID Sensor Hub MFD and IIO sensor drivers
    > -
    > -The functionality in these drivers is the same as an external sensor hub.
    > -Refer to
    > -Documentation/hid/hid-sensor.txt for HID sensor
    > -Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space
    > -
    > -3.6 End to End HID transport Sequence Diagram
    > -
    > -HID-ISH-CLN ISHTP IPC HW
    > - | | | |
    > - | | |-----WAKE UP------------------>|
    > - | | | |
    > - | | |-----HOST READY--------------->|
    > - | | | |
    > - | | |<----MNG_RESET_NOTIFY_ACK----- |
    > - | | | |
    > - | |<----ISHTP_START------ | |
    > - | | | |
    > - | |<-----------------HOST_START_RES_CMD-------------------|
    > - | | | |
    > - | |------------------QUERY_SUBSCRIBER-------------------->|
    > - | | | |
    > - | |------------------HOST_ENUM_REQ_CMD------------------->|
    > - | | | |
    > - | |<-----------------HOST_ENUM_RES_CMD--------------------|
    > - | | | |
    > - | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
    > - | | | |
    > - | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
    > - | Create new device on in ishtp bus | |
    > - | | | |
    > - | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>|
    > - | | | |
    > - | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------|
    > - | Create new device on in ishtp bus | |
    > - | | | |
    > - | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--|
    > - | | | |
    > - probed()
    > - |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->|
    > - | | | |
    > - | |<----------------CLIENT_CONNECT_RES_CMD----------------|
    > - | | | |
    > - |register event callback| | |
    > - | | | |
    > - |ishtp_cl_send(
    > - HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >|
    > - | | | |
    > - | | |<-----IRQ(IPC_PROTOCOL_ISHTP---|
    > - | | | |
    > - |<--ENUM_DEVICE RSP-----| | |
    > - | | | |
    > -for each enumerated device
    > - |ishtp_cl_send(
    > - HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW--- >|
    > - | | | |
    > - ...Response
    > - | | | |
    > -for each enumerated device
    > - |ishtp_cl_send(
    > - HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >|
    > - | | | |
    > - | | | |
    > - hid_allocate_device
    > - | | | |
    > - hid_add_device | | |
    > - | | | |
    > -
    > -
    > -3.7 ISH Debugging
    > -
    > -To debug ISH, event tracing mechanism is used. To enable debug logs
    > -echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable
    > -cat sys/kernel/debug/tracing/trace
    > -
    > -3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260
    > -
    > -root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/
    > -/sys/bus/iio/devices/
    > -├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0
    > -│ ├── buffer
    > -│ │ ├── enable
    > -│ │ ├── length
    > -│ │ └── watermark
    > -...
    > -│ ├── in_accel_hysteresis
    > -│ ├── in_accel_offset
    > -│ ├── in_accel_sampling_frequency
    > -│ ├── in_accel_scale
    > -│ ├── in_accel_x_raw
    > -│ ├── in_accel_y_raw
    > -│ ├── in_accel_z_raw
    > -│ ├── name
    > -│ ├── scan_elements
    > -│ │ ├── in_accel_x_en
    > -│ │ ├── in_accel_x_index
    > -│ │ ├── in_accel_x_type
    > -│ │ ├── in_accel_y_en
    > -│ │ ├── in_accel_y_index
    > -│ │ ├── in_accel_y_type
    > -│ │ ├── in_accel_z_en
    > -│ │ ├── in_accel_z_index
    > -│ │ └── in_accel_z_type
    > -...
    > -│ │ ├── devices
    > -│ │ │ │ ├── buffer
    > -│ │ │ │ │ ├── enable
    > -│ │ │ │ │ ├── length
    > -│ │ │ │ │ └── watermark
    > -│ │ │ │ ├── dev
    > -│ │ │ │ ├── in_intensity_both_raw
    > -│ │ │ │ ├── in_intensity_hysteresis
    > -│ │ │ │ ├── in_intensity_offset
    > -│ │ │ │ ├── in_intensity_sampling_frequency
    > -│ │ │ │ ├── in_intensity_scale
    > -│ │ │ │ ├── name
    > -│ │ │ │ ├── scan_elements
    > -│ │ │ │ │ ├── in_intensity_both_en
    > -│ │ │ │ │ ├── in_intensity_both_index
    > -│ │ │ │ │ └── in_intensity_both_type
    > -│ │ │ │ ├── trigger
    > -│ │ │ │ │ └── current_trigger
    > -...
    > -│ │ │ │ ├── buffer
    > -│ │ │ │ │ ├── enable
    > -│ │ │ │ │ ├── length
    > -│ │ │ │ │ └── watermark
    > -│ │ │ │ ├── dev
    > -│ │ │ │ ├── in_magn_hysteresis
    > -│ │ │ │ ├── in_magn_offset
    > -│ │ │ │ ├── in_magn_sampling_frequency
    > -│ │ │ │ ├── in_magn_scale
    > -│ │ │ │ ├── in_magn_x_raw
    > -│ │ │ │ ├── in_magn_y_raw
    > -│ │ │ │ ├── in_magn_z_raw
    > -│ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw
    > -│ │ │ │ ├── in_rot_hysteresis
    > -│ │ │ │ ├── in_rot_offset
    > -│ │ │ │ ├── in_rot_sampling_frequency
    > -│ │ │ │ ├── in_rot_scale
    > -│ │ │ │ ├── name
    > -...
    > -│ │ │ │ ├── scan_elements
    > -│ │ │ │ │ ├── in_magn_x_en
    > -│ │ │ │ │ ├── in_magn_x_index
    > -│ │ │ │ │ ├── in_magn_x_type
    > -│ │ │ │ │ ├── in_magn_y_en
    > -│ │ │ │ │ ├── in_magn_y_index
    > -│ │ │ │ │ ├── in_magn_y_type
    > -│ │ │ │ │ ├── in_magn_z_en
    > -│ │ │ │ │ ├── in_magn_z_index
    > -│ │ │ │ │ ├── in_magn_z_type
    > -│ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en
    > -│ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index
    > -│ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type
    > -│ │ │ │ ├── trigger
    > -│ │ │ │ │ └── current_trigger
    > -...
    > -│ │ │ │ ├── buffer
    > -│ │ │ │ │ ├── enable
    > -│ │ │ │ │ ├── length
    > -│ │ │ │ │ └── watermark
    > -│ │ │ │ ├── dev
    > -│ │ │ │ ├── in_anglvel_hysteresis
    > -│ │ │ │ ├── in_anglvel_offset
    > -│ │ │ │ ├── in_anglvel_sampling_frequency
    > -│ │ │ │ ├── in_anglvel_scale
    > -│ │ │ │ ├── in_anglvel_x_raw
    > -│ │ │ │ ├── in_anglvel_y_raw
    > -│ │ │ │ ├── in_anglvel_z_raw
    > -│ │ │ │ ├── name
    > -│ │ │ │ ├── scan_elements
    > -│ │ │ │ │ ├── in_anglvel_x_en
    > -│ │ │ │ │ ├── in_anglvel_x_index
    > -│ │ │ │ │ ├── in_anglvel_x_type
    > -│ │ │ │ │ ├── in_anglvel_y_en
    > -│ │ │ │ │ ├── in_anglvel_y_index
    > -│ │ │ │ │ ├── in_anglvel_y_type
    > -│ │ │ │ │ ├── in_anglvel_z_en
    > -│ │ │ │ │ ├── in_anglvel_z_index
    > -│ │ │ │ │ └── in_anglvel_z_type
    > -│ │ │ │ ├── trigger
    > -│ │ │ │ │ └── current_trigger
    > -...
    > -│ │ │ │ ├── buffer
    > -│ │ │ │ │ ├── enable
    > -│ │ │ │ │ ├── length
    > -│ │ │ │ │ └── watermark
    > -│ │ │ │ ├── dev
    > -│ │ │ │ ├── in_anglvel_hysteresis
    > -│ │ │ │ ├── in_anglvel_offset
    > -│ │ │ │ ├── in_anglvel_sampling_frequency
    > -│ │ │ │ ├── in_anglvel_scale
    > -│ │ │ │ ├── in_anglvel_x_raw
    > -│ │ │ │ ├── in_anglvel_y_raw
    > -│ │ │ │ ├── in_anglvel_z_raw
    > -│ │ │ │ ├── name
    > -│ │ │ │ ├── scan_elements
    > -│ │ │ │ │ ├── in_anglvel_x_en
    > -│ │ │ │ │ ├── in_anglvel_x_index
    > -│ │ │ │ │ ├── in_anglvel_x_type
    > -│ │ │ │ │ ├── in_anglvel_y_en
    > -│ │ │ │ │ ├── in_anglvel_y_index
    > -│ │ │ │ │ ├── in_anglvel_y_type
    > -│ │ │ │ │ ├── in_anglvel_z_en
    > -│ │ │ │ │ ├── in_anglvel_z_index
    > -│ │ │ │ │ └── in_anglvel_z_type
    > -│ │ │ │ ├── trigger
    > -│ │ │ │ │ └── current_trigger
    > -...
    > diff --git a/Documentation/hid/uhid.txt b/Documentation/hid/uhid.rst
    > similarity index 94%
    > rename from Documentation/hid/uhid.txt
    > rename to Documentation/hid/uhid.rst
    > index 958fff945304..b18cb96c885f 100644
    > --- a/Documentation/hid/uhid.txt
    > +++ b/Documentation/hid/uhid.rst
    > @@ -1,5 +1,6 @@
    > - UHID - User-space I/O driver support for HID subsystem
    > - ========================================================
    > +======================================================
    > +UHID - User-space I/O driver support for HID subsystem
    > +======================================================
    >
    > UHID allows user-space to implement HID transport drivers. Please see
    > hid-transport.txt for an introduction into HID transport drivers. This document
    > @@ -22,9 +23,9 @@ If a new device is detected by your HID I/O Driver and you want to register this
    > device with the HID subsystem, then you need to open /dev/uhid once for each
    > device you want to register. All further communication is done by read()'ing or
    > write()'ing "struct uhid_event" objects. Non-blocking operations are supported
    > -by setting O_NONBLOCK.
    > +by setting O_NONBLOCK::
    >
    > -struct uhid_event {
    > + struct uhid_event {
    > __u32 type;
    > union {
    > struct uhid_create2_req create2;
    > @@ -32,7 +33,7 @@ struct uhid_event {
    > struct uhid_input2_req input2;
    > ...
    > } u;
    > -};
    > + };
    >
    > The "type" field contains the ID of the event. Depending on the ID different
    > payloads are sent. You must not split a single event across multiple read()'s or
    > @@ -86,31 +87,31 @@ the request was handled successfully. O_NONBLOCK does not affect write() as
    > writes are always handled immediately in a non-blocking fashion. Future requests
    > might make use of O_NONBLOCK, though.
    >
    > - UHID_CREATE2:
    > +UHID_CREATE2:
    > This creates the internal HID device. No I/O is possible until you send this
    > event to the kernel. The payload is of type struct uhid_create2_req and
    > contains information about your device. You can start I/O now.
    >
    > - UHID_DESTROY:
    > +UHID_DESTROY:
    > This destroys the internal HID device. No further I/O will be accepted. There
    > may still be pending messages that you can receive with read() but no further
    > UHID_INPUT events can be sent to the kernel.
    > You can create a new device by sending UHID_CREATE2 again. There is no need to
    > reopen the character device.
    >
    > - UHID_INPUT2:
    > +UHID_INPUT2:
    > You must send UHID_CREATE2 before sending input to the kernel! This event
    > contains a data-payload. This is the raw data that you read from your device
    > on the interrupt channel. The kernel will parse the HID reports.
    >
    > - UHID_GET_REPORT_REPLY:
    > +UHID_GET_REPORT_REPLY:
    > If you receive a UHID_GET_REPORT request you must answer with this request.
    > You must copy the "id" field from the request into the answer. Set the "err"
    > field to 0 if no error occurred or to EIO if an I/O error occurred.
    > If "err" is 0 then you should fill the buffer of the answer with the results
    > of the GET_REPORT request and set "size" correspondingly.
    >
    > - UHID_SET_REPORT_REPLY:
    > +UHID_SET_REPORT_REPLY:
    > This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT,
    > SET_REPORT never returns a data buffer, therefore, it's sufficient to set the
    > "id" and "err" fields correctly.
    > @@ -120,16 +121,18 @@ read()
    > read() will return a queued output report. No reaction is required to any of
    > them but you should handle them according to your needs.
    >
    > - UHID_START:
    > +UHID_START:
    > This is sent when the HID device is started. Consider this as an answer to
    > UHID_CREATE2. This is always the first event that is sent. Note that this
    > event might not be available immediately after write(UHID_CREATE2) returns.
    > Device drivers might required delayed setups.
    > This event contains a payload of type uhid_start_req. The "dev_flags" field
    > describes special behaviors of a device. The following flags are defined:
    > - UHID_DEV_NUMBERED_FEATURE_REPORTS:
    > - UHID_DEV_NUMBERED_OUTPUT_REPORTS:
    > - UHID_DEV_NUMBERED_INPUT_REPORTS:
    > +
    > + - UHID_DEV_NUMBERED_FEATURE_REPORTS
    > + - UHID_DEV_NUMBERED_OUTPUT_REPORTS
    > + - UHID_DEV_NUMBERED_INPUT_REPORTS
    > +
    > Each of these flags defines whether a given report-type uses numbered
    > reports. If numbered reports are used for a type, all messages from
    > the kernel already have the report-number as prefix. Otherwise, no
    > @@ -137,33 +140,35 @@ them but you should handle them according to your needs.
    > For messages sent by user-space to the kernel, you must adjust the
    > prefixes according to these flags.
    >
    > - UHID_STOP:
    > +UHID_STOP:
    > This is sent when the HID device is stopped. Consider this as an answer to
    > UHID_DESTROY.
    > +
    > If you didn't destroy your device via UHID_DESTROY, but the kernel sends an
    > UHID_STOP event, this should usually be ignored. It means that the kernel
    > reloaded/changed the device driver loaded on your HID device (or some other
    > maintenance actions happened).
    > +
    > You can usually ignored any UHID_STOP events safely.
    >
    > - UHID_OPEN:
    > +UHID_OPEN:
    > This is sent when the HID device is opened. That is, the data that the HID
    > device provides is read by some other process. You may ignore this event but
    > it is useful for power-management. As long as you haven't received this event
    > there is actually no other process that reads your data so there is no need to
    > send UHID_INPUT2 events to the kernel.
    >
    > - UHID_CLOSE:
    > +UHID_CLOSE:
    > This is sent when there are no more processes which read the HID data. It is
    > the counterpart of UHID_OPEN and you may as well ignore this event.
    >
    > - UHID_OUTPUT:
    > +UHID_OUTPUT:
    > This is sent if the HID device driver wants to send raw data to the I/O
    > device on the interrupt channel. You should read the payload and forward it to
    > the device. The payload is of type "struct uhid_output_req".
    > This may be received even though you haven't received UHID_OPEN, yet.
    >
    > - UHID_GET_REPORT:
    > +UHID_GET_REPORT:
    > This event is sent if the kernel driver wants to perform a GET_REPORT request
    > on the control channeld as described in the HID specs. The report-type and
    > report-number are available in the payload.
    > @@ -177,11 +182,12 @@ them but you should handle them according to your needs.
    > timed out, the kernel will ignore the response silently. The "id" field is
    > never re-used, so conflicts cannot happen.
    >
    > - UHID_SET_REPORT:
    > +UHID_SET_REPORT:
    > This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall
    > send a SET_REPORT request to your hid device. Once it replies, you must tell
    > the kernel about it via UHID_SET_REPORT_REPLY.
    > The same restrictions as for UHID_GET_REPORT apply.
    >
    > ----------------------------------------------------
    > +
    > Written 2012, David Herrmann <dh.herrmann@gmail.com>
    > diff --git a/Documentation/input/input.rst b/Documentation/input/input.rst
    > index 47f86a4bf16c..0eb61e67a7b7 100644
    > --- a/Documentation/input/input.rst
    > +++ b/Documentation/input/input.rst
    > @@ -188,7 +188,7 @@ LCDs and many other purposes.
    >
    > The monitor and speaker controls should be easy to add to the hid/input
    > interface, but for the UPSs and LCDs it doesn't make much sense. For this,
    > -the hiddev interface was designed. See Documentation/hid/hiddev.txt
    > +the hiddev interface was designed. See Documentation/hid/hiddev.rst
    > for more information about it.
    >
    > The usage of the usbhid module is very simple, it takes no parameters,
    > diff --git a/MAINTAINERS b/MAINTAINERS
    > index 8d39979e4091..969225e6bfce 100644
    > --- a/MAINTAINERS
    > +++ b/MAINTAINERS
    > @@ -16383,7 +16383,7 @@ M: Benjamin Tissoires <benjamin.tissoires@redhat.com>
    > L: linux-usb@vger.kernel.org
    > T: git git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git
    > S: Maintained
    > -F: Documentation/hid/hiddev.txt
    > +F: Documentation/hid/hiddev.rst
    > F: drivers/hid/usbhid/
    >
    > USB INTEL XHCI ROLE MUX DRIVER
    > --
    > 2.21.0
    >

    \
     
     \ /
      Last update: 2019-06-13 18:33    [W:3.739 / U:0.140 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site