Merge branch 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid

+63 -22

Documentation/hid/hid-alps.txt Documentation/hid/hid-alps.rst

··· 1 + ========================== 1 2 ALPS HID Touchpad Protocol 2 - ---------------------- 3 + ========================== 3 4 4 5 Introduction 5 6 ------------ 6 7 Currently ALPS HID driver supports U1 Touchpad device. 7 8 8 - U1 devuce basic information. 9 + U1 device basic information. 10 + 11 + ========== ====== 9 12 Vender ID 0x044E 10 13 Product ID 0x120B 11 14 Version ID 0x0121 15 + ========== ====== 12 16 13 17 14 18 HID Descriptor 15 - ------------ 19 + -------------- 20 + 21 + ======= ==================== ===== ======================================= 16 22 Byte Field Value Notes 23 + ======= ==================== ===== ======================================= 17 24 0 wHIDDescLength 001E Length of HID Descriptor : 30 bytes 18 25 2 bcdVersion 0100 Compliant with Version 1.00 19 26 4 wReportDescLength 00B2 Report Descriptor is 178 Bytes (0x00B2) ··· 35 28 22 wProductID 120B Product ID 0x120B 36 29 24 wVersionID 0121 Version 01.21 37 30 26 RESERVED 0000 RESERVED 31 + ======= ==================== ===== ======================================= 38 32 39 33 40 34 Report ID 41 - ------------ 42 - ReportID-1 (Input Reports) (HIDUsage-Mouse) for TP&SP 43 - ReportID-2 (Input Reports) (HIDUsage-keyboard) for TP 44 - ReportID-3 (Input Reports) (Vendor Usage: Max 10 finger data) for TP 45 - ReportID-4 (Input Reports) (Vendor Usage: ON bit data) for GP 46 - ReportID-5 (Feature Reports) Feature Reports 47 - ReportID-6 (Input Reports) (Vendor Usage: StickPointer data) for SP 48 - ReportID-7 (Feature Reports) Flash update (Bootloader) 35 + --------- 36 + 37 + ========== ================= ========================================= 38 + ReportID-1 (Input Reports) (HIDUsage-Mouse) for TP&SP 39 + ReportID-2 (Input Reports) (HIDUsage-keyboard) for TP 40 + ReportID-3 (Input Reports) (Vendor Usage: Max 10 finger data) for TP 41 + ReportID-4 (Input Reports) (Vendor Usage: ON bit data) for GP 42 + ReportID-5 (Feature Reports) Feature Reports 43 + ReportID-6 (Input Reports) (Vendor Usage: StickPointer data) for SP 44 + ReportID-7 (Feature Reports) Flash update (Bootloader) 45 + ========== ================= ========================================= 49 46 50 47 51 48 Data pattern 52 49 ------------ 50 + 51 + ===== ========== ===== ================= 53 52 Case1 ReportID_1 TP/SP Relative/Relative 54 53 Case2 ReportID_3 TP Absolute 55 54 ReportID_6 SP Absolute 55 + ===== ========== ===== ================= 56 56 57 57 58 58 Command Read/Write 59 59 ------------------ 60 60 To read/write to RAM, need to send a commands to the device. 61 + 61 62 The command format is as below. 62 63 63 64 DataByte(SET_REPORT) 65 + 66 + ===== ====================== 64 67 Byte1 Command Byte 65 68 Byte2 Address - Byte 0 (LSB) 66 69 Byte3 Address - Byte 1 ··· 78 61 Byte5 Address - Byte 3 (MSB) 79 62 Byte6 Value Byte 80 63 Byte7 Checksum 64 + ===== ====================== 81 65 82 66 Command Byte is read=0xD1/write=0xD2 . 67 + 83 68 Address is read/write RAM address. 69 + 84 70 Value Byte is writing data when you send the write commands. 71 + 85 72 When you read RAM, there is no meaning. 86 73 87 74 DataByte(GET_REPORT) 75 + 76 + ===== ====================== 88 77 Byte1 Response Byte 89 78 Byte2 Address - Byte 0 (LSB) 90 79 Byte3 Address - Byte 1 ··· 98 75 Byte5 Address - Byte 3 (MSB) 99 76 Byte6 Value Byte 100 77 Byte7 Checksum 78 + ===== ====================== 101 79 102 80 Read value is stored in Value Byte. 103 81 ··· 106 82 Packet Format 107 83 Touchpad data byte 108 84 ------------------ 109 - b7 b6 b5 b4 b3 b2 b1 b0 85 + 86 + 87 + ======= ======= ======= ======= ======= ======= ======= ======= ===== 88 + - b7 b6 b5 b4 b3 b2 b1 b0 89 + ======= ======= ======= ======= ======= ======= ======= ======= ===== 110 90 1 0 0 SW6 SW5 SW4 SW3 SW2 SW1 111 91 2 0 0 0 Fcv Fn3 Fn2 Fn1 Fn0 112 92 3 Xa0_7 Xa0_6 Xa0_5 Xa0_4 Xa0_3 Xa0_2 Xa0_1 Xa0_0 ··· 142 114 25 Ya4_7 Ya4_6 Ya4_5 Ya4_4 Ya4_3 Ya4_2 Ya4_1 Ya4_0 143 115 26 Ya4_15 Ya4_14 Ya4_13 Ya4_12 Ya4_11 Ya4_10 Ya4_9 Ya4_8 144 116 27 LFB4 Zs4_6 Zs4_5 Zs4_4 Zs4_3 Zs4_2 Zs4_1 Zs4_0 117 + ======= ======= ======= ======= ======= ======= ======= ======= ===== 145 118 146 119 147 - SW1-SW6: SW ON/OFF status 148 - Xan_15-0(16bit):X Absolute data of the "n"th finger 149 - Yan_15-0(16bit):Y Absolute data of the "n"th finger 150 - Zsn_6-0(7bit): Operation area of the "n"th finger 120 + SW1-SW6: 121 + SW ON/OFF status 122 + Xan_15-0(16bit): 123 + X Absolute data of the "n"th finger 124 + Yan_15-0(16bit): 125 + Y Absolute data of the "n"th finger 126 + Zsn_6-0(7bit): 127 + Operation area of the "n"th finger 151 128 152 129 153 130 StickPointer data byte 154 - ------------------ 155 - b7 b6 b5 b4 b3 b2 b1 b0 131 + ---------------------- 132 + 133 + ======= ======= ======= ======= ======= ======= ======= ======= ===== 134 + - b7 b6 b5 b4 b3 b2 b1 b0 135 + ======= ======= ======= ======= ======= ======= ======= ======= ===== 156 136 Byte1 1 1 1 0 1 SW3 SW2 SW1 157 137 Byte2 X7 X6 X5 X4 X3 X2 X1 X0 158 138 Byte3 X15 X14 X13 X12 X11 X10 X9 X8 ··· 168 132 Byte5 Y15 Y14 Y13 Y12 Y11 Y10 Y9 Y8 169 133 Byte6 Z7 Z6 Z5 Z4 Z3 Z2 Z1 Z0 170 134 Byte7 T&P Z14 Z13 Z12 Z11 Z10 Z9 Z8 135 + ======= ======= ======= ======= ======= ======= ======= ======= ===== 171 136 172 - SW1-SW3: SW ON/OFF status 173 - Xn_15-0(16bit):X Absolute data 174 - Yn_15-0(16bit):Y Absolute data 175 - Zn_14-0(15bit):Z 137 + SW1-SW3: 138 + SW ON/OFF status 139 + Xn_15-0(16bit): 140 + X Absolute data 141 + Yn_15-0(16bit): 142 + Y Absolute data 143 + Zn_14-0(15bit): 144 + Z

+105 -87

Documentation/hid/hid-sensor.txt Documentation/hid/hid-sensor.rst

··· 1 - 1 + ===================== 2 2 HID Sensors Framework 3 - ====================== 3 + ===================== 4 4 HID sensor framework provides necessary interfaces to implement sensor drivers, 5 5 which are connected to a sensor hub. The sensor hub is a HID device and it provides 6 6 a report descriptor conforming to HID 1.12 sensor usage tables. ··· 15 15 This specification describes many usage IDs, which describe the type of sensor 16 16 and also the individual data fields. Each sensor can have variable number of 17 17 data fields. The length and order is specified in the report descriptor. For 18 - example a part of report descriptor can look like: 18 + example a part of report descriptor can look like:: 19 19 20 - INPUT(1)[INPUT] 21 - .. 22 - Field(2) 23 - Physical(0020.0073) 24 - Usage(1) 25 - 0020.045f 26 - Logical Minimum(-32767) 27 - Logical Maximum(32767) 28 - Report Size(8) 29 - Report Count(1) 30 - Report Offset(16) 31 - Flags(Variable Absolute) 32 - .. 33 - .. 20 + INPUT(1)[INPUT] 21 + .. 22 + Field(2) 23 + Physical(0020.0073) 24 + Usage(1) 25 + 0020.045f 26 + Logical Minimum(-32767) 27 + Logical Maximum(32767) 28 + Report Size(8) 29 + Report Count(1) 30 + Report Offset(16) 31 + Flags(Variable Absolute) 32 + .. 33 + .. 34 34 35 35 The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73). 36 36 This accelerometer-3D has some fields. Here for example field 2 is motion intensity ··· 40 40 41 41 42 42 Implementation 43 - ================= 43 + ============== 44 44 45 45 This specification defines many different types of sensors with different sets of 46 46 data fields. It is difficult to have a common input event to user space applications, 47 47 for different sensors. For example an accelerometer can send X,Y and Z data, whereas 48 48 an ambient light sensor can send illumination data. 49 49 So the implementation has two parts: 50 + 50 51 - Core hid driver 51 52 - Individual sensor processing part (sensor drivers) 52 53 ··· 56 55 The core driver registers (hid-sensor-hub) registers as a HID driver. It parses 57 56 report descriptors and identifies all the sensors present. It adds an MFD device 58 57 with name HID-SENSOR-xxxx (where xxxx is usage id from the specification). 59 - For example 58 + 59 + For example: 60 + 60 61 HID-SENSOR-200073 is registered for an Accelerometer 3D driver. 62 + 61 63 So if any driver with this name is inserted, then the probe routine for that 62 64 function will be called. So an accelerometer processing driver can register 63 65 with this name and will be probed if there is an accelerometer-3D detected. ··· 70 66 functions, which get and set each input/feature/output report. 71 67 72 68 Individual sensor processing part (sensor drivers) 73 - ----------- 69 + -------------------------------------------------- 70 + 74 71 The processing driver will use an interface provided by the core driver to parse 75 72 the report and get the indexes of the fields and also can get events. This driver 76 73 can use IIO interface to use the standard ABI defined for a type of sensor. ··· 80 75 Core driver Interface 81 76 ===================== 82 77 83 - Callback structure: 84 - Each processing driver can use this structure to set some callbacks. 78 + Callback structure:: 79 + 80 + Each processing driver can use this structure to set some callbacks. 85 81 int (*suspend)(..): Callback when HID suspend is received 86 82 int (*resume)(..): Callback when HID resume is received 87 83 int (*capture_sample)(..): Capture a sample for one of its data fields 88 84 int (*send_event)(..): One complete event is received which can have 89 85 multiple data fields. 90 86 91 - Registration functions: 92 - int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev, 87 + Registration functions:: 88 + 89 + int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev, 93 90 u32 usage_id, 94 91 struct hid_sensor_hub_callbacks *usage_callback): 95 92 96 93 Registers callbacks for an usage id. The callback functions are not allowed 97 - to sleep. 94 + to sleep:: 98 95 99 96 100 - int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev, 97 + int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev, 101 98 u32 usage_id): 102 99 103 100 Removes callbacks for an usage id. 104 101 105 102 106 - Parsing function: 107 - int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev, 103 + Parsing function:: 104 + 105 + int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev, 108 106 u8 type, 109 107 u32 usage_id, u32 attr_usage_id, 110 108 struct hid_sensor_hub_attribute_info *info); ··· 118 110 These indexes avoid searching every time and getting field index to get or set. 119 111 120 112 121 - Set Feature report 122 - int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id, 113 + Set Feature report:: 114 + 115 + int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id, 123 116 u32 field_index, s32 value); 124 117 125 118 This interface is used to set a value for a field in feature report. For example 126 119 if there is a field report_interval, which is parsed by a call to 127 - sensor_hub_input_get_attribute_info before, then it can directly set that individual 128 - field. 120 + sensor_hub_input_get_attribute_info before, then it can directly set that 121 + individual field:: 129 122 130 123 131 - int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id, 124 + int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id, 132 125 u32 field_index, s32 *value); 133 126 134 127 This interface is used to get a value for a field in input report. For example 135 128 if there is a field report_interval, which is parsed by a call to 136 - sensor_hub_input_get_attribute_info before, then it can directly get that individual 137 - field value. 129 + sensor_hub_input_get_attribute_info before, then it can directly get that 130 + individual field value:: 138 131 139 132 140 - int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev, 133 + int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev, 141 134 u32 usage_id, 142 135 u32 attr_usage_id, u32 report_id); 143 136 ··· 152 143 ---------- 153 144 154 145 HID Custom and generic Sensors 146 + ------------------------------ 147 + 155 148 156 149 HID Sensor specification defines two special sensor usage types. Since they 157 150 don't represent a standard sensor, it is not possible to define using Linux IIO ··· 169 158 To allow application to utilize these sensors, here they are exported uses sysfs 170 159 attribute groups, attributes and misc device interface. 171 160 172 - An example of this representation on sysfs: 173 - /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R 174 - . 175 - ????????? enable_sensor 176 - ????????? feature-0-200316 177 - ??????? ????????? feature-0-200316-maximum 178 - ??????? ????????? feature-0-200316-minimum 179 - ??????? ????????? feature-0-200316-name 180 - ??????? ????????? feature-0-200316-size 181 - ??????? ????????? feature-0-200316-unit-expo 182 - ??????? ????????? feature-0-200316-units 183 - ??????? ????????? feature-0-200316-value 184 - ????????? feature-1-200201 185 - ??????? ????????? feature-1-200201-maximum 186 - ??????? ????????? feature-1-200201-minimum 187 - ??????? ????????? feature-1-200201-name 188 - ??????? ????????? feature-1-200201-size 189 - ??????? ????????? feature-1-200201-unit-expo 190 - ??????? ????????? feature-1-200201-units 191 - ??????? ????????? feature-1-200201-value 192 - ????????? input-0-200201 193 - ??????? ????????? input-0-200201-maximum 194 - ??????? ????????? input-0-200201-minimum 195 - ??????? ????????? input-0-200201-name 196 - ??????? ????????? input-0-200201-size 197 - ??????? ????????? input-0-200201-unit-expo 198 - ??????? ????????? input-0-200201-units 199 - ??????? ????????? input-0-200201-value 200 - ????????? input-1-200202 201 - ??????? ????????? input-1-200202-maximum 202 - ??????? ????????? input-1-200202-minimum 203 - ??????? ????????? input-1-200202-name 204 - ??????? ????????? input-1-200202-size 205 - ??????? ????????? input-1-200202-unit-expo 206 - ??????? ????????? input-1-200202-units 207 - ??????? ????????? input-1-200202-value 161 + An example of this representation on sysfs:: 162 + 163 + /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R 164 + . 165 + │ ├── enable_sensor 166 + │ │ ├── feature-0-200316 167 + │ │ │ ├── feature-0-200316-maximum 168 + │ │ │ ├── feature-0-200316-minimum 169 + │ │ │ ├── feature-0-200316-name 170 + │ │ │ ├── feature-0-200316-size 171 + │ │ │ ├── feature-0-200316-unit-expo 172 + │ │ │ ├── feature-0-200316-units 173 + │ │ │ ├── feature-0-200316-value 174 + │ │ ├── feature-1-200201 175 + │ │ │ ├── feature-1-200201-maximum 176 + │ │ │ ├── feature-1-200201-minimum 177 + │ │ │ ├── feature-1-200201-name 178 + │ │ │ ├── feature-1-200201-size 179 + │ │ │ ├── feature-1-200201-unit-expo 180 + │ │ │ ├── feature-1-200201-units 181 + │ │ │ ├── feature-1-200201-value 182 + │ │ ├── input-0-200201 183 + │ │ │ ├── input-0-200201-maximum 184 + │ │ │ ├── input-0-200201-minimum 185 + │ │ │ ├── input-0-200201-name 186 + │ │ │ ├── input-0-200201-size 187 + │ │ │ ├── input-0-200201-unit-expo 188 + │ │ │ ├── input-0-200201-units 189 + │ │ │ ├── input-0-200201-value 190 + │ │ ├── input-1-200202 191 + │ │ │ ├── input-1-200202-maximum 192 + │ │ │ ├── input-1-200202-minimum 193 + │ │ │ ├── input-1-200202-name 194 + │ │ │ ├── input-1-200202-size 195 + │ │ │ ├── input-1-200202-unit-expo 196 + │ │ │ ├── input-1-200202-units 197 + │ │ │ ├── input-1-200202-value 208 198 209 199 Here there is a custom sensors with four fields, two feature and two inputs. 210 200 Each field is represented by a set of attributes. All fields except the "value" 211 201 are read only. The value field is a RW field. 212 - Example 213 - /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . * 214 - feature-0-200316-maximum:6 215 - feature-0-200316-minimum:0 216 - feature-0-200316-name:property-reporting-state 217 - feature-0-200316-size:1 218 - feature-0-200316-unit-expo:0 219 - feature-0-200316-units:25 220 - feature-0-200316-value:1 202 + 203 + Example:: 204 + 205 + /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . * 206 + feature-0-200316-maximum:6 207 + feature-0-200316-minimum:0 208 + feature-0-200316-name:property-reporting-state 209 + feature-0-200316-size:1 210 + feature-0-200316-unit-expo:0 211 + feature-0-200316-units:25 212 + feature-0-200316-value:1 221 213 222 214 How to enable such sensor? 215 + ^^^^^^^^^^^^^^^^^^^^^^^^^^ 216 + 223 217 By default sensor can be power gated. To enable sysfs attribute "enable" can be 224 - used. 225 - $ echo 1 > enable_sensor 218 + used:: 219 + 220 + $ echo 1 > enable_sensor 226 221 227 222 Once enabled and powered on, sensor can report value using HID reports. 228 - These reports are pushed using misc device interface in a FIFO order. 229 - /dev$ tree | grep HID-SENSOR-2000e1.6.auto 230 - ??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto 231 - ????????? HID-SENSOR-2000e1.6.auto 223 + These reports are pushed using misc device interface in a FIFO order:: 224 + 225 + /dev$ tree | grep HID-SENSOR-2000e1.6.auto 226 + │ │ │ ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto 227 + │ ├── HID-SENSOR-2000e1.6.auto 232 228 233 229 Each reports can be of variable length preceded by a header. This header 234 230 consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw

