iio-sensors.txt

   1 iio sensors HAL documentation
   2 _____________________________
   3
   4
   5 PURPOSE OF THE IIO SENSORS HAL
   6
   7 This library links the Android sensors framework to the set of Linux sensors drivers that expose a iio interface.
   8
   9 These layers are mostly documented here:
  10 https://source.android.com/devices/sensors/hal-interface.html      [basic tour of the Android sensors HAL interface]
  11 http://source.android.com/devices/halref/sensors_8h_source.html    [Android sensor details]
  12 https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-bus-iio [overview of the iio interface]
  13
  14
  15 DESIGN GOALS
  16
  17 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
  18 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
  19 to be small, simple, and have minimal CPU and memory overhead.
  20
  21
  22 FUNCTION
  23
  24 The HAL discovers the set of available sensors at startup, reports them to Android, and performs basic operations on them:
  25
  26 - enable and disable sensors
  27 - set the rate at which sensors should report events to Android
  28 - await for samples and return them to Android in the format it expects
  29
  30 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.
  31
  32
  33 SUPPORTED SENSOR TYPES
  34
  35 As of march 2015 the following sensor types are supported:
  36
  37 - accelerometer
  38 - gyroscope
  39 - magnetometer
  40 - ambient light sensor
  41 - temperature sensor
  42 - proximity sensor
  43 - step detector
  44 - step counter
  45
  46
  47 ENUMERATION
  48
  49 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
  50 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
  51 specific sensor will be used in trigger mode (interrupt driven) or in polled mode (sampling happens in response to sysfs reads).
  52
  53
  54 EVENTS and POLLING
  55
  56 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
  57 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
  58 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
  59 several sensors, and split that in "sensor reports" that we translate into the format Android expects.
  60
  61 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
  62 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
  63 then transmitted to the main poll thread through Unix pipes, whose reader end fds get added to the monitored fd set.
  64
  65
  66 TRIGGERS
  67
  68 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
  69 exposed. These are expected to fire periodically, at a programmed sampling rate, whenever the sensor driver acquires a new sample from hardware.
  70
  71 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
  72 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
  73 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
  74 frequencies (~25 Hz or less) as certain games are sensitive to the thresholding effects that motion triggers yield.
  75
  76
  77 FDs and CHANNELS
  78
  79 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
  80 a fd is open on the associated iio device. That is done even for polled sensors.
  81
  82 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
  83 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
  84 complicated synchronization issues in the data decoding code path of the HAL, that we preferred to avoid for the time being.
  85
  86
  87 TIMESTAMPS
  88
  89 Android associates timestamps to samples. These timestamps are expressed as the time elapsed since the beginning of the boot sequence.
  90
  91 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
  92 they come from the driver, and possibly from hardware.
  93
  94
  95 ORIENTATION MAPPING
  96
  97 The sensors HAL is able to interpret optional 'panel' and 'rotation' specifiers from ACPI DSDT entries for sensors. See:
  98 http://www.spinics.net/lists/linux-acpi/msg51540.html
  99
 100 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).
 101
 102
 103 UNIT CONVERSION
 104
 105 iio and Android occasionally disagree on the units to use. That is the case for:
 106 - magnetic field strength: Tesla vs Gauss
 107 - proximity
 108
 109 The HAL performs appropriate mappings.
 110
 111
 112 OPTIONAL PROPERTIES
 113
 114 We support a variety of properties. Some convey user visible information which is passed Android. Properties are expressed by sensor type, such as:
 115 ro.iio.accel.name = "Intel Accelerometer"
 116
 117 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:
 118 ro.iio.temp.bmg160.name = "BMG160 Thermometer".
 119
 120 If several properties match, the most specific form has higher priority.
 121
 122 All properties are optional. As of March 2015 the following properties are supported:
 123
 124 .name         : user visible sensor name, passed to Android
 125 .vendor       : user visible sensor manufacturer name, passed to Android
 126 .resolution   : sensor measurement resolution, in Android units, passed to Android
 127 .power        : sensor estimated power draw, in mA, presumably at 3.7V
 128 .transform    : used to switch to the units used by early ISH drivers ; deprecated
 129 .max_freq     : specifies a cap for the sensor sampling rate
 130 .min_freq     : specify a floor for the sensor sampling rate
 131 .cal_steps    : specify the maximum attempted calibration level for the magnetometer
 132 .illumincalib : specify a gain for certain ALS drivers ; passed through sysfs
 133 .order        : allows reordering channels ; used internally ; deprecated
 134 .quirks       : allows specifying various processing options ; see QUIRKS
 135 .panel        : allows expressing/superseding the _PLD panel indicator (4=front, 5=back)
 136 .rotation     : allows expressing/superseding the _PLD rotation indicator (x 45° clockwise)
 137 .scale        : scaling/sensitivity hint for the driver, stored through sysfs
 138 .opt_scale    : optional scaling applied at a late stage to channel values ; deprecated
 139 .filter       : allows selecting one of the available filters, and its strength
 140
 141
 142 QUIRKS
 143
 144 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
 145 driver idiosyncrasies. Several quirks can be specified using commas to separate them.
 146
 147 Available quirks are:
 148
 149 noisy         : engage default filter for the sensor type to smooth out noise
 150 terse         : auto-repeat events as if the trigger was a motion trigger, even though it's not advertised as such
 151 continuous    : disable use of motion trigger even if the sensor supports it
 152 init-rate     : set sampling rate at 10 Hz after enabling that sensor
 153 biased        : the sensor has unusually high bias ; engage high bias detection and compensation routines
 154 spotty        : the sensor may have gaps in its events sequence ; adjust timestamps accordingly
 155
 156
 157 FILTERING
 158
 159 Some sensor types are inherently low precision and provide data that is statistically noisy. If the noisy quirk is specified, we apply a predetermined
 160 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
 161 output. It's also possible to individually set a sensor filter selection and strength through properties.
 162
 163 ro.iio.anglvel.filter = average
 164
 165 or
 166
 167 ro.iio.anglvel.filter = average, 10
 168
 169
 170 CALIBRATION
 171
 172 Calibration is a different concept from filtering. It has a different meaning depending on the sensor type.
 173
 174
 175 UNCALIBRATED SENSORS
 176
 177 Android 4.4 (KitKat) introduced the uncalibrated gyroscope and uncalibrated magnetometer sensor types. They are virtual sensors that decouple the sensor data
 178 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.
 179
 180
 181 VIRTUAL SENSORS
 182
 183 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.
 184 The Android framework can add its own virtual sensors too. Those are typically composite (fusion) sensors, relying on several base sensors for their work.
 185 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
 186 frequency for the virtual sensor.
 187
 188
 189 SAMPLING RATE
 190
 191 Arbitration levels and iio device colocation, virtual sensors, per sensor rate, Android level arbitration, published rates.
 192
 193
 194 TRANSFORMS
 195
 196 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
 197 deleted in the future.
 198
 199
 200 SOURCE TREE
 201
 202 The most central source files are:
 203
 204 common.h       : definitions shared among all files
 205 entry.c        : iio sensors HAL entry points
 206 enumeration.c  : sensor enumeration routines
 207 control.c      : enabling, disabling, sampling rate control
 208
 209
 210 THREADS
 211
 212 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
 213 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
 214 polling thread waits on.
 215
 216
 217 BATCHING
 218
 219
 220 DRIVER DESIDERATA
 221
 222 - one iio device per sensor
 223 - interrupt driven
 224 - no jitter
 225 - sampling frequency per sensor
 226 - timestamp channel
 227 - fast stabilization time on enabling
 228
 229
 230 MISC
 231
 232 - ueventd.rc file access rights
 233 - iio-sensors-hal.so (IRDA autodetect) vs sensors.gmin.so (GMIN)
 234 - .conf files, persistency
 235 - code writing convention
 236
 237
 238 HISTORICAL PERSPECTIVE
 239 - Star Peak on XPS 12, Harris Beach, T100
 240 - GMIN MRD 7, Anchor 8
 241 - IRDA ECS, ECS 2, CHIPHD, Malata
 242 - SoFIA
 243 - ISH
 244
 245
 246 AUTO-DETECTION
 247
 248 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
 249 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
 250 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
 251 permission files, are possible. For targets that don't rely on autodetection, sensor properties are set in system init scripts.
 252
 253 The following commands may be useful (run as root):
 254
 255 halctl -l                      : lists detected devices
 256 halctl -g sensors              : identifies the selected sensors HAL library
 257 getprop | grep iio             : list sensor properties
 258 pm list features | grep sensor : list sensor features, as defined through permission files
 259 logcat | grep -i sensor        : get sensor traces
 260
 261
 262 TIPS AND TRICKS
 263
 264 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:
 265
 266 mmm
 267 adb root
 268 adb remount
 269 adb pull
 270 adb push
 271 adb reboot
 272 adb shell
 273
 274 ALOGV traces are compiled out ; you may want to redefine ALOGV in common.h in order to get them.