src/devices/sensors/batching.jd

page.title=Batching sensor results
@jd:body

<!--
    Copyright 2013 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.
    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.
-->
<div id="qv-wrapper">
  <div id="qv">
    <h2>In this document</h2>
    <ol id="auto-toc">
    </ol>
  </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>
<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>
</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 
  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 
  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: &lt; 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: &gt; 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: &gt; 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 &gt; 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>