Merge "Docs: Typo fix, remove slash Bug: 22639850" into mnc-dev
diff --git a/src/compatibility/android-cdd.html b/src/compatibility/android-cdd.html
index 1d46261..96f660f 100644
--- a/src/compatibility/android-cdd.html
+++ b/src/compatibility/android-cdd.html
@@ -4358,6 +4358,10 @@
service with android.permission.CONTROL_VPN granted), the device implementation
MUST ask for the user's consent before enabling that mechanism.</p>
+<p>If a device implementation has a USB port with USB peripheral mode support,
+it MUST present a user interface asking for the user's consent before allowing
+access to the contents of the shared storage over the USB port.</p>
+
<h2 id="9_9_full-disk_encryption">9.9. Full-Disk Encryption</h2>
<div class="note">
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 35525d4..8fd6d69 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -119,7 +119,17 @@
<li><a href="<?cs var:toroot ?>devices/input/validate-keymaps.html">Validate Keymaps</a></li>
</ul>
</li>
- <li><a href="<?cs var:toroot ?>devices/media.html">Media</a></li>
+ <li class="nav-section">
+ <div class="nav-section-header">
+ <a href="<?cs var:toroot ?>devices/media/index.html">
+ <span class="en">Media</span>
+ </a>
+ </div>
+ <ul>
+ <li><a href="<?cs var:toroot ?>devices/media/soc.html">SoC Dependencies</a></li>
+ <li><a href="<?cs var:toroot ?>devices/media/oem.html">OEM Dependencies</a></li>
+ </ul>
+ </li>
<li class="nav-section">
<div class="nav-section-header">
<a href="<?cs var:toroot ?>devices/sensors/index.html">
@@ -184,6 +194,7 @@
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/instruction-formats.html">Instruction Formats</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/constraints.html">Constraints</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/dalvik/configure.html">Configuration</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/dalvik/gc-debug.html">Garbage Collection</a></li>
</ul>
</li>
@@ -201,6 +212,7 @@
<li><a href="<?cs var:toroot ?>devices/tech/config/renderer.html">OpenGLRenderer</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/runtime_perms.html">Runtime Permissions</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/uicc.html">UICC</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/config/voicemail.html">Visual Voicemail</a></li>
</ul>
</li>
@@ -262,6 +274,8 @@
<a href="<?cs var:toroot ?>devices/tech/power/index.html"><span class="en">Power</span></a>
</div>
<ul>
+ <li><a href="<?cs var:toroot ?>devices/tech/power/mgmt.html">Power Management</a>
+ </li>
<li><a href="<?cs var:toroot ?>devices/tech/power/component.html">Component Power</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/power/device.html">Device Power</a>
</li>
diff --git a/src/devices/images/media.png b/src/devices/images/media.png
deleted file mode 100644
index 7aaee93..0000000
--- a/src/devices/images/media.png
+++ /dev/null
Binary files differ
diff --git a/src/devices/images/ape_fwk_hal_media.png b/src/devices/media/images/ape_fwk_hal_media.png
similarity index 100%
rename from src/devices/images/ape_fwk_hal_media.png
rename to src/devices/media/images/ape_fwk_hal_media.png
Binary files differ
diff --git a/src/devices/images/ape_fwk_media.png b/src/devices/media/images/ape_fwk_media.png
similarity index 100%
rename from src/devices/images/ape_fwk_media.png
rename to src/devices/media/images/ape_fwk_media.png
Binary files differ
diff --git a/src/devices/media.jd b/src/devices/media/index.jd
similarity index 100%
rename from src/devices/media.jd
rename to src/devices/media/index.jd
diff --git a/src/devices/media/oem.jd b/src/devices/media/oem.jd
new file mode 100644
index 0000000..a271ecd
--- /dev/null
+++ b/src/devices/media/oem.jd
@@ -0,0 +1,162 @@
+page.title=OEM Dependencies for Media Resource Manager
+@jd:body
+
+<!--
+ Copyright 2015 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>
+
+<p>This document is intended to help original equipment manufacturers (OEMs)
+properly implement support for Android media resource manager and related APIs.</p>
+
+<h2 id=1_max_concurrent_codec_instances>1. Max concurrent codec instances</h2>
+
+<p>The <code>CodecCapabilities.getMaxSupportedInstances</code> interface
+returns the maximum number of supported concurrent codec instances.</p>
+
+<p>The CTS test
+<code>testGetMaxSupportedInstances(android.media.cts.MediaCodecCapabilitiesTest)</code>
+is used to enforce the proper maximum is set in
+<code>/etc/media_codecs.xml</code>.</p>
+
+<p>Here is an example:</p>
+
+<pre>
+...
+<MediaCodecs>
+ ...
+ <Encoders>
+ <MediaCodec name="OMX.<em><vendor></em>.video.encoder.avc" type="video/avc" >
+ ...
+ <Limit name="concurrent-instances" max="13" />
+ </MediaCodec>
+ ...
+ </Encoders>
+ ...
+</MediaCodecs>
+</pre>
+
+<p>OEMs can use this test to generate the concurrent limits that pass the test.
+To do this:</p>
+
+ <ol>
+ <li>Run the test first using cts-tradefed.
+ <li>Evaluate the resulting failure message. Here is an example:
+
+<pre>
+There was 1 failure:
+1) testGetMaxSupportedInstances(android.media.cts.MediaCodecCapabilitiesTest)
+junit.framework.AssertionFailedError: In order to pass the test, please publish
+following codecs' concurrent instances limit in /etc/media_codecs.xml:
+<MediaCodec name="OMX.<em><vendor></em>.video.encoder.mpeg4" type="video/mp4v-es" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.encoder.h263" type="video/3gpp" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.encoder.avc" type="video/avc" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.encoder.vp8" type="video/x-vnd.on2.vp8" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.avc" type="video/avc" >
+ <Limit name="concurrent-instances" max="13" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.avc.secure" type="video/avc" >
+ <Limit name="concurrent-instances" max="4" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.mpeg4" type="video/mp4v-es" >
+ <Limit name="concurrent-instances" max="12" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.h263" type="video/3gpp" >
+ <Limit name="concurrent-instances" max="12" />
+</MediaCodec>
+<MediaCodec name="OMX.<em><vendor></em>.video.decoder.vp8" type="video/x-vnd.on2.vp8" >
+ <Limit name="concurrent-instances" max="12" />
+</MediaCodec>
+</pre>
+
+ <li>Add the <code>concurrent-instances</code> lines suggested in the test
+failure message to the <code>/etc/media_codecs.xml</code> file.
+
+ <li>Re-run the test to verify its success.
+ </ol>
+
+<h2 id=2_achievable_frame_rates_for_video_codecs>2. Achievable frame rates for video codecs</h2>
+<p>The <code>VideoCapabilities.getAchievableFrameRatesFor</code> interface
+returns the range of achievable video frame rates for a video size. This
+information must be provided by the OEM for each device via an XML file placed at
+<code>/etc/media_codecs_performance.xml</code>. These settings are tested by
+the <code>com.android.cts.videoperf.VideoEncoderDecoderTest</code> and
+<code>android.media.cts.VideoDecoderPerfTest</code> CTS tests.</p>
+
+<p>OEMs can use the CTS tests to generate the XML files that pass the tests. To do this:</p>
+ <ol>
+ <li>Run the tests first using cts-tradefed. Given the
+variability of Android performance, it is recommended the tests are run
+multiple times to get more accurate minimum and maximum values.
+ <li>Use the provided <code>get_achievable_rates.py</code> script to
+generate the XML file.
+ <li>Place the XML file at: <code>/etc/media_codecs_performance.xml</code><br>
+This is usually done by placing the XML file in the device project
+(device/<em><vendor></em>/<em><product></em>) and adding a
+<code>PRODUCT_COPY_FILES</code> line to <code>device.mk</code> like so:
+<pre>
+PRODUCT_COPY_FILES += \
+...
+ device/moto/shamu/media_codecs.xml:system/etc/media_codecs.xml \
++ device/moto/shamu/media_codecs_performance.xml:system/etc/media_codecs_performance.xml
+</pre>
+ <li>Re-run the performance tests to verify their success.
+ </ol>
+
+<h2 id=3_co-exist_of_secure_codec_and_non-secure_codec>3. Co-exist of secure codec and non-secure codec</h2>
+
+<ul>
+ <li>supports-secure-with-non-secure-codec —
+If the instance of secure codec and the instance of non-secure codec can’t
+co-exist at the same time, that should be indicated as global setting in the
+<code>media_codecs.xml</code> file.
+<pre>
+<MediaCodecs>
+ <Settings>
+ <Setting name="supports-secure-with-non-secure-codec" value="false" />
+ </Settings>
+ <Encoders>
+…
+</pre>
+ <li>supports-multiple-secure-codecs —
+If co-exist of multiple secure codec instances is not supported, that should be
+indicated as a global setting in the <code>media_codecs.xml</code> file.
+<pre>
+<MediaCodecs>
+ <Settings>
+ <Setting name="supports-multiple-secure-codecs" value="false" />
+ </Settings>
+ <Encoders>
+…
+</pre>
+ <li>Note that the both settings are true by default, meaning if they are supported,
+there’s no need to add the setting line to the <code>media_codecs.xml</code>.
+ <li>The <code>ResourceManagerTest</code> CTS tests may fail if these two settings were not set
+properly.
+</ul>
diff --git a/src/devices/media/soc.jd b/src/devices/media/soc.jd
new file mode 100644
index 0000000..e42a2af
--- /dev/null
+++ b/src/devices/media/soc.jd
@@ -0,0 +1,74 @@
+page.title=SoC Vendor Dependencies for Media Resource Manager
+@jd:body
+
+<!--
+ Copyright 2015 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>
+
+<p>This document is intended to help system on chip vendors (SoCs) properly
+implement support for priority, operating rate and the hooks needed for Android
+media resource manager.</p>
+
+<h2 id=1_omx_errorinsufficientresources>1. OMX_ErrorInsufficientResources</h2>
+
+<p>The codec component should return
+<code>OMX_ErrorInsufficientResources</code> on <code>GetHandle</code>,
+<code>Init</code>, <code>UseBuffer</code>, <code>AllocateBuffer</code> or a
+state transition if the failure is due to insufficient resource. The error code
+will be used by the media resource manager as the indicator to potentially
+preempt media resource from other lower priority process.</p>
+
+<p>An Android Compatibility Test Suite (CTS) test exists to allocate, configure
+and start each codec repeatedly until <code>catching
+OMX_ErrorInsufficientResources</code> (pass) or any other error (fail).</p>
+
+<h2 id=2_omx_indexconfigpriority>2. OMX_IndexConfigPriority</h2>
+
+<p>This configuration lets the application describe desired codec priority.</p>
+
+<p>The associated value is an integer. Higher value means lower priority.
+Currently, only two levels are supported:</p>
+
+<ul>
+ <li>0: realtime priority - meaning that the codec shall support the given
+performance configuration (e.g. framerate) at realtime. This will only be used
+by media playback, capture, and possibly by realtime communication scenarios if
+best effort performance is not suitable.</li>
+ <li>1: non-realtime priority (best effort). This is the default value.</li>
+</ul>
+
+<p>Vendor is suggested to use this as a hint used at codec configuration and
+resource planning - to understand the realtime requirements of the application.</p>
+
+<p>Don’t assume realtime priority unless it is configured to 0.</p>
+
+<h2 id=3_omx_indexconfigoperatingrate>3. OMX_IndexConfigOperatingRate</h2>
+
+<p>This configuration lets the application describe operating frame rate for
+video or sample rate for audio at which the codec will need to operate.</p>
+
+<p>This is used for cases like high-speed/slow-motion video capture, where the
+video encoder format contains the target playback rate (e.g. 30fps), but the
+component must be able to handle the high operating capture rate (e.g. 240fps).</p>
+
+<p>This rate should be used for resource planning and setting the operating
+points.</p>
diff --git a/src/devices/tech/config/voicemail.jd b/src/devices/tech/config/voicemail.jd
new file mode 100644
index 0000000..2d88828
--- /dev/null
+++ b/src/devices/tech/config/voicemail.jd
@@ -0,0 +1,185 @@
+page.title=Visual Voicemail
+@jd:body
+
+<!--
+ Copyright 2015 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>
+
+<p>Android 6.0 (Marshmallow) brings an implementation of Visual Voicemail (VVM)
+support integrated into the Dialer, allowing compatible Carrier VVM services to
+hook into the Dialer with minimal configuration. Visual voicemail lets users
+easily check voicemail without making any phone calls. Users can view a list of
+messages in an inbox-like interface, listen to them in any order, and can
+delete them as desired.</p>
+
+<p>This article gives an overview of what is provided, how carriers can integrate
+with it, and some details of the implementation.</p>
+
+<h2 id=visual_voicemail_vvm_client>Visual Voicemail (VVM) client</h2>
+
+<p>Android 6.0 includes a OMTP VVM client, which (when provided with the correct
+configuration) will connect to Carrier VVM servers and populate Visual
+Voicemail messages within the AOSP Dialer. The VVM client:</p>
+
+<ul>
+ <li>Handles the SMS messages used to activate/deactivate/query status of the
+service and the SMS messages used to notify the device of events in the
+subscriber’s mailbox
+ <li>Syncs the mailbox with the IMAP server
+ <li>Downloads the voicemails when the user chooses to listen to them
+ <li>Integrates into the Dialer for user functionality such as calling back, viewing
+unread messages, deleting messages, etc.
+</ul>
+
+<h2 id=integrate_with_the_vvm_client>Integrate with the VVM client</h2>
+
+<h3 id=implementation>Implementation</h3>
+
+<p>The Carrier must provide a Visual Voicemail server implementing the <a href="http://www.gsma.com/newsroom/wp-content/uploads/2012/07/OMTP_VVM_Specification_1_3.pdf">OMTP VVM specifications</a>. The current implementation of the Google VVM client supports the core
+features (read/delete voicemails, download/sync/listen) but the additional TUI
+features (password change, voicemail greeting, languages) are not implemented.
+At this time, we only support OMTP version 1.1 and do not use encryption for
+IMAP authentication. </p>
+
+<p><strong>Note</strong> that server-originated SMS messages to the device (e.g. STATUS or SYNC) must
+not be class 0 messages.</p>
+
+<h3 id=configuration>Configuration</h3>
+
+<p>In order for a carrier to integrate with the VVM service, the carrier must
+provide configuration details to the platform that the OMTP client can use.
+These parameters are:</p>
+
+<ul>
+ <li>Destination number and port number for SMS
+ <li>Authentication security type for IMAP (SSL, TLS, none, etc.)
+ <li>The package name of the carrier-provided Visual Voicemail app (if one is
+provided), so that the platform implementation can be disabled if that package
+is installed
+</ul>
+
+<p>These values are provided through the <a href="https://developer.android.com/reference/android/telephony/CarrierConfigManager.html">Carrier Config API</a>. This functionality, launched in Android 6.0, allows an application to
+dynamically provide telephony-related configuration to the various platform
+components that need it. In particular the following keys must have values
+defined:</p>
+
+<ul>
+ <li><code>KEY_VVM_DESTINATION_NUMBER_STRING</code>
+ <li><code>KEY_VVM_PORT_NUMBER_INT</code>
+ <li><code>KEY_VVM_TYPE_STRING</code>
+ <li><code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code>
+</ul>
+
+<p>Please see the <a href="{@docRoot}devices/tech/config/carrier.html">Carrier Configuration</a> article for more detail.</p>
+
+<h2 id=implementation>Implementation</h2>
+
+<p>The OMTP VVM client is implemented within <code>packages/services/Telephony</code>, in particular within <code>src/com/android/phone/vvm/</code></p>
+
+<h3 id=setup>Setup</h3>
+
+<ol>
+ <li>The VVM client listens for <code>TelephonyIntents#ACTION_SIM_STATE_CHANGED</code> or <code>CarrierConfigManager#ACTION_CARRIER_CONFIG_CHANGED</code>.
+ <li>When a SIM is added that has the right Carrier Config values (<code>KEY_VVM_TYPE_STRING</code> set to <code>TelephonyManager.VVM_TYPE_OMTP</code> or <code>TelephonyManager.VVM_TYPE_CVVM</code>), the VVM client sends an ACTIVATE SMS to the value specified in <code>KEY_VVM_DESTINATION_NUMBER_STRING</code>.
+ <li>The server activates the visual voicemail service and sends the OMTP
+credentials via STATUS sms. When the VVM client receives the STATUS sms, it
+registers the voicemail source and displays the voicemail tab on the device.
+ <li>The OMTP credentials are saved locally and the device begins a full sync, as
+described below.
+</ol>
+
+<h3 id=syncing>Syncing</h3>
+
+<p>There are a variety of ways that the VVM client can sync with the carrier
+server and vice versa.</p>
+
+<ul>
+ <li><strong>Full syncs</strong> occur upon initial download. The VVM client only fetches voicemail metadata
+like date and time, origin number, duration, etc. Full syncs can be triggered
+by a:
+ <ul>
+ <li>new SIM
+ <li>device reboot
+ <li>device coming back in service
+ </ul>
+ <li><strong>Upload sync</strong> happens when a user interacts with a voicemail to read or delete it. Upload
+syncs result in the server changing its data to match the data on the device.
+For example, if the user reads a voicemail, it's marked as read on the server;
+if a user deletes a voicemail, it's deleted on the server.
+ <li><strong>Download sync</strong> occurs when the VVM client receives a "MBU" (mailbox update) SYNC sms from the
+carrier. A SYNC message contains the metadata for a new message so that it can
+be stored in the voicemail content provider.
+</ul>
+
+<h3 id=voicemail_download>Voicemail Download</h3>
+
+<p>When a user presses play to listen to a voicemail, the corresponding audio file
+is downloaded. If the user chooses to listen to the Voicemail, the Dialer can
+broadcast <code>VoicemailContract.ACTION_FETCH_VOICEMAIL</code>, which the voicemail client will receive, initiate the download of the
+content, and update the record in the platform Voicemail content provider.</p>
+
+<h3 id=disabling_vvm>Disabling VVM</h3>
+
+<p>The VVM service can be disabled or deactivated by user interaction, removal of
+a valid SIM, or replacement by a carrier VVM app. <em>Disabled</em> means that the local device no longer displays visual voicemail. <em>Deactivated</em> means that the service is turned off for the subscriber. User interaction can
+deactivate the service, SIM removal temporarily disables the service because
+it's no longer present, and carrier VVM replacement disables the Google
+component of visual voicemail.</p>
+
+<h4 id=user_interaction>User interaction</h4>
+
+<p>The user may manually enable or disable visual voicemail. If a user disables
+visual voicemail, they are also deactivating their service. When they disable
+visual voicemail, a DEACTIVATE sms is sent, the voicemail source is
+unregistered locally, and voicemail tab disappears. If they re-enable visual
+voicemail, their service is reactivated as well.</p>
+
+<h4 id=sim_removal>SIM removal</h4>
+
+<p>If there are changes to the device’s SIM state (<code>ACTION_SIM_STATE_CHANGED</code>) or Carrier Config values (<code>ACTION_CARRIER_CONFIG_CHANGED</code>), and a valid configuration for the given SIM no longer exists, then the
+voicemail source is unregistered locally and the voicemail tab disappears. If
+the SIM is replaced, VVM will be re-enabled.</p>
+
+<h4 id=replaced_by_carrier_vvm>Replaced by carrier VVM</h4>
+
+<p>If the device or the user installs a corresponding carrier visual voicemail app
+and the carrier has opted to disable Google visual voicemail if the carrier
+equivalent is installed, then the Google visual voicemail client will be
+automatically disabled. This is achieved by checking if a package with a name
+matching the <code>KEY_CARRIER_VVM_PACKAGE_NAME_STRING</code> parameter is installed.</p>
+
+<p>The VVM client can still be enabled through user interaction.</p>
+
+<h2 id=testing>Testing</h2>
+
+<p>There is an existing (since Android 4.0) set of CTS tests for the
+VoicemailProvider APIs that allow an app to insert/query/delete voicemails into
+the platform. These are the same APIs that VVM uses to add/delete voicemails so
+that any Dialer app can display them in the UI.</p>
+
+<p>To test your configuration application is passing the OMTP configuration
+correctly you can test your code with:</p>
+
+<ul>
+ <li>A SIM containing a valid certificate signature
+ <li>A device running Android 6.0 with an unmodified version of the AOSP phone framework
+</ul>
diff --git a/src/devices/tech/dalvik/gc-debug.jd b/src/devices/tech/dalvik/gc-debug.jd
new file mode 100644
index 0000000..676d38b
--- /dev/null
+++ b/src/devices/tech/dalvik/gc-debug.jd
@@ -0,0 +1,449 @@
+page.title=Debugging ART Garbage Collection
+@jd:body
+
+<!--
+ Copyright 2015 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 id="Contents">In this document</h2>
+ <ol id="auto-toc">
+ </ol>
+</div>
+</div>
+
+<p>This document describes how to debug Android Runtime (ART) Garbage Collection
+(GC) correctness and performance issues. It explains how to use GC verification
+options, identify solutions for GC verification failures, and measure and
+address GC performance problems.</p>
+
+<p>See <a href="index.html">ART and Dalvik</a>, the <a
+href="dex-format.html">Dalvik Executable format</a>, and the remaining pages
+within this <a href="index.html">ART and Dalvik</a> section to work with
+ART. See <a
+href="http://developer.android.com/guide/practices/verifying-apps-art.html">Verifying
+App Behavior on the Android Runtime (ART)</a> for additional help verifying app
+behavior.</p>
+
+<h2 id=art_gc_overview>ART GC overview</h2>
+
+<p>ART, introduced as a developer option in Android 4.4, is the default Android
+runtime for Android 5.0 and beyond. The Dalvik runtime is no longer maintained
+or available and its byte-code format is now used by ART. Please note this
+section merely summarizes ART’s GC. For additional information, see the <a
+href="https://www.google.com/events/io/io14videos/b750c8da-aebe-e311-b297-00155d5066d7">Android
+runtime</a> presentation conducted at Google I/O 2014. </p>
+
+<p>ART has a few different GC plans that consist of running different garbage
+collectors. The default plan is the CMS (concurrent mark sweep) plan, which
+uses mostly sticky CMS and partial CMS. Sticky CMS is ART’s non-moving
+generational garbage collector. It scans only the portion of the heap that was
+modified since the last GC and can reclaim only the objects allocated since the
+last GC. In addition to the CMS plan, ART performs heap compaction when an app
+changes process state to a jank-imperceptible process state (e.g. background or
+cached).</p>
+
+<p>Aside from the new garbage collectors, ART also introduces a new bitmap-based
+memory allocator called RosAlloc (runs of slots allocator). This new allocator
+has sharded locking and outperforms DlMalloc by adding thread local buffers for
+small allocation sizes.</p>
+
+<p>Compared to Dalvik, the ART CMS garbage collection plan has a number of
+improvements:</p>
+
+<ul>
+ <li>The number of pauses is reduced from two to one compared to Dalvik.
+Dalvik’s first pause, which did mostly root marking, is done concurrently in
+ART by getting the threads to mark their own roots, then resume running right away.
+ <li>Similarly to Dalvik, the ART GC also has a pause before the sweeping process.
+The key difference in this area is that some of the Dalvik phases during this
+pause are done concurrently in ART. These phases include
+<code>java.lang.ref.Reference</code> processing, system weak sweeping (e.g. jni
+weak globals, etc.), re-marking non-thread roots, and card pre-cleaning. The
+phases that are still done paused in ART are scanning the dirty cards and
+re-marking the thread roots, which helps reduce the pause time.
+ <li>The last area where the ART GC improves over Dalvik is with increased GC
+throughput enabled by the sticky CMS collector. Unlike normal generational GC,
+sticky CMS is non-moving. Instead of having a dedicated region for young
+objects, young objects are kept in an allocation stack, which is basically an
+array of <code>java.lang.Object</code>. This avoids moving objects required to
+maintain low pauses but has the disadvantage of having longer collections for
+heaps with complex object graphs.
+</ul>
+
+<p>The other main other area where the ART GC is different than Dalvik is the
+introduction of moving garbage collectors. The goal of moving GCs is to
+reduce memory usage of backgrounded apps through heap compaction. Currently,
+the event that triggers heap compaction is ActivityManager process-state
+changes. When an app goes to background, it notifies ART the process state is
+no longer jank “perceptible.” This enables ART do things that cause long
+application thread pauses, such as compaction and monitor deflation. The two
+current moving GCs that are in use are homogeneous space compaction and
+semi-space compaction.</p>
+
+<ul>
+ <li>Semi-space compaction moves objects between two tightly packed bump pointer
+spaces. This moving GC occurs on low-memory devices since it saves slightly
+more memory than homogeneous space compaction. The additional savings come
+mostly from having tightly packed objects, which avoid RosAlloc / DlMalloc
+allocator accounting overhead. Since CMS is still used in the foreground and it
+can’t collect from a bump pointer space, semi space requires another transition
+when the app is foregrounded. This is not ideal since it can cause a noticeable pause.
+ <li>Homogenous space compaction works by copying from one RosAlloc space to another
+RosAlloc space. This helps reduce memory usage by reducing heap fragmentation.
+This is currently the default compaction mode for non-low-memory devices. The
+main advantage that homogeneous space compaction has over semi-space compaction
+is not needing a heap transition when the app goes back to foreground.
+</ul>
+
+<h2 id=gc_verification_and_performance_options>GC verification and performance options</h2>
+
+<p>It is possible to change the GC type if you are an OEM. The process for doing
+this involves modifying system properties through adb. Keep in mind that these
+are only modifiable on non-user or rooted builds.</p>
+
+<h3 id=changing_the_gc_type>Changing the GC type</h3>
+
+<p>There are ways to change the GC plans that ART uses. The main way to change the
+foreground GC plan is by changing the <code>dalvik.vm.gctype</code> property or
+passing in an <code>-Xgc:</code> option. It is possible to pass in multiple GC
+options separated by commas.</p>
+
+<p>In order to derive the entire list of available <code>-Xgc</code> settings,
+it is possible to type <code>adb shell dalvikvm -help</code> to print the
+various runtime command-line options.</p>
+
+<p>Here is one example that changes the GC to semi space and turns on pre-GC heap
+verification:
+<code>adb shell setprop dalvik.vm.gctype SS,preverify</code></p>
+
+<ul>
+ <li><code>CMS</code>, which is also the default value, specifies the
+concurrent mark sweep GC plan. This plan consists of running sticky
+generational CMS, partial CMS, and full CMS. The allocator for this plan is
+RosAlloc for movable objects and DlMalloc for non-movable objects.
+ <li><code>SS</code> specifies the semi space GC plan. This plan has two semi
+spaces for movable objects and a DlMalloc space for non-movable objects. The
+movable object allocator defaults to a shared bump pointer allocator which uses
+atomic operations. However, if the <code>-XX:UseTLAB</code> flag is also passed
+in, the allocator uses thread local bump pointer allocation.
+ <li><code>GSS</code> specifies the generational semi space plan. This plan is
+very similar to the semi-space plan with the exception that older-lived objects
+are promoted into a large RosAlloc space. This has the advantage of needing to
+copy significantly fewer objects for typical use cases.
+</ul>
+
+<h3 id=verifying_the_heap>Verifying the heap</h3>
+
+<p>Heap verification is probably the most useful GC option for debugging
+GC-related errors or heap corruption. Enabling heap verification causes the GC
+to check the correctness of the heap at a few points during the garbage
+collection process. Heap verification shares the same options as the ones that
+change the GC type. If enabled, heap verification verifies the roots and
+ensures that reachable objects reference only other reachable objects. GC
+verification is enabled by passing in the following -<code>Xgc</code> values:</p>
+
+<ul>
+ <li>If enabled, <code>[no]preverify</code> performs heap verification before starting the GC.
+ <li>If enabled, <code>[no]presweepingverify</code> performs heap verification
+before starting the garbage collector sweeping
+process.
+ <li>If enabled, <code>[no]postverify</code> performs heap verification after
+the GC has finished sweeping.
+ <li><code>[no]preverify_rosalloc</code>,
+<code>[no]postsweepingverify_rosalloc</code>,
+<code>[no]postverify_rosalloc</code> are also additional GC options that verify
+only the state of RosAlloc’s internal accounting. The main things verified are
+that magic values match expected constants, and free blocks of memory are all
+registered in the <code>free_page_runs_</code> map.
+</ul>
+
+<h3 id=using_the_tlab_allocator_option>Using the TLAB allocator option</h3>
+
+<p>Currently, the only option that changes the allocator used without affecting
+the active GC type is the TLAB option. This option is not available through
+system properties but can be enabled by passing in -<code>XX:UseTLAB</code> to
+<code>dalvikvm</code>. This option enables faster allocation by having a
+shorter allocation code path. Since this option requires using either the SS or
+GSS GC types, which have rather long pauses, it is not enabled by default.</p>
+
+<h2 id=performance>Performance</h2>
+
+<p>There are two main tools that can be used to measure GC performance. GC timing
+dumps and systrace. The most visual way to measure GC performance problems
+would be to use systrace to determine which GCs are causing long pauses or
+preempting application threads. Although the ART GC is relatively efficient,
+there are still a few ways to get performance problems through excessive
+allocations or bad mutator behavior.</p>
+
+<h3 id=ergonomics>Ergonomics</h3>
+
+<p>Compared to Dalvik, ART has a few key differences regarding GC ergonomics. One
+of the major improvements compared to Dalvik is no longer having GC for alloc
+in cases where we start the concurrent GC later than needed. However, there is
+one downside to this, not blocking on the GC can cause the heap to grow more
+than Dalvik in some circumstances. Fortunately, ART has heap compaction, which
+mitigates this issue by defragmenting the heap when the process changes to a
+background process state.</p>
+
+<p>The CMS GC ergonomics have two types of GCs that are regularly run. Ideally,
+the GC ergonomics will run the generational sticky CMS more often than the
+partial CMS. The GC does sticky CMS until the throughput (calculated by bytes
+freed / second of GC duration) of the last GC is less than the mean throughput
+of partial CMS. When this occurs, the ergonomics plan the next concurrent GC to
+be a partial CMS instead of sticky CMS. After the partial CMS completes, the
+ergonomics changes the next GC back to sticky CMS. One key factor that makes
+the ergonomics work is that sticky CMS doesn’t adjust the heap footprint limit
+after it completes. This causes sticky CMS to happen more and more often until
+the throughput is lower than partial CMS, which ends up growing the heap.</p>
+
+<h3 id=using_sigquit_to_obtain_gc_performance_info>Using SIGQUIT to obtain GC performance info</h3>
+
+<p>It is possible to get GC performance timings for apps by sending SIGQUIT to
+already running apps or passing in -<code>XX:DumpGCPerformanceOnShutdown</code>
+to <code>dalvikvm</code> when starting a command line program. When an app gets
+the ANR request signal (SIGQUIT) it dumps information related to its locks,
+thread stacks, and GC performance.</p>
+
+<p>The way to get GC timing dumps is to use:<br>
+<code>$ adb shell kill -S QUIT <pid></code></p>
+
+<p>This creates a <code>traces.txt</code> file in <code>/data/anr/</code>. This
+file contains some ANR dumps as well as GC timings. You can locate the
+GC timings by searching for: “Dumping cumulative Gc timings” These timings will
+show a few things that may be of interest. It will show the histogram info for
+each GC type’s phases and pauses. The pauses are usually more important to look
+at. For example:</p>
+
+<pre>
+sticky concurrent mark sweep paused: Sum: 5.491ms 99% C.I. 1.464ms-2.133ms Avg: 1.830ms Max: 2.133ms
+</pre>
+
+<p><code>This</code> shows that the average pause was 1.83ms. This should be low enough to not
+cause missed frames in most applications and shouldn’t be a concern.</p>
+
+<p>Another area of interest is time to suspend. What time to suspend measures is
+how long it takes a thread to reach a suspend point after the GC requests that
+it suspends. This time is included in the GC pauses, so it is useful to
+determine if long pauses are caused by the GC being slow or the thread
+suspending slowly. Here is an example of what a normal time to suspend
+resembles on a Nexus 5:</p>
+
+<pre>
+suspend all histogram: Sum: 1.513ms 99% C.I. 3us-546.560us Avg: 47.281us Max: 601us
+</pre>
+
+<p>There are also a few other areas of interest, such as total time spent, GC
+throughput, etc. Examples:</p>
+
+<pre>
+Total time spent in GC: 502.251ms
+Mean GC size throughput: 92MB/s
+Mean GC object throughput: 1.54702e+06 objects/s
+</pre>
+
+<p>Here is an example of how to dump the GC timings of an already running app:
+
+<pre>
+$ adb shell kill -s QUIT <pid>
+$ adb pull /data/anr/traces.txt
+</pre>
+
+<p>At this point the GC timings are inside of traces.txt. Here is example output
+from Google maps:</p>
+
+<pre>
+Start Dumping histograms for 34 iterations for sticky concurrent mark sweep
+ScanGrayAllocSpaceObjects: Sum: 196.174ms 99% C.I. 0.011ms-11.615ms Avg: 1.442ms Max: 14.091ms
+FreeList: Sum: 140.457ms 99% C.I. 6us-1676.749us Avg: 128.505us Max: 9886us
+MarkRootsCheckpoint: Sum: 110.687ms 99% C.I. 0.056ms-9.515ms Avg: 1.627ms Max: 10.280ms
+SweepArray: Sum: 78.727ms 99% C.I. 0.121ms-11.780ms Avg: 2.315ms Max: 12.744ms
+ProcessMarkStack: Sum: 77.825ms 99% C.I. 1.323us-9120us Avg: 576.481us Max: 10185us
+(Paused)ScanGrayObjects: Sum: 32.538ms 99% C.I. 286us-3235.500us Avg: 986us Max: 3434us
+AllocSpaceClearCards: Sum: 30.592ms 99% C.I. 10us-2249.999us Avg: 224.941us Max: 4765us
+MarkConcurrentRoots: Sum: 30.245ms 99% C.I. 3us-3017.999us Avg: 444.779us Max: 3774us
+ReMarkRoots: Sum: 13.144ms 99% C.I. 66us-712us Avg: 386.588us Max: 712us
+ScanGrayImageSpaceObjects: Sum: 13.075ms 99% C.I. 29us-2538.999us Avg: 192.279us Max: 3080us
+MarkingPhase: Sum: 9.743ms 99% C.I. 170us-518us Avg: 286.558us Max: 518us
+SweepSystemWeaks: Sum: 8.046ms 99% C.I. 28us-479us Avg: 236.647us Max: 479us
+MarkNonThreadRoots: Sum: 5.215ms 99% C.I. 31us-698.999us Avg: 76.691us Max: 703us
+ImageModUnionClearCards: Sum: 2.708ms 99% C.I. 26us-92us Avg: 39.823us Max: 92us
+ScanGrayZygoteSpaceObjects: Sum: 2.488ms 99% C.I. 19us-250.499us Avg: 37.696us Max: 295us
+ResetStack: Sum: 2.226ms 99% C.I. 24us-449us Avg: 65.470us Max: 452us
+ZygoteModUnionClearCards: Sum: 2.124ms 99% C.I. 18us-233.999us Avg: 32.181us Max: 291us
+FinishPhase: Sum: 1.881ms 99% C.I. 31us-431.999us Avg: 55.323us Max: 466us
+RevokeAllThreadLocalAllocationStacks: Sum: 1.749ms 99% C.I. 8us-349us Avg: 51.441us Max: 377us
+EnqueueFinalizerReferences: Sum: 1.513ms 99% C.I. 3us-201us Avg: 44.500us Max: 201us
+ProcessReferences: Sum: 438us 99% C.I. 3us-212us Avg: 12.882us Max: 212us
+ProcessCards: Sum: 381us 99% C.I. 4us-17us Avg: 5.602us Max: 17us
+PreCleanCards: Sum: 363us 99% C.I. 8us-17us Avg: 10.676us Max: 17us
+ReclaimPhase: Sum: 357us 99% C.I. 7us-91.500us Avg: 10.500us Max: 93us
+(Paused)PausePhase: Sum: 312us 99% C.I. 7us-15us Avg: 9.176us Max: 15us
+SwapBitmaps: Sum: 166us 99% C.I. 4us-8us Avg: 4.882us Max: 8us
+(Paused)ScanGrayAllocSpaceObjects: Sum: 126us 99% C.I. 14us-112us Avg: 63us Max: 112us
+MarkRoots: Sum: 121us 99% C.I. 2us-7us Avg: 3.558us Max: 7us
+(Paused)ScanGrayImageSpaceObjects: Sum: 68us 99% C.I. 68us-68us Avg: 68us Max: 68us
+BindBitmaps: Sum: 50us 99% C.I. 1us-3us Avg: 1.470us Max: 3us
+UnBindBitmaps: Sum: 49us 99% C.I. 1us-3us Avg: 1.441us Max: 3us
+SwapStacks: Sum: 47us 99% C.I. 1us-3us Avg: 1.382us Max: 3us
+RecordFree: Sum: 42us 99% C.I. 1us-3us Avg: 1.235us Max: 3us
+ForwardSoftReferences: Sum: 37us 99% C.I. 1us-2us Avg: 1.121us Max: 2us
+InitializePhase: Sum: 36us 99% C.I. 1us-2us Avg: 1.058us Max: 2us
+FindDefaultSpaceBitmap: Sum: 32us 99% C.I. 250ns-1000ns Avg: 941ns Max: 1000ns
+(Paused)ProcessMarkStack: Sum: 5us 99% C.I. 250ns-3000ns Avg: 147ns Max: 3000ns
+PreSweepingGcVerification: Sum: 0 99% C.I. 0ns-0ns Avg: 0ns Max: 0ns
+Done Dumping histograms
+sticky concurrent mark sweep paused: Sum: 63.268ms 99% C.I. 0.308ms-8.405ms
+Avg: 1.860ms Max: 8.883ms
+sticky concurrent mark sweep total time: 763.787ms mean time: 22.464ms
+sticky concurrent mark sweep freed: 1072342 objects with total size 75MB
+sticky concurrent mark sweep throughput: 1.40543e+06/s / 98MB/s
+Total time spent in GC: 4.805s
+Mean GC size throughput: 18MB/s
+Mean GC object throughput: 330899 objects/s
+Total number of allocations 2015049
+Total bytes allocated 177MB
+Free memory 4MB
+Free memory until GC 4MB
+Free memory until OOME 425MB
+Total memory 90MB
+Max memory 512MB
+Zygote space size 4MB
+Total mutator paused time: 229.566ms
+Total time waiting for GC to complete: 187.655us
+</pre>
+
+<h2 id=tools_for_analyzing_gc_correctness_problems>Tools for analyzing GC correctness problems</h2>
+
+<p>There are various things that can cause crashes inside of ART. Crashes that
+occur reading or writing to object fields may indicate heap corruption. If the
+GC crashes when it is running, it could also point to heap corruption. There
+are various things that can cause heap corruption, the most common cause is
+probably incorrect app code. Fortunately, there are tools to debug GC and
+heap-related crashes. These include the heap verification options specified
+above, valgrind, and CheckJNI.</p>
+
+<h3 id=checkjni>CheckJNI</h3>
+
+<p>Another way to verify app behavior is to use CheckJNI. CheckJNI is a mode that
+adds additional JNI checks; these aren’t enabled by default due to performance
+reasons. The checks will catch a few errors that could cause heap corruption
+such as using invalid/stale local and global references. Here is how to enable
+CheckJNI:</p>
+
+<pre>
+$ adb shell setprop dalvik.vm.checkjni true
+</pre>
+
+<p>Forcecopy mode is another part of CheckJNI that is very useful for detecting
+writes past the end of array regions. When enabled, forcecopy causes the array
+access JNI functions to always return copies with red zones. A <em>red
+zone</em> is a region at the end/start of the returned pointer that has a
+special value, which is verified when the array is released. If the values in
+the red zone don’t match what is expected, this usually means a buffer overrun
+or underrun occurred. This would cause CheckJNI to abort. Here is how to enable
+forcecopy mode:</p>
+
+<pre>
+$ adb shell setprop dalvik.vm.jniopts forcecopy
+</pre>
+
+<p>One example of an error that CheckJNI should catch is writing past the end of
+an array obtained from <code>GetPrimitiveArrayCritical</code>. This operation
+would very likely corrupt the Java heap. If the write is
+within the CheckJNI red zone area, then CheckJNI would catch the issue when the
+corresponding <code>ReleasePrimitiveArrayCritical</code> is called. Otherwise,
+the write will end up corrupting some random object in
+the Java heap and possibly causing a future GC crash. If the corrupted memory
+is a reference field, then the GC may catch the error and print a “<em>Tried to
+mark <ptr> not contained by any spaces</em>” error.</p>
+
+<p>This error occurs when the GC attempts to mark an object for which it can’t
+find a space. After this check fails, the GC traverses the roots and tries to
+see if the invalid object is a root. From here, there are two options: The
+object is a root or a non-root object.</p>
+
+<h3 id=valgrind>Valgrind</h3>
+
+<p>The ART heap supports optional valgrind instrumentation, which provides a
+way to detect reads and writes to and from an invalid heap address. ART detects
+when the app is running under valgrind and inserts red zones before and after
+each object allocation. If there are any reads or writes to these red zones,
+valgrind prints an error. One example of when this could happen is if you read
+or write past the end of an array’s elements while using direct array access
+through JNI. Since the AOT compilers use implicit null checks, it is
+recommended to use eng builds for running valgrind. Another thing to note is
+that valgrind is orders of magnitude slower than normal execution.</p>
+
+<p>Here is an example use:</p>
+
+<pre>
+# build and install
+$ mmm external/valgrind
+$ adb remount && adb sync
+# disable selinux
+$ adb shell setenforce 0
+$ adb shell setprop wrap.com.android.calculator2
+"TMPDIR=/data/data/com.android.calculator2 logwrapper valgrind"
+# push symbols
+$ adb shell mkdir /data/local/symbols
+$ adb push $OUT/symbols /data/local/symbols
+$ adb logcat
+</pre>
+
+
+<h3 id=invalid_root_example>Invalid root example</h3>
+
+<p>In the case where the object is actually an invalid root, it will print some
+useful information:
+<code>art E 5955 5955 art/runtime/gc/collector/mark_sweep.cc:383] Tried to mark 0x2
+not contained by any spaces</code></p>
+
+<pre>
+art E 5955 5955 art/runtime/gc/collector/mark_sweep.cc:384] Attempting see if
+it's a bad root
+art E 5955 5955 art/runtime/gc/collector/mark_sweep.cc:485] Found invalid
+root: 0x2
+art E 5955 5955 art/runtime/gc/collector/mark_sweep.cc:486]
+Type=RootJavaFrame thread_id=1 location=Visiting method 'java.lang.Object
+com.google.gwt.corp.collections.JavaReadableJsArray.get(int)' at dex PC 0x0002
+(native PC 0xf19609d9) vreg=1
+</pre>
+
+<p>In this case, <code>vreg 1</code> inside of
+<code>com.google.gwt.corp.collections.JavaReadableJsArray.get</code> is
+supposed to contain a heap reference but actually contains an invalid pointer
+of address <code>0x2</code>. This is clearly an invalid root. The next step to
+debug this issue would be to use <code>oatdump</code> on the oat file and look
+at the method that has the invalid root. In this case, the error turned out to
+be a compiler bug in the x86 backend. Here is the changelist that fixed it: <a
+href="https://android-review.googlesource.com/#/c/133932/">https://android-review.googlesource.com/#/c/133932/</a></p>
+
+<h3 id=corrupted_object_example>Corrupted object example</h3>
+
+<p>In the case where the object isn’t a root, output similar to the following
+prints:</p>
+
+<pre>
+01-15 12:38:00.196 1217 1238 E art : Attempting see if it's a bad root
+01-15 12:38:00.196 1217 1238 F art :
+art/runtime/gc/collector/mark_sweep.cc:381] Can't mark invalid object
+</pre>
+
+<p>When heap corruption isn’t an invalid root, it is unfortunately hard to debug.
+This error message indicates that there was at least one object in the heap
+that was pointing to the invalid object.</p>
diff --git a/src/devices/tech/power/batterystats.jd b/src/devices/tech/power/batterystats.jd
index 11b0b48..d42bc33 100644
--- a/src/devices/tech/power/batterystats.jd
+++ b/src/devices/tech/power/batterystats.jd
@@ -42,41 +42,67 @@
<li>App UID aggregated statistics</li>
</ul>
- <p class="note">You can use the <a href=
- "https://github.com/google/battery-historian">Battery Historian</a> tool on
- the output of the dumpsys command to generate an HTML visualization of
- power-related events from the logs. This information makes it easier for
- you to understand and diagnose any battery-related issues.</p>
+ <p>Use the <a href="https://github.com/google/battery-historian">Battery
+ Historian</a> tool on the output of the dumpsys command to generate an HTML
+ visualization of power-related events from the logs. This information makes it
+ easier to understand and diagnose battery-related issues.</p>
- <h2 id="command-line_options">Command line options</h2>
-
- <p>Use the <code>--help</code> option to learn about the various options
- for tailoring the output.</p>
-
- <p>Use the <code>--checkin</code> option to get the results in
- machine-readable csv format.</p>
-
- <p>To print battery usage statistics for a given app package since the
- device was last charged, run this command:</p>
+ <h2 id="command-line_options">Command input</h2>
+ <p>The basic <code>batterystats</code> command is:</p>
<pre class="prettyprint">
-$ adb shell dumpsys batterystats --charged <package-name>
- </pre>
-
- <h2 id="sample_input">Input</h2>
-
- <p>To print battery usage statistics for all apps since the device was last
- charged, in machine-readable format, run this command:</p>
+$ adb shell dumpsys batterystats</pre>
+ <p>Supported options:</p>
+ <ul>
+ <li><code>--help</code> displays additional options for tailoring the output.
+ </li>
+ <li><code>--checkin</code> exports results in machine-readable csv format.
+ </li>
+ </ul>
+ <p>For example, to print battery usage statistics in csv format for all apps
+ since the device was last charged, run the command:</p>
<pre class="prettyprint">
-$ adb shell dumpsys batterystats --charged --checkin
- </pre>
+$ adb shell dumpsys batterystats --charged --checkin</pre>
+ <p>You can also specify a package name to get statistics for a single app. For
+ example, to print battery usage statistics for a given app package
+ since the device was last charged, run the command:</p>
+ <pre class="prettyprint">
+$ adb shell dumpsys batterystats --charged <package-name></pre>
- <h2 id="output">Output</h2>
+ <h2 id="output">Command output</h2>
- <p>The output looks like this:</p>
+ <p>The <code>batterystats</code> command generates aggregated observations
+ about battery use on the device since it was last charged. Observations may be
+ per-UID or system-level; data is selected for inclusion based on its
+ usefulness in analyzing battery performance. Output includes one (1) entry
+ per observation, and each entry consists of a comma-separated list of values
+ in the format:
+ <em>int</em>,<em>uid</em>,<em>mode</em>,<em>section</em>,<em>fields</em>
+ (one or more).</p>
- <p>$ adb shell dumpsys batterystats --charged --checkin</p>
+ <p>The first four values correspond to the following:</p>
- <pre class="no-pretty=print">
+ <ul>
+ <li>Dummy integer</li>
+
+ <li>UID</li>
+
+ <li>Aggregation mode
+
+ <ul>
+ <li>"i" for information not tied to charged/uncharged status.</li>
+ <li>"l" for --charged (usage since last charge).</li>
+ <li>"u" for --unplugged (usage since last unplugged). Deprecated in
+ Android 5.1.1.</li>
+ </ul>
+ </li>
+
+ <li><a href="#interpreting_the_output">Section identifier</a>, which
+ determines how to interpret subsequent values in the line.</li>
+ </ul>
+
+<p>Sample output:</p>
+
+ <pre class="no-pretty-print">
9,0,i,vers,11,116,K,L 9,0,i,uid,1000,android
9,0,i,uid,1000,com.android.providers.settings
9,0,i,uid,1000,com.android.inputdevices
@@ -177,6 +203,8 @@
9,0,l,pwi,idle,8.73 9,0,l,pwi,uid,5.46 9,1000,l,pwi,uid,5.11
9,0,l,pwi,wifi,3.28 9,10019,l,pwi,uid,0.847 9,10069,l,pwi,uid,0.408
9,0,l,pwi,scrn,0.385 9,10034,l,pwi,uid,0.322 9,10025,l,pwi,uid,0.185
+ 9,0,l,pwi,blue,0.0273
+ 9,0,l,pwi,cell,14.0
9,10002,l,pwi,uid,0.180 9,10023,l,pwi,uid,0.168 9,1001,l,pwi,uid,0.0297
9,10068,l,pwi,uid,0.0296 9,10057,l,pwi,uid,0.0234 9,1027,l,pwi,uid,0.0157
9,10079,l,pwi,uid,0.00905 9,10054,l,pwi,uid,0.00527
@@ -227,811 +255,320 @@
9,10068,l,nt,0,0,11929,8383,0,0,50,47,0,0
9,10069,l,nt,0,0,41553,22886,0,0,85,91,0,0</pre>
- <h2 id="interpreting_the_output">Interpreting the output</h2>
+ <h2 id="interpreting_the_output">Section identifiers</h2>
- <p>The sample output is in CSV format. Each line in the output contains
- statistics related to battery usage.</p>
+ <p>Command output for <code>batterystats</code> supports the following
+ sections:</p>
- <p>The first four values in each line correspond to the following:</p>
+ <table id="batterystats-section-ids">
- <ul>
- <li>Dummy integer</li>
-
- <li>UID</li>
-
- <li>Aggregation mode
-
- <ul>
- <li>"l" for --charged, means usage since last charge.</li>
- <li>"u" for --unplugged, which means usage since last unplugged.</li>
- <li>"i" for information that is not
- tied to charged/uncharged status.</li>
- </ul>
- </li>
-
- <li>Section identifier, which determines how to interpret the fifth
- value and the following ones in the line.</li>
- </ul>
-
- <p>Currently, there are 41 sections and the interpretation for each section
- is shown in the following table:</p>
-
- <table>
<tr>
- <td>
- <p><strong>Order</strong></p>
- </td>
-
- <td class="tab0">
- <p><strong>Section Identifier</strong></p>
- </td>
-
- <td class="tab0">
- <p><strong>Description</strong></p>
- </td>
-
- <td class="tab0">
- <p><strong>Remaining Fields</strong></p>
- </td>
+ <th width="10%">Section Identifier</th>
+ <th width="20%">Description</th>
+ <th width="70%">Remaining Fields</th>
</tr>
<tr>
- <td>
- <p>1</p>
- </td>
-
- <td class="tab0">
- <p>vers</p>
- </td>
-
- <td class="tab0">
- <p>Version</p>
- </td>
-
- <td class="tab0">
- <p>checkin version, parcel version, start platform version, end
- platform version</p>
- </td>
+ <td><p>vers</p></td>
+ <td><p>Version</p></td>
+ <td><p>checkin version, parcel version, start platform version, end
+ platform version</p></td>
</tr>
<tr>
- <td>
- <p>2</p>
- </td>
-
- <td class="tab0">
- <p>uid</p>
- </td>
-
- <td class="tab0">
- <p>UID</p>
- </td>
-
- <td class="tab0">
- <p>uid, package name</p>
- </td>
+ <td><p>uid</p></td>
+ <td><p>UID</p></td>
+ <td><p>uid, package name</p></td>
</tr>
<tr>
- <td>
- <p>3</p>
- </td>
-
- <td class="tab0">
- <p>apk</p>
- </td>
-
- <td class="tab0">
- <p>APK</p>
- </td>
-
- <td class="tab0">
- <p>wakeups, APK, service, start time, starts, launches</p>
- </td>
+ <td><p>apk</p></td>
+ <td><p>APK</p></td>
+ <td><p>wakeups, APK, service, start time, starts, launches</p></td>
</tr>
<tr>
- <td>
- <p>4</p>
- </td>
-
- <td class="tab0">
- <p>pr</p>
- </td>
-
- <td class="tab0">
- <p>Process</p>
- </td>
-
- <td class="tab0">
- <p>process, user, system, foreground, starts</p>
- </td>
+ <td><p>pr</p></td>
+ <td><p>Process</p></td>
+ <td><p>process, user, system, foreground, starts</p></td>
</tr>
<tr>
- <td>
- <p>5</p>
- </td>
-
- <td class="tab0">
- <p>sr</p>
- </td>
-
- <td class="tab0">
- <p>Sensor</p>
- </td>
-
- <td class="tab0">
- <p>sensor number, time, count</p>
- </td>
+ <td><p>sr</p></td>
+ <td><p>Sensor</p></td>
+ <td><p>sensor number, time, count</p></td>
</tr>
<tr>
- <td>
- <p>6</p>
- </td>
-
- <td class="tab0">
- <p>vib</p>
- </td>
-
- <td class="tab0">
- <p>Vibrator</p>
- </td>
-
- <td class="tab0">
- <p>time, count</p>
- </td>
+ <td><p>vib</p></td>
+ <td><p>Vibrator</p></td>
+ <td><p>time, count</p></td>
</tr>
<tr>
- <td>
- <p>7</p>
- </td>
-
- <td class="tab0">
- <p>fg</p>
- </td>
-
- <td class="tab0">
- <p>Foreground</p>
- </td>
-
- <td class="tab0">
- <p>time, count</p>
- </td>
+ <td><p>fg</p></td>
+ <td><p>Foreground</p></td>
+ <td><p>time, count</p></td>
</tr>
<tr>
- <td>
- <p>8</p>
- </td>
-
- <td class="tab0">
- <p>st</p>
- </td>
-
- <td class="tab0">
- <p>State Time</p>
- </td>
-
- <td class="tab0">
- <p>foreground, active, running</p>
- </td>
+ <td><p>st</p></td>
+ <td><p>State Time</p></td>
+ <td><p>foreground, active, running</p></td>
</tr>
<tr>
- <td>
- <p>9</p>
- </td>
-
- <td class="tab0">
- <p>wl</p>
- </td>
-
- <td class="tab0">
- <p>Wake lock</p>
- </td>
-
- <td class="tab0">
- <p>wake lock, full time, 'f', full count, partial time, 'p', partial
- count, window time, 'w', window count</p>
- </td>
+ <td><p>wl</p></td>
+ <td><p>Wake lock</p></td>
+ <td><p>wake lock, full time, 'f', full count, partial time, 'p', partial
+ count, window time, 'w', window count</p></td>
</tr>
<tr>
- <td>
- <p>10</p>
- </td>
-
- <td class="tab0">
- <p>sy</p>
- </td>
-
- <td class="tab0">
- <p>Sync</p>
- </td>
-
- <td class="tab0">
- <p>sync, time, count</p>
- </td>
+ <td><p>sy</p></td>
+ <td><p>Sync</p></td>
+ <td><p>sync, time, count</p></td>
</tr>
<tr>
- <td>
- <p>11</p>
- </td>
-
- <td class="tab0">
- <p>jb</p>
- </td>
-
- <td class="tab0">
- <p>Job</p>
- </td>
-
- <td class="tab0">
- <p>job, time, count</p>
- </td>
+ <td><p>jb</p></td>
+ <td><p>Job</p></td>
+ <td><p>job, time, count</p></td>
</tr>
<tr>
- <td>
- <p>12</p>
- </td>
-
- <td class="tab0">
- <p>kwl</p>
- </td>
-
- <td class="tab0">
- <p>Kernel Wake Lock</p>
- </td>
-
- <td class="tab0">
- <p>kernel wake lock, time, count</p>
- </td>
+ <td><p>kwl</p></td>
+ <td><p>Kernel Wake Lock</p></td>
+ <td><p>kernel wake lock, time, count</p></td>
</tr>
<tr>
- <td>
- <p>13</p>
- </td>
-
- <td class="tab0">
- <p>wr</p>
- </td>
-
- <td class="tab0">
- <p>Wakeup Reason</p>
- </td>
-
- <td class="tab0">
- <p>wakeup reason, time, count</p>
- </td>
+ <td><p>wr</p></td>
+ <td><p>Wakeup Reason</p></td>
+ <td><p>wakeup reason, time, count</p></td>
</tr>
<tr>
- <td>
- <p>14</p>
- </td>
-
- <td class="tab0">
- <p>nt</p>
- </td>
-
- <td class="tab0">
- <p>Network</p>
- </td>
-
- <td class="tab0">
- <p>mobile bytes RX, mobile bytes TX, Wi-Fi bytes RX, Wi-Fi bytes TX,
+ <td><p>nt</p></td>
+ <td><p>Network</p></td>
+ <td><p>mobile bytes RX, mobile bytes TX, Wi-Fi bytes RX, Wi-Fi bytes TX,
mobile packets RX, mobile packets TX, Wi-Fi packets RX, Wi-Fi packets
- TX, mobile active time, mobile active count</p>
- </td>
+ TX, mobile active time, mobile active count</p></td>
</tr>
<tr>
- <td>
- <p>15</p>
- </td>
-
- <td class="tab0">
- <p>ua</p>
- </td>
-
- <td class="tab0">
- <p>User Activity</p>
- </td>
-
- <td class="tab0">
- <p>other, button, touch</p>
- </td>
+ <td><p>ua</p></td>
+ <td><p>User Activity</p></td>
+ <td><p>other, button, touch</p></td>
</tr>
<tr>
- <td>
- <p>16</p>
- </td>
-
- <td class="tab0">
- <p>bt</p>
- </td>
-
- <td class="tab0">
- <p>Battery</p>
- </td>
-
- <td class="tab0">
- <p>start count, battery realtime, battery uptime, total realtime,
+ <td><p>bt</p></td>
+ <td><p>Battery</p></td>
+ <td><p>start count, battery realtime, battery uptime, total realtime,
total uptime, start clock time, battery screen off realtime, battery
- screen off uptime</p>
+ screen off uptime</p></td>
+ </tr>
+
+ <tr>
+ <td><p>dc</p></td>
+ <td><p>Battery Discharge</p></td>
+ <td><p>low, high, screen on, screen off</p></td>
+ </tr>
+
+ <tr>
+ <td><p>lv</p></td>
+ <td><p>Battery Level</p></td>
+ <td><p>start level, current level</p></td>
+ </tr>
+
+ <tr>
+ <td><p>wfl</p></td>
+ <td><p>Wi-Fi</p></td>
+ <td><p>full Wi-Fi lock on time, Wi-Fi scan time, Wi-Fi running time, Wi-Fi
+ scan count, Wi-Fi idle time, Wi-Fi receive time, Wi-Fi transmit time</p>
</td>
</tr>
<tr>
- <td>
- <p>17</p>
- </td>
+ <td><p>gwfl</p></td>
+ <td><p>Global Wi-Fi</p></td>
+ <td><p>Wi-Fi on time, Wi-Fi running time, Wi-Fi idle time, Wi-Fi receive
+ time, Wi-Fi transmit time, Wi-Fi power (mAh)</p></td>
+ </tr>
- <td class="tab0">
- <p>dc</p>
- </td>
-
- <td class="tab0">
- <p>Battery Discharge</p>
- </td>
-
- <td class="tab0">
- <p>low, high, screen on, screen off</p>
+ <tr>
+ <td><p>gble</p></td>
+ <td><p>Global Bluetooth</p></td>
+ <td><p>BT idle time, BT receive time, BT transmit time, BT power (mAh)</p>
</td>
</tr>
<tr>
- <td>
- <p>18</p>
- </td>
-
- <td class="tab0">
- <p>lv</p>
- </td>
-
- <td class="tab0">
- <p>Battery Level</p>
- </td>
-
- <td class="tab0">
- <p>start level, current level</p>
- </td>
+ <td><p>m</p></td>
+ <td><p>Misc</p></td>
+ <td><p>screen on time, phone on time, full wakelock time total, partial
+ wakelock time total, mobile radio active time, mobile radio active
+ adjusted time, interactive time, power save mode enabled time,
+ connectivity changes, device idle mode enabled time, device idle mode
+ enabled count, device idling time, device idling count, mobile radio
+ active count, mobile radio active unknown time</p></td>
</tr>
<tr>
- <td>
- <p>19</p>
- </td>
-
- <td class="tab0">
- <p>wfl</p>
- </td>
-
- <td class="tab0">
- <p>Wi-Fi</p>
- </td>
-
- <td class="tab0">
- <p>full Wi-Fi lock on time, Wi-Fi scan time, Wi-Fi running time</p>
- </td>
- </tr>
-
- <tr>
- <td>
- <p>20</p>
- </td>
-
- <td class="tab0">
- <p>m</p>
- </td>
-
- <td class="tab0">
- <p>Misc</p>
- </td>
-
- <td class="tab0">
- <p>screen on time, phone on time, Wi-Fi on time, Wi-Fi running time,
- Bluetooth on time, mobile RX total bytes, mobile TX total bytes,
- Wi-Fi RX total bytes, Wi-Fi TX total bytes, full wake lock time
- total, partial wake lock time total, legacy input event count, mobile
- radio active time, mobile radio active adjusted time, interactive
- time, low-power mode enabled time</p>
- </td>
- </tr>
-
- <tr>
- <td>
- <p>21</p>
- </td>
-
- <td class="tab0">
- <p>gn</p>
- </td>
-
- <td class="tab0">
- <p>Global Network</p>
- </td>
-
- <td class="tab0">
- <p>mobile RX total bytes, mobile TX total bytes, Wi-Fi RX total
+ <td><p>gn</p></td>
+ <td><p>Global Network</p></td>
+ <td><p>mobile RX total bytes, mobile TX total bytes, Wi-Fi RX total
bytes, Wi-Fi TX total bytes, mobile RX total packets, mobile TX total
- packets, Wi-Fi RX total packets, Wi-Fi TX total packets</p>
- </td>
+ packets, Wi-Fi RX total packets, Wi-Fi TX total packets</p></td>
</tr>
<tr>
- <td>
- <p>22</p>
- </td>
-
- <td class="tab0">
- <p>br</p>
- </td>
-
- <td class="tab0">
- <p>Screen Brightness</p>
- </td>
-
- <td class="tab0">
- <p>dark, dim, medium, light, bright</p>
- </td>
+ <td><p>br</p></td>
+ <td><p>Screen Brightness</p></td>
+ <td><p>dark, dim, medium, light, bright</p></td>
</tr>
<tr>
- <td>
- <p>23</p>
- </td>
-
- <td class="tab0">
- <p>sst</p>
- </td>
-
- <td class="tab0">
- <p>Signal Scanning Time</p>
- </td>
-
- <td class="tab0">
- <p>signal scanning time</p>
- </td>
+ <td><p>sst</p></td>
+ <td><p>Signal Scanning Time</p></td>
+ <td><p>signal scanning time</p></td>
</tr>
<tr>
- <td>
- <p>24</p>
- </td>
-
- <td class="tab0">
- <p>sgt</p>
- </td>
-
- <td class="tab0">
- <p>Signal Strength Time</p>
- </td>
-
- <td class="tab0">
- <p>none, poor, moderate, good, great</p>
- </td>
+ <td><p>sgt</p></td>
+ <td><p>Signal Strength Time</p></td>
+ <td><p>none, poor, moderate, good, great</p></td>
</tr>
<tr>
- <td>
- <p>25</p>
- </td>
-
- <td class="tab0">
- <p>sgc</p>
- </td>
-
- <td class="tab0">
- <p>Signal Strength Count</p>
- </td>
-
- <td class="tab0">
- <p>none, poor, moderate, good, great</p>
- </td>
+ <td><p>sgc</p></td>
+ <td><p>Signal Strength Count</p></td>
+ <td><p>none, poor, moderate, good, great</p></td>
</tr>
<tr>
- <td>
- <p>26</p>
- </td>
-
- <td class="tab0">
- <p>dct</p>
- </td>
-
- <td class="tab0">
- <p>Data Connection Time</p>
- </td>
-
- <td class="tab0">
- <p>none, GPRS, EDGE, UMTS, CDMA, EVDO_0, EVDO_A, 1xRTT, HSDPA, HSUPA,
- HSPA, IDEN, EVDO_B, LTE, EHRPD, HSPAP, other</p>
- </td>
+ <td><p>dct</p></td>
+ <td><p>Data Connection Time</p></td>
+ <td><p>none, GPRS, EDGE, UMTS, CDMA, EVDO_0, EVDO_A, 1xRTT, HSDPA, HSUPA,
+ HSPA, IDEN, EVDO_B, LTE, EHRPD, HSPAP, other</p></td>
</tr>
<tr>
- <td>
- <p>27</p>
- </td>
-
- <td class="tab0">
- <p>dcc</p>
- </td>
-
- <td class="tab0">
- <p>Data Connection Count</p>
- </td>
-
- <td class="tab0">
- <p>none, GPRS, EDGE, UMTS, CDMA, EVDO_0, EVDO_A, 1xRTT, HSDPA, HSUPA,
- HSPA, IDEN, EVDO_B, LTE, EHRPD, HSPAP, other</p>
- </td>
+ <td><p>dcc</p></td>
+ <td><p>Data Connection Count</p></td>
+ <td><p>none, GPRS, EDGE, UMTS, CDMA, EVDO_0, EVDO_A, 1xRTT, HSDPA, HSUPA,
+ HSPA, IDEN, EVDO_B, LTE, EHRPD, HSPAP, other</p></td>
</tr>
<tr>
- <td>
- <p>28</p>
- </td>
-
- <td class="tab0">
- <p>wst</p>
- </td>
-
- <td class="tab0">
- <p>Wi-Fi State Time</p>
- </td>
-
- <td class="tab0">
- <p>off, off scanning, on no networks, on disconnected, on connected
- STA, on connected P2P, on connected STA P2P, soft AP</p>
- </td>
+ <td><p>wst</p></td>
+ <td><p>Wi-Fi State Time</p></td>
+ <td><p>off, off scanning, on no networks, on disconnected, on connected
+ STA, on connected P2P, on connected STA P2P, soft AP</p></td>
</tr>
<tr>
- <td>
- <p>29</p>
- </td>
-
- <td class="tab0">
- <p>wsc</p>
- </td>
-
- <td class="tab0">
- <p>Wi-Fi State Count</p>
- </td>
-
- <td class="tab0">
- <p>off, off scanning, on no networks, on disconnected, on connected
- STA, on connected P2P, on connected STA P2P, soft AP</p>
- </td>
+ <td><p>wsc</p></td>
+ <td><p>Wi-Fi State Count</p></td>
+ <td><p>off, off scanning, on no networks, on disconnected, on connected
+ STA, on connected P2P, on connected STA P2P, soft AP</p></td>
</tr>
<tr>
- <td>
- <p>30</p>
- </td>
-
- <td class="tab0">
- <p>wsst</p>
- </td>
-
- <td class="tab0">
- <p>Wi-Fi Supplicant State Time</p>
- </td>
-
- <td class="tab0">
- <p>invalid, disconnected, interface disabled, inactive, scanning,
+ <td><p>wsst</p></td>
+ <td><p>Wi-Fi Supplicant State Time</p></td>
+ <td><p>invalid, disconnected, interface disabled, inactive, scanning,
authenticating, associating, associated, four-way handshake, group
- handshake, completed, dormant, uninitialized</p>
- </td>
+ handshake, completed, dormant, uninitialized</p></td>
</tr>
<tr>
- <td>
- <p>31</p>
- </td>
-
- <td class="tab0">
- <p>wssc</p>
- </td>
-
- <td class="tab0">
- <p>Wi-Fi Supplicant State Count</p>
- </td>
-
- <td class="tab0">
- <p>invalid, disconnected, interface disabled, inactive, scanning,
+ <td><p>wssc</p></td>
+ <td><p>Wi-Fi Supplicant State Count</p></td>
+ <td><p>invalid, disconnected, interface disabled, inactive, scanning,
authenticating, associating, associated, four-way handshake, group
- handshake, completed, dormant, uninitialized</p>
- </td>
+ handshake, completed, dormant, uninitialized</p></td>
</tr>
<tr>
- <td>
- <p>32</p>
- </td>
-
- <td class="tab0">
- <p>wsgt</p>
- </td>
-
- <td class="tab0">
- <p>Wi-Fi Signal Strength Time</p>
- </td>
-
- <td class="tab0">
- <p>none, poor, moderate, good, great</p>
- </td>
+ <td><p>wsgt</p></td>
+ <td><p>Wi-Fi Signal Strength Time</p></td>
+ <td><p>none, poor, moderate, good, great</p></td>
</tr>
<tr>
- <td>
- <p>33</p>
- </td>
-
- <td class="tab0">
- <p>wsgc</p>
- </td>
-
- <td class="tab0">
- <p>Wi-Fi Signal Strength Count</p>
- </td>
-
- <td class="tab0">
- <p>none, poor, moderate, good, great</p>
- </td>
+ <td><p>wsgc</p></td>
+ <td><p>Wi-Fi Signal Strength Count</p></td>
+ <td><p>none, poor, moderate, good, great</p></td>
</tr>
<tr>
- <td>
- <p>34</p>
- </td>
+ <td><p>bst</p></td>
+ <td><p>Bluetooth State Time</p></td>
+ <td><p>inactive, low, med, high</p></td>
+ </tr>
- <td class="tab0">
- <p>bst</p>
- </td>
-
- <td class="tab0">
- <p>Bluetooth State Time</p>
- </td>
-
- <td class="tab0">
- <p>inactive, low, med, high</p>
- </td>
+ <tr>
+ <td><p>bsc</p></td>
+ <td><p>Bluetooth State Count</p></td>
+ <td><p>inactive, low, med, high</p></td>
</tr>
<tr>
- <td>
- <p>35</p>
- </td>
-
- <td class="tab0">
- <p>bsc</p>
- </td>
-
- <td class="tab0">
- <p>Bluetooth State Count</p>
- </td>
-
- <td class="tab0">
- <p>inactive, low, med, high</p>
- </td>
+ <td><p>pws</p></td>
+ <td><p>Power Use Summary</p></td>
+ <td><p>battery capacity, computed power, minimum drained power, maximum
+ drained power</p></td>
</tr>
<tr>
- <td>
- <p>36</p>
- </td>
-
- <td class="tab0">
- <p>pws</p>
- </td>
-
- <td class="tab0">
- <p>Power Use Summary</p>
- </td>
-
- <td class="tab0">
- <p>battery capacity, computed power, minimum drained power, maximum
- drained power</p>
- </td>
+ <td><p>pwi</p></td>
+ <td><p>Power Use Item</p></td>
+ <td><p>label, mAh</p></td>
</tr>
<tr>
- <td>
- <p>37</p>
- </td>
-
- <td class="tab0">
- <p>pwi</p>
- </td>
-
- <td class="tab0">
- <p>Power Use Item</p>
- </td>
-
- <td class="tab0">
- <p>label, mAh</p>
- </td>
+ <td><p>dsd</p></td>
+ <td><p>Discharge Step</p></td>
+ <td><p>duration, level, screen, power-save</p></td>
</tr>
<tr>
- <td>
- <p>38</p>
- </td>
-
- <td class="tab0">
- <p>dsd</p>
- </td>
-
- <td class="tab0">
- <p>Discharge Step</p>
- </td>
-
- <td class="tab0">
- <p>duration, level, screen, power-save</p>
- </td>
+ <td><p>csd</p></td>
+ <td><p>Charge Step</p></td>
+ <td><p>duration, level, screen, power-save</p></td>
</tr>
<tr>
- <td>
- <p>39</p>
- </td>
-
- <td class="tab0">
- <p>csd</p>
- </td>
-
- <td class="tab0">
- <p>Charge Step</p>
- </td>
-
- <td class="tab0">
- <p>duration, level, screen, power-save</p>
- </td>
+ <td><p>dtr</p></td>
+ <td><p>Discharge Time Remaining</p></td>
+ <td><p>battery time remaining</p></td>
</tr>
<tr>
- <td>
- <p>40</p>
- </td>
-
- <td class="tab0">
- <p>dtr</p>
- </td>
-
- <td class="tab0">
- <p>Discharge Time Remaining</p>
- </td>
-
- <td class="tab0">
- <p>battery time remaining</p>
- </td>
+ <td><p>ctr</p></td>
+ <td><p>Charge Time Remaining</p></td>
+ <td><p>charge time remaining</p></td>
</tr>
- <tr>
- <td>
- <p>41</p>
- </td>
-
- <td class="tab0">
- <p>ctr</p>
- </td>
-
- <td class="tab0">
- <p>Charge Time Remaining</p>
- </td>
-
- <td class="tab0">
- <p>charge time remaining</p>
- </td>
- </tr>
</table>
+
+<h2 id="wifi-reqs">Wi-Fi, Bluetooth, and cellular usage</h2>
+
+<p>Support for battery usage data on Wi-Fi, Bluetooth, and cellular data
+requires that the device Wi-Fi, Bluetooth, and cellular chipsets implement radio
+support and the chipset firmware passes usage data to the framework. OEMs must
+work with their chipset providers to facilitate in-field firmware updates on
+existing chipsets and compatible firmware on new chipsets.</p>
+
+<p>Additionally, OEMs must continue to configure and submit the power profile
+for their devices. However, when the platform detects that Wi-Fi and Bluetooth
+radio power data is available from the chipset, it uses chipset data instead of
+power profile data (cell radio power data is not yet used).</p>
+
+<p class="note"><strong>Note</strong>: Prior to Android 6.0, power use for Wi-Fi
+radio, Bluetooth radio, and cellular radio was tracked in the <em>m</em> (Misc)
+section category. In Android 6.0 and higher, power use for these components is
+tracked in the <em>pwi</em> (Power Use Item) section with individual labels
+(<em>wifi</em>, <em>blue</em>, <em>cell</em>) for each component.</p>
\ No newline at end of file
diff --git a/src/devices/tech/power/mgmt.jd b/src/devices/tech/power/mgmt.jd
new file mode 100644
index 0000000..51c87e7
--- /dev/null
+++ b/src/devices/tech/power/mgmt.jd
@@ -0,0 +1,261 @@
+page.title=Power Management
+@jd:body
+
+<!--
+ Copyright 2015 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>
+
+<p>Battery life is a perennial user concern. To extend battery life, Android
+continually adds new features and optimizations to help the platform optimize
+the off-charger behavior of applications and devices.</p>
+<p>The Android 6.0 release includes the following improvements to battery life:
+</p>
+
+<ul>
+<li><b><a href="#app-standby">App Standby</b></a>. The platform can now place
+unused applications in App Standby mode, temporarily restricting network access
+and deferring syncs and jobs for those applications.</li>
+<li><b><a href="#doze">Doze</b></a>. The platform now enters a state of deep
+sleep (periodically resuming normal operations) if users have not actively used
+their device (screen off and stationary) for extended periods of time. As this
+feature requires the platform to detect the stationary state, it is available
+only on devices that implement the significant motion detection APIs in the
+Sensor HAL. Doze dramatically improves battery life.</li>
+<li><b><a href="#exempt-apps">Exemptions</b></a>. System apps and cloud
+messaging services preloaded on a device are typically exempted by default. App
+developers can intent their applications into this setting. Users can also
+exempt applications from App Standby and Doze via Settings > Battery >
+Battery optimization > All apps and then selecting the app to turn off (or back
+on) optimization.</li>
+</ul>
+<p>The following sections describe these improvements.</p>
+
+<h2 id="app-standby">App Standby</h2>
+<p>App Standby extends battery life by deferring background network activity
+and jobs for applications the user is not actively using.</p>
+
+<h3 id="app-standby-life">App Standby lifecycle</h3>
+<p>The platform detects inactive applications and places them in App Standby
+until the user begins actively engaging with the application.</p>
+
+<table>
+<tbody>
+<tr>
+<th width=33%>Detection</th>
+<th width=33%>During App Standby</th>
+<th width=33%>Exit</th>
+</tr>
+
+<tr>
+<td><p>The platform detects an application is inactive when the device is not
+charging <strong>and</strong> the user has not launched the application directly
+or indirectly for a specific amount of clock time as well as a specific amount
+of screen-on time. (Indirect launches occur when a foreground app accesses a
+service in a second app.)</p></td>
+<td><p>The platform prevents applications from accessing the network more than
+once a day, deferring application syncs and other jobs.</p></td>
+<td><p>The platform exits the app from App Standby when:</p>
+<ul>
+<li>Application becomes active.</li>
+<li>Device is plugged in and charging.</li>
+</ul>
+</td>
+</tr>
+</tbody>
+</table>
+
+<p>Active applications are unaffected by App Standby. An application is active
+when it has:</p>
+<ul>
+<li>A process currently in the foreground (either as an activity or foreground
+service, or in use by another activity or foreground service), such as
+notification listener, accessibility services, live wallpaper, etc.</li>
+<li>A notification viewed by the user, such as in the lock screen or
+notification tray.</li>
+<li>Explicitly been launched by the user.</li>
+</ul>
+<p>An application is inactive if none of the above activities has occurred for
+a period of time.
+</p>
+
+<h3>Testing App Standby</h3>
+<p>You can manually test App Standby using the following ADB commands:</p>
+
+<pre>
+$ adb shell dumpsys battery unplug
+$ adb shell am set-idle packageName true
+$ adb shell am set-idle packageName false
+$ adb shell am get-idle packageName
+</pre>
+
+<h2 id="doze">Doze</h2>
+
+<p>Doze extends battery life by deferring application background CPU and
+network activity when a device is unused for long periods.</p>
+
+<p>Idle devices in Doze periodically enter a maintenance window, during which
+apps can complete pending activities (syncs, jobs, etc.). Doze then resumes sleep
+for a longer period of time, followed by another maintenance window. The
+platform continues the Doze sleep/maintenance sequence, increasing the length of
+idle each time, until a maximum of a few hours of sleep time is reached. At all
+times, a device in Doze remains aware of motion and immediately leaves Doze
+if motion is detected.</p>
+
+<p>System services (such as telephony) and other preloaded services/apps are
+exempted from Doze by default. Users can also exempt specific applications from
+Doze in the Settings menu. By default, Doze is <b>disabled</b> in the Android
+Open Source Project (AOSP). For details on enabling Doze, see
+<a href="#integrate-doze">Integrating Doze</a>.</p>
+
+<h3 id="doze-reqs">Doze requirements</h3>
+
+<p>Doze support requires the following:</p>
+<ul>
+<li>Device implements the
+<a href="http://source.android.com/devices/sensors/sensor-types.html#significant_motion">significant
+motion detector (SMD) APIs</a> in the Sensor HAL. Devices that do not implement
+these APIs cannot support Doze.</li>
+<li>Device has a cloud messaging service, such as
+<a href="https://developers.google.com/cloud-messaging/">Google Cloud Messaging
+(GCM).</a> This enables the device to know when to wake from Doze.</li>
+</ul>
+
+<h3 id="doze-life">Doze lifecycle</h3>
+
+<p>The Doze lifecycle begins when the platform detects the device is idle and
+ends when the device exits Doze mode.</p>
+
+<table>
+<tbody>
+<tr>
+<th width=33%>Detection</td>
+<th width=33%>During Doze</th>
+<th width=33%>Exit</th>
+</tr>
+<tr>
+<td><p>The platform detects a device is idle when:</p>
+<ul>
+<li>Device is stationary (using significant motion detector).</li>
+<li>Device screen is off for some amount of time.</li>
+</ul>
+<p>Doze mode does not engage when the device is plugged into a power charger.
+</p>
+</td>
+<td><p>The platform attempts to keep the system in a sleep state, periodically
+resuming normal operations during a maintenance window then returning the device
+to sleep for longer repeating periods. During the sleep state, the following
+restrictions are active:</p>
+<ul>
+<li>Apps not allowed network access.</li>
+<li>App wakelocks ignored.</li>
+<li>Alarms deferred. Excludes alarm clock alarms and alarms set using
+<code>setAndAllowWhileIdle()</code>. This exemption is intended for apps (such
+as Calendar) that must show event reminder notifications.</li>
+<li>Wi-Fi scans not performed.</li>
+<li>SyncAdapter syncs and JobScheduler jobs deferred until the next maintenance
+window.</li>
+<li>Apps receiving SMS and MMS messages are put on a temporary whitelist so
+they can complete their processing.</li>
+</ul>
+</td>
+<td><p>The platform exits the device from Doze when it detects:</p>
+<ul>
+<li>User interaction with device.</li>
+<li>Device movement.</li>
+<li>Device screen turns on.</li>
+<li>Imminent AlarmClock alarm.</li>
+</ul>
+<p>Notifications do not cause the device to exit from Doze.</p>
+</td>
+</tr>
+</tbody>
+</table>
+
+<h3 id="doze-interactions">Interaction with App Standby</h3>
+<ul>
+<li>Time spent in Doze does not count towards App Standby.</li>
+<li>While the device is in Doze, idle applications are allowed to perform normal
+operations at least once a day.</li>
+</ul>
+
+<h3 id="integrate-doze">Integrating Doze</h3>
+<p>To enable Doze for a device, perform the following tasks:</p>
+
+<ol>
+<li>Confirm the device supports
+<a href="http://source.android.com/devices/sensors/sensor-types.html#significant_motion">SENSOR_TYPE_SIGNIFICANT_MOTION
+</a>. If the device does not support this sensor, it cannot support Doze.</li>
+<li>Confirm the device has a cloud messaging service installed.</li>
+<li>In the device overlay config file
+<code>overlay/frameworks/base/core/res/res/values/config.xml</code>, set
+<code>config_enableAutoPowerModes</code> to <b>true</b>:
+<pre>
+bool name="config_enableAutoPowerModes">true</bool>
+</pre>
+<br>In AOSP, this parameter is set to false (Doze disabled) by default.<br>
+</li>
+<li>Confirm that preloaded apps and services:
+<ul>
+<li>Use the new
+<a href="https://developer.android.com/preview/behavior-changes.html#behavior-power">power-saving
+optimization guidelines</a>. For details, see <a href="#test-apps">Testing and
+optimizing applications</a>.
+<p><b>OR</b></p>
+<li>Are exempted from Doze and App Standby. For details, see
+<a href="#exempt-apps">Exempting applications</a>.</li>
+</ul>
+</li>
+<li>Confirm the necessary services are exempted from Doze.</a>
+</li>
+</ol>
+
+<h4 id="test-apps">Testing and optimizing applications</h4>
+<p>Test all applications (especially preloaded applications) in Doze mode. For
+details, refer to
+<a href="https://developer.android.com/preview/testing/guide.html#doze-standby">Testing
+Doze and App Standby</a>.</p>
+
+<p class="note"><b>Note</b>: MMS/SMS/Telephony services function independently
+of Doze and will always wake client apps even while the device remains in Doze
+mode.</p>
+
+<h2 id="exempt-apps">Exempting applications</h2>
+<p>You can exempt applications from being subject to Doze or App Standby.</p>
+
+<p class="warning"><b>Warning</b>: Do not exempt apps to avoid testing and
+optimizing. Unnecessary exemptions undermine the benefits of Doze and App
+Standby and can compromise the user experience, so we strongly suggest
+minimizing such exemptions as they allow applications to defeat beneficial
+controls the platform has over power use. If users become unhappy about the
+power consumption of these apps, it can lead to frustration, bad experiences
+(and negative user reviews for the app), and customer support questions. For
+these reasons, we strongly recommend that you do not exempt third-party
+applications and instead exempt only cloud messaging services or apps with
+similar functions.</p>
+
+<p>Apps exempted by default are listed in a single view within the Settings >
+Battery menu. This list is used for exempting the app from both Doze and App
+Standby modes. To provide transparency to the user, the Settings menu
+<b>MUST</b> show all exempted applications.</p>
+
+<p>Users can manually exempt apps using the Settings menu. However, users cannot
+unexempt any application or service that is exempted by default in the system
+image.</p>
\ No newline at end of file
diff --git a/src/devices/tech/power/values.jd b/src/devices/tech/power/values.jd
index e88900a..8c6d4ac 100644
--- a/src/devices/tech/power/values.jd
+++ b/src/devices/tech/power/values.jd
@@ -33,7 +33,46 @@
the values (deriving differences from other baseline power uses as appropriate).
</p>
+<h2 id="multiple-cpus">Devices with heterogeneous CPUs</h2>
+
+<p>The power profile for devices with CPU cores of heterogeneous architecture
+must include the following additional fields:
+<ul>
+<li>Number of total CPUs for each cluster.</li>
+<li>CPU speeds supported by each cluster.</li>
+</ul>
+
+<p>To differentiate between active CPUs and supported CPU speeds for each
+cluster, append the cluster number to the name of the array. Example:</p>
+
+<pre>
+<array name="cpu.active.cluster0">
+<value>200</value>
+<value>300</value>
+<value>400</value>
+</array>
+<array name="cpu.speeds.cluster0">
+<value>600000</value>
+<value>800000</value>
+<value>1200000</value>
+</array>
+
+<array name="cpu.active.cluster1">
+<value>400</value>
+<value>500</value>
+<value>600</value>
+</array>
+<array name="cpu.speeds.cluster1">
+<value>800000</value>
+<value>1200000</value>
+<value>1400000</value>
+</array>
+</pre>
+
<h2 id="values">Power values</h2>
+<p>The following table describes available power value settings. To view the
+sample file in AOSP, see
+<a href="https://android.googlesource.com/platform/frameworks/base/+/master/core/res/res/xml/power_profile.xml">power_profile.xml</a>.</p>
<table>
<tr>
@@ -205,60 +244,20 @@
</tr>
<tr>
+ <td>cpu.clusters.cores</td>
+ <td>Number of cores each CPU cluster contains.</td>
+ <td>4, 2</td>
+ <td>Required only for devices with <a href="#multiple-cpus">heterogeneous CPU
+ architectures</a>. Number of entries and order should match the number of
+ cluster entries for the cpu.active and cpu.speeds. The first entry represents
+ the number of CPU cores in cluster0, the second entry represents the number of
+ CPU cores in cluster1, and so on.</td>
+</tr>
+
+<tr>
<td>battery.capacity</td>
<td>Total battery capacity in mAh.</td>
<td>3000mAh</td>
<td></td>
</tr>
-</table>
-
-<h2 id="sample">Sample file</h2>
-
-<pre>
-<!-- Most values are the incremental current used by a feature, in mA (measured at
-nominal voltage). OEMs must measure and provide actual values before shipping a device.
-Example real-world values are given, but are dependent on the platform
-and can vary significantly, so should be measured on the shipping platform with a power meter.
--->
-0
-200
-160
-10
-<!-- Bluetooth stereo audio playback 10.0 mA -->
-1.3
-0.5
-30
-100
-12
-50
-50
-75
-1.1
-<!-- Strength 0 to BINS-1 (4) -->
-1.1
-
-<!-- Different CPU speeds as reported in
-/sys/devices/system/cpu/cpu0/cpufreq/stats/time_in_state -->
-
-250000 <!-- 250 MHz -->
-500000 <!-- 500 MHz -->
-750000 <!-- 750 MHz -->
-1000000 <!-- 1 GHz -->
-1200000 <!-- 1.2 GHz -->
-
-<!-- Power consumption when CPU is idle -->
-3.0
-50.1
-<!-- Power consumption at different speeds -->
-
-100 <!-- 250 MHz -->
-120 <!-- 500 MHz -->
-140 <!-- 750 MHz -->
-155 <!-- 1 GHz -->
-175 <!-- 1.2 GHz -->
-
-<!-- This is the battery capacity in mAh -->
-3000
-<!-- Battery capacity is 3000 mAH (at 3.6 Volts) -->
-
-</pre>
\ No newline at end of file
+</table>
\ No newline at end of file
