In this document
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.
batch(int handle, int flags, int64_t period_ns, int64_t max_report_latency)
Enabling batch mode for a given sensor sets the delay between events. max_report_latency 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 period_ns 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 period_ns parameter.
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.
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 "maxReportingLatency" 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.
setDelay() is not affected and it behaves as usual.
Each event has a timestamp associated with it. The timestamp must be accurate and correspond to the time at which the event physically happened.
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.
Behavior outside of suspend mode
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.
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.
Normal behavior in suspend mode
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.
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.
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.
WAKE_UPON_FIFO_FULL behavior in suspend mode
There are cases, however, where an application cannot afford to lose any events, even when the device goes into suspend mode.
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 WAKE_UPON_FIFO_FULL mode.
The caller will set the SENSORS_BATCH_WAKE_UPON_FIFO_FULL flag to activate this mode. If the sensor does not support this mode, batch() will fail when the flag is set.
In batch mode, and only when the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL 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.
When running with the WAKE_UPON_FIFO_FULL 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.
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).
Implementing the WAKE_UPON_FIFO_FULL 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 must fail when the flag SENSORS_BATCH_WAKE_UPON_FIFO_FULL is set, regardless of the value of the maxReportingLatency parameter.
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.
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.
For example, if the following sensors are activated:
- accelerometer batched with maxReportingLatency = 20s
- gyroscope batched with maxReportingLatency = 5s
Then the accelerometer batches can be reported at the same time the gyroscope
batches are reported (every 5 seconds).
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.
FiFo allocation priority
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.
High value: Low power pedestrian dead reckoning
Target batching time: 20 seconds to 1 minute
Sensors to batch:
- Step detector
- Rotation vector or game rotation vector at 5Hz
Gives us step and heading while letting the SoC go to Suspend.
High value: Medium power activity/gesture recognition
Target batching time: 3 seconds
Sensors to batch: accelerometer between 20Hz and 50Hz
Allows recognizing arbitrary activities and gestures without having
to keep the SoC fully awake while the data is collected.
Medium-high value: Interrupt load reduction
Target batching time: < 1 second
Sensors to batch: any high frequency sensor.
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.
Medium value: Continuous low frequency data collection
Target batching time: > 1 minute
Sensors to batch: barometer, humidity sensor, other low frequency
Allows creating monitoring applications at low power.
Medium value: Continuous full-sensors collection
Target batching time: > 1 minute
Sensors to batch: all, at high frequencies
Allows full collection of sensor data while leaving the SoC in
suspend mode. Only to consider if fifo space is not an issue.
In each of the cases above, if WAKE_UPON_FIFO_FULL is implemented, the
applications might decide to let the SoC go to suspend, allowing for even
more power savings.
If the flag SENSORS_BATCH_DRY_RUN 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.
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 SENSORS_BATCH_DRY_RUN is set (in other words, if a batch call with SENSORS_BATCH_DRY_RUN is successful, the same call without SENSORS_BATCH_DRY_RUN must succeed as well).
If successful, 0 is returned.
If the specified sensor doesn't support batch mode, -EINVAL is returned.
If the specified sensor's trigger-mode is one-shot, -EINVAL is returned.
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.
If some other constraints above cannot be satisfied, -EINVAL is returned.
Note: the maxReportingLatency parameter when > 0 has no impact on whether this function succeeds or fails.
If maxReportingLatency is set to 0, this function must succeed.