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 no-poll       : specifically disable the iio polling (sysfs) way of getting data from this driver, even if it's seemingly available
 156 no-trig       : specifically disable the iio trigger way of getting data from this driver, even if it's seemingly available
 157 no-event      : specifically disable the iio event way of getting data from this driver, even if it's seemingly available
 158
 159
 160 FILTERING
 161
 162 Some sensor types are inherently low precision and provide data that is statistically noisy. If the noisy quirk is specified, we apply a predetermined
 163 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
 164 output. It's also possible to individually set a sensor filter selection and strength through properties.
 165
 166 ro.iio.anglvel.filter = average
 167
 168 or
 169
 170 ro.iio.anglvel.filter = average, 10
 171
 172
 173 CALIBRATION
 174
 175 Calibration is a different concept from filtering. It has a different meaning depending on the sensor type.
 176
 177
 178 UNCALIBRATED SENSORS
 179
 180 Android 4.4 (KitKat) introduced the uncalibrated gyroscope and uncalibrated magnetometer sensor types. They are virtual sensors that decouple the sensor data
 181 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.
 182
 183
 184 VIRTUAL SENSORS
 185
 186 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.
 187 The Android framework can add its own virtual sensors too. Those are typically composite (fusion) sensors, relying on several base sensors for their work.
 188 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
 189 frequency for the virtual sensor.
 190
 191
 192 SAMPLING RATE
 193
 194 Arbitration levels and iio device colocation, virtual sensors, per sensor rate, Android level arbitration, published rates.
 195
 196
 197 TRANSFORMS
 198
 199 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
 200 deleted in the future.
 201
 202
 203 SOURCE TREE
 204
 205 The most central source files are:
 206
 207 common.h       : definitions shared among all files
 208 entry.c        : iio sensors HAL entry points
 209 enumeration.c  : sensor enumeration routines
 210 control.c      : enabling, disabling, sampling rate control
 211
 212
 213 THREADS
 214
 215 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
 216 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
 217 polling thread waits on.
 218
 219
 220 BATCHING
 221
 222
 223 DRIVER DESIDERATA
 224
 225 - one iio device per sensor
 226 - interrupt driven
 227 - no jitter
 228 - sampling frequency per sensor
 229 - timestamp channel
 230 - fast stabilization time on enabling
 231
 232
 233 MISC
 234
 235 - ueventd.rc file access rights
 236 - iio-sensors-hal.so (IRDA autodetect) vs sensors.gmin.so (GMIN)
 237 - .conf files, persistency
 238 - code writing convention
 239
 240
 241 HISTORICAL PERSPECTIVE
 242 - Star Peak on XPS 12, Harris Beach, T100
 243 - GMIN MRD 7, Anchor 8
 244 - IRDA ECS, ECS 2, CHIPHD, Malata
 245 - SoFIA
 246 - ISH
 247
 248
 249 AUTO-DETECTION
 250
 251 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
 252 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
 253 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
 254 permission files, are possible. For targets that don't rely on autodetection, sensor properties are set in system init scripts.
 255
 256 The following commands may be useful (run as root):
 257
 258 halctl -l                      : lists detected devices
 259 halctl -g sensors              : identifies the selected sensors HAL library
 260 getprop | grep iio             : list sensor properties
 261 pm list features | grep sensor : list sensor features, as defined through permission files
 262 logcat | grep -i sensor        : get sensor traces
 263
 264
 265 TIPS AND TRICKS
 266
 267 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:
 268
 269 mmm
 270 adb root
 271 adb remount
 272 adb pull
 273 adb push
 274 adb reboot
 275 adb shell
 276
 277 ALOGV traces are compiled out ; you may want to redefine ALOGV in common.h in order to get them.