+62 -20

Documentation/hid/hid-transport.txt Documentation/hid/hid-transport.rst

··· 1 - HID I/O Transport Drivers 2 - =========================== 1 + ========================= 2 + HID I/O Transport Drivers 3 + ========================= 3 4 4 5 The HID subsystem is independent of the underlying transport driver. Initially, 5 6 only USB was supported, but other specifications adopted the HID design and ··· 16 15 transport and device setup/management. HID core is responsible of 17 16 report-parsing, report interpretation and the user-space API. Device specifics 18 17 and quirks are handled by all layers depending on the quirk. 18 + 19 + :: 19 20 20 21 +-----------+ +-----------+ +-----------+ +-----------+ 21 22 | Device #1 | | Device #i | | Device #j | | Device #k | ··· 45 42 +----------------+ +-----------+ +------------------+ +------------------+ 46 43 47 44 Example Drivers: 48 - I/O: USB, I2C, Bluetooth-l2cap 49 - Transport: USB-HID, I2C-HID, BT-HIDP 45 + 46 + - I/O: USB, I2C, Bluetooth-l2cap 47 + - Transport: USB-HID, I2C-HID, BT-HIDP 50 48 51 49 Everything below "HID Core" is simplified in this graph as it is only of 52 50 interest to HID device drivers. Transport drivers do not need to know the ··· 187 183 ------------------- 188 184 189 185 Transport drivers normally use the following procedure to register a new device 190 - with HID core: 186 + with HID core:: 191 187 192 188 struct hid_device *hid; 193 189 int ret; ··· 219 215 "custom_ll_driver". Note that fields like "country" can be ignored by underlying 220 216 transport-drivers if not supported. 221 217 222 - To unregister a device, use: 218 + To unregister a device, use:: 223 219 224 220 hid_destroy_device(hid); 225 221 ··· 230 226 ----------------------------- 231 227 232 228 The available HID callbacks are: 233 - - int (*start) (struct hid_device *hdev) 229 + 230 + :: 231 + 232 + int (*start) (struct hid_device *hdev) 233 + 234 234 Called from HID device drivers once they want to use the device. Transport 235 235 drivers can choose to setup their device in this callback. However, normally 236 236 devices are already set up before transport drivers register them to HID core 237 237 so this is mostly only used by USB-HID. 238 238 239 - - void (*stop) (struct hid_device *hdev) 239 + :: 240 + 241 + void (*stop) (struct hid_device *hdev) 242 + 240 243 Called from HID device drivers once they are done with a device. Transport 241 244 drivers can free any buffers and deinitialize the device. But note that 242 245 ->start() might be called again if another HID device driver is loaded on the 243 246 device. 247 + 244 248 Transport drivers are free to ignore it and deinitialize devices after they 245 249 destroyed them via hid_destroy_device(). 246 250 247 - - int (*open) (struct hid_device *hdev) 251 + :: 252 + 253 + int (*open) (struct hid_device *hdev) 254 + 248 255 Called from HID device drivers once they are interested in data reports. 249 256 Usually, while user-space didn't open any input API/etc., device drivers are 250 257 not interested in device data and transport drivers can put devices asleep. 251 258 However, once ->open() is called, transport drivers must be ready for I/O. 252 259 ->open() calls are nested for each client that opens the HID device. 253 260 254 - - void (*close) (struct hid_device *hdev) 261 + :: 262 + 263 + void (*close) (struct hid_device *hdev) 264 + 255 265 Called from HID device drivers after ->open() was called but they are no 256 266 longer interested in device reports. (Usually if user-space closed any input 257 267 devices of the driver). 268 + 258 269 Transport drivers can put devices asleep and terminate any I/O of all 259 270 ->open() calls have been followed by a ->close() call. However, ->start() may 260 271 be called again if the device driver is interested in input reports again. 261 272 262 - - int (*parse) (struct hid_device *hdev) 273 + :: 274 + 275 + int (*parse) (struct hid_device *hdev) 276 + 263 277 Called once during device setup after ->start() has been called. Transport 264 278 drivers must read the HID report-descriptor from the device and tell HID core 265 279 about it via hid_parse_report(). 266 280 267 - - int (*power) (struct hid_device *hdev, int level) 281 + :: 282 + 283 + int (*power) (struct hid_device *hdev, int level) 284 + 268 285 Called by HID core to give PM hints to transport drivers. Usually this is 269 286 analogical to the ->open() and ->close() hints and redundant. 270 287 271 - - void (*request) (struct hid_device *hdev, struct hid_report *report, 272 - int reqtype) 288 + :: 289 + 290 + void (*request) (struct hid_device *hdev, struct hid_report *report, 291 + int reqtype) 292 + 273 293 Send an HID request on the ctrl channel. "report" contains the report that 274 294 should be sent and "reqtype" the request type. Request-type can be 275 295 HID_REQ_SET_REPORT or HID_REQ_GET_REPORT. 296 + 276 297 This callback is optional. If not provided, HID core will assemble a raw 277 298 report following the HID specs and send it via the ->raw_request() callback. 278 299 The transport driver is free to implement this asynchronously. 279 300 280 - - int (*wait) (struct hid_device *hdev) 301 + :: 302 + 303 + int (*wait) (struct hid_device *hdev) 304 + 281 305 Used by HID core before calling ->request() again. A transport driver can use 282 306 it to wait for any pending requests to complete if only one request is 283 307 allowed at a time. 284 308 285 - - int (*raw_request) (struct hid_device *hdev, unsigned char reportnum, 286 - __u8 *buf, size_t count, unsigned char rtype, 287 - int reqtype) 309 + :: 310 + 311 + int (*raw_request) (struct hid_device *hdev, unsigned char reportnum, 312 + __u8 *buf, size_t count, unsigned char rtype, 313 + int reqtype) 314 + 288 315 Same as ->request() but provides the report as raw buffer. This request shall 289 316 be synchronous. A transport driver must not use ->wait() to complete such 290 317 requests. This request is mandatory and hid core will reject the device if 291 318 it is missing. 292 319 293 - - int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len) 320 + :: 321 + 322 + int (*output_report) (struct hid_device *hdev, __u8 *buf, size_t len) 323 + 294 324 Send raw output report via intr channel. Used by some HID device drivers 295 325 which require high throughput for outgoing requests on the intr channel. This 296 326 must not cause SET_REPORT calls! This must be implemented as asynchronous 297 327 output report on the intr channel! 298 328 299 - - int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype) 329 + :: 330 + 331 + int (*idle) (struct hid_device *hdev, int report, int idle, int reqtype) 332 + 300 333 Perform SET/GET_IDLE request. Only used by USB-HID, do not implement! 301 334 302 335 2.3) Data Path ··· 355 314 Acknowledgements to SET_REPORT requests are not of interest to HID core. 356 315 357 316 ---------------------------------------------------- 317 + 358 318 Written 2013, David Herrmann <dh.herrmann@gmail.com>

+100 -54

Documentation/hid/hiddev.txt Documentation/hid/hiddev.rst

