page.title=Power Management
pdk.version=1.0
doc.type=guide
@jd:body
<a name="toc"/>
<div style="padding:10px">
<a href="#androidPowerIntro">Introduction</a><br/>
<a href="#androidPowerWakeLocks">Wake Locks</a><br/><div style="padding-left:40px">
<a href="#androidPowerWakeLocksDefinitions">Types of Wake Locks</a><br/>
<a href="#androidPowerWakeLockExample">Exploring a Wake Lock Example</a><br/></div>
<a href="#androidPowerPowerManagerClass">PowerManager class</a><br/>
<a href="#androidPowerKernelRegistration">Registering Drivers with the PM Driver</a><br/>
<a href="#androidPowerEarlySuspend">Early Suspend</a><br/>
</div>
<a name="androidPowerIntro"></a><h2>Introduction</h2>
<p>Android supports its own Power Management (on top of the standard Linux Power Management) designed with the premise that the CPU shouldn't consume power if no applications or services require power. For more information regarding standard Linux power management, please see <a href="http://git.kernel.org/?p=linux/kernel/git/stable/linux-2.6.24.y.git;a=blob;f=Documentation/pm.txt">Linux Power Management Support</a> at <a href="http://kernel.org">http://kernel.org</a>.</p>
<p>Android requires that applications and services request CPU resources with "wake locks" through the Android application framework and native Linux libraries. If there are no active wake locks, Android will shut down the CPU. </p>
<p>The image below illustrates the Android power management architecture. </p>
<p><img src='images/androidPMArchitecture.gif'></p>
Solid elements represent Android blocks and dashed elements represent partner-specific blocks.
<a name="androidPowerWakeLocks"></a><h2>Wake Locks</h2>
<p>Wake locks are used by applications and services to request CPU resources.</p>
<p>A locked wakelock, depending on its type, prevents the system from entering suspend or other low-power states. This document describes how to employ wakelocks. </p>
<p>There are two settings for a wakelock:</p>
<ul>
<li><code>WAKE_LOCK_SUSPEND</code>: prevents a full system suspend. </li>
<li><code></code><code>WAKE_LOCK_IDLE</code>: low-power states, which often cause large interrupt latencies or that disable a set of interrupts, will not be entered from idle until the wakelocks are released. </li>
</ul>
<p>Unless the type is specified, this document refers to wakelocks of type <code>WAKE_LOCK_SUSPEND</code>. </p>
<p>If the suspend operation has already started when locking a wakelock, the system will abort the suspend operation as long it has not already reached the <code>suspend_late</code> stage. This means that locking a wakelock from an interrupt handler or a freezeable thread always works, but if you lock a wakelock from a <code>suspend_late</code> handler, you must also return an error from that handler to abort suspend. You can use wakelocks to allow the user-space to decide which keys should wake the full system and turn on the screen. Use <code>set_irq_wake</code> or a platform-specific API to ensure that the keypad interrupt wakes up the CPU. Once the keypad driver has resumed, the sequence of events can look like this:</p>
<ol>
<li> The Keypad driver receives an interrupt, locks the keypad-scan wakelock,
and starts scanning the keypad matrix. </li>
<li>The keypad-scan code detects a key change and reports it to the input-event
driver. </li>
<li>The input-event driver sees the key change, enqueues an event, and locks
the input-event-queue wakelock. </li>
<li>The keypad-scan code detects that no keys are held and unlocks the
keypad-scan wakelock. </li>
<li>The user-space input-event thread returns from select/poll, locks the
process-input-events wakelock, and calls read in the input-event device. </li>
<li>The input-event driver dequeues the key-event and, since the queue is now
empty, unlocks the input-event-queue wakelock. </li>
<li>The user-space input-event thread returns from read. It determines that the
key should not wake up the full system, releases the process-input-events
wakelock, and calls select or poll. </li>
</ol>
<p>The simple sequence diagram below illustrates these steps:</p>
<pre>
Key pressed Key released
| |
keypad-scan ++++++++++++++++++++++
input-event-queue +++ +++
process-input-events +++ +++
</pre>
<a name="driverAPI"></a><h3>Driver API</h3>
<p>A driver can use the wakelock API by adding a wakelock variable to its state and calling <code>wake_lock_init</code>, as illustrated in the snippet below:</p>
<pre>
struct state {
struct wakelock wakelock;
}
init() {
wake_lock_init(&state->wakelock, WAKE_LOCK_SUSPEND, "wakelockname");
}
Before freeing the memory, wake_lock_destroy must be called:
uninit() {
wake_lock_destroy(&state->wakelock);
}
</pre>
<p> When the driver determines that it needs to run (usually in an interrupt handler), it calls <code>wake_lock</code>:</p>
<pre>
wake_lock(&state->wakelock);
</pre>
<p>When it no longer needs to run, it calls <code>wake_unlock</code>:</p>
<pre>
wake_unlock(&state->wakelock);
</pre>
<p> It can also call <code>wake_lock_timeout</code> to release the wakelock after a delay:</p>
<pre>
wake_lock_timeout(&state->wakelock, HZ);
</pre>
<p> This works whether or not the wakelock is already held. It is useful if the driver woke up other parts of the system that do not use wakelocks but still need to run. Avoid this when possible, since it will waste power if the timeout is long or may fail to finish needed work if the timeout is short.</p>
<a name="userspaceAPI"></a><h3>User-space API</h3>
<p>Write <code>lockname</code> or <code>lockname timeout</code> to <code>/sys/power/wake_lock</code> lock and, if needed, create a wakelock. The timeout here is specified in nanoseconds. Write <code>lockname</code> to <code>/sys/power/wake_unlock</code> to unlock a user wakelock.</p>
<p> Do not use randomly generated wakelock names as there is no API to free a user-space wakelock.</p>
<a name="androidPowerWakeLocksDefinitions"></a><h3>Types of Wake Locks</h3>
<table border=1 cellpadding=2 cellspacing=0>
<tbody><tr>
<th scope="col">Wake Lock </th>
<th scope="col">Description</th>
</tr>
<tr>
<td>ACQUIRE_CAUSES_WAKEUP<br/></td>
<td>Normally wake locks don't actually wake the device, they just cause it to remain on once it's already on. Think of the video player app as the normal behavior. Notifications that pop up and want the device to be on are the exception; use this flag to be like them.</td>
</tr>
<tr>
<td>FULL_WAKE_LOCK</td>
<td>Wake lock that ensures that the screen and keyboard are on at full brightness. </td>
</tr>
<tr>
<td>ON_AFTER_RELEASE</td>
<td>When this wake lock is released, poke the user activity timer so the screen stays on for a little longer.</td>
</tr>
<tr>
<td>PARTIAL_WAKE_LOCK</td>
<td>Wake lock that ensures that the CPU is running. The screen might not be on.</td>
</tr>
<tr>
<td>SCREEN_BRIGHT_WAKE_LOCK</td>
<td>Wake lock that ensures that the screen is on at full brightness; the keyboard backlight will be allowed to go off.</td>
</tr>
<tr>
<td>SCREEN_DIM_WAKE_LOCK</td>
<td>Wake lock that ensures that the screen is on, but the keyboard backlight will be allowed to go off, and the screen backlight will be allowed to go dim.</td>
</tr>
</table>
<a name="androidPowerWakeLockExample"></a><h3>Exploring a Wake Lock Example</h3>
<p>All power management calls follow the same basic format:</p>
<p><ol><li>Acquire handle to the <code>PowerManager</code> service.</li>
<li>Create a wake lock and specify the power management flags for screen, timeout, etc.</li>
<li>Acquire wake lock.</li>
<li>Perform operation (play MP3, open HTML page, etc.).</li>
<li>Release wake lock.</li>
</ol>
</p>
<p>The snippet below illustrates this process.</p>
<pre class="prettify">
PowerManager pm = (PowerManager)mContext.getSystemService(
Context.POWER_SERVICE);
PowerManager.WakeLock wl = pm.newWakeLock(
PowerManager.SCREEN_DIM_WAKE_LOCK
| PowerManager.ON_AFTER_RELEASE,
TAG);
wl.acquire();
// ...
wl.release();
</pre>
<a name="androidPowerPowerManagerClass"></a><h2>PowerManager class</h2>
<p>The Android Framework exposes power management to services and applications through the <code>PowerManager</code> class.</p>
<p>User space native libraries (any hardware function in <code>//device/lib/hardware/</code> meant to serve as supporting libraries for Android runtime) should never call into Android Power Management directly (see the image above). Bypassing the power management policy in the Android runtime will destabilize the system.</p>
<p>All calls into Power Management should go through the Android runtime PowerManager APIs.</p>
<p> Please visit
<a href="http://code.google.com/android/reference/android/os/PowerManager.html">http://code.google.com/android/reference/android/os/PowerManager.html</a> for a description of the API and examples.</p>
<a name="androidPowerKernelRegistration"></a><h2>Registering Drivers with the PM Driver</h2>
<p>You can register Kernel-level drivers with the Android Power Manager driver so that they're notified immediately before power down or after power up. For example, you might set a display driver to completely power down when a request comes in to power down from the user space (see the Android MSM MDDI display driver for a sample implementation).</p>
<p>To register drivers with the Android PM driver, implement call-back handlers and register them with the Android PM, as illustrated in the snippet below:</p>
<pre class="prettify">
android_register_early_suspend(android_early_suspend_t *handler)
android_register_early_resume(android_early_resume_t *handler)
</pre>
<p>It is critical in a drive to return immediately and not wait for anything to happen in the call back.</p>
<a name="androidPowerEarlySuspend"></a><h2>Early Suspend</h2>
<p>The early-suspend API allows drivers to get notified when user-space writes to <code>/sys/power/request_state</code> to indicate that the user visible sleep state should change. Suspend handlers are called in order of low to high (4 - 1 below) and resume handlers are called in order of high to low (1 - 4 below).</p>
<ol>
<li><code>EARLY_SUSPEND_LEVEL_BLANK_SCREEN</code>: </li>
<ul>
<li>on suspend: the screen should be turned off but the framebuffer must still be accessible. </li>
<li>on resume: the screen can be turned back on.</li>
</ul>
<li><code>EARLY_SUSPEND_LEVEL_STOP_DRAWING</code>:
<ul>
<li>on suspend: this level notifies user-space that it should stop accessing the framebuffer and it waits for it to complete.</li>
<li>on resume: it notifies user-space that it should resume screen access. Two methods are provided, console switch or a sysfs interface.</li>
</ul>
</li>
<li><code>EARLY_SUSPEND_LEVEL_DISABLE_FB</code>: Turn off the framebuffer
<ul>
<li>on suspend: turn off the framebuffer</li>
<li>on resume: turn the framebuffer back on. </li>
</ul>
</li>
<li><code>EARLY_SUSPEND_LEVEL_STOP_INPUT</code>:
<ul>
<li>on suspend: turn off input devices that are not capable of wakeup or where wakeup is disabled. </li>
<li>on resume: turn the same devices back on.</li>
</ul>
</li>
</ol>