# Copyright (c) 2015 Intel Corporation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

iio sensors HAL documentation
_____________________________


PURPOSE OF THE IIO SENSORS HAL

This library links the Android sensors framework to the set of Linux sensors
drivers that expose a iio interface.

These layers are mostly documented here:
https://source.android.com/devices/sensors/hal-interface.html
 [basic tour of the Android sensors HAL interface]

http://source.android.com/devices/halref/sensors_8h_source.html
 [Android sensor details]

https://www.kernel.org/doc/Documentation/ABI/testing/sysfs-bus-iio
 [overview of the iio interface]


DESIGN GOALS

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 modification across a variety of boards, avoiding creating custom
HALs over and over, and allowing quick sensors enabling on new hardware
platforms. It's meant to be small, simple, and have minimal CPU and memory
overhead.


FUNCTION

The HAL discovers the set of available sensors at startup, reports them to
Android, and performs basic operations on them:

- enable and disable sensors
- set the rate at which sensors should report events to Android
- await for samples and return them to Android in the format it expects

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.


SUPPORTED SENSOR TYPES

As of march 2015 the following sensor types are supported:

- accelerometer
- gyroscope
- magnetometer
- ambient light sensor
- temperature sensor
- proximity sensor
- step detector
- step counter


ENUMERATION

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
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 specific sensor will be used in trigger mode (interrupt driven)
or in polled mode (sampling happens in response to sysfs reads).


EVENTS and POLLING

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
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 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 several sensors, and split that in "sensor reports" that we translate
into the format Android expects.

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 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 then transmitted to the main poll thread through Unix pipes,
whose reader end fds get added to the monitored fd set.


TRIGGERS

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
exposed. These are expected to fire periodically, at a programmed sampling
rate, whenever the sensor driver acquires a new sample from hardware.

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
practice, 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 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 frequencies (~25 Hz or less) as certain games are sensitive
to the thresholding effects that motion triggers yield.


FDs and CHANNELS

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 a fd is open on the associated iio device. That is done even for
polled sensors.

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
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 complicated synchronization issues in the data decoding code path of
the HAL, that we preferred to avoid for the time being.


TIMESTAMPS

Android associates timestamps to samples. These timestamps are expressed as
the time elapsed since the beginning of the boot sequence.

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 they come from the driver, and possibly from hardware.


ORIENTATION MAPPING

The sensors HAL is able to interpret optional 'panel' and 'rotation' specifiers
from ACPI DSDT entries for sensors. See:
http://www.spinics.net/lists/linux-acpi/msg51540.html

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).


UNIT CONVERSION

IIO and Android occasionally disagree on the units to use.
That is the case for:
- magnetic field strength: Tesla vs Gauss
- proximity

The HAL performs appropriate mappings.


OPTIONAL PROPERTIES

We support a variety of properties. Some convey user visible information which
is passed Android. Properties are expressed by sensor type, such as:
ro.iio.accel.name = "Intel Accelerometer"

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:
ro.iio.temp.bmg160.name = "BMG160 Thermometer".

If several properties match, the most specific form has higher priority.

All properties are optional. As of March 2015 the following properties are
supported:

.name         : user visible sensor name, passed to Android
.vendor       : user visible sensor manufacturer name, passed to Android
.resolution   : sensor measurement resolution, in Android units, passed to
                Android
.power        : sensor estimated power draw, in mA, presumably at 3.7V
.transform    : used to switch to the units used by early ISH drivers;
                deprecated
.max_freq     : specifies a cap for the sensor sampling rate
.min_freq     : specify a floor for the sensor sampling rate
.cal_steps    : specify the maximum attempted calibration level for the
                magnetometer
.illumincalib : specify a gain for certain ALS drivers ; passed through sysfs
.order        : allows reordering channels ; used internally ; deprecated
.quirks       : allows specifying various processing options ; see QUIRKS
.panel        : allows expressing/superseding the _PLD panel indicator
                (4=front, 5=back)
.rotation     : allows expressing/superseding the _PLD rotation indicator
                (x 45° clockwise)
.scale        : scaling/sensitivity hint for the driver, stored through sysfs
.opt_scale    : optional scaling applied at a late stage to channel values;
                deprecated
.filter       : allows selecting one of the available filters, and its strength


QUIRKS

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
driver idiosyncrasies. Several quirks can be specified using commas to separate
them.

Available quirks are:

noisy         : engage default filter for the sensor type to smooth out noise
terse         : auto-repeat events as if the trigger was a motion trigger,
                even though it's not advertised as such
continuous    : disable use of motion trigger even if the sensor supports it
init-rate     : set sampling rate at 10 Hz after enabling that sensor
biased        : the sensor has unusually high bias ; engage high bias detection
                and compensation routines
spotty        : the sensor may have gaps in its events sequence; adjust
                timestamps accordingly
no-poll       : specifically disable the iio polling (sysfs) way of getting
                data from this driver, even if it's seemingly available
no-trig       : specifically disable the iio trigger way of getting data from
                this driver, even if it's seemingly available
no-event      : specifically disable the iio event way of getting data from
                this driver, even if it's seemingly available
binarize      : set the proximity sensor to only return near (0) and far (5)


FILTERING

Some sensor types are inherently low precision and provide data that is
statistically noisy. If the noisy quirk is specified, we apply a predetermined
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
output. It's also possible to individually set a sensor filter selection and
strength through properties.

ro.iio.anglvel.filter = average

or

ro.iio.anglvel.filter = average, 10


CALIBRATION

Calibration is a different concept from filtering. It has a different meaning
depending on the sensor type.


UNCALIBRATED SENSORS

Android 4.4 (KitKat) introduced the uncalibrated gyroscope and uncalibrated
magnetometer sensor types. They are virtual sensors that decouple the sensor
data 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.


VIRTUAL SENSORS

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.
The Android framework can add its own virtual sensors too. Those are typically
composite (fusion) sensors, relying on several base sensors for their work.
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
frequency for the virtual sensor.


SAMPLING RATE

Arbitration levels and iio device collocation, virtual sensors, per sensor
rate, Android level arbitration, published rates.


TRANSFORMS

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 deleted in the future.


SOURCE TREE

The most central source files are:

common.h       : definitions shared among all files
entry.c        : iio sensors HAL entry points
enumeration.c  : sensor enumeration routines
control.c      : enabling, disabling, sampling rate control


THREADS

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
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 polling thread waits on.


BATCHING


DRIVER DESIDERATA

- one iio device per sensor
- interrupt driven
- no jitter
- sampling frequency per sensor
- timestamp channel
- fast stabilization time on enabling


MISC

- ueventd.rc file access rights
- iio-sensors-hal.so (IRDA autodetect) vs sensors.gmin.so (GMIN)
- .conf files, persistency
- code writing convention


HISTORICAL PERSPECTIVE
- Star Peak on XPS 12, Harris Beach, T100
- GMIN MRD 7, Anchor 8
- IRDA ECS, ECS 2, CHIPHD, Malata
- SoFIA
- ISH


AUTO-DETECTION

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 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 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 permission files, are possible. For targets that don't rely
on autodetection, sensor properties are set in system init scripts.

The following commands may be useful (run as root):

halctl -l                      : lists detected devices
halctl -g sensors              : identifies the selected sensors HAL library
getprop | grep iio             : list sensor properties
pm list features | grep sensor : list sensor features, as defined through
                                 permission files
logcat | grep -i sensor        : get sensor traces


TIPS AND TRICKS

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:

mmm
adb root
adb remount
adb pull
adb push
adb reboot
adb shell

ALOGV traces are compiled out ; you may want to redefine ALOGV in common.h in
order to get them.