··· 1 + ================================================ 1 2 Care and feeding of your Human Interface Devices 3 + ================================================ 2 4 3 - INTRODUCTION 5 + Introduction 6 + ============ 4 7 5 8 In addition to the normal input type HID devices, USB also uses the 6 9 human interface device protocols for things that are not really human ··· 19 16 * the hiddev interface, which provides fairly raw HID events 20 17 21 18 The data flow for a HID event produced by a device is something like 22 - the following : 19 + the following:: 23 20 24 21 usb.c ---> hid-core.c ----> hid-input.c ----> [keyboard/mouse/joystick/event] 25 22 | 26 23 | 27 - --> hiddev.c ----> POWER / MONITOR CONTROL 24 + --> hiddev.c ----> POWER / MONITOR CONTROL 28 25 29 26 In addition, other subsystems (apart from USB) can potentially feed 30 27 events into the input subsystem, but these have no effect on the hid 31 28 device interface. 32 29 33 - USING THE HID DEVICE INTERFACE 30 + Using the HID Device Interface 31 + ============================== 34 32 35 33 The hiddev interface is a char interface using the normal USB major, 36 34 with the minor numbers starting at 96 and finishing at 111. Therefore, 37 - you need the following commands: 38 - mknod /dev/usb/hiddev0 c 180 96 39 - mknod /dev/usb/hiddev1 c 180 97 40 - mknod /dev/usb/hiddev2 c 180 98 41 - mknod /dev/usb/hiddev3 c 180 99 42 - mknod /dev/usb/hiddev4 c 180 100 43 - mknod /dev/usb/hiddev5 c 180 101 44 - mknod /dev/usb/hiddev6 c 180 102 45 - mknod /dev/usb/hiddev7 c 180 103 46 - mknod /dev/usb/hiddev8 c 180 104 47 - mknod /dev/usb/hiddev9 c 180 105 48 - mknod /dev/usb/hiddev10 c 180 106 49 - mknod /dev/usb/hiddev11 c 180 107 50 - mknod /dev/usb/hiddev12 c 180 108 51 - mknod /dev/usb/hiddev13 c 180 109 52 - mknod /dev/usb/hiddev14 c 180 110 53 - mknod /dev/usb/hiddev15 c 180 111 35 + you need the following commands:: 36 + 37 + mknod /dev/usb/hiddev0 c 180 96 38 + mknod /dev/usb/hiddev1 c 180 97 39 + mknod /dev/usb/hiddev2 c 180 98 40 + mknod /dev/usb/hiddev3 c 180 99 41 + mknod /dev/usb/hiddev4 c 180 100 42 + mknod /dev/usb/hiddev5 c 180 101 43 + mknod /dev/usb/hiddev6 c 180 102 44 + mknod /dev/usb/hiddev7 c 180 103 45 + mknod /dev/usb/hiddev8 c 180 104 46 + mknod /dev/usb/hiddev9 c 180 105 47 + mknod /dev/usb/hiddev10 c 180 106 48 + mknod /dev/usb/hiddev11 c 180 107 49 + mknod /dev/usb/hiddev12 c 180 108 50 + mknod /dev/usb/hiddev13 c 180 109 51 + mknod /dev/usb/hiddev14 c 180 110 52 + mknod /dev/usb/hiddev15 c 180 111 54 53 55 54 So you point your hiddev compliant user-space program at the correct 56 55 interface for your device, and it all just works. ··· 61 56 course. If you need to write one, read on. 62 57 63 58 64 - THE HIDDEV API 59 + The HIDDEV API 60 + ============== 61 + 65 62 This description should be read in conjunction with the HID 66 63 specification, freely available from http://www.usb.org, and 67 64 conveniently linked of http://www.linux-usb.org. ··· 76 69 each one of these usages has a single signed 32 bit value. 77 70 78 71 read(): 72 + ------- 73 + 79 74 This is the event interface. When the HID device's state changes, 80 75 it performs an interrupt transfer containing a report which contains 81 76 the changed value. The hid-core.c module parses the report, and 82 77 returns to hiddev.c the individual usages that have changed within 83 78 the report. In its basic mode, the hiddev will make these individual 84 - usage changes available to the reader using a struct hiddev_event: 79 + usage changes available to the reader using a struct hiddev_event:: 85 80 86 81 struct hiddev_event { 87 82 unsigned hid; ··· 99 90 ioctl() described below. 100 91 101 92 102 - ioctl(): 103 - This is the control interface. There are a number of controls: 93 + ioctl(): 94 + -------- 104 95 105 - HIDIOCGVERSION - int (read) 106 - Gets the version code out of the hiddev driver. 96 + This is the control interface. There are a number of controls: 107 97 108 - HIDIOCAPPLICATION - (none) 98 + HIDIOCGVERSION 99 + - int (read) 100 + 101 + Gets the version code out of the hiddev driver. 102 + 103 + HIDIOCAPPLICATION 104 + - (none) 105 + 109 106 This ioctl call returns the HID application usage associated with the 110 107 hid device. The third argument to ioctl() specifies which application 111 108 index to get. This is useful when the device has more than one ··· 119 104 the number of application collections this device has) the ioctl 120 105 returns -1. You can find out beforehand how many application 121 106 collections the device has from the num_applications field from the 122 - hiddev_devinfo structure. 107 + hiddev_devinfo structure. 123 108 124 - HIDIOCGCOLLECTIONINFO - struct hiddev_collection_info (read/write) 109 + HIDIOCGCOLLECTIONINFO 110 + - struct hiddev_collection_info (read/write) 111 + 125 112 This returns a superset of the information above, providing not only 126 113 application collections, but all the collections the device has. It 127 114 also returns the level the collection lives in the hierarchy. 128 - The user passes in a hiddev_collection_info struct with the index 129 - field set to the index that should be returned. The ioctl fills in 130 - the other fields. If the index is larger than the last collection 115 + The user passes in a hiddev_collection_info struct with the index 116 + field set to the index that should be returned. The ioctl fills in 117 + the other fields. If the index is larger than the last collection 131 118 index, the ioctl returns -1 and sets errno to -EINVAL. 132 119 133 - HIDIOCGDEVINFO - struct hiddev_devinfo (read) 120 + HIDIOCGDEVINFO 121 + - struct hiddev_devinfo (read) 122 + 134 123 Gets a hiddev_devinfo structure which describes the device. 135 124 136 - HIDIOCGSTRING - struct hiddev_string_descriptor (read/write) 125 + HIDIOCGSTRING 126 + - struct hiddev_string_descriptor (read/write) 127 + 137 128 Gets a string descriptor from the device. The caller must fill in the 138 129 "index" field to indicate which descriptor should be returned. 139 130 140 - HIDIOCINITREPORT - (none) 131 + HIDIOCINITREPORT 132 + - (none) 133 + 141 134 Instructs the kernel to retrieve all input and feature report values 142 135 from the device. At this point, all the usage structures will contain 143 136 current values for the device, and will maintain it as the device ··· 153 130 since later kernels automatically initialize the reports from the 154 131 device at attach time. 155 132 156 - HIDIOCGNAME - string (variable length) 133 + HIDIOCGNAME 134 + - string (variable length) 135 + 157 136 Gets the device name 158 137 159 - HIDIOCGREPORT - struct hiddev_report_info (write) 138 + HIDIOCGREPORT 139 + - struct hiddev_report_info (write) 140 + 160 141 Instructs the kernel to get a feature or input report from the device, 161 142 in order to selectively update the usage structures (in contrast to 162 143 INITREPORT). 163 144 164 - HIDIOCSREPORT - struct hiddev_report_info (write) 145 + HIDIOCSREPORT 146 + - struct hiddev_report_info (write) 147 + 165 148 Instructs the kernel to send a report to the device. This report can 166 149 be filled in by the user through HIDIOCSUSAGE calls (below) to fill in 167 150 individual usage values in the report before sending the report in full 168 - to the device. 151 + to the device. 169 152 170 - HIDIOCGREPORTINFO - struct hiddev_report_info (read/write) 153 + HIDIOCGREPORTINFO 154 + - struct hiddev_report_info (read/write) 155 + 171 156 Fills in a hiddev_report_info structure for the user. The report is 172 157 looked up by type (input, output or feature) and id, so these fields 173 158 must be filled in by the user. The ID can be absolute -- the actual ··· 185 154 information about report ids, the right way to use this ioctl is to 186 155 use the relative IDs above to enumerate the valid IDs. The ioctl 187 156 returns non-zero when there is no more next ID. The real report ID is 188 - filled into the returned hiddev_report_info structure. 157 + filled into the returned hiddev_report_info structure. 189 158 190 - HIDIOCGFIELDINFO - struct hiddev_field_info (read/write) 159 + HIDIOCGFIELDINFO 160 + - struct hiddev_field_info (read/write) 161 + 191 162 Returns the field information associated with a report in a 192 163 hiddev_field_info structure. The user must fill in report_id and 193 164 report_type in this structure, as above. The field_index should also 194 165 be filled in, which should be a number from 0 and maxfield-1, as 195 - returned from a previous HIDIOCGREPORTINFO call. 166 + returned from a previous HIDIOCGREPORTINFO call. 196 167 197 - HIDIOCGUCODE - struct hiddev_usage_ref (read/write) 168 + HIDIOCGUCODE 169 + - struct hiddev_usage_ref (read/write) 170 + 198 171 Returns the usage_code in a hiddev_usage_ref structure, given that 199 172 given its report type, report id, field index, and index within the 200 173 field have already been filled into the structure. 201 174 202 - HIDIOCGUSAGE - struct hiddev_usage_ref (read/write) 175 + HIDIOCGUSAGE 176 + - struct hiddev_usage_ref (read/write) 177 + 203 178 Returns the value of a usage in a hiddev_usage_ref structure. The 204 179 usage to be retrieved can be specified as above, or the user can 205 180 choose to fill in the report_type field and specify the report_id as 206 181 HID_REPORT_ID_UNKNOWN. In this case, the hiddev_usage_ref will be 207 182 filled in with the report and field information associated with this 208 - usage if it is found. 183 + usage if it is found. 209 184 210 - HIDIOCSUSAGE - struct hiddev_usage_ref (write) 185 + HIDIOCSUSAGE 186 + - struct hiddev_usage_ref (write) 187 + 211 188 Sets the value of a usage in an output report. The user fills in 212 189 the hiddev_usage_ref structure as above, but additionally fills in 213 190 the value field. 214 191 215 - HIDIOGCOLLECTIONINDEX - struct hiddev_usage_ref (write) 192 + HIDIOGCOLLECTIONINDEX 193 + - struct hiddev_usage_ref (write) 194 + 216 195 Returns the collection index associated with this usage. This 217 196 indicates where in the collection hierarchy this usage sits. 218 197 219 - HIDIOCGFLAG - int (read) 220 - HIDIOCSFLAG - int (write) 198 + HIDIOCGFLAG 199 + - int (read) 200 + HIDIOCSFLAG 201 + - int (write) 202 + 221 203 These operations respectively inspect and replace the mode flags 222 204 that influence the read() call above. The flags are as follows: 223 205 224 - HIDDEV_FLAG_UREF - read() calls will now return 206 + HIDDEV_FLAG_UREF 207 + - read() calls will now return 225 208 struct hiddev_usage_ref instead of struct hiddev_event. 226 209 This is a larger structure, but in situations where the 227 210 device has more than one usage in its reports with the 228 211 same usage code, this mode serves to resolve such 229 212 ambiguity. 230 213 231 - HIDDEV_FLAG_REPORT - This flag can only be used in conjunction 214 + HIDDEV_FLAG_REPORT 215 + - This flag can only be used in conjunction 232 216 with HIDDEV_FLAG_UREF. With this flag set, when the device 233 217 sends a report, a struct hiddev_usage_ref will be returned 234 - to read() filled in with the report_type and report_id, but 218 + to read() filled in with the report_type and report_id, but 235 219 with field_index set to FIELD_INDEX_NONE. This serves as 236 220 additional notification when the device has sent a report.

+36 -17

Documentation/hid/hidraw.txt Documentation/hid/hidraw.rst

··· 1 - HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices 2 - ================================================================== 1 + ================================================================ 2 + HIDRAW - Raw Access to USB and Bluetooth Human Interface Devices 3 + ================================================================ 3 4 4 5 The hidraw driver provides a raw interface to USB and Bluetooth Human 5 6 Interface Devices (HIDs). It differs from hiddev in that reports sent and ··· 32 31 and udev rule-dependent, applications should use libudev to locate hidraw 33 32 devices attached to the system. There is a tutorial on libudev with a 34 33 working example at: 34 + 35 35 http://www.signal11.us/oss/udev/ 36 36 37 37 The HIDRAW API ··· 53 51 will begin at the first byte. 54 52 55 53 write() 56 - -------- 54 + ------- 57 55 The write() function will write a report to the device. For USB devices, if 58 56 the device has an INTERRUPT OUT endpoint, the report will be sent on that 59 57 endpoint. If it does not, the report will be sent over the control endpoint, ··· 64 62 be set to 0. The report data itself should begin at the second byte. 65 63 66 64 ioctl() 67 - -------- 65 + ------- 68 66 Hidraw supports the following ioctls: 69 67 70 - HIDIOCGRDESCSIZE: Get Report Descriptor Size 68 + HIDIOCGRDESCSIZE: 69 + Get Report Descriptor Size 70 + 71 71 This ioctl will get the size of the device's report descriptor. 72 72 73 - HIDIOCGRDESC: Get Report Descriptor 73 + HIDIOCGRDESC: 74 + Get Report Descriptor 75 + 74 76 This ioctl returns the device's report descriptor using a 75 77 hidraw_report_descriptor struct. Make sure to set the size field of the 76 78 hidraw_report_descriptor struct to the size returned from HIDIOCGRDESCSIZE. 77 79 78 - HIDIOCGRAWINFO: Get Raw Info 80 + HIDIOCGRAWINFO: 81 + Get Raw Info 82 + 79 83 This ioctl will return a hidraw_devinfo struct containing the bus type, the 80 84 vendor ID (VID), and product ID (PID) of the device. The bus type can be one 81 - of: 82 - BUS_USB 83 - BUS_HIL 84 - BUS_BLUETOOTH 85 - BUS_VIRTUAL 85 + of:: 86 + 87 + - BUS_USB 88 + - BUS_HIL 89 + - BUS_BLUETOOTH 90 + - BUS_VIRTUAL 91 + 86 92 which are defined in uapi/linux/input.h. 87 93 88 - HIDIOCGRAWNAME(len): Get Raw Name 94 + HIDIOCGRAWNAME(len): 95 + Get Raw Name 96 + 89 97 This ioctl returns a string containing the vendor and product strings of 90 98 the device. The returned string is Unicode, UTF-8 encoded. 91 99 92 - HIDIOCGRAWPHYS(len): Get Physical Address 100 + HIDIOCGRAWPHYS(len): 101 + Get Physical Address 102 + 93 103 This ioctl returns a string representing the physical address of the device. 94 104 For USB devices, the string contains the physical path to the device (the 95 105 USB controller, hubs, ports, etc). For Bluetooth devices, the string 96 106 contains the hardware (MAC) address of the device. 97 107 98 - HIDIOCSFEATURE(len): Send a Feature Report 108 + HIDIOCSFEATURE(len): 109 + Send a Feature Report 110 + 99 111 This ioctl will send a feature report to the device. Per the HID 100 112 specification, feature reports are always sent using the control endpoint. 101 113 Set the first byte of the supplied buffer to the report number. For devices ··· 117 101 begins in the second byte. Make sure to set len accordingly, to one more 118 102 than the length of the report (to account for the report number). 119 103 120 - HIDIOCGFEATURE(len): Get a Feature Report 104 + HIDIOCGFEATURE(len): 105 + Get a Feature Report 106 + 121 107 This ioctl will request a feature report from the device using the control 122 108 endpoint. The first byte of the supplied buffer should be set to the report 123 109 number of the requested report. For devices which do not use numbered ··· 127 109 the first byte of the buffer (ie: the report number is not returned). 128 110 129 111 Example 130 - --------- 112 + ------- 131 113 In samples/, find hid-example.c, which shows examples of read(), write(), 132 114 and all the ioctls for hidraw. The code may be used by anyone for any 133 115 purpose, and can serve as a starting point for developing applications using 134 116 hidraw. 135 117 136 118 Document by: 119 + 137 120 Alan Ott <alan@signal11.us>, Signal 11 Software

+18

Documentation/hid/index.rst

··· 1 + :orphan: 2 + 3 + ============================= 4 + Human Interface Devices (HID) 5 + ============================= 6 + 7 + .. toctree:: 8 + :maxdepth: 1 9 + 10 + hiddev 11 + hidraw 12 + hid-sensor 13 + hid-transport 14 + 15 + uhid 16 + 17 + hid-alps 18 + intel-ish-hid

+485

Documentation/hid/intel-ish-hid.rst

