iio-sensors.txt

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