blob: 1f9c35116935d359f5835d9d4a97d68b68df7a7e [file] [log] [blame]
page.title=Suspend mode
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.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
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">
<h2 id="soc_power_states">SoC power states</h2>
<p>The power states of the system on a chip (SoC) are: on, idle, and suspend. On is when the
SoC is running. Idle is a medium power mode where the SoC is powered but
doesn't perform any tasks. “Suspend” is a low-power mode where the SoC is not
powered. The power consumption of the device in this mode is usually 100 times
less than in the “On” mode.</p>
<h2 id="non-wake-up_sensors">Non-wake-up sensors</h2>
<p>Non-wake-up sensors are sensors that do not prevent the SoC
from going into suspend mode and do not wake the SoC up to report data. In
particular, the drivers are not allowed to hold wake-locks. It is the
responsibility of applications to keep a partial wake lock should they wish to
receive events from non-wake-up sensors while the screen is off. While the SoC
is in suspend mode, the sensors must continue to function and generate events,
which are put in a hardware FIFO. (See <a
href="batching.html">Batching</a> for more details.) The events in the
FIFO are delivered to the applications when the SoC wakes up. If the FIFO is
too small to store all events, the older events are lost; the oldest data is dropped to accommodate
the latest data. In the extreme case where the FIFO is nonexistent, all events
generated while the SoC is in suspend mode are lost. One exception is the
latest event from each on-change sensor: the last event <a href="batching.html#precautions_to_take_when_batching_non-wake-up_on-change_sensors">must be saved </a>outside of the FIFO so it cannot be lost.</p>
<p>As soon as the SoC gets out of suspend mode, all events from the FIFO are
reported and operations resume as normal.</p>
<p>Applications using non-wake-up sensors should either hold a wake lock to ensure
the system doesn't go to suspend, unregister from the sensors when they do
not need them, or expect to lose events while the SoC is in suspend mode.</p>
<h2 id="wake-up_sensors">Wake-up sensors</h2>
<p>In opposition to non-wake-up sensors, wake-up sensors ensure that their data is
delivered independently of the state of the SoC. While the SoC is awake, the
wake-up sensors behave like non-wake-up-sensors. When the SoC is asleep,
wake-up sensors must wake up the SoC to deliver events. They must still let the
SoC go into suspend mode, but must also wake it up when an event needs to be
reported. That is, the sensor must wake the SoC up and deliver the events
before the maximum reporting latency has elapsed or the hardware FIFO gets full.
See <a href="batching.html">Batching</a> for more details.</p>
<p>To ensure the applications have the time to receive the event before the SoC
goes back to sleep, the driver must hold a &quot;timeout wake lock&quot; for 200
milliseconds each time an event is being reported. <em>That is, the SoC should not
be allowed to go back to sleep in the 200 milliseconds following a wake-up
interrupt.</em> This requirement will disappear in a future Android release, and we
need this timeout wake lock until then.</p>
<h2 id="how_to_define_wake-up_and_non-wake-up_sensors">How to define wake-up and non-wake-up sensors?</h2>
<p>Up to KitKat, whether a sensor was a wake-up or a non-wake-up sensor was
dictated by the sensor type: most were non-wake-up sensors, with the exception
of the <a href="sensor-types.html#proximity">proximity</a> sensor and the <a href="sensor-types.html#significant_motion">significant motion detector</a>.</p>
<p>Starting in L, whether a given sensor is a wake-up sensor or not is specified
by a flag in the sensor definition. Most sensors can be defined by pairs of
wake-up and non-wake-up variants of the same sensor, in which case they must
behave as two independent sensors, not interacting with one another. See
<a href="interaction.html">Interaction</a> for more details.</p>
<p>Unless specified otherwise in the sensor type definition, it is recommended to
implement one wake-up sensor and one non-wake-up sensor for each sensor type
listed in <a href="sensor-types.html">Sensor types</a>. In each sensor type
definition, see what sensor (wake-up or non-wake-up) will be returned by
<code>SensorManager.getDefaultSensor(sensorType)</code>. It is the sensor
that most applications will use.</p>