··· 1 + ================================= 2 + Intel Integrated Sensor Hub (ISH) 3 + ================================= 4 + 5 + A sensor hub enables the ability to offload sensor polling and algorithm 6 + processing to a dedicated low power co-processor. This allows the core 7 + processor to go into low power modes more often, resulting in the increased 8 + battery life. 9 + 10 + There are many vendors providing external sensor hubs confirming to HID 11 + Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops 12 + and embedded products. Linux had this support since Linux 3.9. 13 + 14 + Intel® introduced integrated sensor hubs as a part of the SoC starting from 15 + Cherry Trail and now supported on multiple generations of CPU packages. There 16 + are many commercial devices already shipped with Integrated Sensor Hubs (ISH). 17 + These ISH also comply to HID sensor specification, but the difference is the 18 + transport protocol used for communication. The current external sensor hubs 19 + mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB. 20 + 21 + 1. Overview 22 + =========== 23 + 24 + Using a analogy with a usbhid implementation, the ISH follows a similar model 25 + for a very high speed communication:: 26 + 27 + ----------------- ---------------------- 28 + | USB HID | --> | ISH HID | 29 + ----------------- ---------------------- 30 + ----------------- ---------------------- 31 + | USB protocol | --> | ISH Transport | 32 + ----------------- ---------------------- 33 + ----------------- ---------------------- 34 + | EHCI/XHCI | --> | ISH IPC | 35 + ----------------- ---------------------- 36 + PCI PCI 37 + ----------------- ---------------------- 38 + |Host controller| --> | ISH processor | 39 + ----------------- ---------------------- 40 + USB Link 41 + ----------------- ---------------------- 42 + | USB End points| --> | ISH Clients | 43 + ----------------- ---------------------- 44 + 45 + Like USB protocol provides a method for device enumeration, link management 46 + and user data encapsulation, the ISH also provides similar services. But it is 47 + very light weight tailored to manage and communicate with ISH client 48 + applications implemented in the firmware. 49 + 50 + The ISH allows multiple sensor management applications executing in the 51 + firmware. Like USB endpoints the messaging can be to/from a client. As part of 52 + enumeration process, these clients are identified. These clients can be simple 53 + HID sensor applications, sensor calibration application or senor firmware 54 + update application. 55 + 56 + The implementation model is similar, like USB bus, ISH transport is also 57 + implemented as a bus. Each client application executing in the ISH processor 58 + is registered as a device on this bus. The driver, which binds each device 59 + (ISH HID driver) identifies the device type and registers with the hid core. 60 + 61 + 2. ISH Implementation: Block Diagram 62 + ==================================== 63 + 64 + :: 65 + 66 + --------------------------- 67 + | User Space Applications | 68 + --------------------------- 69 + 70 + ----------------IIO ABI---------------- 71 + -------------------------- 72 + | IIO Sensor Drivers | 73 + -------------------------- 74 + -------------------------- 75 + | IIO core | 76 + -------------------------- 77 + -------------------------- 78 + | HID Sensor Hub MFD | 79 + -------------------------- 80 + -------------------------- 81 + | HID Core | 82 + -------------------------- 83 + -------------------------- 84 + | HID over ISH Client | 85 + -------------------------- 86 + -------------------------- 87 + | ISH Transport (ISHTP) | 88 + -------------------------- 89 + -------------------------- 90 + | IPC Drivers | 91 + -------------------------- 92 + OS 93 + ---------------- PCI ----------------- 94 + Hardware + Firmware 95 + ---------------------------- 96 + | ISH Hardware/Firmware(FW) | 97 + ---------------------------- 98 + 99 + 3. High level processing in above blocks 100 + ======================================== 101 + 102 + 3.1 Hardware Interface 103 + ---------------------- 104 + 105 + The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI 106 + product and vendor IDs are changed from different generations of processors. So 107 + the source code which enumerate drivers needs to update from generation to 108 + generation. 109 + 110 + 3.2 Inter Processor Communication (IPC) driver 111 + ---------------------------------------------- 112 + 113 + Location: drivers/hid/intel-ish-hid/ipc 114 + 115 + The IPC message used memory mapped I/O. The registers are defined in 116 + hw-ish-regs.h. 117 + 118 + 3.2.1 IPC/FW message types 119 + ^^^^^^^^^^^^^^^^^^^^^^^^^^ 120 + 121 + There are two types of messages, one for management of link and other messages 122 + are to and from transport layers. 123 + 124 + TX and RX of Transport messages 125 + ............................... 126 + 127 + A set of memory mapped register offers support of multi byte messages TX and 128 + RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains 129 + internal queues to sequence messages and send them in order to the FW. 130 + Optionally the caller can register handler to get notification of completion. 131 + A door bell mechanism is used in messaging to trigger processing in host and 132 + client firmware side. When ISH interrupt handler is called, the ISH2HOST 133 + doorbell register is used by host drivers to determine that the interrupt 134 + is for ISH. 135 + 136 + Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell 137 + register has the following format: 138 + Bits 0..6: fragment length (7 bits are used) 139 + Bits 10..13: encapsulated protocol 140 + Bits 16..19: management command (for IPC management protocol) 141 + Bit 31: doorbell trigger (signal H/W interrupt to the other side) 142 + Other bits are reserved, should be 0. 143 + 144 + 3.2.2 Transport layer interface 145 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 146 + 147 + To abstract HW level IPC communication, a set of callbacks are registered. 148 + The transport layer uses them to send and receive messages. 149 + Refer to struct ishtp_hw_ops for callbacks. 150 + 151 + 3.3 ISH Transport layer 152 + ----------------------- 153 + 154 + Location: drivers/hid/intel-ish-hid/ishtp/ 155 + 156 + 3.3.1 A Generic Transport Layer 157 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 158 + 159 + The transport layer is a bi-directional protocol, which defines: 160 + - Set of commands to start, stop, connect, disconnect and flow control 161 + (ishtp/hbm.h) for details 162 + - A flow control mechanism to avoid buffer overflows 163 + 164 + This protocol resembles bus messages described in the following document: 165 + http://www.intel.com/content/dam/www/public/us/en/documents/technical-\ 166 + specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer" 167 + 168 + 3.3.2 Connection and Flow Control Mechanism 169 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 170 + 171 + Each FW client and a protocol is identified by an UUID. In order to communicate 172 + to a FW client, a connection must be established using connect request and 173 + response bus messages. If successful, a pair (host_client_id and fw_client_id) 174 + will identify the connection. 175 + 176 + Once connection is established, peers send each other flow control bus messages 177 + independently. Every peer may send a message only if it has received a 178 + flow-control credit before. Once it sent a message, it may not send another one 179 + before receiving the next flow control credit. 180 + Either side can send disconnect request bus message to end communication. Also 181 + the link will be dropped if major FW reset occurs. 182 + 183 + 3.3.3 Peer to Peer data transfer 184 + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 185 + 186 + Peer to Peer data transfer can happen with or without using DMA. Depending on 187 + the sensor bandwidth requirement DMA can be enabled by using module parameter 188 + ishtp_use_dma under intel_ishtp. 189 + 190 + Each side (host and FW) manages its DMA transfer memory independently. When an 191 + ISHTP client from either host or FW side wants to send something, it decides 192 + whether to send over IPC or over DMA; for each transfer the decision is 193 + independent. The sending side sends DMA_XFER message when the message is in 194 + the respective host buffer (TX when host client sends, RX when FW client 195 + sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating 196 + the sender that the memory region for that message may be reused. 197 + 198 + DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message 199 + (that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK. 200 + Additionally to DMA address communication, this sequence checks capabilities: 201 + if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't 202 + send DMA; if FW doesn't support DMA then it won't respond with 203 + DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers. 204 + Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER, 205 + it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means 206 + that it already did DMA and the message resides at host. Thus, DMA_XFER 207 + and DMA_XFER_ACK act as ownership indicators. 208 + 209 + At initial state all outgoing memory belongs to the sender (TX to host, RX to 210 + FW), DMA_XFER transfers ownership on the region that contains ISHTP message to 211 + the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender 212 + needs not wait for previous DMA_XFER to be ack'ed, and may send another message 213 + as long as remaining continuous memory in its ownership is enough. 214 + In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once 215 + (up to IPC MTU), thus allowing for interrupt throttling. 216 + Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC 217 + fragments and via IPC otherwise. 218 + 219 + 3.3.4 Ring Buffers 220 + ^^^^^^^^^^^^^^^^^^ 221 + 222 + When a client initiate a connection, a ring or RX and TX buffers are allocated. 223 + The size of ring can be specified by the client. HID client set 16 and 32 for 224 + TX and RX buffers respectively. On send request from client, the data to be 225 + sent is copied to one of the send ring buffer and scheduled to be sent using 226 + bus message protocol. These buffers are required because the FW may have not 227 + have processed the last message and may not have enough flow control credits 228 + to send. Same thing holds true on receive side and flow control is required. 229 + 230 + 3.3.5 Host Enumeration 231 + ^^^^^^^^^^^^^^^^^^^^^^ 232 + 233 + The host enumeration bus command allow discovery of clients present in the FW. 234 + There can be multiple sensor clients and clients for calibration function. 235 + 236 + To ease in implantation and allow independent driver handle each client 237 + this transport layer takes advantage of Linux Bus driver model. Each 238 + client is registered as device on the the transport bus (ishtp bus). 239 + 240 + Enumeration sequence of messages: 241 + 242 + - Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up. 243 + - FW responds with HOST_START_RES_CMD 244 + - Host sends HOST_ENUM_REQ_CMD (enumerate FW clients) 245 + - FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW 246 + client IDs 247 + - For each FW ID found in that bitmap host sends 248 + HOST_CLIENT_PROPERTIES_REQ_CMD 249 + - FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID, 250 + max ISHTP message size, etc. 251 + - Once host received properties for that last discovered client, it considers 252 + ISHTP device fully functional (and allocates DMA buffers) 253 + 254 + 3.4 HID over ISH Client 255 + ----------------------- 256 + 257 + Location: drivers/hid/intel-ish-hid 258 + 259 + The ISHTP client driver is responsible for: 260 + 261 + - enumerate HID devices under FW ISH client 262 + - Get Report descriptor 263 + - Register with HID core as a LL driver 264 + - Process Get/Set feature request 265 + - Get input reports 266 + 267 + 3.5 HID Sensor Hub MFD and IIO sensor drivers 268 + --------------------------------------------- 269 + 270 + The functionality in these drivers is the same as an external sensor hub. 271 + Refer to 272 + Documentation/hid/hid-sensor.rst for HID sensor 273 + Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space 274 + 275 + 3.6 End to End HID transport Sequence Diagram 276 + --------------------------------------------- 277 + 278 + :: 279 + 280 + HID-ISH-CLN ISHTP IPC HW 281 + | | | | 282 + | | |-----WAKE UP------------------>| 283 + | | | | 284 + | | |-----HOST READY--------------->| 285 + | | | | 286 + | | |<----MNG_RESET_NOTIFY_ACK----- | 287 + | | | | 288 + | |<----ISHTP_START------ | | 289 + | | | | 290 + | |<-----------------HOST_START_RES_CMD-------------------| 291 + | | | | 292 + | |------------------QUERY_SUBSCRIBER-------------------->| 293 + | | | | 294 + | |------------------HOST_ENUM_REQ_CMD------------------->| 295 + | | | | 296 + | |<-----------------HOST_ENUM_RES_CMD--------------------| 297 + | | | | 298 + | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| 299 + | | | | 300 + | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| 301 + | Create new device on in ishtp bus | | 302 + | | | | 303 + | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| 304 + | | | | 305 + | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| 306 + | Create new device on in ishtp bus | | 307 + | | | | 308 + | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--| 309 + | | | | 310 + probed() 311 + |----ishtp_cl_connect--->|----------------- CLIENT_CONNECT_REQ_CMD-------------->| 312 + | | | | 313 + | |<----------------CLIENT_CONNECT_RES_CMD----------------| 314 + | | | | 315 + |register event callback | | | 316 + | | | | 317 + |ishtp_cl_send( 318 + HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >| 319 + | | | | 320 + | | |<-----IRQ(IPC_PROTOCOL_ISHTP---| 321 + | | | | 322 + |<--ENUM_DEVICE RSP------| | | 323 + | | | | 324 + for each enumerated device 325 + |ishtp_cl_send( 326 + HOSTIF_GET_HID_DESCRIPTOR|----------fill ishtp_msg_hdr struct write to HW----- >| 327 + | | | | 328 + ...Response 329 + | | | | 330 + for each enumerated device 331 + |ishtp_cl_send( 332 + HOSTIF_GET_REPORT_DESCRIPTOR|--------------fill ishtp_msg_hdr struct write to HW-- >| 333 + | | | | 334 + | | | | 335 + hid_allocate_device 336 + | | | | 337 + hid_add_device | | | 338 + | | | | 339 + 340 + 341 + 3.7 ISH Debugging 342 + ----------------- 343 + 344 + To debug ISH, event tracing mechanism is used. To enable debug logs 345 + echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable 346 + cat sys/kernel/debug/tracing/trace 347 + 348 + 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 349 + ----------------------------------------------------- 350 + 351 + :: 352 + 353 + root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/ 354 + /sys/bus/iio/devices/ 355 + ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0 356 + │ ├── buffer 357 + │ │ ├── enable 358 + │ │ ├── length 359 + │ │ └── watermark 360 + ... 361 + │ ├── in_accel_hysteresis 362 + │ ├── in_accel_offset 363 + │ ├── in_accel_sampling_frequency 364 + │ ├── in_accel_scale 365 + │ ├── in_accel_x_raw 366 + │ ├── in_accel_y_raw 367 + │ ├── in_accel_z_raw 368 + │ ├── name 369 + │ ├── scan_elements 370 + │ │ ├── in_accel_x_en 371 + │ │ ├── in_accel_x_index 372 + │ │ ├── in_accel_x_type 373 + │ │ ├── in_accel_y_en 374 + │ │ ├── in_accel_y_index 375 + │ │ ├── in_accel_y_type 376 + │ │ ├── in_accel_z_en 377 + │ │ ├── in_accel_z_index 378 + │ │ └── in_accel_z_type 379 + ... 380 + │ │ ├── devices 381 + │ │ │ │ ├── buffer 382 + │ │ │ │ │ ├── enable 383 + │ │ │ │ │ ├── length 384 + │ │ │ │ │ └── watermark 385 + │ │ │ │ ├── dev 386 + │ │ │ │ ├── in_intensity_both_raw 387 + │ │ │ │ ├── in_intensity_hysteresis 388 + │ │ │ │ ├── in_intensity_offset 389 + │ │ │ │ ├── in_intensity_sampling_frequency 390 + │ │ │ │ ├── in_intensity_scale 391 + │ │ │ │ ├── name 392 + │ │ │ │ ├── scan_elements 393 + │ │ │ │ │ ├── in_intensity_both_en 394 + │ │ │ │ │ ├── in_intensity_both_index 395 + │ │ │ │ │ └── in_intensity_both_type 396 + │ │ │ │ ├── trigger 397 + │ │ │ │ │ └── current_trigger 398 + ... 399 + │ │ │ │ ├── buffer 400 + │ │ │ │ │ ├── enable 401 + │ │ │ │ │ ├── length 402 + │ │ │ │ │ └── watermark 403 + │ │ │ │ ├── dev 404 + │ │ │ │ ├── in_magn_hysteresis 405 + │ │ │ │ ├── in_magn_offset 406 + │ │ │ │ ├── in_magn_sampling_frequency 407 + │ │ │ │ ├── in_magn_scale 408 + │ │ │ │ ├── in_magn_x_raw 409 + │ │ │ │ ├── in_magn_y_raw 410 + │ │ │ │ ├── in_magn_z_raw 411 + │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw 412 + │ │ │ │ ├── in_rot_hysteresis 413 + │ │ │ │ ├── in_rot_offset 414 + │ │ │ │ ├── in_rot_sampling_frequency 415 + │ │ │ │ ├── in_rot_scale 416 + │ │ │ │ ├── name 417 + ... 418 + │ │ │ │ ├── scan_elements 419 + │ │ │ │ │ ├── in_magn_x_en 420 + │ │ │ │ │ ├── in_magn_x_index 421 + │ │ │ │ │ ├── in_magn_x_type 422 + │ │ │ │ │ ├── in_magn_y_en 423 + │ │ │ │ │ ├── in_magn_y_index 424 + │ │ │ │ │ ├── in_magn_y_type 425 + │ │ │ │ │ ├── in_magn_z_en 426 + │ │ │ │ │ ├── in_magn_z_index 427 + │ │ │ │ │ ├── in_magn_z_type 428 + │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en 429 + │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index 430 + │ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type 431 + │ │ │ │ ├── trigger 432 + │ │ │ │ │ └── current_trigger 433 + ... 434 + │ │ │ │ ├── buffer 435 + │ │ │ │ │ ├── enable 436 + │ │ │ │ │ ├── length 437 + │ │ │ │ │ └── watermark 438 + │ │ │ │ ├── dev 439 + │ │ │ │ ├── in_anglvel_hysteresis 440 + │ │ │ │ ├── in_anglvel_offset 441 + │ │ │ │ ├── in_anglvel_sampling_frequency 442 + │ │ │ │ ├── in_anglvel_scale 443 + │ │ │ │ ├── in_anglvel_x_raw 444 + │ │ │ │ ├── in_anglvel_y_raw 445 + │ │ │ │ ├── in_anglvel_z_raw 446 + │ │ │ │ ├── name 447 + │ │ │ │ ├── scan_elements 448 + │ │ │ │ │ ├── in_anglvel_x_en 449 + │ │ │ │ │ ├── in_anglvel_x_index 450 + │ │ │ │ │ ├── in_anglvel_x_type 451 + │ │ │ │ │ ├── in_anglvel_y_en 452 + │ │ │ │ │ ├── in_anglvel_y_index 453 + │ │ │ │ │ ├── in_anglvel_y_type 454 + │ │ │ │ │ ├── in_anglvel_z_en 455 + │ │ │ │ │ ├── in_anglvel_z_index 456 + │ │ │ │ │ └── in_anglvel_z_type 457 + │ │ │ │ ├── trigger 458 + │ │ │ │ │ └── current_trigger 459 + ... 460 + │ │ │ │ ├── buffer 461 + │ │ │ │ │ ├── enable 462 + │ │ │ │ │ ├── length 463 + │ │ │ │ │ └── watermark 464 + │ │ │ │ ├── dev 465 + │ │ │ │ ├── in_anglvel_hysteresis 466 + │ │ │ │ ├── in_anglvel_offset 467 + │ │ │ │ ├── in_anglvel_sampling_frequency 468 + │ │ │ │ ├── in_anglvel_scale 469 + │ │ │ │ ├── in_anglvel_x_raw 470 + │ │ │ │ ├── in_anglvel_y_raw 471 + │ │ │ │ ├── in_anglvel_z_raw 472 + │ │ │ │ ├── name 473 + │ │ │ │ ├── scan_elements 474 + │ │ │ │ │ ├── in_anglvel_x_en 475 + │ │ │ │ │ ├── in_anglvel_x_index 476 + │ │ │ │ │ ├── in_anglvel_x_type 477 + │ │ │ │ │ ├── in_anglvel_y_en 478 + │ │ │ │ │ ├── in_anglvel_y_index 479 + │ │ │ │ │ ├── in_anglvel_y_type 480 + │ │ │ │ │ ├── in_anglvel_z_en 481 + │ │ │ │ │ ├── in_anglvel_z_index 482 + │ │ │ │ │ └── in_anglvel_z_type 483 + │ │ │ │ ├── trigger 484 + │ │ │ │ │ └── current_trigger 485 + ...

