Docs: Porting new sensors content to site.
Bug: 17410055
Change-Id: Ice1a842e90f1c644b1bc94727383ad7c095cc650
diff --git a/src/devices/sensors/batching.jd b/src/devices/sensors/batching.jd
index 405df88..4986f6a 100644
--- a/src/devices/sensors/batching.jd
+++ b/src/devices/sensors/batching.jd
@@ -1,8 +1,8 @@
-page.title=Batching sensor results
+page.title=Batching
@jd:body
<!--
- Copyright 2013 The Android Open Source Project
+ Copyright 2014 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
@@ -24,178 +24,196 @@
</div>
</div>
-<h2 id="Why">Why batch?</h2>
-<p>This page presents the specificities of Batch mode and the expected behaviors
- of sensors while in batch mode. Batching can enable significant power savings by
- preventing the application processor from waking up to receive each event. Instead, these
- events can be grouped and processed together.</p>
-<h2 id="batch-function">batch(int handle, int flags, int64_t period_ns, int64_t
- max_report_latency)</h2>
-<p>Enabling batch mode for a given sensor sets the delay between events.
- <code>max_report_latency</code> sets the maximum time by which events can be delayed and
- batched together before being reported to the applications. A value of zero
- disables batch mode for the given sensor. The <code>period_ns</code> parameter is equivalent
- to calling setDelay() -- this function both enables or disables the batch mode
- AND sets the event's period in nanoseconds. See setDelay() for a detailed
- explanation of the <code>period_ns</code> parameter.</p>
-<p>In non-batch mode, all sensor events must be reported as soon as they are
- detected. For example, an accelerometer activated at 50Hz will trigger
- interrupts 50 times per second.<br/>
- While in batch mode, sensor events do not need to be reported as soon as they
- are detected. They can be temporarily stored and reported in batches, as long as
- no event is delayed by more than <code>maxReportingLatency</code> nanoseconds. That is, all events
- since the previous batch are recorded and returned at once. This reduces the
- amount of interrupts sent to the SoC and allows the SoC to switch to a lower
- power mode (idle) while the sensor is capturing and batching data.</p>
-<p>setDelay() is not affected and it behaves as usual. <br/>
- <br/>
- Each event has a timestamp associated with it. The timestamp must be accurate
- and correspond to the time at which the event physically happened.</p>
-<p>Batching does not modify the behavior of poll(): batches from different sensors
- can be interleaved and split. As usual, all events from the same sensor are
- time-ordered.</p>
-<h2 id="Suspend">Behavior outside of suspend mode</h2>
-<p>These are the power modes of the application processor: on, idle, and suspend.
- The sensors behave differently in each of these modes. As you would imagine, on
- mode is when the application processor is running. Idle mode is a medium power mode
- where the application processor is powered but doesn't perform any tasks.
- Suspend is a low-power mode where the application processor is not powered. The
- power consumption of the device in this mode is usually 100 times less than in the On
- mode.</p>
-<p>When the SoC is awake (not in suspend mode), events must be reported in batches
- at least every maxReportingLatency. No event shall be dropped or lost. If internal
- hardware FIFOs fill up before the maxReportingLatency, then events are reported at that
- point to ensure no event is lost.</p>
-<h2 id="Normal">Normal behavior in suspend mode</h2>
-<p>By default, batch mode doesn't significantly change the interaction with suspend
- mode. That is, sensors must continue to allow the SoC to go into suspend mode
- and sensors must stay active to fill their internal FIFO. In this mode, when the
- FIFO fills up, it shall wrap around and behave like a circular buffer,
- overwriting older events.<br/>
- <br/>
- As soon as the SoC comes out of suspend mode, a batch is produced with as much
-as the recent history as possible, and batch operation resumes as usual.</p>
-<p>The behavior described above allows applications to record the recent history of
- a set of sensor types while keeping the SoC in suspend. It also allows the
- hardware to not have to rely on a wake-up interrupt line.</p>
-<h2 id="WAKE_UPON_FIFO_FULL">WAKE_UPON_FIFO_FULL behavior in suspend mode</h2>
-<p>There are cases, however, where an application cannot afford to lose any events,
- even when the device goes into suspend mode.</p>
-<p>For a given rate, if a sensor has the capability to store at least 10 seconds
- worth of events in its FIFO and is able to wake up the SoC, it can implement an
- optional secondary mode: the <code>WAKE_UPON_FIFO_FULL</code> mode.</p>
-<p>The caller will set the <code>SENSORS_BATCH_WAKE_UPON_FIFO_FULL</code> flag to activate this
- mode. If the sensor does not support this mode, batch() will fail when the flag
- is set.</p>
-<p>In batch mode, and only when the flag
-<code>SENSORS_BATCH_WAKE_UPON_FIFO_FULL</code> is
- set and supported, the specified sensor must be able to wake-up the SoC and be
- able to buffer at least 10 seconds worth of the requested sensor events.</p>
-<p>When running with the <code>WAKE_UPON_FIFO_FULL</code> flag set, no events can be lost. When
- the FIFO is getting full, the sensor must wake up the SoC from suspend and
- return a batch before the FIFO fills-up.</p>
-<p>Depending on the device, it might take a few milliseconds for the SoC to
- entirely come out of suspend and start flushing the FIFO. Enough head room must
- be allocated in the FIFO to allow the device to entirely come out of suspend
- without the FIFO overflowing (no events shall be lost).</p>
-<p>Implementing the <code>WAKE_UPON_FIFO_FULL</code> mode is optional. If the hardware cannot
- support this mode, or if the physical FIFO is so small that the device would
- never be allowed to go into suspend for at least 10 seconds, then this function
- <strong>must</strong> fail when the flag
-<code>SENSORS_BATCH_WAKE_UPON_FIFO_FULL</code> is set, regardless
- of the value of the maxReportingLatency parameter.</p>
-<h2 id="Implementing">Implementing batching</h2>
-<p>Batch mode, if supported, should happen at the hardware level, typically using
- hardware FIFOs. In particular, it SHALL NOT be implemented in the HAL, as this
- would be counter productive. The goal here is to save significant amounts of
- power. Batching should be implemented without the aid of the SoC, which should
- be allowed to be in suspend mode during batching.</p>
-<p>In some implementations, events from several sensors can share the same physical
- FIFO. In that case, all events in the FIFO can be sent and processed by the HAL
- as soon as one batch must be reported.</p>
+<h2 id="what_is_batching">What is batching?</h2>
+<p>“Batching” refers to storing sensor events in a hardware FIFO before reporting
+ them through the <a href="hal-interface.html">HAL</a> instead of reporting them immediately.</p>
+<p>Batching can enable significant power savings by preventing the SoC from waking
+ up to receive each event. Instead, the events can be grouped and processed
+ together. </p>
+<p>The bigger the FIFOs, the more power can be saved. Implementing batching is an
+ exercise of trading off hardware memory for reduced power consumption.</p>
+<p>Batching happens when a sensor possesses a hardware FIFO
+ (<code>sensor_t.fifoMaxEventCount > 0</code>) and we are in one of two situations:</p>
+<ul>
+ <li> <code>max_report_latency > 0</code>, meaning the sensor events for this specific sensor can
+ be delayed up to <code>max_report_latency</code> before being reported through the HAL. </li>
+ <li> or the SoC is in suspend mode and the sensor is a non-wake-up sensor, meaning
+ events must be stored while waiting for the SoC to wake up. </li>
+</ul>
+<p>See the paragraph on the <a
+ href="hal-interface.html#batch_sensor_flags_sampling_period_maximum_report_latency">HAL
+ batch function</a> for more details.</p>
+<p>The opposite of batching is the continuous operation, where events are not
+ buffered, meaning they are reported immediately. Continuous operation
+ corresponds to:</p>
+<ul>
+ <li> when <code>max_report_latency = 0</code> and the events can be delivered to the application,
+ meaning
+ <ul>
+ <li> the SoC is awake </li>
+ <li> or the sensor is a wake-up sensor </li>
+ </ul>
+ </li>
+ <li> or when the sensor doesn’t have a hardware FIFO (<code>sensor_t.fifoMaxEventCount =
+ 0</code>), in which case
+ <ul>
+ <li> the events are reported if the SoC is awake or the sensor is a wake-up sensor </li>
+ <li> the events are lost when the SoC is asleep and the sensor is not a wake-up
+ sensor </li>
+ </ul>
+ </li>
+</ul>
+<h2 id="wake-up_fifos_and_non-wake-up_fifos">Wake-up FIFOs and non-wake-up FIFOs</h2>
+<p>Sensor events from <a href="suspend-mode.html#wake-up_sensors">wake-up
+ sensors</a> must be stored into a wake-up FIFO. There can be one wake-up FIFO
+ per sensor, or, more commonly, one big shared wake-up FIFO where events from all wake-up
+ sensors are interleaved. Other options are also possible, with for example some
+ wake-up sensors having a dedicated FIFO, and the rest of the wake-up sensors
+ all sharing the same one.</p>
+<p>Similarly, sensor events from <a
+ href="suspend-mode.html#non-wake-up_sensors">non-wake-up sensors</a> must be
+ stored into a non-wake-up FIFOs, and there can be one or several
+ non-wake-up FIFOs.</p>
+<p>In all cases, wake-up sensor events and non-wake-up sensor events cannot be
+ interleaved into the same FIFO. Wake-up events go in wake-up FIFOs, and
+ non-wake-up events go in non-wake-up FIFOs.</p>
+<p>For the wake-up FIFO, the “one big shared FIFO” design provides the best power
+ benefits. For the non-wake-up FIFO, there is no preference between the “one big
+ shared FIFO” and “several small reserved FIFOs”. See <a
+ href="#fifo_allocation_priority">FIFO allocation priority</a> for suggestions
+ on how to dimension each FIFO.</p>
+<h2 id="behavior_outside_of_suspend_mode">Behavior outside of suspend mode</h2>
+<p>When the SoC is awake (not in suspend mode), the events can be stored
+ temporarily in their FIFO, as long as they are not delayed by more than
+ <code>max_report_latency</code>.</p>
+<p>As long as the SoC doesn’t enter the suspend mode, no event shall be dropped or
+ lost. If internal hardware FIFOs is getting full before <code>max_report_latency</code>
+ elapsed, then events are reported at that point to ensure that no event is
+ lost.</p>
+<p>If several sensors share the same FIFO and the <code>max_report_latency</code> of one of
+ them elapses, all events from the FIFO are reported, even if the
+ <code>max_report_latency</code> of the other sensors didn’t elapse yet. The general goal is
+ to reduce the number of times batches of events must be reported, so as soon as
+ one event must be reported, all events from all sensors can be reported.</p>
<p>For example, if the following sensors are activated:</p>
<ul>
- <li>accelerometer batched with <code>maxReportingLatency</code> = 20s</li>
- <li>gyroscope batched with <code>maxReportingLatency</code> = 5s</li>
+ <li> accelerometer batched with <code>max_report_latency</code> = 20s </li>
+ <li> gyroscope batched with <code>max_report_latency</code> = 5s </li>
</ul>
-<p>Then the accelerometer batches can be reported at the same time the gyroscope
- batches are reported (every 5 seconds).<br/>
- <br/>
- Batch mode can be enabled or disabled at any time, in particular while the
- specified sensor is already enabled; and this shall not result in the loss of
+<p>Then the accelerometer batches can be reported at the same time the gyroscope
+ batches are reported (every 5 seconds), even if the accelerometer and the
+ gyroscope do not share the same FIFO.</p>
+<h2 id="behavior_in_suspend_mode">Behavior in suspend mode</h2>
+<p>Batching is particularly beneficial when wanting to collect sensor data in the
+ background without keeping the SoC awake. Because the sensor drivers and HAL
+ implementation are not allowed to hold a wake-lock*, the SoC can enter the
+ suspend mode even while sensor data is being collected.</p>
+<p>The behavior of sensors while the SoC is suspended depends on whether the
+ sensor is a wake-up sensor. See <a
+href="suspend-mode.html#wake-up_sensors">Wake-up sensors</a> for some
+details.</p>
+<p>When a non-wake-up FIFO fills up, it must wrap around and behave like a
+ circular buffer, overwriting older events: the new events replace the old ones.
+ <code>max_report_latency</code> has no impact on non-wake-up FIFOs while in suspend mode.</p>
+<p>When a wake-up FIFO fills up, or when the <code>max_report_latency</code> of one of the
+ wake-up sensor elapsed, the hardware must wake up the SoC and report the data.</p>
+<p>In both cases (wake-up and non-wake-up), as soon as the SoC comes out of
+ suspend mode, a batch is produced with the content of all FIFOs, even if
+ <code>max_report_latency</code> of some sensors didn’t elapse yet. This minimizes the risk
+ of having to wake-up the SoC again soon if it goes back to suspend. Hence, it
+ minimizes power consumption.</p>
+<p>*One notable exception of drivers not being allowed to hold a wake lock is when
+ a wake-up sensor with <a href="report-modes.html#continuous">continuous
+ reporting mode</a> is activated with <code>max_report_latency</code> < 1
+ second. In that case, the driver can hold a wake lock because the SoC would
+ anyway not have the time to enter the suspend mode, as it would be awoken by
+ a wake-up event before reaching the suspend mode.</p>
+<h2 id="precautions_to_take_when_batching_wake-up_sensors">Precautions to take when batching wake-up sensors</h2>
+<p>Depending on the device, it might take a few milliseconds for the SoC to
+ entirely come out of suspend and start flushing the FIFO. Enough head room must
+ be allocated in the FIFO to allow the device to entirely come out of suspend
+ without the wake-up FIFO overflowing. No events shall be lost, and the
+ <code>max_report_latency</code> must be respected.</p>
+<h2 id="precautions_to_take_when_batching_non-wake-up_on-change_sensors">Precautions to take when batching non-wake-up on-change sensors</h2>
+<p>On-change sensors only generate events when the value they are measuring is
+ changing. If the measured value changes while the SoC is in suspend mode,
+ applications expect to receive an event as soon as the SoC wakes up. Because of
+ this, batching of <a href="suspend-mode.html#non-wake-up_sensors">non-wake-up</a> on-change sensor events must be performed carefully if the sensor shares its
+ FIFO with other sensors. The last event generated by each on-change sensor must
+ always be saved outside of the shared FIFO so it can never be overwritten by
+ other events. When the SoC wakes up, after all events from the FIFO have been
+ reported, the last on-change sensor event must be reported.</p>
+<p>Here is a situation we want to avoid:</p>
+<ol>
+ <li> An application registers to the non-wake-up step counter (on-change) and the
+ non-wake-up accelerometer (continuous), both sharing the same FIFO </li>
+ <li> The application receives a step counter event “step_count=1000 steps” </li>
+ <li> The SoC goes to suspend </li>
+ <li> The user walks 20 steps, causing step counter and accelerometer events to be
+ interleaved, the last step counter event being “step_count = 1020 steps” </li>
+ <li> The user doesn’t move for a long time, causing accelerometer events to continue
+ accumulating in the FIFO, eventually overwriting every step_count event in the
+ shared FIFO </li>
+ <li> SoC wakes up and all events from the FIFO are sent to the application </li>
+ <li> The application receives only accelerometer events and thinks that the user
+ didn’t walk (bad!) </li>
+</ol>
+<p>By saving the last step counter event outside of the FIFO, the HAL can report
+ this event when the SoC wakes up, even if all other step counter events were
+ overwritten by accelerometer events. This way, the application receives
+ “step_count = 1020 steps” when the SoC wakes up.</p>
+<h2 id="implementing_batching">Implementing batching</h2>
+<p>Batching cannot be emulated in software. It must be implemented entirely in
+ hardware, with hardware FIFOs. In particular, it cannot be implemented on the
+ SoC, for example in the HAL implementation, as this would be
+ counter-productive. The goal here is to save significant amounts of power.
+ Batching must be implemented without the aid of the SoC, which should be
+ allowed to be in suspend mode during batching.</p>
+<p><code>max_report_latency</code> can be modified at any time, in particular while the
+ specified sensor is already enabled; and this shall not result in the loss of
events.</p>
-<h2 id="fifo-allocation">FiFo allocation priority</h2>
-<p>On platforms in which hardware FIFO size is limited, the system designers may
- have to choose how much FIFO to reserve for each sensor. To help with this
- choice, here is a list of applications made possible when batching is
+<h2 id="fifo_allocation_priority">FIFO allocation priority</h2>
+<p>On platforms in which hardware FIFO size is limited, the system designers may
+ have to choose how much FIFO to reserve for each sensor. To help with this
+ choice, here is a list of applications made possible when batching is
implemented on the different sensors.</p>
-<p><strong>High value: Low power pedestrian dead reckoning</strong><br/>
- Target batching time: 20 seconds to 1 minute<br/>
- Sensors to batch:<br/>
- - Step detector<br/>
- - Rotation vector or game rotation vector at 5Hz<br/>
- Gives us step and heading while letting the SoC go to Suspend.<br/>
- <br/>
- <strong>High value: Medium power activity/gesture recognition</strong><br/>
- Target batching time: 3 seconds<br/>
- Sensors to batch: accelerometer between 20Hz and 50Hz<br/>
- Allows recognizing arbitrary activities and gestures without having<br/>
- to keep the SoC fully awake while the data is collected.<br/>
- <br/>
- <strong>Medium-high value: Interrupt load reduction</strong><br/>
- Target batching time: < 1 second<br/>
- Sensors to batch: any high frequency sensor.<br/>
- If the gyroscope is set at 240Hz, even batching just 10 gyro events can<br/>
- reduce the number of interrupts from 240/second to 24/second.<br/>
- <br/>
- <strong>Medium value: Continuous low frequency data collection</strong><br/>
- Target batching time: > 1 minute<br/>
- Sensors to batch: barometer, humidity sensor, other low frequency<br/>
- sensors.<br/>
- Allows creating monitoring applications at low power.<br/>
- <br/>
- <strong>Medium value: Continuous full-sensors collection</strong><br/>
- Target batching time: > 1 minute<br/>
- Sensors to batch: all, at high frequencies<br/>
- Allows full collection of sensor data while leaving the SoC in<br/>
- suspend mode. Only to consider if fifo space is not an issue.<br/>
- <br/>
- In each of the cases above, if <code>WAKE_UPON_FIFO_FULL</code> is implemented, the<br/>
- applications might decide to let the SoC go to suspend, allowing for even<br/>
- more power savings.</p>
-<h2 id="Dry-run">Dry run</h2>
-<p>If the flag <code>SENSORS_BATCH_DRY_RUN</code> is set, this function returns without
- modifying the batch mode or the event period and has no side effects, but
- returns errors as usual (as it would if this flag was not set). This flag is
- used to check if batch mode is available for a given configuration, in
- particular for a given sensor at a given rate.</p>
-<h2 id="Return-values">Return values</h2>
-<p>Because sensors must be independent, the return value must not depend on the
- state of the system (whether another sensor is on or not), nor on whether the
- flag <code>SENSORS_BATCH_DRY_RUN</code> is set (in other words, if a batch call with
- <code>SENSORS_BATCH_DRY_RUN</code> is successful, the same call without
-<code>SENSORS_BATCH_DRY_RUN</code>
- must succeed as well).</p>
-<p>If successful, 0 is returned.</p>
-<p>If the specified sensor doesn't support batch mode, -EINVAL is returned.<br/>
- If the specified sensor's trigger-mode is one-shot, -EINVAL is returned.</p>
-<p>If WAKE UPON FIFO_FULL is specified and the specified sensor's internal FIFO is
- too small to store at least 10 seconds worth of data at the given rate, -EINVAL
- is returned. Note that as stated above, this has to be determined at compile
- time and not based on the state of the system.</p>
-<p>If some other constraints above cannot be satisfied, -EINVAL is returned.<br/>
- <br/>
- Note: The <code>maxReportingLatency</code> parameter when > 0 has no impact on
- whether this function succeeds or fails.<br/>
- <br/>
- If <code>maxReportingLatency</code> is set to 0, this function must succeed.</p>
-<h2 id="Supporting-docs">Supporting documentation</h2>
-<p><a href="http://developer.android.com/guide/topics/sensors/index.html">Developer - Location and Sensors
- APIs</a></p>
-<p><a href="http://developer.android.com/guide/topics/sensors/sensors_overview.html">Developer - Sensors
- Overview</a></p>
-<p><a href="http://developer.android.com/reference/android/hardware/Sensor.html">Sensors SDK API
- reference</a></p>
-<p><a href="{@docRoot}devices/reference/sensors_8h_source.html">Android
- Hardware Abstraction Layer - sensors.h</a></p>
-<p><a href="http://developer.android.com/reference/android/hardware/SensorManager.html">SensorManager</a></p>
+<h3 id="high_value_low_power_pedestrian_dead_reckoning">High value: Low power pedestrian dead reckoning</h3>
+<p>Target batching time: 1 to 10 minutes</p>
+<p>Sensors to batch:</p>
+<ul>
+ <li> Wake-up Step detector </li>
+ <li> Wake-up Game rotation vector at 5Hz </li>
+ <li> Wake-up Barometer at 5Hz </li>
+ <li> Wake-up Uncalibrated Magnetometer at 5Hz </li>
+</ul>
+<p>Batching this data allows performing pedestrian dead reckoning while letting
+ the SoC go to suspend.</p>
+<h3 id="high_value_medium_power_intermittent_activity_gesture_recognition">High value: Medium power intermittent activity/gesture recognition</h3>
+<p>Target batching time: 3 seconds</p>
+<p>Sensors to batch: Non-wake-up Accelerometer at 50Hz</p>
+<p>Batching this data allows periodically recognizing arbitrary activities and
+ gestures without having to keep the SoC awake while the data is collected.</p>
+<h3 id="medium_value_medium_power_continuous_activity_gesture_recognition">Medium value: Medium power continuous activity/gesture recognition</h3>
+<p>Target batching time: 1 to 3 minutes</p>
+<p>Sensors to batch: Wake-up Accelerometer at 50Hz</p>
+<p>Batching this data allows continuously recognizing arbitrary activities and
+ gestures without having to keep the SoC awake while the data is collected.</p>
+<h3 id="medium-high_value_interrupt_load_reduction">Medium-high value: Interrupt load reduction</h3>
+<p>Target batching time: < 1 second</p>
+<p>Sensors to batch: any high frequency sensor, usually non-wake-up.</p>
+<p>If the gyroscope is set at 240Hz, even batching just 10 gyro events can reduce
+ the number of interrupts from 240/second to 24/second.</p>
+<h3 id="medium_value_continuous_low_frequency_data_collection">Medium value: Continuous low frequency data collection</h3>
+<p>Target batching time: 1 to 10 minutes</p>
+<p>Sensors to batch:</p>
+<ul>
+ <li> Wake-up barometer at 1Hz, </li>
+ <li> Wake-up humidity sensor at 1Hz </li>
+ <li> Other low frequency wake-up sensors at similar rates </li>
+</ul>
+<p>Allows creating monitoring applications at low power.</p>
+<h3 id="medium-low_value_continuous_full-sensors_collection">Medium-low value: Continuous full-sensors collection</h3>
+<p>Target batching time: 1 to 10 minutes</p>
+<p>Sensors to batch: all wake-up sensors, at high frequencies</p>
+<p>Allows full collection of sensor data while leaving the SoC in suspend mode.
+ Only to consider if FIFO space is not an issue.</p>