README

   1 # Copyright (c) 2015 Intel Corporation
   2 #
   3 # Licensed under the Apache License, Version 2.0 (the "License");
   4 # you may not use this file except in compliance with the License.
   5 # You may obtain a copy of the License at
   6 #
   7 #      http://www.apache.org/licenses/LICENSE-2.0
   8 #
   9 # Unless required by applicable law or agreed to in writing, software
  10 # distributed under the License is distributed on an "AS IS" BASIS,
  11 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12 # See the License for the specific language governing permissions and
  13 # limitations under the License.
  14
  15 iio sensors HAL documentation
  16 _____________________________
  17
  18
  19 PURPOSE OF THE IIO SENSORS HAL
  20
  21 This library links the Android sensors framework to the set of Linux sensors
  22 drivers that expose a iio interface.
  23
  24 These layers are mostly documented here:
  25 https://source.android.com/devices/sensors/hal-interface.html
  26  [basic tour of the Android sensors HAL interface]
  27
  28 http://source.android.com/devices/halref/sensors_8h_source.html
  29  [Android sensor details]
  30
  31 https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-bus-iio
  32  [overview of the iio interface]
  33
  34
  35 DESIGN GOALS
  36
  37 The iio sensors HAL is designed to drive a complete collection of sensors,
  38 whose types and properties are discovered dynamically. It should be reusable
  39 without modification across a variety of boards, avoiding creating custom
  40 HALs over and over, and allowing quick sensors enabling on new hardware
  41 platforms. It's meant to be small, simple, and have minimal CPU and memory
  42 overhead.
  43
  44
  45 FUNCTION
  46
  47 The HAL discovers the set of available sensors at startup, reports them to
  48 Android, and performs basic operations on them:
  49
  50 - enable and disable sensors
  51 - set the rate at which sensors should report events to Android
  52 - await for samples and return them to Android in the format it expects
  53
  54 This is primarily done by reading and writing sysfs files located under
  55 /sys/bus/iio, as well as interacting with /dev/iio:deviceX character devices.
  56
  57
  58 SUPPORTED SENSOR TYPES
  59
  60 As of march 2015 the following sensor types are supported:
  61
  62 - accelerometer
  63 - gyroscope
  64 - magnetometer
  65 - ambient light sensor
  66 - temperature sensor
  67 - proximity sensor
  68 - step detector
  69 - step counter
  70
  71
  72 ENUMERATION
  73
  74 Basic enumeration happens by scanning /sys/bus/iio/devices. We search each of
  75 the device subfolders for sysfs entries that we can associate to known sensor
  76 types. Each of the iio devices can possibly support several sensors.
  77 Of particular interest is the scan_elements subfolder, which we use to
  78 determine if a specific sensor will be used in trigger mode (interrupt driven)
  79 or in polled mode (sampling happens in response to sysfs reads).
  80
  81
  82 EVENTS and POLLING
  83
  84 The preferred way to retrieve data from a sensor is though the associated iio
  85 character device. That implies that the sensor can report events whenever new
  86 samples become available. The iio sensor HAL opens a fd on each of the
  87 /dev/iio:deviceX files associated to enabled sensors, and add these fds to a
  88 fd set monitored by a single poll call, which blocks the HAL's main sensor data
  89 polling function. From there we read "device reports" that can possibly hold
  90 data for several sensors, and split that in "sensor reports" that we translate
  91 into the format Android expects.
  92
  93 Another mode of operation is polling mode. It is engaged if no scan_elements
  94 folder is found, or if no iio channels are detected for the sensor. In that
  95 case we start a dedicated data acquisition thread for the sensor, which will
  96 periodically read sysfs entries (either _raw or _input) to get sensor data.
  97 This data is then transmitted to the main poll thread through Unix pipes,
  98 whose reader end fds get added to the monitored fd set.
  99
 100
 101 TRIGGERS
 102
 103 Triggers are the iio way of selecting when a iio driver should alert userspace
 104 that there is new data available. At least one "data ready" trigger needs to be
 105 exposed. These are expected to fire periodically, at a programmed sampling
 106 rate, whenever the sensor driver acquires a new sample from hardware.
 107
 108 Another type of trigger we support is motion based ; if a motion trigger is
 109 selected, the driver will avoid sending duplicate samples to userspace. In
 110 practice, the sensors HAL only gets data when there the device position
 111 changes. The iio sensor HAL has an internal "repeat last sample" logic for
 112 sensor types from which Android expects to get data periodically, unbeknown
 113 that layers below are only sending data on motion. We selected to engage this
 114 mode only for low frequencies (~25 Hz or less) as certain games are sensitive
 115 to the thresholding effects that motion triggers yield.
 116
 117
 118 FDs and CHANNELS
 119
 120 The iio sensors HAL always open a fd on the iio device associated to an
 121 enabled sensor. The assumption there is that the hardware should be powered
 122 off unless a fd is open on the associated iio device. That is done even for
 123 polled sensors.
 124
 125 If the iio device supports several sensors types we can handle, all recognized
 126 channels get enabled at startup, and remain so. Although the iio interface
 127 supports dynamic enabling and disabling of individual channels, doing so
 128 changes the size of the "device reports" we read from the iio device fds, and
 129 creates complicated synchronization issues in the data decoding code path of
 130 the HAL, that we preferred to avoid for the time being.
 131
 132
 133 TIMESTAMPS
 134
 135 Android associates timestamps to samples. These timestamps are expressed as
 136 the time elapsed since the beginning of the boot sequence.
 137
 138 If possible, we read the iio timestamps from the timestamp channel, alongside
 139 sample data ; these are closely correlated to the actual data acquisition time,
 140 as they come from the driver, and possibly from hardware.
 141
 142
 143 ORIENTATION MAPPING
 144
 145 The sensors HAL is able to interpret optional 'panel' and 'rotation' specifiers
 146 from ACPI DSDT entries for sensors. See:
 147 http://www.spinics.net/lists/linux-acpi/msg51540.html
 148
 149 It is possible to supersede these values using the .panel and .rotation
 150 properties (both need to be specified, and they are read only once at boot
 151 time).
 152
 153
 154 UNIT CONVERSION
 155
 156 IIO and Android occasionally disagree on the units to use.
 157 That is the case for:
 158 - magnetic field strength: Tesla vs Gauss
 159 - proximity
 160
 161 The HAL performs appropriate mappings.
 162
 163
 164 OPTIONAL PROPERTIES
 165
 166 We support a variety of properties. Some convey user visible information which
 167 is passed Android. Properties are expressed by sensor type, such as:
 168 ro.iio.accel.name = "Intel Accelerometer"
 169
 170 On certain boards we may have several sensors of the same type. It's then
 171 possible to specialize the name using the iio sysfs 'name' contents:
 172 ro.iio.temp.bmg160.name = "BMG160 Thermometer".
 173
 174 If several properties match, the most specific form has higher priority.
 175
 176 All properties are optional. As of March 2015 the following properties are
 177 supported:
 178
 179 .name         : user visible sensor name, passed to Android
 180 .vendor       : user visible sensor manufacturer name, passed to Android
 181 .resolution   : sensor measurement resolution, in Android units, passed to
 182                 Android
 183 .power        : sensor estimated power draw, in mA, presumably at 3.7V
 184 .transform    : used to switch to the units used by early ISH drivers;
 185                 deprecated
 186 .max_freq     : specifies a cap for the sensor sampling rate
 187 .min_freq     : specify a floor for the sensor sampling rate
 188 .cal_steps    : specify the maximum attempted calibration level for the
 189                 magnetometer
 190 .illumincalib : specify a gain for certain ALS drivers ; passed through sysfs
 191 .order        : allows reordering channels ; used internally ; deprecated
 192 .quirks       : allows specifying various processing options ; see QUIRKS
 193 .panel        : allows expressing/superseding the _PLD panel indicator
 194                 (4=front, 5=back)
 195 .rotation     : allows expressing/superseding the _PLD rotation indicator
 196                 (x 45° clockwise)
 197 .scale        : scaling/sensitivity hint for the driver, stored through sysfs
 198 .opt_scale    : optional scaling applied at a late stage to channel values;
 199                 deprecated
 200 .filter       : allows selecting one of the available filters, and its strength
 201
 202
 203 QUIRKS
 204
 205 One of the properties we use allows influencing how a specific sensor is used.
 206 It's the 'quirks' property, and allows the HAL to compensate for hardware or
 207 driver idiosyncrasies. Several quirks can be specified using commas to separate
 208 them.
 209
 210 Available quirks are:
 211
 212 noisy         : engage default filter for the sensor type to smooth out noise
 213 terse         : auto-repeat events as if the trigger was a motion trigger,
 214                 even though it's not advertised as such
 215 continuous    : disable use of motion trigger even if the sensor supports it
 216 init-rate     : set sampling rate at 10 Hz after enabling that sensor
 217 biased        : the sensor has unusually high bias ; engage high bias detection
 218                 and compensation routines
 219 spotty        : the sensor may have gaps in its events sequence; adjust
 220                 timestamps accordingly
 221 no-poll       : specifically disable the iio polling (sysfs) way of getting
 222                 data from this driver, even if it's seemingly available
 223 no-trig       : specifically disable the iio trigger way of getting data from
 224                 this driver, even if it's seemingly available
 225 no-event      : specifically disable the iio event way of getting data from
 226                 this driver, even if it's seemingly available
 227
 228
 229 FILTERING
 230
 231 Some sensor types are inherently low precision and provide data that is
 232 statistically noisy. If the noisy quirk is specified, we apply a predetermined
 233 filtering strategy depending on the sensor type, to smooth out the noise in
 234 samples before they are passed to Android. That can add latency in the sensor
 235 output. It's also possible to individually set a sensor filter selection and
 236 strength through properties.
 237
 238 ro.iio.anglvel.filter = average
 239
 240 or
 241
 242 ro.iio.anglvel.filter = average, 10
 243
 244
 245 CALIBRATION
 246
 247 Calibration is a different concept from filtering. It has a different meaning
 248 depending on the sensor type.
 249
 250
 251 UNCALIBRATED SENSORS
 252
 253 Android 4.4 (KitKat) introduced the uncalibrated gyroscope and uncalibrated
 254 magnetometer sensor types. They are virtual sensors that decouple the sensor
 255 data from the correction that is applied to it by the HAL, so upper layers can
 256 choose to alter or ignore the correction that got applied at the HAL level.
 257
 258
 259 VIRTUAL SENSORS
 260
 261 The HAL can expose logical sensors, such as the uncalibrated gyroscope, in
 262 addition to the set of iio sensors. These are built on top of base sensors.
 263 The Android framework can add its own virtual sensors too. Those are typically
 264 composite (fusion) sensors, relying on several base sensors for their work.
 265 The current Android code for this, as of Android 5.0, sets the gyroscope at
 266 200 Hz, the magnetometer at 50 Hz, and the accelerometer at the target
 267 frequency for the virtual sensor.
 268
 269
 270 SAMPLING RATE
 271
 272 Arbitration levels and iio device collocation, virtual sensors, per sensor
 273 rate, Android level arbitration, published rates.
 274
 275
 276 TRANSFORMS
 277
 278 The transform property got used to support early iio drivers for the Intel
 279 Sensor Hub on Haswell machines. It should no longer be used and support for
 280 it may be deleted in the future.
 281
 282
 283 SOURCE TREE
 284
 285 The most central source files are:
 286
 287 common.h       : definitions shared among all files
 288 entry.c        : iio sensors HAL entry points
 289 enumeration.c  : sensor enumeration routines
 290 control.c      : enabling, disabling, sampling rate control
 291
 292
 293 THREADS
 294
 295 The sensors HAL code runs in the context of the calling threads (Android Sensor
 296 Service threads, from the Service Manager process). It spawns one additional
 297 thread per polling sensor in use though. This thread communicates its data to
 298 the single polling thread through a pipe, whose fd is added to the set of fds
 299 the polling thread waits on.
 300
 301
 302 BATCHING
 303
 304
 305 DRIVER DESIDERATA
 306
 307 - one iio device per sensor
 308 - interrupt driven
 309 - no jitter
 310 - sampling frequency per sensor
 311 - timestamp channel
 312 - fast stabilization time on enabling
 313
 314
 315 MISC
 316
 317 - ueventd.rc file access rights
 318 - iio-sensors-hal.so (IRDA autodetect) vs sensors.gmin.so (GMIN)
 319 - .conf files, persistency
 320 - code writing convention
 321
 322
 323 HISTORICAL PERSPECTIVE
 324 - Star Peak on XPS 12, Harris Beach, T100
 325 - GMIN MRD 7, Anchor 8
 326 - IRDA ECS, ECS 2, CHIPHD, Malata
 327 - SoFIA
 328 - ISH
 329
 330
 331 AUTO-DETECTION
 332
 333 Multi-device targets (coho/cohol) rely on the hardware auto-detection daemon
 334 (hald) to set properties for the enumerated sensors. hald listens for uevents
 335 that get sent by the kernel during system startup, and matches them against a
 336 list of known sensor parts. This list is built from the set of HAL record files
 337 located under /system/etc/hald/hrec.d. Whenever a match is found, the
 338 properties defined in the sensor's record file are set. Additional actions,
 339 such as installing permission files, are possible. For targets that don't rely
 340 on autodetection, sensor properties are set in system init scripts.
 341
 342 The following commands may be useful (run as root):
 343
 344 halctl -l                      : lists detected devices
 345 halctl -g sensors              : identifies the selected sensors HAL library
 346 getprop | grep iio             : list sensor properties
 347 pm list features | grep sensor : list sensor features, as defined through
 348                                  permission files
 349 logcat | grep -i sensor        : get sensor traces
 350
 351
 352 TIPS AND TRICKS
 353
 354 The iio sensors HAL .so file is stored on a read-only partition, under
 355 /system/lib/hw. Quick testing of code changes can be done using the following
 356 commands:
 357
 358 mmm
 359 adb root
 360 adb remount
 361 adb pull
 362 adb push
 363 adb reboot
 364 adb shell
 365
 366 ALOGV traces are compiled out ; you may want to redefine ALOGV in common.h in
 367 order to get them.