-454

Documentation/hid/intel-ish-hid.txt

··· 1 - Intel Integrated Sensor Hub (ISH) 2 - =============================== 3 - 4 - A sensor hub enables the ability to offload sensor polling and algorithm 5 - processing to a dedicated low power co-processor. This allows the core 6 - processor to go into low power modes more often, resulting in the increased 7 - battery life. 8 - 9 - There are many vendors providing external sensor hubs confirming to HID 10 - Sensor usage tables, and used in several tablets, 2 in 1 convertible laptops 11 - and embedded products. Linux had this support since Linux 3.9. 12 - 13 - Intel® introduced integrated sensor hubs as a part of the SoC starting from 14 - Cherry Trail and now supported on multiple generations of CPU packages. There 15 - are many commercial devices already shipped with Integrated Sensor Hubs (ISH). 16 - These ISH also comply to HID sensor specification, but the difference is the 17 - transport protocol used for communication. The current external sensor hubs 18 - mainly use HID over i2C or USB. But ISH doesn't use either i2c or USB. 19 - 20 - 1. Overview 21 - 22 - Using a analogy with a usbhid implementation, the ISH follows a similar model 23 - for a very high speed communication: 24 - 25 - ----------------- ---------------------- 26 - | USB HID | --> | ISH HID | 27 - ----------------- ---------------------- 28 - ----------------- ---------------------- 29 - | USB protocol | --> | ISH Transport | 30 - ----------------- ---------------------- 31 - ----------------- ---------------------- 32 - | EHCI/XHCI | --> | ISH IPC | 33 - ----------------- ---------------------- 34 - PCI PCI 35 - ----------------- ---------------------- 36 - |Host controller| --> | ISH processor | 37 - ----------------- ---------------------- 38 - USB Link 39 - ----------------- ---------------------- 40 - | USB End points| --> | ISH Clients | 41 - ----------------- ---------------------- 42 - 43 - Like USB protocol provides a method for device enumeration, link management 44 - and user data encapsulation, the ISH also provides similar services. But it is 45 - very light weight tailored to manage and communicate with ISH client 46 - applications implemented in the firmware. 47 - 48 - The ISH allows multiple sensor management applications executing in the 49 - firmware. Like USB endpoints the messaging can be to/from a client. As part of 50 - enumeration process, these clients are identified. These clients can be simple 51 - HID sensor applications, sensor calibration application or senor firmware 52 - update application. 53 - 54 - The implementation model is similar, like USB bus, ISH transport is also 55 - implemented as a bus. Each client application executing in the ISH processor 56 - is registered as a device on this bus. The driver, which binds each device 57 - (ISH HID driver) identifies the device type and registers with the hid core. 58 - 59 - 2. ISH Implementation: Block Diagram 60 - 61 - --------------------------- 62 - | User Space Applications | 63 - --------------------------- 64 - 65 - ----------------IIO ABI---------------- 66 - -------------------------- 67 - | IIO Sensor Drivers | 68 - -------------------------- 69 - -------------------------- 70 - | IIO core | 71 - -------------------------- 72 - -------------------------- 73 - | HID Sensor Hub MFD | 74 - -------------------------- 75 - -------------------------- 76 - | HID Core | 77 - -------------------------- 78 - -------------------------- 79 - | HID over ISH Client | 80 - -------------------------- 81 - -------------------------- 82 - | ISH Transport (ISHTP) | 83 - -------------------------- 84 - -------------------------- 85 - | IPC Drivers | 86 - -------------------------- 87 - OS 88 - ---------------- PCI ----------------- 89 - Hardware + Firmware 90 - ---------------------------- 91 - | ISH Hardware/Firmware(FW) | 92 - ---------------------------- 93 - 94 - 3. High level processing in above blocks 95 - 96 - 3.1 Hardware Interface 97 - 98 - The ISH is exposed as "Non-VGA unclassified PCI device" to the host. The PCI 99 - product and vendor IDs are changed from different generations of processors. So 100 - the source code which enumerate drivers needs to update from generation to 101 - generation. 102 - 103 - 3.2 Inter Processor Communication (IPC) driver 104 - Location: drivers/hid/intel-ish-hid/ipc 105 - 106 - The IPC message used memory mapped I/O. The registers are defined in 107 - hw-ish-regs.h. 108 - 109 - 3.2.1 IPC/FW message types 110 - 111 - There are two types of messages, one for management of link and other messages 112 - are to and from transport layers. 113 - 114 - TX and RX of Transport messages 115 - 116 - A set of memory mapped register offers support of multi byte messages TX and 117 - RX (E.g.IPC_REG_ISH2HOST_MSG, IPC_REG_HOST2ISH_MSG). The IPC layer maintains 118 - internal queues to sequence messages and send them in order to the FW. 119 - Optionally the caller can register handler to get notification of completion. 120 - A door bell mechanism is used in messaging to trigger processing in host and 121 - client firmware side. When ISH interrupt handler is called, the ISH2HOST 122 - doorbell register is used by host drivers to determine that the interrupt 123 - is for ISH. 124 - 125 - Each side has 32 32-bit message registers and a 32-bit doorbell. Doorbell 126 - register has the following format: 127 - Bits 0..6: fragment length (7 bits are used) 128 - Bits 10..13: encapsulated protocol 129 - Bits 16..19: management command (for IPC management protocol) 130 - Bit 31: doorbell trigger (signal H/W interrupt to the other side) 131 - Other bits are reserved, should be 0. 132 - 133 - 3.2.2 Transport layer interface 134 - 135 - To abstract HW level IPC communication, a set of callbacks are registered. 136 - The transport layer uses them to send and receive messages. 137 - Refer to struct ishtp_hw_ops for callbacks. 138 - 139 - 3.3 ISH Transport layer 140 - Location: drivers/hid/intel-ish-hid/ishtp/ 141 - 142 - 3.3.1 A Generic Transport Layer 143 - 144 - The transport layer is a bi-directional protocol, which defines: 145 - - Set of commands to start, stop, connect, disconnect and flow control 146 - (ishtp/hbm.h) for details 147 - - A flow control mechanism to avoid buffer overflows 148 - 149 - This protocol resembles bus messages described in the following document: 150 - http://www.intel.com/content/dam/www/public/us/en/documents/technical-\ 151 - specifications/dcmi-hi-1-0-spec.pdf "Chapter 7: Bus Message Layer" 152 - 153 - 3.3.2 Connection and Flow Control Mechanism 154 - 155 - Each FW client and a protocol is identified by an UUID. In order to communicate 156 - to a FW client, a connection must be established using connect request and 157 - response bus messages. If successful, a pair (host_client_id and fw_client_id) 158 - will identify the connection. 159 - 160 - Once connection is established, peers send each other flow control bus messages 161 - independently. Every peer may send a message only if it has received a 162 - flow-control credit before. Once it sent a message, it may not send another one 163 - before receiving the next flow control credit. 164 - Either side can send disconnect request bus message to end communication. Also 165 - the link will be dropped if major FW reset occurs. 166 - 167 - 3.3.3 Peer to Peer data transfer 168 - 169 - Peer to Peer data transfer can happen with or without using DMA. Depending on 170 - the sensor bandwidth requirement DMA can be enabled by using module parameter 171 - ishtp_use_dma under intel_ishtp. 172 - 173 - Each side (host and FW) manages its DMA transfer memory independently. When an 174 - ISHTP client from either host or FW side wants to send something, it decides 175 - whether to send over IPC or over DMA; for each transfer the decision is 176 - independent. The sending side sends DMA_XFER message when the message is in 177 - the respective host buffer (TX when host client sends, RX when FW client 178 - sends). The recipient of DMA message responds with DMA_XFER_ACK, indicating 179 - the sender that the memory region for that message may be reused. 180 - 181 - DMA initialization is started with host sending DMA_ALLOC_NOTIFY bus message 182 - (that includes RX buffer) and FW responds with DMA_ALLOC_NOTIFY_ACK. 183 - Additionally to DMA address communication, this sequence checks capabilities: 184 - if thw host doesn't support DMA, then it won't send DMA allocation, so FW can't 185 - send DMA; if FW doesn't support DMA then it won't respond with 186 - DMA_ALLOC_NOTIFY_ACK, in which case host will not use DMA transfers. 187 - Here ISH acts as busmaster DMA controller. Hence when host sends DMA_XFER, 188 - it's request to do host->ISH DMA transfer; when FW sends DMA_XFER, it means 189 - that it already did DMA and the message resides at host. Thus, DMA_XFER 190 - and DMA_XFER_ACK act as ownership indicators. 191 - 192 - At initial state all outgoing memory belongs to the sender (TX to host, RX to 193 - FW), DMA_XFER transfers ownership on the region that contains ISHTP message to 194 - the receiving side, DMA_XFER_ACK returns ownership to the sender. A sender 195 - needs not wait for previous DMA_XFER to be ack'ed, and may send another message 196 - as long as remaining continuous memory in its ownership is enough. 197 - In principle, multiple DMA_XFER and DMA_XFER_ACK messages may be sent at once 198 - (up to IPC MTU), thus allowing for interrupt throttling. 199 - Currently, ISH FW decides to send over DMA if ISHTP message is more than 3 IPC 200 - fragments and via IPC otherwise. 201 - 202 - 3.3.4 Ring Buffers 203 - 204 - When a client initiate a connection, a ring or RX and TX buffers are allocated. 205 - The size of ring can be specified by the client. HID client set 16 and 32 for 206 - TX and RX buffers respectively. On send request from client, the data to be 207 - sent is copied to one of the send ring buffer and scheduled to be sent using 208 - bus message protocol. These buffers are required because the FW may have not 209 - have processed the last message and may not have enough flow control credits 210 - to send. Same thing holds true on receive side and flow control is required. 211 - 212 - 3.3.5 Host Enumeration 213 - 214 - The host enumeration bus command allow discovery of clients present in the FW. 215 - There can be multiple sensor clients and clients for calibration function. 216 - 217 - To ease in implantation and allow independent driver handle each client 218 - this transport layer takes advantage of Linux Bus driver model. Each 219 - client is registered as device on the the transport bus (ishtp bus). 220 - 221 - Enumeration sequence of messages: 222 - - Host sends HOST_START_REQ_CMD, indicating that host ISHTP layer is up. 223 - - FW responds with HOST_START_RES_CMD 224 - - Host sends HOST_ENUM_REQ_CMD (enumerate FW clients) 225 - - FW responds with HOST_ENUM_RES_CMD that includes bitmap of available FW 226 - client IDs 227 - - For each FW ID found in that bitmap host sends 228 - HOST_CLIENT_PROPERTIES_REQ_CMD 229 - - FW responds with HOST_CLIENT_PROPERTIES_RES_CMD. Properties include UUID, 230 - max ISHTP message size, etc. 231 - - Once host received properties for that last discovered client, it considers 232 - ISHTP device fully functional (and allocates DMA buffers) 233 - 234 - 3.4 HID over ISH Client 235 - Location: drivers/hid/intel-ish-hid 236 - 237 - The ISHTP client driver is responsible for: 238 - - enumerate HID devices under FW ISH client 239 - - Get Report descriptor 240 - - Register with HID core as a LL driver 241 - - Process Get/Set feature request 242 - - Get input reports 243 - 244 - 3.5 HID Sensor Hub MFD and IIO sensor drivers 245 - 246 - The functionality in these drivers is the same as an external sensor hub. 247 - Refer to 248 - Documentation/hid/hid-sensor.txt for HID sensor 249 - Documentation/ABI/testing/sysfs-bus-iio for IIO ABIs to user space 250 - 251 - 3.6 End to End HID transport Sequence Diagram 252 - 253 - HID-ISH-CLN ISHTP IPC HW 254 - | | | | 255 - | | |-----WAKE UP------------------>| 256 - | | | | 257 - | | |-----HOST READY--------------->| 258 - | | | | 259 - | | |<----MNG_RESET_NOTIFY_ACK----- | 260 - | | | | 261 - | |<----ISHTP_START------ | | 262 - | | | | 263 - | |<-----------------HOST_START_RES_CMD-------------------| 264 - | | | | 265 - | |------------------QUERY_SUBSCRIBER-------------------->| 266 - | | | | 267 - | |------------------HOST_ENUM_REQ_CMD------------------->| 268 - | | | | 269 - | |<-----------------HOST_ENUM_RES_CMD--------------------| 270 - | | | | 271 - | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| 272 - | | | | 273 - | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| 274 - | Create new device on in ishtp bus | | 275 - | | | | 276 - | |------------------HOST_CLIENT_PROPERTIES_REQ_CMD------>| 277 - | | | | 278 - | |<-----------------HOST_CLIENT_PROPERTIES_RES_CMD-------| 279 - | Create new device on in ishtp bus | | 280 - | | | | 281 - | |--Repeat HOST_CLIENT_PROPERTIES_REQ_CMD-till last one--| 282 - | | | | 283 - probed() 284 - |----ishtp_cl_connect-->|----------------- CLIENT_CONNECT_REQ_CMD-------------->| 285 - | | | | 286 - | |<----------------CLIENT_CONNECT_RES_CMD----------------| 287 - | | | | 288 - |register event callback| | | 289 - | | | | 290 - |ishtp_cl_send( 291 - HOSTIF_DM_ENUM_DEVICES) |----------fill ishtp_msg_hdr struct write to HW----- >| 292 - | | | | 293 - | | |<-----IRQ(IPC_PROTOCOL_ISHTP---| 294 - | | | | 295 - |<--ENUM_DEVICE RSP-----| | | 296 - | | | | 297 - for each enumerated device 298 - |ishtp_cl_send( 299 - HOSTIF_GET_HID_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW--- >| 300 - | | | | 301 - ...Response 302 - | | | | 303 - for each enumerated device 304 - |ishtp_cl_send( 305 - HOSTIF_GET_REPORT_DESCRIPTOR |----------fill ishtp_msg_hdr struct write to HW- >| 306 - | | | | 307 - | | | | 308 - hid_allocate_device 309 - | | | | 310 - hid_add_device | | | 311 - | | | | 312 - 313 - 314 - 3.7 ISH Debugging 315 - 316 - To debug ISH, event tracing mechanism is used. To enable debug logs 317 - echo 1 > /sys/kernel/debug/tracing/events/intel_ish/enable 318 - cat sys/kernel/debug/tracing/trace 319 - 320 - 3.8 ISH IIO sysfs Example on Lenovo thinkpad Yoga 260 321 - 322 - root@otcpl-ThinkPad-Yoga-260:~# tree -l /sys/bus/iio/devices/ 323 - /sys/bus/iio/devices/ 324 - ├── iio:device0 -> ../../../devices/0044:8086:22D8.0001/HID-SENSOR-200073.9.auto/iio:device0 325 - │ ├── buffer 326 - │ │ ├── enable 327 - │ │ ├── length 328 - │ │ └── watermark 329 - ... 330 - │ ├── in_accel_hysteresis 331 - │ ├── in_accel_offset 332 - │ ├── in_accel_sampling_frequency 333 - │ ├── in_accel_scale 334 - │ ├── in_accel_x_raw 335 - │ ├── in_accel_y_raw 336 - │ ├── in_accel_z_raw 337 - │ ├── name 338 - │ ├── scan_elements 339 - │ │ ├── in_accel_x_en 340 - │ │ ├── in_accel_x_index 341 - │ │ ├── in_accel_x_type 342 - │ │ ├── in_accel_y_en 343 - │ │ ├── in_accel_y_index 344 - │ │ ├── in_accel_y_type 345 - │ │ ├── in_accel_z_en 346 - │ │ ├── in_accel_z_index 347 - │ │ └── in_accel_z_type 348 - ... 349 - │ │ ├── devices 350 - │ │ │ │ ├── buffer 351 - │ │ │ │ │ ├── enable 352 - │ │ │ │ │ ├── length 353 - │ │ │ │ │ └── watermark 354 - │ │ │ │ ├── dev 355 - │ │ │ │ ├── in_intensity_both_raw 356 - │ │ │ │ ├── in_intensity_hysteresis 357 - │ │ │ │ ├── in_intensity_offset 358 - │ │ │ │ ├── in_intensity_sampling_frequency 359 - │ │ │ │ ├── in_intensity_scale 360 - │ │ │ │ ├── name 361 - │ │ │ │ ├── scan_elements 362 - │ │ │ │ │ ├── in_intensity_both_en 363 - │ │ │ │ │ ├── in_intensity_both_index 364 - │ │ │ │ │ └── in_intensity_both_type 365 - │ │ │ │ ├── trigger 366 - │ │ │ │ │ └── current_trigger 367 - ... 368 - │ │ │ │ ├── buffer 369 - │ │ │ │ │ ├── enable 370 - │ │ │ │ │ ├── length 371 - │ │ │ │ │ └── watermark 372 - │ │ │ │ ├── dev 373 - │ │ │ │ ├── in_magn_hysteresis 374 - │ │ │ │ ├── in_magn_offset 375 - │ │ │ │ ├── in_magn_sampling_frequency 376 - │ │ │ │ ├── in_magn_scale 377 - │ │ │ │ ├── in_magn_x_raw 378 - │ │ │ │ ├── in_magn_y_raw 379 - │ │ │ │ ├── in_magn_z_raw 380 - │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_raw 381 - │ │ │ │ ├── in_rot_hysteresis 382 - │ │ │ │ ├── in_rot_offset 383 - │ │ │ │ ├── in_rot_sampling_frequency 384 - │ │ │ │ ├── in_rot_scale 385 - │ │ │ │ ├── name 386 - ... 387 - │ │ │ │ ├── scan_elements 388 - │ │ │ │ │ ├── in_magn_x_en 389 - │ │ │ │ │ ├── in_magn_x_index 390 - │ │ │ │ │ ├── in_magn_x_type 391 - │ │ │ │ │ ├── in_magn_y_en 392 - │ │ │ │ │ ├── in_magn_y_index 393 - │ │ │ │ │ ├── in_magn_y_type 394 - │ │ │ │ │ ├── in_magn_z_en 395 - │ │ │ │ │ ├── in_magn_z_index 396 - │ │ │ │ │ ├── in_magn_z_type 397 - │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_en 398 - │ │ │ │ │ ├── in_rot_from_north_magnetic_tilt_comp_index 399 - │ │ │ │ │ └── in_rot_from_north_magnetic_tilt_comp_type 400 - │ │ │ │ ├── trigger 401 - │ │ │ │ │ └── current_trigger 402 - ... 403 - │ │ │ │ ├── buffer 404 - │ │ │ │ │ ├── enable 405 - │ │ │ │ │ ├── length 406 - │ │ │ │ │ └── watermark 407 - │ │ │ │ ├── dev 408 - │ │ │ │ ├── in_anglvel_hysteresis 409 - │ │ │ │ ├── in_anglvel_offset 410 - │ │ │ │ ├── in_anglvel_sampling_frequency 411 - │ │ │ │ ├── in_anglvel_scale 412 - │ │ │ │ ├── in_anglvel_x_raw 413 - │ │ │ │ ├── in_anglvel_y_raw 414 - │ │ │ │ ├── in_anglvel_z_raw 415 - │ │ │ │ ├── name 416 - │ │ │ │ ├── scan_elements 417 - │ │ │ │ │ ├── in_anglvel_x_en 418 - │ │ │ │ │ ├── in_anglvel_x_index 419 - │ │ │ │ │ ├── in_anglvel_x_type 420 - │ │ │ │ │ ├── in_anglvel_y_en 421 - │ │ │ │ │ ├── in_anglvel_y_index 422 - │ │ │ │ │ ├── in_anglvel_y_type 423 - │ │ │ │ │ ├── in_anglvel_z_en 424 - │ │ │ │ │ ├── in_anglvel_z_index 425 - │ │ │ │ │ └── in_anglvel_z_type 426 - │ │ │ │ ├── trigger 427 - │ │ │ │ │ └── current_trigger 428 - ... 429 - │ │ │ │ ├── buffer 430 - │ │ │ │ │ ├── enable 431 - │ │ │ │ │ ├── length 432 - │ │ │ │ │ └── watermark 433 - │ │ │ │ ├── dev 434 - │ │ │ │ ├── in_anglvel_hysteresis 435 - │ │ │ │ ├── in_anglvel_offset 436 - │ │ │ │ ├── in_anglvel_sampling_frequency 437 - │ │ │ │ ├── in_anglvel_scale 438 - │ │ │ │ ├── in_anglvel_x_raw 439 - │ │ │ │ ├── in_anglvel_y_raw 440 - │ │ │ │ ├── in_anglvel_z_raw 441 - │ │ │ │ ├── name 442 - │ │ │ │ ├── scan_elements 443 - │ │ │ │ │ ├── in_anglvel_x_en 444 - │ │ │ │ │ ├── in_anglvel_x_index 445 - │ │ │ │ │ ├── in_anglvel_x_type 446 - │ │ │ │ │ ├── in_anglvel_y_en 447 - │ │ │ │ │ ├── in_anglvel_y_index 448 - │ │ │ │ │ ├── in_anglvel_y_type 449 - │ │ │ │ │ ├── in_anglvel_z_en 450 - │ │ │ │ │ ├── in_anglvel_z_index 451 - │ │ │ │ │ └── in_anglvel_z_type 452 - │ │ │ │ ├── trigger 453 - │ │ │ │ │ └── current_trigger 454 - ...

+26 -20

Documentation/hid/uhid.txt Documentation/hid/uhid.rst

··· 1 - UHID - User-space I/O driver support for HID subsystem 2 - ======================================================== 1 + ====================================================== 2 + UHID - User-space I/O driver support for HID subsystem 3 + ====================================================== 3 4 4 5 UHID allows user-space to implement HID transport drivers. Please see 5 6 hid-transport.txt for an introduction into HID transport drivers. This document ··· 23 22 device with the HID subsystem, then you need to open /dev/uhid once for each 24 23 device you want to register. All further communication is done by read()'ing or 25 24 write()'ing "struct uhid_event" objects. Non-blocking operations are supported 26 - by setting O_NONBLOCK. 25 + by setting O_NONBLOCK:: 27 26 28 - struct uhid_event { 27 + struct uhid_event { 29 28 __u32 type; 30 29 union { 31 30 struct uhid_create2_req create2; ··· 33 32 struct uhid_input2_req input2; 34 33 ... 35 34 } u; 36 - }; 35 + }; 37 36 38 37 The "type" field contains the ID of the event. Depending on the ID different 39 38 payloads are sent. You must not split a single event across multiple read()'s or ··· 87 86 writes are always handled immediately in a non-blocking fashion. Future requests 88 87 might make use of O_NONBLOCK, though. 89 88 90 - UHID_CREATE2: 89 + UHID_CREATE2: 91 90 This creates the internal HID device. No I/O is possible until you send this 92 91 event to the kernel. The payload is of type struct uhid_create2_req and 93 92 contains information about your device. You can start I/O now. 94 93 95 - UHID_DESTROY: 94 + UHID_DESTROY: 96 95 This destroys the internal HID device. No further I/O will be accepted. There 97 96 may still be pending messages that you can receive with read() but no further 98 97 UHID_INPUT events can be sent to the kernel. 99 98 You can create a new device by sending UHID_CREATE2 again. There is no need to 100 99 reopen the character device. 101 100 102 - UHID_INPUT2: 101 + UHID_INPUT2: 103 102 You must send UHID_CREATE2 before sending input to the kernel! This event 104 103 contains a data-payload. This is the raw data that you read from your device 105 104 on the interrupt channel. The kernel will parse the HID reports. 106 105 107 - UHID_GET_REPORT_REPLY: 106 + UHID_GET_REPORT_REPLY: 108 107 If you receive a UHID_GET_REPORT request you must answer with this request. 109 108 You must copy the "id" field from the request into the answer. Set the "err" 110 109 field to 0 if no error occurred or to EIO if an I/O error occurred. 111 110 If "err" is 0 then you should fill the buffer of the answer with the results 112 111 of the GET_REPORT request and set "size" correspondingly. 113 112 114 - UHID_SET_REPORT_REPLY: 113 + UHID_SET_REPORT_REPLY: 115 114 This is the SET_REPORT equivalent of UHID_GET_REPORT_REPLY. Unlike GET_REPORT, 116 115 SET_REPORT never returns a data buffer, therefore, it's sufficient to set the 117 116 "id" and "err" fields correctly. ··· 121 120 read() will return a queued output report. No reaction is required to any of 122 121 them but you should handle them according to your needs. 123 122 124 - UHID_START: 123 + UHID_START: 125 124 This is sent when the HID device is started. Consider this as an answer to 126 125 UHID_CREATE2. This is always the first event that is sent. Note that this 127 126 event might not be available immediately after write(UHID_CREATE2) returns. 128 127 Device drivers might required delayed setups. 129 128 This event contains a payload of type uhid_start_req. The "dev_flags" field 130 129 describes special behaviors of a device. The following flags are defined: 131 - UHID_DEV_NUMBERED_FEATURE_REPORTS: 132 - UHID_DEV_NUMBERED_OUTPUT_REPORTS: 133 - UHID_DEV_NUMBERED_INPUT_REPORTS: 130 + 131 + - UHID_DEV_NUMBERED_FEATURE_REPORTS 132 + - UHID_DEV_NUMBERED_OUTPUT_REPORTS 133 + - UHID_DEV_NUMBERED_INPUT_REPORTS 134 + 134 135 Each of these flags defines whether a given report-type uses numbered 135 136 reports. If numbered reports are used for a type, all messages from 136 137 the kernel already have the report-number as prefix. Otherwise, no ··· 140 137 For messages sent by user-space to the kernel, you must adjust the 141 138 prefixes according to these flags. 142 139 143 - UHID_STOP: 140 + UHID_STOP: 144 141 This is sent when the HID device is stopped. Consider this as an answer to 145 142 UHID_DESTROY. 143 + 146 144 If you didn't destroy your device via UHID_DESTROY, but the kernel sends an 147 145 UHID_STOP event, this should usually be ignored. It means that the kernel 148 146 reloaded/changed the device driver loaded on your HID device (or some other 149 147 maintenance actions happened). 148 + 150 149 You can usually ignored any UHID_STOP events safely. 151 150 152 - UHID_OPEN: 151 + UHID_OPEN: 153 152 This is sent when the HID device is opened. That is, the data that the HID 154 153 device provides is read by some other process. You may ignore this event but 155 154 it is useful for power-management. As long as you haven't received this event 156 155 there is actually no other process that reads your data so there is no need to 157 156 send UHID_INPUT2 events to the kernel. 158 157 159 - UHID_CLOSE: 158 + UHID_CLOSE: 160 159 This is sent when there are no more processes which read the HID data. It is 161 160 the counterpart of UHID_OPEN and you may as well ignore this event. 162 161 163 - UHID_OUTPUT: 162 + UHID_OUTPUT: 164 163 This is sent if the HID device driver wants to send raw data to the I/O 165 164 device on the interrupt channel. You should read the payload and forward it to 166 165 the device. The payload is of type "struct uhid_output_req". 167 166 This may be received even though you haven't received UHID_OPEN, yet. 168 167 169 - UHID_GET_REPORT: 168 + UHID_GET_REPORT: 170 169 This event is sent if the kernel driver wants to perform a GET_REPORT request 171 170 on the control channeld as described in the HID specs. The report-type and 172 171 report-number are available in the payload. ··· 182 177 timed out, the kernel will ignore the response silently. The "id" field is 183 178 never re-used, so conflicts cannot happen. 184 179 185 - UHID_SET_REPORT: 180 + UHID_SET_REPORT: 186 181 This is the SET_REPORT equivalent of UHID_GET_REPORT. On receipt, you shall 187 182 send a SET_REPORT request to your hid device. Once it replies, you must tell 188 183 the kernel about it via UHID_SET_REPORT_REPLY. 189 184 The same restrictions as for UHID_GET_REPORT apply. 190 185 191 186 ---------------------------------------------------- 187 + 192 188 Written 2012, David Herrmann <dh.herrmann@gmail.com>

+1 -1

Documentation/input/input.rst

··· 188 188 189 189 The monitor and speaker controls should be easy to add to the hid/input 190 190 interface, but for the UPSs and LCDs it doesn't make much sense. For this, 191 - the hiddev interface was designed. See Documentation/hid/hiddev.txt 191 + the hiddev interface was designed. See Documentation/hid/hiddev.rst 192 192 for more information about it. 193 193 194 194 The usage of the usbhid module is very simple, it takes no parameters,

+1 -1

MAINTAINERS

··· 16432 16432 L: linux-usb@vger.kernel.org 16433 16433 T: git git://git.kernel.org/pub/scm/linux/kernel/git/hid/hid.git 16434 16434 S: Maintained 16435 - F: Documentation/hid/hiddev.txt 16435 + F: Documentation/hid/hiddev.rst 16436 16436 F: drivers/hid/usbhid/ 16437 16437 16438 16438 USB INTEL XHCI ROLE MUX DRIVER

+2

drivers/hid/hid-ids.h

··· 1157 1157 #define USB_DEVICE_ID_UGEE_XPPEN_TABLET_DECO01 0x0042 1158 1158 #define USB_DEVICE_ID_UGEE_TABLET_G5 0x0074 1159 1159 #define USB_DEVICE_ID_UGEE_TABLET_EX07S 0x0071 1160 + #define USB_DEVICE_ID_UGEE_TABLET_RAINBOW_CV720 0x0055 1160 1161 1161 1162 #define USB_VENDOR_ID_UNITEC 0x227d 1162 1163 #define USB_DEVICE_ID_UNITEC_USB_TOUCH_0709 0x0709 ··· 1242 1241 #define USB_DEVICE_ID_PRIMAX_KEYBOARD 0x4e05 1243 1242 #define USB_DEVICE_ID_PRIMAX_REZEL 0x4e72 1244 1243 #define USB_DEVICE_ID_PRIMAX_PIXART_MOUSE_4D0F 0x4d0f 1244 + #define USB_DEVICE_ID_PRIMAX_PIXART_MOUSE_4D65 0x4d65 1245 1245 #define USB_DEVICE_ID_PRIMAX_PIXART_MOUSE_4E22 0x4e22 1246 1246 1247 1247

-2

drivers/hid/hid-lg.c

··· 869 869 } 870 870 871 871 static const struct hid_device_id lg_devices[] = { 872 - { HID_USB_DEVICE(USB_VENDOR_ID_LOGITECH, USB_DEVICE_ID_MX3000_RECEIVER), 873 - .driver_data = LG_RDESC | LG_WIRELESS }, 874 872 { HID_USB_DEVICE(USB_VENDOR_ID_LOGITECH, USB_DEVICE_ID_S510_RECEIVER), 875 873 .driver_data = LG_RDESC | LG_WIRELESS }, 876 874

+12 -7

drivers/hid/hid-logitech-dj.c

··· 1103 1103 1104 1104 static int logi_dj_recv_query_hidpp_devices(struct dj_receiver_dev *djrcv_dev) 1105 1105 { 1106 - const u8 template[] = {REPORT_ID_HIDPP_SHORT, 1107 - HIDPP_RECEIVER_INDEX, 1108 - HIDPP_SET_REGISTER, 1109 - HIDPP_REG_CONNECTION_STATE, 1110 - HIDPP_FAKE_DEVICE_ARRIVAL, 1111 - 0x00, 0x00}; 1106 + static const u8 template[] = { 1107 + REPORT_ID_HIDPP_SHORT, 1108 + HIDPP_RECEIVER_INDEX, 1109 + HIDPP_SET_REGISTER, 1110 + HIDPP_REG_CONNECTION_STATE, 1111 + HIDPP_FAKE_DEVICE_ARRIVAL, 1112 + 0x00, 0x00 1113 + }; 1112 1114 u8 *hidpp_report; 1113 1115 int retval; 1114 1116 ··· 1125 1123 HID_REQ_SET_REPORT); 1126 1124 1127 1125 kfree(hidpp_report); 1128 - return 0; 1126 + return retval; 1129 1127 } 1130 1128 1131 1129 static int logi_dj_recv_query_paired_devices(struct dj_receiver_dev *djrcv_dev) ··· 1836 1834 HID_USB_DEVICE(USB_VENDOR_ID_LOGITECH, 1837 1835 USB_DEVICE_ID_LOGITECH_NANO_RECEIVER_GAMING), 1838 1836 .driver_data = recvr_type_gaming_hidpp}, 1837 + { /* Logitech 27 MHz HID++ 1.0 receiver (0xc513) */ 1838 + HID_USB_DEVICE(USB_VENDOR_ID_LOGITECH, USB_DEVICE_ID_MX3000_RECEIVER), 1839 + .driver_data = recvr_type_27mhz}, 1839 1840 { /* Logitech 27 MHz HID++ 1.0 receiver (0xc517) */ 1840 1841 HID_USB_DEVICE(USB_VENDOR_ID_LOGITECH, 1841 1842 USB_DEVICE_ID_S510_RECEIVER_2),

+1 -1

drivers/hid/hid-logitech-hidpp.c

··· 2858 2858 u8 *_rdesc, unsigned int *rsize) 2859 2859 { 2860 2860 /* Note 0 terminated so we can use strnstr to search for this. */ 2861 - const char consumer_rdesc_start[] = { 2861 + static const char consumer_rdesc_start[] = { 2862 2862 0x05, 0x0C, /* USAGE_PAGE (Consumer Devices) */ 2863 2863 0x09, 0x01, /* USAGE (Consumer Control) */ 2864 2864 0xA1, 0x01, /* COLLECTION (Application) */

+1

drivers/hid/hid-quirks.c

··· 130 130 { HID_USB_DEVICE(USB_VENDOR_ID_PIXART, USB_DEVICE_ID_PIXART_USB_OPTICAL_MOUSE), HID_QUIRK_ALWAYS_POLL }, 131 131 { HID_USB_DEVICE(USB_VENDOR_ID_PRIMAX, USB_DEVICE_ID_PRIMAX_MOUSE_4D22), HID_QUIRK_ALWAYS_POLL }, 132 132 { HID_USB_DEVICE(USB_VENDOR_ID_PRIMAX, USB_DEVICE_ID_PRIMAX_PIXART_MOUSE_4D0F), HID_QUIRK_ALWAYS_POLL }, 133 + { HID_USB_DEVICE(USB_VENDOR_ID_PRIMAX, USB_DEVICE_ID_PRIMAX_PIXART_MOUSE_4D65), HID_QUIRK_ALWAYS_POLL }, 133 134 { HID_USB_DEVICE(USB_VENDOR_ID_PRIMAX, USB_DEVICE_ID_PRIMAX_PIXART_MOUSE_4E22), HID_QUIRK_ALWAYS_POLL }, 134 135 { HID_USB_DEVICE(USB_VENDOR_ID_PRODIGE, USB_DEVICE_ID_PRODIGE_CORDLESS), HID_QUIRK_NOGET }, 135 136 { HID_USB_DEVICE(USB_VENDOR_ID_QUANTA, USB_DEVICE_ID_QUANTA_OPTICAL_TOUCH_3001), HID_QUIRK_NOGET },

+2

drivers/hid/hid-uclogic-core.c

··· 390 390 { HID_USB_DEVICE(USB_VENDOR_ID_UGEE, 391 391 USB_DEVICE_ID_UGEE_TABLET_EX07S) }, 392 392 { HID_USB_DEVICE(USB_VENDOR_ID_UGEE, 393 + USB_DEVICE_ID_UGEE_TABLET_RAINBOW_CV720) }, 394 + { HID_USB_DEVICE(USB_VENDOR_ID_UGEE, 393 395 USB_DEVICE_ID_UGEE_XPPEN_TABLET_G540) }, 394 396 { HID_USB_DEVICE(USB_VENDOR_ID_UGEE, 395 397 USB_DEVICE_ID_UGEE_XPPEN_TABLET_G640) },

+2

drivers/hid/hid-uclogic-params.c

··· 1001 1001 USB_DEVICE_ID_UGEE_XPPEN_TABLET_G540): 1002 1002 case VID_PID(USB_VENDOR_ID_UGEE, 1003 1003 USB_DEVICE_ID_UGEE_XPPEN_TABLET_G640): 1004 + case VID_PID(USB_VENDOR_ID_UGEE, 1005 + USB_DEVICE_ID_UGEE_TABLET_RAINBOW_CV720): 1004 1006 /* If this is the pen interface */ 1005 1007 if (bInterfaceNumber == 1) { 1006 1008 /* Probe v1 pen parameters */

+1

drivers/hid/intel-ish-hid/ipc/pci-ish.c

··· 184 184 struct ishtp_device *ishtp_dev = pci_get_drvdata(pdev); 185 185 186 186 ishtp_bus_remove_all_clients(ishtp_dev, false); 187 + pdev->dev_flags &= ~PCI_DEV_FLAGS_NO_D3; 187 188 ish_device_disable(ishtp_dev); 188 189 } 189 190

+9 -4

drivers/hid/wacom_sys.c

··· 304 304 wacom_hid_usage_quirk(hdev, field, usage); 305 305 306 306 switch (equivalent_usage) { 307 + case WACOM_HID_WD_TOUCH_RING_SETTING: 308 + wacom->generic_has_leds = true; 309 + break; 307 310 case HID_DG_CONTACTMAX: 308 311 /* leave touch_max as is if predefined */ 309 312 if (!features->touch_max) { 310 313 /* read manually */ 311 - data = kzalloc(2, GFP_KERNEL); 314 + n = hid_report_len(field->report); 315 + data = hid_alloc_report_buf(field->report, GFP_KERNEL); 312 316 if (!data) 313 317 break; 314 318 data[0] = field->report->id; 315 319 ret = wacom_get_report(hdev, HID_FEATURE_REPORT, 316 - data, 2, WAC_CMD_RETRIES); 317 - if (ret == 2) { 318 - features->touch_max = data[1]; 320 + data, n, WAC_CMD_RETRIES); 321 + if (ret == n) { 322 + ret = hid_report_raw_event(hdev, 323 + HID_FEATURE_REPORT, data, n, 0); 319 324 } else { 320 325 features->touch_max = 16; 321 326 hid_warn(hdev, "wacom_feature_mapping: "

+117 -35

drivers/hid/wacom_wac.c

··· 1216 1216 unsigned char *data = wacom->data; 1217 1217 int i; 1218 1218 1219 - if (wacom->features.type == INTUOSP2_BT) { 1219 + if (wacom->features.type == INTUOSP2_BT || 1220 + wacom->features.type == INTUOSP2S_BT) { 1220 1221 wacom->serial[0] = get_unaligned_le64(&data[99]); 1221 1222 wacom->id[0] = get_unaligned_le16(&data[107]); 1222 1223 pen_frame_len = 14; ··· 1269 1268 input_report_abs(pen_input, ABS_X, get_unaligned_le16(&frame[1])); 1270 1269 input_report_abs(pen_input, ABS_Y, get_unaligned_le16(&frame[3])); 1271 1270 1272 - if (wacom->features.type == INTUOSP2_BT) { 1271 + if (wacom->features.type == INTUOSP2_BT || 1272 + wacom->features.type == INTUOSP2S_BT) { 1273 1273 /* Fix rotation alignment: userspace expects zero at left */ 1274 1274 int16_t rotation = 1275 1275 (int16_t)get_unaligned_le16(&frame[9]); ··· 1288 1286 get_unaligned_le16(&frame[11])); 1289 1287 } 1290 1288 } 1291 - 1292 1289 if (wacom->tool[0]) { 1293 1290 input_report_abs(pen_input, ABS_PRESSURE, get_unaligned_le16(&frame[5])); 1294 1291 if (wacom->features.type == INTUOSP2_BT) { ··· 1457 1456 } 1458 1457 1459 1458 wacom_intuos_pro2_bt_pen(wacom); 1460 - if (wacom->features.type == INTUOSP2_BT) { 1459 + if (wacom->features.type == INTUOSP2_BT || 1460 + wacom->features.type == INTUOSP2S_BT) { 1461 1461 wacom_intuos_pro2_bt_touch(wacom); 1462 1462 wacom_intuos_pro2_bt_pad(wacom); 1463 1463 wacom_intuos_pro2_bt_battery(wacom); ··· 1770 1768 int subpage = (usage & 0xFF00) << 8; 1771 1769 int subusage = (usage & 0xFF); 1772 1770 1771 + if (usage == WACOM_HID_WT_REPORT_VALID) 1772 + return usage; 1773 + 1773 1774 if (subpage == HID_UP_UNDEFINED) 1774 1775 subpage = WACOM_HID_SP_DIGITIZER; 1775 1776 ··· 1931 1926 features->device_type |= WACOM_DEVICETYPE_PAD; 1932 1927 break; 1933 1928 case WACOM_HID_WD_BUTTONCENTER: 1934 - wacom->generic_has_leds = true; 1935 - /* fall through */ 1936 1929 case WACOM_HID_WD_BUTTONHOME: 1937 1930 case WACOM_HID_WD_BUTTONUP: 1938 1931 case WACOM_HID_WD_BUTTONDOWN: ··· 2046 2043 */ 2047 2044 if (hdev->vendor == 0x56a && 2048 2045 (hdev->product == 0x34d || hdev->product == 0x34e || /* MobileStudio Pro */ 2049 - hdev->product == 0x357 || hdev->product == 0x358)) { /* Intuos Pro 2 */ 2046 + hdev->product == 0x357 || hdev->product == 0x358 || /* Intuos Pro 2 */ 2047 + hdev->product == 0x392 || /* Intuos Pro 2 */ 2048 + hdev->product == 0x399)) { /* MobileStudio Pro */ 2050 2049 value = (field->logical_maximum - value); 2051 2050 2052 - if (hdev->product == 0x357 || hdev->product == 0x358) 2051 + if (hdev->product == 0x357 || hdev->product == 0x358 || 2052 + hdev->product == 0x392) 2053 2053 value = wacom_offset_rotation(input, usage, value, 3, 16); 2054 - else if (hdev->product == 0x34d || hdev->product == 0x34e) 2054 + else if (hdev->product == 0x34d || hdev->product == 0x34e || 2055 + hdev->product == 0x399) 2055 2056 value = wacom_offset_rotation(input, usage, value, 1, 2); 2056 2057 } 2057 2058 else { ··· 2126 2119 bool active = wacom_wac->hid_data.inrange_state != 0; 2127 2120 2128 2121 /* report prox for expresskey events */ 2129 - if ((wacom_equivalent_usage(field->physical) == HID_DG_TABLETFUNCTIONKEY) && 2130 - wacom_wac->hid_data.pad_input_event_flag) { 2122 + if (wacom_wac->hid_data.pad_input_event_flag) { 2131 2123 input_event(input, EV_ABS, ABS_MISC, active ? PAD_DEVICE_ID : 0); 2132 2124 input_sync(input); 2133 2125 if (!active) 2134 2126 wacom_wac->hid_data.pad_input_event_flag = false; 2135 2127 } 2136 - 2137 2128 } 2138 2129 2139 2130 static void wacom_wac_pen_usage_mapping(struct hid_device *hdev, ··· 2517 2512 struct wacom *wacom = hid_get_drvdata(hdev); 2518 2513 struct wacom_wac *wacom_wac = &wacom->wacom_wac; 2519 2514 unsigned equivalent_usage = wacom_equivalent_usage(usage->hid); 2515 + struct wacom_features *features = &wacom->wacom_wac.features; 2516 + 2517 + if (wacom_wac->is_invalid_bt_frame) 2518 + return; 2520 2519 2521 2520 switch (equivalent_usage) { 2522 2521 case HID_GD_X: ··· 2541 2532 case HID_DG_TIPSWITCH: 2542 2533 wacom_wac->hid_data.tipswitch = value; 2543 2534 break; 2535 + case WACOM_HID_WT_REPORT_VALID: 2536 + wacom_wac->is_invalid_bt_frame = !value; 2537 + return; 2538 + case HID_DG_CONTACTMAX: 2539 + features->touch_max = value; 2540 + return; 2544 2541 } 2545 - 2546 2542 2547 2543 if (usage->usage_index + 1 == field->report_count) { 2548 2544 if (equivalent_usage == wacom_wac->hid_data.last_slot_field) ··· 2562 2548 struct wacom_wac *wacom_wac = &wacom->wacom_wac; 2563 2549 struct hid_data* hid_data = &wacom_wac->hid_data; 2564 2550 int i; 2551 + 2552 + wacom_wac->is_invalid_bt_frame = false; 2565 2553 2566 2554 for (i = 0; i < report->maxfield; i++) { 2567 2555 struct hid_field *field = report->field[i]; ··· 2585 2569 case HID_DG_TIPSWITCH: 2586 2570 hid_data->last_slot_field = equivalent_usage; 2587 2571 break; 2588 - case HID_DG_CONTACTCOUNT: 2589 - hid_data->cc_report = report->id; 2590 - hid_data->cc_index = i; 2591 - hid_data->cc_value_index = j; 2592 - break; 2593 2572 } 2594 2573 } 2595 - } 2596 - 2597 - if (hid_data->cc_report != 0 && 2598 - hid_data->cc_index >= 0) { 2599 - struct hid_field *field = report->field[hid_data->cc_index]; 2600 - int value = field->value[hid_data->cc_value_index]; 2601 - if (value) 2602 - hid_data->num_expected = value; 2603 - } 2604 - else { 2605 - hid_data->num_expected = wacom_wac->features.touch_max; 2606 2574 } 2607 2575 } 2608 2576 ··· 2597 2597 struct wacom_wac *wacom_wac = &wacom->wacom_wac; 2598 2598 struct input_dev *input = wacom_wac->touch_input; 2599 2599 unsigned touch_max = wacom_wac->features.touch_max; 2600 + struct hid_data *hid_data = &wacom_wac->hid_data; 2600 2601 2601 2602 /* If more packets of data are expected, give us a chance to 2602 2603 * process them rather than immediately syncing a partial ··· 2611 2610 2612 2611 input_sync(input); 2613 2612 wacom_wac->hid_data.num_received = 0; 2613 + hid_data->num_expected = 0; 2614 2614 2615 2615 /* keep touch state for pen event */ 2616 2616 wacom_wac->shared->touch_down = wacom_wac_finger_count_touches(wacom_wac); ··· 2686 2684 } 2687 2685 } 2688 2686 2687 + static void wacom_set_num_expected(struct hid_device *hdev, 2688 + struct hid_report *report, 2689 + int collection_index, 2690 + struct hid_field *field, 2691 + int field_index) 2692 + { 2693 + struct wacom *wacom = hid_get_drvdata(hdev); 2694 + struct wacom_wac *wacom_wac = &wacom->wacom_wac; 2695 + struct hid_data *hid_data = &wacom_wac->hid_data; 2696 + unsigned int original_collection_level = 2697 + hdev->collection[collection_index].level; 2698 + bool end_collection = false; 2699 + int i; 2700 + 2701 + if (hid_data->num_expected) 2702 + return; 2703 + 2704 + // find the contact count value for this segment 2705 + for (i = field_index; i < report->maxfield && !end_collection; i++) { 2706 + struct hid_field *field = report->field[i]; 2707 + unsigned int field_level = 2708 + hdev->collection[field->usage[0].collection_index].level; 2709 + unsigned int j; 2710 + 2711 + if (field_level != original_collection_level) 2712 + continue; 2713 + 2714 + for (j = 0; j < field->maxusage; j++) { 2715 + struct hid_usage *usage = &field->usage[j]; 2716 + 2717 + if (usage->collection_index != collection_index) { 2718 + end_collection = true; 2719 + break; 2720 + } 2721 + if (wacom_equivalent_usage(usage->hid) == HID_DG_CONTACTCOUNT) { 2722 + hid_data->cc_report = report->id; 2723 + hid_data->cc_index = i; 2724 + hid_data->cc_value_index = j; 2725 + 2726 + if (hid_data->cc_report != 0 && 2727 + hid_data->cc_index >= 0) { 2728 + 2729 + struct hid_field *field = 2730 + report->field[hid_data->cc_index]; 2731 + int value = 2732 + field->value[hid_data->cc_value_index]; 2733 + 2734 + if (value) 2735 + hid_data->num_expected = value; 2736 + } 2737 + } 2738 + } 2739 + } 2740 + 2741 + if (hid_data->cc_report == 0 || hid_data->cc_index < 0) 2742 + hid_data->num_expected = wacom_wac->features.touch_max; 2743 + } 2744 + 2689 2745 static int wacom_wac_collection(struct hid_device *hdev, struct hid_report *report, 2690 2746 int collection_index, struct hid_field *field, 2691 2747 int field_index) 2692 2748 { 2693 2749 struct wacom *wacom = hid_get_drvdata(hdev); 2694 2750 2751 + if (WACOM_FINGER_FIELD(field)) 2752 + wacom_set_num_expected(hdev, report, collection_index, field, 2753 + field_index); 2695 2754 wacom_report_events(hdev, report, collection_index, field_index); 2696 2755 2697 2756 /* ··· 2765 2702 if (report->type != HID_INPUT_REPORT) 2766 2703 return -1; 2767 2704 2768 - if (WACOM_PAD_FIELD(field) && wacom->wacom_wac.pad_input) 2769 - wacom_wac_pad_report(hdev, report, field); 2770 - else if (WACOM_PEN_FIELD(field) && wacom->wacom_wac.pen_input) 2705 + if (WACOM_PEN_FIELD(field) && wacom->wacom_wac.pen_input) 2771 2706 wacom_wac_pen_report(hdev, report); 2772 2707 else if (WACOM_FINGER_FIELD(field) && wacom->wacom_wac.touch_input) 2773 2708 wacom_wac_finger_report(hdev, report); ··· 2779 2718 struct wacom_wac *wacom_wac = &wacom->wacom_wac; 2780 2719 struct hid_field *field; 2781 2720 bool pad_in_hid_field = false, pen_in_hid_field = false, 2782 - finger_in_hid_field = false; 2721 + finger_in_hid_field = false, true_pad = false; 2783 2722 int r; 2784 2723 int prev_collection = -1; 2785 2724 ··· 2795 2734 pen_in_hid_field = true; 2796 2735 if (WACOM_FINGER_FIELD(field)) 2797 2736 finger_in_hid_field = true; 2737 + if (wacom_equivalent_usage(field->physical) == HID_DG_TABLETFUNCTIONKEY) 2738 + true_pad = true; 2798 2739 } 2799 2740 2800 2741 wacom_wac_battery_pre_report(hdev, report); ··· 2820 2757 } 2821 2758 2822 2759 wacom_wac_battery_report(hdev, report); 2760 + 2761 + if (true_pad && wacom->wacom_wac.pad_input) 2762 + wacom_wac_pad_report(hdev, report, field); 2823 2763 } 2824 2764 2825 2765 static int wacom_bpt_touch(struct wacom_wac *wacom) ··· 3291 3225 break; 3292 3226 3293 3227 case INTUOSP2_BT: 3228 + case INTUOSP2S_BT: 3294 3229 case INTUOSHT3_BT: 3295 3230 sync = wacom_intuos_pro2_bt_irq(wacom_wac, len); 3296 3231 break; ··· 3472 3405 if (features->type == REMOTE) 3473 3406 features->device_type = WACOM_DEVICETYPE_PAD; 3474 3407 3475 - if (features->type == INTUOSP2_BT) { 3408 + if (features->type == INTUOSP2_BT || 3409 + features->type == INTUOSP2S_BT) { 3476 3410 features->device_type |= WACOM_DEVICETYPE_PEN | 3477 3411 WACOM_DEVICETYPE_PAD | 3478 3412 WACOM_DEVICETYPE_TOUCH; ··· 3654 3586 case INTUOS5S: 3655 3587 case INTUOSPS: 3656 3588 case INTUOSP2_BT: 3589 + case INTUOSP2S_BT: 3657 3590 input_set_abs_params(input_dev, ABS_DISTANCE, 0, 3658 3591 features->distance_max, 3659 3592 features->distance_fuzz, 0); ··· 3766 3697 3767 3698 switch (features->type) { 3768 3699 case INTUOSP2_BT: 3700 + case INTUOSP2S_BT: 3769 3701 input_dev->evbit[0] |= BIT_MASK(EV_SW); 3770 3702 __set_bit(SW_MUTE_DEVICE, input_dev->swbit); 3771 3703 ··· 3782 3712 input_set_abs_params(input_dev, ABS_MT_POSITION_Y, 3783 3713 0, 5920, 4, 0); 3784 3714 } 3715 + else if (wacom_wac->shared->touch->product == 0x393) { 3716 + input_set_abs_params(input_dev, ABS_MT_POSITION_X, 3717 + 0, 6400, 4, 0); 3718 + input_set_abs_params(input_dev, ABS_MT_POSITION_Y, 3719 + 0, 4000, 4, 0); 3720 + } 3785 3721 input_abs_set_res(input_dev, ABS_MT_POSITION_X, 40); 3786 - input_abs_set_res(input_dev, ABS_MT_POSITION_X, 40); 3722 + input_abs_set_res(input_dev, ABS_MT_POSITION_Y, 40); 3787 3723 3788 3724 /* fall through */ 3789 3725 ··· 4097 4021 case INTUOS5S: 4098 4022 case INTUOSPS: 4099 4023 case INTUOSP2_BT: 4024 + case INTUOSP2S_BT: 4100 4025 input_set_abs_params(input_dev, ABS_WHEEL, 0, 71, 0, 0); 4101 4026 break; 4102 4027 ··· 4675 4598 static const struct wacom_features wacom_features_0x37B = 4676 4599 { "Wacom One by Wacom M", 21600, 13500, 2047, 63, 4677 4600 BAMBOO_PEN, WACOM_INTUOS_RES, WACOM_INTUOS_RES }; 4601 + static const struct wacom_features wacom_features_0x393 = 4602 + { "Wacom Intuos Pro S", 31920, 19950, 8191, 63, 4603 + INTUOSP2S_BT, WACOM_INTUOS3_RES, WACOM_INTUOS3_RES, 7, 4604 + .touch_max = 10 }; 4678 4605 4679 4606 static const struct wacom_features wacom_features_HID_ANY_ID = 4680 4607 { "Wacom HID", .type = HID_GENERIC, .oVid = HID_ANY_ID, .oPid = HID_ANY_ID }; ··· 4851 4770 { BT_DEVICE_WACOM(0x379) }, 4852 4771 { USB_DEVICE_WACOM(0x37A) }, 4853 4772 { USB_DEVICE_WACOM(0x37B) }, 4773 + { BT_DEVICE_WACOM(0x393) }, 4854 4774 { USB_DEVICE_WACOM(0x4001) }, 4855 4775 { USB_DEVICE_WACOM(0x4004) }, 4856 4776 { USB_DEVICE_WACOM(0x5000) },

+3

drivers/hid/wacom_wac.h

··· 141 141 #define WACOM_HID_WD_OFFSETBOTTOM (WACOM_HID_UP_WACOMDIGITIZER | 0x0d33) 142 142 #define WACOM_HID_WD_DATAMODE (WACOM_HID_UP_WACOMDIGITIZER | 0x1002) 143 143 #define WACOM_HID_WD_DIGITIZERINFO (WACOM_HID_UP_WACOMDIGITIZER | 0x1013) 144 + #define WACOM_HID_WD_TOUCH_RING_SETTING (WACOM_HID_UP_WACOMDIGITIZER | 0x1032) 144 145 #define WACOM_HID_UP_G9 0xff090000 145 146 #define WACOM_HID_G9_PEN (WACOM_HID_UP_G9 | 0x02) 146 147 #define WACOM_HID_G9_TOUCHSCREEN (WACOM_HID_UP_G9 | 0x11) ··· 155 154 #define WACOM_HID_WT_SERIALNUMBER (WACOM_HID_UP_WACOMTOUCH | 0x5b) 156 155 #define WACOM_HID_WT_X (WACOM_HID_UP_WACOMTOUCH | 0x130) 157 156 #define WACOM_HID_WT_Y (WACOM_HID_UP_WACOMTOUCH | 0x131) 157 + #define WACOM_HID_WT_REPORT_VALID (WACOM_HID_UP_WACOMTOUCH | 0x1d0) 158 158 159 159 #define WACOM_BATTERY_USAGE(f) (((f)->hid == HID_DG_BATTERYSTRENGTH) || \ 160 160 ((f)->hid == WACOM_HID_WD_BATTERY_CHARGING) || \ ··· 212 210 INTUOSPM, 213 211 INTUOSPL, 214 212 INTUOSP2_BT, 213 + INTUOSP2S_BT, 215 214 INTUOSHT3_BT, 216 215 WACOM_21UX2, 217 216 WACOM_22HD,