Documentation/hid/hid-sensor.txt

   1
   2 HID Sensors Framework
   3 ======================
   4 HID sensor framework provides necessary interfaces to implement sensor drivers,
   5 which are connected to a sensor hub. The sensor hub is a HID device and it provides
   6 a report descriptor conforming to HID 1.12 sensor usage tables.
   7
   8 Description from the HID 1.12 "HID Sensor Usages" specification:
   9 "Standardization of HID usages for sensors would allow (but not require) sensor
  10 hardware vendors to provide a consistent Plug And Play interface at the USB boundary,
  11 thereby enabling some operating systems to incorporate common device drivers that
  12 could be reused between vendors, alleviating any need for the vendors to provide
  13 the drivers themselves."
  14
  15 This specification describes many usage IDs, which describe the type of sensor
  16 and also the individual data fields. Each sensor can have variable number of
  17 data fields. The length and order is specified in the report descriptor. For
  18 example a part of report descriptor can look like:
  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 ..
  34
  35 The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73).
  36 This accelerometer-3D has some fields. Here for example field 2 is motion intensity
  37 (0x045f) with a logical minimum value of -32767 and logical maximum of 32767. The
  38 order of fields and length of each field is important as the input event raw
  39 data will use this format.
  40
  41
  42 Implementation
  43 =================
  44
  45 This specification defines many different types of sensors with different sets of
  46 data fields. It is difficult to have a common input event to user space applications,
  47 for different sensors. For example an accelerometer can send X,Y and Z data, whereas
  48 an ambient light sensor can send illumination data.
  49 So the implementation has two parts:
  50 - Core hid driver
  51 - Individual sensor processing part (sensor drivers)
  52
  53 Core driver
  54 -----------
  55 The core driver registers (hid-sensor-hub) registers as a HID driver. It parses
  56 report descriptors and identifies all the sensors present. It adds an MFD device
  57 with name HID-SENSOR-xxxx (where xxxx is usage id from the specification).
  58 For example
  59 HID-SENSOR-200073 is registered for an Accelerometer 3D driver.
  60 So if any driver with this name is inserted, then the probe routine for that
  61 function will be called. So an accelerometer processing driver can register
  62 with this name and will be probed if there is an accelerometer-3D detected.
  63
  64 The core driver provides a set of APIs which can be used by the processing
  65 drivers to register and get events for that usage id. Also it provides parsing
  66 functions, which get and set each input/feature/output report.
  67
  68 Individual sensor processing part (sensor drivers)
  69 -----------
  70 The processing driver will use an interface provided by the core driver to parse
  71 the report and get the indexes of the fields and also can get events. This driver
  72 can use IIO interface to use the standard ABI defined for a type of sensor.
  73
  74
  75 Core driver Interface
  76 =====================
  77
  78 Callback structure:
  79 Each processing driver can use this structure to set some callbacks.
  80         int (*suspend)(..): Callback when HID suspend is received
  81         int (*resume)(..): Callback when HID resume is received
  82         int (*capture_sample)(..): Capture a sample for one of its data fields
  83         int (*send_event)(..): One complete event is received which can have
  84                                multiple data fields.
  85
  86 Registration functions:
  87 int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev,
  88                         u32 usage_id,
  89                         struct hid_sensor_hub_callbacks *usage_callback):
  90
  91 Registers callbacks for an usage id. The callback functions are not allowed
  92 to sleep.
  93
  94
  95 int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev,
  96                         u32 usage_id):
  97
  98 Removes callbacks for an usage id.
  99
 100
 101 Parsing function:
 102 int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev,
 103                         u8 type,
 104                         u32 usage_id, u32 attr_usage_id,
 105                         struct hid_sensor_hub_attribute_info *info);
 106
 107 A processing driver can look for some field of interest and check if it exists
 108 in a report descriptor. If it exists it will store necessary information
 109 so that fields can be set or get individually.
 110 These indexes avoid searching every time and getting field index to get or set.
 111
 112
 113 Set Feature report
 114 int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
 115                         u32 field_index, s32 value);
 116
 117 This interface is used to set a value for a field in feature report. For example
 118 if there is a field report_interval, which is parsed by a call to
 119 sensor_hub_input_get_attribute_info before, then it can directly set that individual
 120 field.
 121
 122
 123 int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id,
 124                         u32 field_index, s32 *value);
 125
 126 This interface is used to get a value for a field in input report. For example
 127 if there is a field report_interval, which is parsed by a call to
 128 sensor_hub_input_get_attribute_info before, then it can directly get that individual
 129 field value.
 130
 131
 132 int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev,
 133                         u32 usage_id,
 134                         u32 attr_usage_id, u32 report_id);
 135
 136 This is used to get a particular field value through input reports. For example
 137 accelerometer wants to poll X axis value, then it can call this function with
 138 the usage id of X axis. HID sensors can provide events, so this is not necessary
 139 to poll for any field. If there is some new sample, the core driver will call
 140 registered callback function to process the sample.
 141
 142
 143 ----------
 144
 145 HID Custom and generic Sensors
 146
 147 HID Sensor specification defines two special sensor usage types. Since they
 148 don't represent a standard sensor, it is not possible to define using Linux IIO
 149 type interfaces.
 150 The purpose of these sensors is to extend the functionality or provide a
 151 way to obfuscate the data being communicated by a sensor. Without knowing the
 152 mapping between the data and its encapsulated form, it is difficult for
 153 an application/driver to determine what data is being communicated by the sensor.
 154 This allows some differentiating use cases, where vendor can provide applications.
 155 Some common use cases are debug other sensors or to provide some events like
 156 keyboard attached/detached or lid open/close.
 157
 158 To allow application to utilize these sensors, here they are exported uses sysfs
 159 attribute groups, attributes and misc device interface.
 160
 161 An example of this representation on sysfs:
 162 /sys/devices/pci0000:00/INT33C2:00/i2c-0/i2c-INT33D1:00/0018:8086:09FA.0001/HID-SENSOR-2000e1.6.auto$ tree -R
 163 .
 164 ????????? enable_sensor
 165 ????????? feature-0-200316
 166 ??????? ????????? feature-0-200316-maximum
 167 ??????? ????????? feature-0-200316-minimum
 168 ??????? ????????? feature-0-200316-name
 169 ??????? ????????? feature-0-200316-size
 170 ??????? ????????? feature-0-200316-unit-expo
 171 ??????? ????????? feature-0-200316-units
 172 ??????? ????????? feature-0-200316-value
 173 ????????? feature-1-200201
 174 ??????? ????????? feature-1-200201-maximum
 175 ??????? ????????? feature-1-200201-minimum
 176 ??????? ????????? feature-1-200201-name
 177 ??????? ????????? feature-1-200201-size
 178 ??????? ????????? feature-1-200201-unit-expo
 179 ??????? ????????? feature-1-200201-units
 180 ??????? ????????? feature-1-200201-value
 181 ????????? input-0-200201
 182 ??????? ????????? input-0-200201-maximum
 183 ??????? ????????? input-0-200201-minimum
 184 ??????? ????????? input-0-200201-name
 185 ??????? ????????? input-0-200201-size
 186 ??????? ????????? input-0-200201-unit-expo
 187 ??????? ????????? input-0-200201-units
 188 ??????? ????????? input-0-200201-value
 189 ????????? input-1-200202
 190 ??????? ????????? input-1-200202-maximum
 191 ??????? ????????? input-1-200202-minimum
 192 ??????? ????????? input-1-200202-name
 193 ??????? ????????? input-1-200202-size
 194 ??????? ????????? input-1-200202-unit-expo
 195 ??????? ????????? input-1-200202-units
 196 ??????? ????????? input-1-200202-value
 197
 198 Here there is a custom sensors with four fields, two feature and two inputs.
 199 Each field is represented by a set of attributes. All fields except the "value"
 200 are read only. The value field is a RW field.
 201 Example
 202 /sys/bus/platform/devices/HID-SENSOR-2000e1.6.auto/feature-0-200316$ grep -r . *
 203 feature-0-200316-maximum:6
 204 feature-0-200316-minimum:0
 205 feature-0-200316-name:property-reporting-state
 206 feature-0-200316-size:1
 207 feature-0-200316-unit-expo:0
 208 feature-0-200316-units:25
 209 feature-0-200316-value:1
 210
 211 How to enable such sensor?
 212 By default sensor can be power gated. To enable sysfs attribute "enable" can be
 213 used.
 214 $ echo 1 > enable_sensor
 215
 216 Once enabled and powered on, sensor can report value using HID reports.
 217 These reports are pushed using misc device interface in a FIFO order.
 218 /dev$ tree | grep HID-SENSOR-2000e1.6.auto
 219 ??????? ????????? 10:53 -> ../HID-SENSOR-2000e1.6.auto
 220 ????????? HID-SENSOR-2000e1.6.auto
 221
 222 Each reports can be of variable length preceded by a header. This header
 223 consist of a 32 bit usage id, 64 bit time stamp and 32 bit length field of raw
 224 data.