0001 =====================
0002 HID Sensors Framework
0003 =====================
0004 HID sensor framework provides necessary interfaces to implement sensor drivers,
0005 which are connected to a sensor hub. The sensor hub is a HID device and it provides
0006 a report descriptor conforming to HID 1.12 sensor usage tables.
0007
0008 Description from the HID 1.12 "HID Sensor Usages" specification:
0009 "Standardization of HID usages for sensors would allow (but not require) sensor
0010 hardware vendors to provide a consistent Plug And Play interface at the USB boundary,
0011 thereby enabling some operating systems to incorporate common device drivers that
0012 could be reused between vendors, alleviating any need for the vendors to provide
0013 the drivers themselves."
0014
0015 This specification describes many usage IDs, which describe the type of sensor
0016 and also the individual data fields. Each sensor can have variable number of
0017 data fields. The length and order is specified in the report descriptor. For
0018 example a part of report descriptor can look like::
0019
0020 INPUT(1)[INPUT]
0021 ..
0022 Field(2)
0023 Physical(0020.0073)
0024 Usage(1)
0025 0020.045f
0026 Logical Minimum(-32767)
0027 Logical Maximum(32767)
0028 Report Size(8)
0029 Report Count(1)
0030 Report Offset(16)
0031 Flags(Variable Absolute)
0032 ..
0033 ..
0034
0035 The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
0036 This accelerometer-3D has some fields. Here for example field 2 is motion intensity
0037 (0x045f) with a logical minimum value of -32767 and logical maximum of 32767. The
0038 order of fields and length of each field is important as the input event raw
0039 data will use this format.
0040
0041
0042 Implementation
0043 ==============
0044
0045 This specification defines many different types of sensors with different sets of
0046 data fields. It is difficult to have a common input event to user space applications,
0047 for different sensors. For example an accelerometer can send X,Y and Z data, whereas
0048 an ambient light sensor can send illumination data.
0049 So the implementation has two parts:
0050
0051 - Core HID driver
0052 - Individual sensor processing part (sensor drivers)
0053
0054 Core driver
0055 -----------
0056 The core driver (hid-sensor-hub) registers as a HID driver. It parses
0057 report descriptors and identifies all the sensors present. It adds an MFD device
0058 with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
0059
0060 For example:
0061
0062 HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
0063
0064 So if any driver with this name is inserted, then the probe routine for that
0065 function will be called. So an accelerometer processing driver can register
0066 with this name and will be probed if there is an accelerometer-3D detected.
0067
0068 The core driver provides a set of APIs which can be used by the processing
0069 drivers to register and get events for that usage id. Also it provides parsing
0070 functions, which get and set each input/feature/output report.
0071
0072 Individual sensor processing part (sensor drivers)
0073 --------------------------------------------------
0074
0075 The processing driver will use an interface provided by the core driver to parse
0076 the report and get the indexes of the fields and also can get events. This driver
0077 can use IIO interface to use the standard ABI defined for a type of sensor.
0078
0079
0080 Core driver Interface
0081 =====================
0082
0083 Callback structure::
0084
0085 Each processing driver can use this structure to set some callbacks.
0086 int (*suspend)(..): Callback when HID suspend is received
0087 int (*resume)(..): Callback when HID resume is received
0088 int (*capture_sample)(..): Capture a sample for one of its data fields
0089 int (*send_event)(..): One complete event is received which can have
0090 multiple data fields.
0091
0092 Registration functions::
0093
0094 int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
0095 u32 usage_id,
0096 struct hid_sensor_hub_callbacks *usage_callback):
0097
0098 Registers callbacks for a usage id. The callback functions are not allowed
0099 to sleep::
0100
0101
0102 int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
0103 u32 usage_id):
0104
0105 Removes callbacks for a usage id.
0106
0107
0108 Parsing function::
0109
0110 int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
0111 u8 type,
0112 u32 usage_id, u32 attr_usage_id,
0113 struct hid_sensor_hub_attribute_info *info);
0114
0115 A processing driver can look for some field of interest and check if it exists
0116 in a report descriptor. If it exists it will store necessary information
0117 so that fields can be set or get individually.
0118 These indexes avoid searching every time and getting field index to get or set.
0119
0120
0121 Set Feature report::
0122
0123 int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
0124 u32 field_index, s32 value);
0125
0126 This interface is used to set a value for a field in feature report. For example
0127 if there is a field report_interval, which is parsed by a call to
0128 sensor_hub_input_get_attribute_info before, then it can directly set that
0129 individual field::
0130
0131
0132 int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
0133 u32 field_index, s32 *value);
0134
0135 This interface is used to get a value for a field in input report. For example
0136 if there is a field report_interval, which is parsed by a call to
0137 sensor_hub_input_get_attribute_info before, then it can directly get that
0138 individual field value::
0139
0140
0141 int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
0142 u32 usage_id,
0143 u32 attr_usage_id, u32 report_id);
0144
0145 This is used to get a particular field value through input reports. For example
0146 accelerometer wants to poll X axis value, then it can call this function with
0147 the usage id of X axis. HID sensors can provide events, so this is not necessary
0148 to poll for any field. If there is some new sample, the core driver will call
0149 registered callback function to process the sample.
0150
0151
0152 ----------
0153
0154 HID Custom and generic Sensors
0155 ------------------------------
0156
0157
0158 HID Sensor specification defines two special sensor usage types. Since they
0159 don't represent a standard sensor, it is not possible to define using Linux IIO
0160 type interfaces.
0161 The purpose of these sensors is to extend the functionality or provide a
0162 way to obfuscate the data being communicated by a sensor. Without knowing the
0163 mapping between the data and its encapsulated form, it is difficult for
0164 an application/driver to determine what data is being communicated by the sensor.
0165 This allows some differentiating use cases, where vendor can provide applications.
0166 Some common use cases are debug other sensors or to provide some events like
0167 keyboard attached/detached or lid open/close.
0168
0169 To allow application to utilize these sensors, here they are exported using sysfs
0170 attribute groups, attributes and misc device interface.
0171
0172 An example of this representation on sysfs::
0173
0174 /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
0175 .
0176 │ ├── enable_sensor
0177 │ │ ├── feature-0-200316
0178 │ │ │ ├── feature-0-200316-maximum
0179 │ │ │ ├── feature-0-200316-minimum
0180 │ │ │ ├── feature-0-200316-name
0181 │ │ │ ├── feature-0-200316-size
0182 │ │ │ ├── feature-0-200316-unit-expo
0183 │ │ │ ├── feature-0-200316-units
0184 │ │ │ ├── feature-0-200316-value
0185 │ │ ├── feature-1-200201
0186 │ │ │ ├── feature-1-200201-maximum
0187 │ │ │ ├── feature-1-200201-minimum
0188 │ │ │ ├── feature-1-200201-name
0189 │ │ │ ├── feature-1-200201-size
0190 │ │ │ ├── feature-1-200201-unit-expo
0191 │ │ │ ├── feature-1-200201-units
0192 │ │ │ ├── feature-1-200201-value
0193 │ │ ├── input-0-200201
0194 │ │ │ ├── input-0-200201-maximum
0195 │ │ │ ├── input-0-200201-minimum
0196 │ │ │ ├── input-0-200201-name
0197 │ │ │ ├── input-0-200201-size
0198 │ │ │ ├── input-0-200201-unit-expo
0199 │ │ │ ├── input-0-200201-units
0200 │ │ │ ├── input-0-200201-value
0201 │ │ ├── input-1-200202
0202 │ │ │ ├── input-1-200202-maximum
0203 │ │ │ ├── input-1-200202-minimum
0204 │ │ │ ├── input-1-200202-name
0205 │ │ │ ├── input-1-200202-size
0206 │ │ │ ├── input-1-200202-unit-expo
0207 │ │ │ ├── input-1-200202-units
0208 │ │ │ ├── input-1-200202-value
0209
0210 Here there is a custom sensor with four fields: two feature and two inputs.
0211 Each field is represented by a set of attributes. All fields except the "value"
0212 are read only. The value field is a read-write field.
0213
0214 Example::
0215
0216 /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
0217 feature-0-200316-maximum:6
0218 feature-0-200316-minimum:0
0219 feature-0-200316-name:property-reporting-state
0220 feature-0-200316-size:1
0221 feature-0-200316-unit-expo:0
0222 feature-0-200316-units:25
0223 feature-0-200316-value:1
0224
0225 How to enable such sensor?
0226 ^^^^^^^^^^^^^^^^^^^^^^^^^^
0227
0228 By default sensor can be power gated. To enable sysfs attribute "enable" can be
0229 used::
0230
0231 $ echo 1 > enable_sensor
0232
0233 Once enabled and powered on, sensor can report value using HID reports.
0234 These reports are pushed using misc device interface in a FIFO order::
0235
0236 /dev$ tree | grep HID-SENSOR-2000e1.6.auto
0237 │ │ │ ├── 10:53 -> ../HID-SENSOR-2000e1.6.auto
0238 │ ├── HID-SENSOR-2000e1.6.auto
0239
0240 Each report can be of variable length preceded by a header. This header
0241 consists of a 32-bit usage id, 64-bit time stamp and 32-bit length field of raw
0242 data.
