Merge "Docs: Adding new page for stylus, updating toc" into mnc-dev
diff --git a/src/compatibility/android-cdd.html b/src/compatibility/android-cdd.html
index 55fa014..96f660f 100644
--- a/src/compatibility/android-cdd.html
+++ b/src/compatibility/android-cdd.html
@@ -350,7 +350,7 @@
implementer to ensure compatibility with existing implementations.</p>
<p>For this reason, the Android Open Source Project [<a href="http://source.android.com/">Resources, 2</a>] is both the reference and preferred implementation of Android. Device
-implementers are strongly encouraged to base their implementations to the
+implementers are STRONGLY RECOMMENDED to base their implementations to the
greatest extent possible on the “upstream” source code available from the
Android Open Source Project. While some components can hypothetically be
replaced with alternate implementations this practice is strongly discouraged,
@@ -595,13 +595,13 @@
<td>VERSION.SDK</td>
<td>The version of the currently-executing Android system, in a format accessible
to third-party application code. For Android ANDROID_VERSION, this field MUST have the
-integer value 22.</td>
+integer value ANDROID_VERSION_INT.</td>
</tr>
<tr>
<td>VERSION.SDK_INT</td>
<td>The version of the currently-executing Android system, in a format accessible
to third-party application code. For Android ANDROID_VERSION, this field MUST have the
-integer value 22.</td>
+integer value ANDROID_VERSION_INT.</td>
</tr>
<tr>
<td>VERSION.INCREMENTAL</td>
@@ -917,7 +917,7 @@
implemented.</p>
<p>Native code compatibility is challenging. For this reason, device implementers
-are <strong>very strongly encouraged</strong> to use the implementations of the libraries listed above from the upstream
+are <strong>STRONGLY RECOMMENDED</strong> to use the implementations of the libraries listed above from the upstream
Android Open Source Project. </p>
<h3 id="3_3_2_32-bit_arm_native_code_compatibility">
@@ -1433,7 +1433,7 @@
interacts with screens.</li>
</ul>
-<p>Device implementations are STRONGLY ENCOURAGED to use the upstream Android user
+<p>Device implementations are STRONGLY RECOMMENDED to use the upstream Android user
interface (or a similar thumbnail-based interface) for the overview screen.</p>
<h3 id="3_8_9_input_management">3.8.9. Input Management</h3>
@@ -1723,8 +1723,8 @@
<td></td>
<td>REQUIRED <br>(Android 3.1+)</td>
<td>Mono/Stereo (no multichannel). Sample rates up to 48 kHz (but up to 44.1 kHz is
-recommended on devices with 44.1 kHz output, as the 48 to 44.1 kHz downsampler
-does not include a low-pass filter). 16-bit recommended; no dither applied for
+RECOMMENDED on devices with 44.1 kHz output, as the 48 to 44.1 kHz downsampler
+does not include a low-pass filter). 16-bit RECOMMENDED; no dither applied for
24-bit.</td>
<td>FLAC (.flac) only</td>
</tr>
@@ -1915,7 +1915,7 @@
<p class="table_footnote">4 Device implementations SHOULD support writing Matroska WebM files.</p>
-<p class="table_footnote">5 Strongly recommended for Android Automotive, optional for Android Watch, and required for all other device types.</p>
+<p class="table_footnote">5 STRONGLY RECOMMENDED for Android Automotive, optional for Android Watch, and required for all other device types.</p>
<h2 id="5_2_video_encoding">5.2. Video Encoding</h2>
@@ -2191,7 +2191,7 @@
<p>While some of the requirements outlined in this section are stated as SHOULD
since Android 4.3, the Compatibility Definition for a future version is planned
-to change these to MUST. Existing and new Android devices are <strong>very strongly encouraged</strong> to meet these requirements, or they will not be able to attain Android
+to change these to MUST. Existing and new Android devices are <strong>STRONGLY RECOMMENDED</strong> to meet these requirements, or they will not be able to attain Android
compatibility when upgraded to the future version.</p>
<h3 id="5_4_1_raw_audio_capture">5.4.1. Raw Audio Capture</h3>
@@ -2339,7 +2339,7 @@
NDK_root/docs/opensles/index.html.</li>
</ul>
-<p>Device implementations that declare android.hardware.audio.output are STRONGLY ENCOURAGED to meet
+<p>Device implementations that declare android.hardware.audio.output are STRONGLY RECOMMENDED to meet
or exceed these audio output requirements:</p>
<ul>
@@ -2356,7 +2356,7 @@
android.content.pm.PackageManager class [<a href="http://developer.android.com/reference/android/content/pm/PackageManager.html">Resources, 53</a>]. Conversely, if the device implementation does not meet these requirements it
MUST NOT report support for low-latency audio.</p>
-<p>Device implementations that include android.hardware.microphone are STRONGLY ENCOURAGED to meet
+<p>Device implementations that include android.hardware.microphone are STRONGLY RECOMMENDED to meet
these input audio requirements:</p>
<ul>
@@ -2471,7 +2471,7 @@
<li>
If the device includes a 4 conductor 3.5mm audio jack,
-the device implementation is STRONGLY ENCOURAGED to comply with section
+the device implementation is STRONGLY RECOMMENDED to comply with section
<a href="https://source.android.com/accessories/headset/specification.html#mobile_device_jack_specifications">Mobile device (jack) specifications</a>
of the
<a href="https://source.android.com/accessories/headset/specification.html">Wired Audio Headset Specification (v1.1)</a>.
@@ -3209,7 +3209,7 @@
<li>SHOULD report the event time in nanoseconds as defined in the Android SDK
documentation, representing the time the event happened and synchronized with
the SystemClock.elapsedRealtimeNano() clock. Existing and new Android devices
-are <strong>very strongly encouraged</strong> to meet these requirement so they will be able to upgrade to the future
+are <strong>STRONGLY RECOMMENDED</strong> to meet these requirement so they will be able to upgrade to the future
platform releases where this might become a REQUIRED component. The
synchronization error SHOULD be below 100 milliseconds [<a href="http://developer.android.com/reference/android/hardware/SensorEvent.html#timestamp">Resources, 75</a>].</li>
</ul>
@@ -3244,7 +3244,7 @@
<p>Device implementations SHOULD include a 3-axis accelerometer. Android Handheld
-devices and Android Watch devices are strongly encouraged to include this
+devices and Android Watch devices are STRONGLY RECOMMENDED to include this
sensor. If a device implementation does include a 3-axis accelerometer, it:</p>
<ul>
@@ -3268,14 +3268,14 @@
period of at least 3 seconds at the fastest sampling rate.</li>
<li>SHOULD implement the TYPE_SIGNIFICANT_MOTION, TYPE_TILT_DETECTOR,
TYPE_STEP_DETECTOR, TYPE_STEP_COUNTER composite sensors as described in the
-Android SDK document. Existing and new Android devices are <strong>very strongly encouraged</strong> to implement the TYPE_SIGNIFICANT_MOTION composite sensor. If any of these
+Android SDK document. Existing and new Android devices are <strong>STRONGLY RECOMMENDED</strong> to implement the TYPE_SIGNIFICANT_MOTION composite sensor. If any of these
sensors are implemented, the sum of their power consumption MUST always be less
than 4 mW and SHOULD each be below 2 mW and 0.5 mW for when the device is in a
dynamic or static condition.</li>
<li>If a gyroscope sensor is included, MUST implement the TYPE_GRAVITY and
TYPE_LINEAR_ACCELERATION composite sensors and SHOULD implement the
TYPE_GAME_ROTATION_VECTOR composite sensor. Existing and new Android devices
-are strongly encouraged to implement the TYPE_GAME_ROTATION_VECTOR sensor.</li>
+are STRONGLY RECOMMENDED to implement the TYPE_GAME_ROTATION_VECTOR sensor.</li>
<li>SHOULD implement a TYPE_ROTATION_VECTOR composite sensor, if a gyroscope sensor
and a magnetometer sensor is also included.</li>
</ul>
@@ -3289,7 +3289,7 @@
<ul>
<li>MUST implement the TYPE_MAGNETIC_FIELD sensor and SHOULD also implement
TYPE_MAGNETIC_FIELD_UNCALIBRATED sensor. Existing and new Android devices are
-strongly encouraged to implement the TYPE_MAGNETIC_FIELD_UNCALIBRATED sensor.</li>
+STRONGLY RECOMMENDED to implement the TYPE_MAGNETIC_FIELD_UNCALIBRATED sensor.</li>
<li>MUST be able to report events up to a frequency of at least 10 Hz and SHOULD
report events up to at least 50 Hz.</li>
<li>MUST comply with the Android sensor coordinate system as detailed in the
@@ -3333,7 +3333,7 @@
<ul>
<li>MUST implement the TYPE_GYROSCOPE sensor and SHOULD also implement
TYPE_GYROSCOPE_UNCALIBRATED sensor. Existing and new Android devices are
-strongly encouraged to implement the SENSOR_TYPE_GYROSCOPE_UNCALIBRATED sensor.</li>
+STRONGLY RECOMMENDED to implement the SENSOR_TYPE_GYROSCOPE_UNCALIBRATED sensor.</li>
<li>MUST be capable of measuring orientation changes up to 1,000 degrees per second.</li>
<li>MUST be able to report events up to a frequency of at least 50 Hz for
Android Watch devices as such devices have a stricter power constraint and
@@ -3353,7 +3353,7 @@
<li>If an accelerometer sensor is included, MUST implement the TYPE_GRAVITY and
TYPE_LINEAR_ACCELERATION composite sensors and SHOULD implement the
TYPE_GAME_ROTATION_VECTOR composite sensor. Existing and new Android devices
-are strongly encouraged to implement the TYPE_GAME_ROTATION_VECTOR sensor.</li>
+are STRONGLY RECOMMENDED to implement the TYPE_GAME_ROTATION_VECTOR sensor.</li>
</ul>
<h3 id="7_3_5_barometer">7.3.5. Barometer</h3>
@@ -3907,7 +3907,7 @@
implementations MUST have at least 1.5GB of non-volatile storage available for
application private data. That is, the /data partition MUST be at least 5GB for
Android Television devices and at least 1.5GB for other device implementations.
-Device implementations that run Android are <strong>very strongly encouraged</strong> to have at least 3GB of non-volatile storage for application private data so
+Device implementations that run Android are <strong>STRONGLY RECOMMENDED</strong> to have at least 3GB of non-volatile storage for application private data so
they will be able to upgrade to the future platform releases.</p>
<p>The Android APIs include a Download Manager that applications MAY use to
@@ -3985,12 +3985,12 @@
<li>The port MUST be connectable to a USB host that has a standard type-A or type
-C USB port.</li>
<li>The port SHOULD use micro-A, micro-AB or type-C USB form factor. Existing and
-new Android devices are <strong>very strongly encouraged to meet these requirements</strong> so they will be able to upgrade to the future platform releases.</li>
+new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to the future platform releases.</li>
<li>The port SHOULD be centered in the middle of an edge. Device implementations
SHOULD either locate the port on the bottom of the device (according to natural
orientation) or enable software screen rotation for all apps (including home
screen), so that the display draws correctly when the device is oriented with
-the port at bottom. Existing and new Android devices are <strong>very strongly encouraged to meet these requirements</strong> so they will be able to upgrade to future platform releases.</li>
+the port at bottom. Existing and new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to future platform releases.</li>
<li>It MUST allow a USB host connected with the Android device to access the
contents of the shared storage volume using either USB mass storage or Media
Transfer Protocol.</li>
@@ -4004,7 +4004,7 @@
documentation [<a href="http://developer.android.com/reference/android/hardware/usb/UsbConstants.html#USB_CLASS_AUDIO">Resources, 98</a>].</li>
</ul></li>
<li>It SHOULD implement support to draw 1.5 A current during HS chirp and traffic
-as specified in the USB battery charging specification [<a href="http://www.usb.org/developers/docs/devclass_docs/USB_Battery_Charging_1.2.pdf">Resources, 99</a>]. Existing and new Android devices are <strong>very strongly encouraged to meet these requirements</strong> so they will be able to upgrade to the future platform releases.</li>
+as specified in the USB battery charging specification [<a href="http://www.usb.org/developers/docs/devclass_docs/USB_Battery_Charging_1.2.pdf">Resources, 99</a>]. Existing and new Android devices are <strong>STRONGLY RECOMMENDED to meet these requirements</strong> so they will be able to upgrade to the future platform releases.</li>
<li>The value of iSerialNumber in USB standard device descriptor MUST be equal to
the value of android.os.Build.SERIAL.</li>
</ul>
@@ -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">
@@ -4419,7 +4423,7 @@
<p>Device implementations MUST pass all tests described in this section.</p>
<p>However, note that no software test package is fully comprehensive. For this
-reason, device implementers are <strong>very strongly encouraged</strong> to make the minimum number of changes as possible to the reference and
+reason, device implementers are <strong>STRONGLY RECOMMENDED</strong> to make the minimum number of changes as possible to the reference and
preferred implementation of Android available from the Android Open Source
Project. This will minimize the risk of introducing bugs that create
incompatibilities requiring rework and potential device updates.</p>
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 82a4750..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">
@@ -145,8 +155,10 @@
</a>
</div>
<ul>
- <li><a href="<?cs var:toroot ?>devices/storage/config.html">Device Specific Configuration</a></li>
- <li><a href="<?cs var:toroot ?>devices/storage/config-example.html">Typical Configuration Examples</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/traditional.html">Traditional Storage</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/adoptable.html">Adoptable Storage</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/config.html">Device Configuration</a></li>
+ <li><a href="<?cs var:toroot ?>devices/storage/config-example.html">Configuration Examples</a></li>
</ul>
</li>
<li class="nav-section">
@@ -182,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>
@@ -199,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>
@@ -260,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/storage/adoptable.jd b/src/devices/storage/adoptable.jd
new file mode 100644
index 0000000..899db9b
--- /dev/null
+++ b/src/devices/storage/adoptable.jd
@@ -0,0 +1,98 @@
+page.title=Adoptable Storage
+@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 has always supported external storage accessories (such as SD cards), but
+these accessories were historically limited to simple file storage, due to
+their expected impermanence and the minimal data protection offered to
+<a href="{@docRoot}devices/storage/traditional.html">traditional external storage</a>.
+Android 6.0 introduces the ability to
+<a href="https://developer.android.com/preview/behavior-changes.html#behavior-adoptable-storage">adopt</a>
+external storage media to act like internal storage.</p>
+
+<p>When external storage media is adopted, it’s formatted and encrypted to only
+work with a single Android device at a time. Because the media is strongly tied
+to the Android device that adopted it, it can safely store both apps and
+private data for all users.</p>
+
+<p>When users insert new storage media (such as an SD card) in an adoptable
+location, Android asks them how they want to use the media. They can choose to
+adopt the media, which formats and encrypts it, or they can continue using it
+as-is for simple file storage. If they choose to adopt, the platform offers to
+migrate the primary shared storage contents (typically mounted at <code>/sdcard</code>)
+to the newly adopted media, freeing up valuable space on internal storage.</p>
+
+<p>Apps can be placed on adopted storage media only when the developer has
+indicated support through the <code>android:installLocation</code> attribute.
+New installs of supported apps are automatically placed on the
+storage device with the most free space, and users can move supported apps
+between storage devices in the <em>Settings</em> app. Apps moved to adopted
+media are remembered while the media is ejected,
+and return when the media is reinserted.</p>
+
+<h2 id=security>Security</h2>
+
+
+<p>The platform randomly generates an encryption key for each adopted device,
+and that key is stored on the internal storage of the Android device. This
+effectively makes the adopted media as secure as internal storage. Keys are
+associated with adopted devices based on the adopted partition GUID. The
+adopted device is encrypted using <code>dm-crypt</code> configured with the
+<code>aes-cbc-essiv:sha256</code> algorithm and a 128-bit key size.</p>
+
+<p>The on-disk layout of the adopted device closely mirrors the internal data
+partition, including SELinux labels, etc. When multi-user is supported on the
+Android device, the adopted storage device also supports multi-user with the
+same level of isolation as internal storage.</p>
+
+<p>Because the contents of an adopted storage device are strongly tied to the
+Android device that adopted it, the encryption keys should not be extractable
+from the parent device, and therefore the storage device can't be mounted elsewhere.</p>
+
+<h2 id=performance_and_stability>Performance and stability</h2>
+
+
+<p>Only external storage media in stable locations, such as a slot inside a
+battery compartment or behind a protective cover, should be considered for
+adoption to help avoid accidental data loss or corruption. In particular, USB
+devices connected to a phone or tablet should never be considered for adoption.
+One common exception would be an external USB drive connected to a TV-style
+device, because the entire TV is typically installed in a stable location.</p>
+
+<p>When a user adopts a new storage device, the platform runs a benchmark and
+compares its performance against internal storage. If the adopted device is
+significantly slower than internal storage, the platform warns the user about a
+possibly degraded experience. This benchmark was derived from the actual I/O
+behavior of popular Android apps. Currently, the AOSP implementation will only
+warn users beyond a single threshold, but device manufacturers may adapt this
+further, such as rejecting adoption completely if the card is extremely slow.</p>
+
+<p>Adopted devices must be formatted with a filesystem that supports POSIX
+permissions and extended attributes, such as <code>ext4</code> or <code>f2fs</code>.
+For optimal performance, the <code>f2fs</code> filesystem is recommended for
+flash-based storage devices.</p>
+
+<p>When performing periodic idle maintenance, the platform issues <code>FI_TRIM</code>
+to adopted media just like it does for internal storage. The current SD card
+specification does not support the <code>DISCARD</code> command; but the kernel
+instead falls back to the <code>ERASE</code> command, which SD card firmware
+may choose to use for optimization purposes.</p>
diff --git a/src/devices/storage/config-example.jd b/src/devices/storage/config-example.jd
index 347d8d5..91be81b 100644
--- a/src/devices/storage/config-example.jd
+++ b/src/devices/storage/config-example.jd
@@ -1,56 +1,53 @@
-page.title=Typical Configuration Examples
+page.title=Configuration Examples
@jd:body
-
<!--
- Copyright 2013 The Android Open Source Project
-
+ 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>Below are examples of external storage configurations as of Android 4.4
-for various typical devices. Only the relevant portions of the configuration
+<p>Below are examples of external storage configurations
+for various device types. Only the relevant portions of the configuration
files are included.
+<p>Due to configuration changes in Android 6.0 (like the removal of the
+<code>storage_list.xml</code> resource overlay), the configuration examples are
+split into two categories.</p>
-<h2>Physical primary only (like Nexus One)</h2>
-
+<h2 id=android_5_x>Android 5.x and earlier</h2>
+<h3 id=android_5_x_physical>Physical primary only</h3>
<p>This is a typical configuration for a device with single external storage
-device which is a physical SD card.</p>
-
+device which is a physical SD card, like Nexus One.</p>
<p>The raw physical device must first be mounted under
<code>/mnt/media_rw</code> where only the system and FUSE daemon can access
it. <code>vold</code> will then manage the <code>fuse_sdcard0</code> service
when media is inserted/removed.
-
-<h3>fstab.hardware</h3>
-
+<h4>fstab.hardware</h4>
<pre><code>[physical device node] auto vfat defaults voldmanaged=sdcard0:auto,noemulatedsd
</code></pre>
-
-<h3>init.hardware.rc</h3>
-
+<h4>init.hardware.rc</h4>
<pre><code>on init
mkdir /mnt/media_rw/sdcard0 0700 media_rw media_rw
mkdir /storage/sdcard0 0700 root root
-
export EXTERNAL_STORAGE /storage/sdcard0
-
service fuse_sdcard0 /system/bin/sdcard -u 1023 -g 1023 -d /mnt/media_rw/sdcard0 /storage/sdcard0
class late_start
disabled
</code></pre>
-
-<h3>storage_list.xml</h3>
-
+<h4>storage_list.xml</h4>
<pre><code><storage
android:mountPoint="/storage/sdcard0"
android:storageDescription="@string/storage_sd_card"
@@ -58,82 +55,57 @@
android:primary="true"
android:maxFileSize="4096" />
</code></pre>
-
-
-<h2>Emulated primary only (like Nexus 4)</h2>
-
+<h3 id=android_5_x_emulated>Emulated primary only</h3>
<p>This is a typical configuration for a device with single external storage
-device which is backed by internal storage on the device.</p>
-
-<h3>init.hardware.rc</h3>
-
+device which is backed by internal storage on the device, like Nexus 4.</p>
+<h4>init.hardware.rc</h4>
<pre><code>on init
mkdir /mnt/shell/emulated 0700 shell shell
mkdir /storage/emulated 0555 root root
-
export EXTERNAL_STORAGE /storage/emulated/legacy
export EMULATED_STORAGE_SOURCE /mnt/shell/emulated
export EMULATED_STORAGE_TARGET /storage/emulated
-
on fs
setprop ro.crypto.fuse_sdcard true
-
service sdcard /system/bin/sdcard -u 1023 -g 1023 -l /data/media /mnt/shell/emulated
class late_start
</code></pre>
-
-<h3>storage_list.xml</h3>
-
+<h4>storage_list.xml</h4>
<pre><code><storage
android:storageDescription="@string/storage_internal"
android:emulated="true"
android:mtpReserve="100" />
</code></pre>
-
-
-<h2>Emulated primary, physical secondary (like Xoom)</h2>
-
+<h3 id=android_5_x_both>Emulated primary, physical secondary</h3>
<p>This is a typical configuration for a device with multiple external
storage devices, where the primary device is backed by internal storage
-on the device, and where the secondary device is a physical SD card.</p>
-
+on the device, and where the secondary device is a physical SD card, like Xoom.</p>
<p>The raw physical device must first be mounted under
<code>/mnt/media_rw</code> where only the system and FUSE daemon can
access it. <code>vold</code> will then manage the <code>fuse_sdcard1</code>
service when media is inserted/removed.</p>
-
-<h3>fstab.hardware</h3>
-
+<h4>fstab.hardware</h4>
<pre><code>[physical device node] auto vfat defaults voldmanaged=sdcard1:auto
</code></pre>
-
-<h3>init.hardware.rc</h3>
-
+<h4>init.hardware.rc</h4>
<pre><code>on init
mkdir /mnt/shell/emulated 0700 shell shell
mkdir /storage/emulated 0555 root root
-
mkdir /mnt/media_rw/sdcard1 0700 media_rw media_rw
mkdir /storage/sdcard1 0700 root root
-
export EXTERNAL_STORAGE /storage/emulated/legacy
export EMULATED_STORAGE_SOURCE /mnt/shell/emulated
export EMULATED_STORAGE_TARGET /storage/emulated
export SECONDARY_STORAGE /storage/sdcard1
-
on fs
setprop ro.crypto.fuse_sdcard true
-
service sdcard /system/bin/sdcard -u 1023 -g 1023 -l /data/media /mnt/shell/emulated
class late_start
-
service fuse_sdcard1 /system/bin/sdcard -u 1023 -g 1023 -w 1023 -d /mnt/media_rw/sdcard1 /storage/sdcard1
class late_start
disabled
</code></pre>
-
-<h3>storage_list.xml</h3>
-
+<h4>storage_list.xml</h4>
<pre><code><storage
android:storageDescription="@string/storage_internal"
android:emulated="true"
@@ -144,3 +116,43 @@
android:removable="true"
android:maxFileSize="4096" />
</code></pre>
+
+<h2 id=android_6>Android 6.0</h2>
+<h3 id=android_6_physical>Physical primary only</h3>
+<p>This is a typical configuration for a device with single external storage
+device which is a physical SD card, like the original Android One. There is no
+secondary shared storage and the device cannot support multi-user.</p>
+<h4>fstab.device</h4>
+<pre><code>/devices/platform/mtk-msdc.1/mmc_host* auto auto defaults
+voldmanaged=sdcard0:auto,encryptable=userdata,noemulatedsd
+</code></pre>
+<h4>init.device.rc</h4>
+<pre><code>on init
+ # By default, primary storage is physical
+ setprop ro.vold.primary_physical 1
+ </code></pre>
+<h3 id=android_6_emulated> Emulated primary only</h3>
+<p>This is a typical configuration for a device with single external storage
+device which is backed by internal storage on the device, like Nexus 6.</p>
+<ul>
+ <li>Primary shared storage (<code>/sdcard</code>) is emulated on top of internal storage.
+ <li>No secondary SD card storage.
+ <li>USB OTG storage devices supported.
+ <li>Supports multi-user.
+</ul>
+<h4>fstab.device</h4>
+<pre><code>/devices/*/xhci-hcd.0.auto/usb* auto auto defaults
+ voldmanaged=usb:auto</code></pre>
+<h3 id=android_6_both>Emulated primary, physical secondary</h3>
+<p>This is a typical configuration for a device with multiple external storage
+devices, where the primary device is backed by internal storage on the device,
+and where the secondary device is a physical SD card, like Xoom.</p>
+<ul>
+ <li>Primary shared storage (<code>/sdcard</code>) is emulated on top of internal storage.
+ <li>Secondary storage is a physical SD card slot that can be adopted.
+ <li>Supports multi-user.
+</ul>
+<h4>fstab.device</h4>
+<pre><code>/devices/platform/mtk-msdc.1/mmc_host* auto auto defaults
+voldmanaged=sdcard1:auto,encryptable=userdata
+</code></pre>
diff --git a/src/devices/storage/config.jd b/src/devices/storage/config.jd
index b8e4e4f..6db706c 100644
--- a/src/devices/storage/config.jd
+++ b/src/devices/storage/config.jd
@@ -1,34 +1,36 @@
-page.title=Device Specific Configuration
+page.title=Device Configuration
@jd:body
-
<!--
- Copyright 2013 The Android Open Source Project
-
+ 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>External storage is managed by a combination of the <code>vold</code> init
-service and <code>MountService</code> system servic. Mounting of physical
+service and <code>MountService</code> system service. Mounting of physical
external storage volumes is handled by <code>vold</code>, which performs
staging operations to prepare the media before exposing it to apps.</p>
+<h2 id=file_mappings>File mappings</h2>
<p>For Android 4.2.2 and earlier, the device-specific <code>vold.fstab</code>
configuration file defines mappings from sysfs devices to filesystem mount
points, and each line follows this format:</p>
-
<pre><code>dev_mount <label> <mount_point> <partition> <sysfs_path> [flags]
</code></pre>
-
<ul>
<li><code>label</code>: Label for the volume.</li>
<li><code>mount_point</code>: Filesystem path where the volume should be mounted.</li>
@@ -38,7 +40,6 @@
<li><code>flags</code>: Optional comma separated list of flags, must not contain <code>/</code>.
Possible values include <code>nonremovable</code> and <code>encryptable</code>.</li>
</ul>
-
<p>For Android releases 4.3 and later, the various fstab files used by init, vold and
recovery were unified in the <code>/fstab.<device></code> file. For external
storage volumes that are managed by <code>vold</code>, the entries should have the
@@ -58,10 +59,18 @@
be followed by a label describing the card, and a partition number or the word
<code>auto</code>. Here is an example: <code>voldmanaged=sdcard:auto</code>.
Other possible flags are <code>nonremovable</code>,
-<code>encryptable=sdcard</code>, and <code>noemulatedsd</code>.</li>
+<code>encryptable=sdcard</code>, <code>noemulatedsd</code>, and <code>encryptable=userdata</code>.</li>
</ul>
+
+<h2 id=configuration_details>Configuration details</h2>
<p>External storage interactions at and above the framework level are handled
-through <code>MountService</code>. The device-specific <code>storage_list.xml</code> configuration
+through <code>MountService</code>.
+Due to configuration changes in Android 6.0 (like the
+removal of the storage_list.xml resource overlay), the configuration details
+are split into two categories.
+
+<h3 id=android_5_x_and_earlier>Android 5.x and earlier</h3>
+The device-specific <code>storage_list.xml</code> configuration
file, typically provided through a <code>frameworks/base</code> overlay, defines the
attributes and constraints of storage devices. The <code><StorageList></code> element
contains one or more <code><storage></code> elements, exactly one of which should be marked
@@ -94,3 +103,46 @@
storage. The <code>/sdcard</code> path must also resolve to the same location, possibly
through a symlink. If a device adjusts the location of external storage between
platform updates, symlinks should be created so that old paths continue working.</p>
+
+<h3 id=android_6_0>Android 6.0</h3>
+<p>Configuration of the storage subsystem is now concentrated in the
+device-specific <code>fstab</code> file, and several historical static configuration files/variables have been
+removed to support more dynamic behavior:</p>
+<ul>
+ <li>The <code>storage_list.xml</code> resource overlay has been removed and is no longer used by the framework.
+Storage devices are now configured dynamically when detected by <code>vold</code>.
+ <li>The <code>EMULATED_STORAGE_SOURCE/TARGET</code> environment variables have been removed and are no longer used by Zygote to
+configure user-specific mount points. Instead, user separation is now enforced
+with user-specific GIDs, and primary shared storage is mounted into place by <code>vold</code> at runtime.
+ <ul>
+ <li>Developers may continue to build paths dynamically or statically depending on
+their use case. Including the UUID in the path identifies each card to make
+location clearer for developers. (For example, <code>/storage/ABCD-1234/report.txt</code> is clearly a different file than <code>/storage/DCBA-4321/report.txt</code>.)
+ </ul>
+ <li>The hard-coded FUSE services have been removed from device-specific <code>init.rc</code> files and are instead forked dynamically from <code>vold</code> when needed.
+</ul>
+<p>In addition to these configuration changes, Android 6.0 includes the notion of
+adoptable storage. For Android 6.0 devices, any physical media that is not
+adopted is viewed as portable. </p>
+
+<h4 id=adoptable_storage>Adoptable storage </h4>
+<p>To indicate an adoptable storage device in the <code>fstab</code>, use the <code>encryptable=userdata</code> attribute in the <code>fs_mgr_flags</code> field. Here’s a typical definition:</p>
+<pre><code>/devices/platform/mtk-msdc.1/mmc_host* auto auto defaults
+voldmanaged=sdcard1:auto,encryptable=userdata
+</code></pre>
+<p>When a storage device is adopted, the platform erases the contents and writes a
+GUID partition table that defines two partitions:</p>
+<ul>
+ <li>a small empty <code>android_meta</code> partition that is reserved for future use. The partition type GUID is
+19A710A2-B3CA-11E4-B026-10604B889DCF.
+ <li>a large <code>android_ext</code> partition that is encrypted using dm-crypt and formatted using either <code>ext4</code> or <code>f2fs</code> depending on the kernel capabilities. The partition type GUID is
+193D1EA4-B3CA-11E4-B075-10604B889DCF.
+</ul>
+<h4 id=portable_storage>Portable storage </h4>
+<p>In the <code>fstab</code>, storage devices with the <code>voldmanaged</code> attribute are considered to be portable by default unless another attribute
+like <code>encryptable=userdata</code> is defined. For example, here’s a typical definition for USB OTG devices:</p>
+<pre><code>/devices/*/xhci-hcd.0.auto/usb* auto auto defaults
+ voldmanaged=usb:auto
+</code></pre>
+<p>The platform uses <code>blkid</code> to detect filesystem types before mounting, and users can choose to format the
+media when the filesystem is unsupported.</p>
diff --git a/src/devices/storage/index.jd b/src/devices/storage/index.jd
index 177e945..7e62fe6 100644
--- a/src/devices/storage/index.jd
+++ b/src/devices/storage/index.jd
@@ -1,36 +1,45 @@
page.title=Storage
@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>
<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_extstor.png" alt="Android external storage HAL icon"/>
+<p>Android has evolved over time to support a wide variety of storage device types
+and features. All versions of Android support devices with <a href="{@docRoot}devices/storage/traditional.html">traditional storage</a>,
+which includes portable and emulated storage. <em>Portable</em> storage can be provided by physical media, like an SD card or USB, that is for
+temporary data transfer/ file storage. The physical media may remain with the
+device for an extended period of time, but is not tied to the device and may be
+removed. SD cards have been available as portable storage since Android 1.0;
+Android 6.0 added USB support. <em>Emulated</em> storage is provided by exposing a portion of internal storage through an
+emulation layer and has been available since Android 3.0.</p>
-<p>Android supports devices with external storage, which is defined to be a
-case-insensitive filesystem with immutable POSIX permission classes and
-modes. External storage can be provided by physical media (such as an SD
-card), or by exposing a portion of internal storage through an emulation
-layer. Devices may contain multiple instances of external storage.</p>
+<p>Starting in Android 6.0, Android supports <a href="{@docRoot}devices/storage/adoptable.html"><em>adoptable</em> storage</a>, which is provided by physical media, like an SD card or USB, that is
+encrypted and formatted to behave like internal storage. Adoptable storage can
+store all types of application data. </p>
+<h2 id=permissions>Permissions</h2>
<p>Access to external storage is protected by various Android
permissions. Starting in Android 1.0, write access is protected with the
<code>WRITE_EXTERNAL_STORAGE</code> permission. Starting in Android 4.1,
read access is protected with the <code>READ_EXTERNAL_STORAGE</code>
permission.</p>
-
<p>Starting in Android 4.4, the owner, group and modes of files on external
storage devices are now synthesized based on directory structure. This
enables apps to manage their package-specific directories on external
@@ -41,65 +50,29 @@
no permissions. These synthesized permissions are accomplished by wrapping
raw storage devices in a FUSE daemon.</p>
-<p>Since external storage offers minimal protection for stored data, system
-code should not store sensitive data on external storage. Specifically,
-configuration and log files should only be stored on internal storage where
-they can be effectively protected.</p>
+<h3 id=runtime_permissions>Runtime permissions</h3>
-<h2 id="multiple-external-storage-devices">Multiple external storage devices</h2>
-
-<p>Starting in Android 4.4, multiple external storage devices are surfaced
-to developers through <code>Context.getExternalFilesDirs()</code>,
-<code>Context.getExternalCacheDirs()</code>, and
-<code>Context.getObbDirs()</code>.</p>
-
-</p>External storage devices surfaced through these APIs must be a
-semi-permanent part of the device (such as an SD card slot in a battery
-compartment). Developers expect data stored in these locations to be
-available over long periods of time. For this reason, transient storage
-devices (such as USB mass storage drives) should not be surfaced through
-these APIs.</p>
-
-<p>The <code>WRITE_EXTERNAL_STORAGE</code> permission must only grant write
-access to the primary external storage on a device. Apps must not be
-allowed to write to secondary external storage devices, except in their
-package-specific directories as allowed by synthesized
-permissions. Restricting writes in this way ensures the system can clean
-up files when applications are uninstalled.</p>
-
-
-<h2 id="multi-user-external-storage">Multi-user external storage</h2>
-
-<p>Starting in Android 4.2, devices can support multiple users, and external
-storage must meet the following constraints:</p>
+<p>Android 6.0 introduces a new <a href="{@docRoot}devices/tech/config/runtime_perms.html">runtime permissions</a> model where apps request
+capabilities when needed at runtime. Because the new model includes the <code>READ/WRITE_EXTERNAL_STORAGE</code> permissions, the platform needs to dynamically grant storage access without
+killing or restarting already-running apps. It does this by maintaining three
+distinct views of all mounted storage devices:</p>
<ul>
-<li>Each user must have their own isolated primary external storage, and
-must not have access to the primary external storage of other users.</li>
-<li>The <code>/sdcard</code> path must resolve to the correct user-specific
-primary external storage based on the user a process is running as.</li>
-<li>Storage for large OBB files in the <code>Android/obb</code> directory
-may be shared between multiple users as an optimization.</li>
-<li>Secondary external storage must not be writable by apps, except in
-package-specific directories as allowed by synthesized permissions.</li>
+ <li><code>/mnt/runtime/default</code> is shown to apps with no special storage permissions, and to the root
+namespace where <code>adbd</code> and other system components live.
+ <li><code>/mnt/runtime/read</code> is shown to apps with <code>READ_EXTERNAL_STORAGE</code>
+ <li><code>/mnt/runtime/write</code> is shown to apps with <code>WRITE_EXTERNAL_STORAGE</code>
</ul>
-<p>The default platform implementation of this feature leverages Linux kernel
-namespaces to create isolated mount tables for each Zygote-forked process,
-and then uses bind mounts to offer the correct user-specific primary external
-storage into that private namespace.</p>
+<p>At Zygote fork time, we create a mount namespace for each running app and bind
+mount the appropriate initial view into place. Later, when runtime permissions
+are granted, <code>vold</code> jumps into the mount namespace of already-running apps and bind mounts the
+upgraded view into place. Note that permission downgrades always result in the
+app being killed.</p>
-<p>At boot, the system mounts a single emulated external storage FUSE daemon
-at <code>EMULATED_STORAGE_SOURCE</code>, which is hidden from apps. After
-the Zygote forks, it bind mounts the appropriate user-specific subdirectory
-from under the FUSE daemon to <code>EMULATED_STORAGE_TARGET</code> so that
-external storage paths resolve correctly for the app. Because an app lacks
-accessible mount points for other users' storage, they can only access
-storage for the user it was started as.</p>
+<p>The <code>setns()</code> functionality used to implement this feature requires at least Linux 3.8, but
+patches have been backported successfully to Linux 3.4. The <code>PermissionsHostTest</code> CTS test can be used to verify correct kernel behavior.</p>
-<p>This implementation also uses the shared subtree kernel feature to
-propagate mount events from the default root namespace into app namespaces,
-which ensures that features like ASEC containers and OBB mounting continue
-working correctly. It does this by mounting the rootfs as shared, and then
-remounting it as slave after each Zygote namespace is created.</p>
+<p>In Android 6.0, third-party apps don’t have access to the <code>sdcard_r</code> and <code>sdcard_rw</code> GIDs. Instead, access is controlled by mounting only the appropriate runtime
+view in place for that app. Cross-user interactions are blocked using the <code>everybody</code> GID.</p>
diff --git a/src/devices/storage/traditional.jd b/src/devices/storage/traditional.jd
new file mode 100644
index 0000000..c71c644
--- /dev/null
+++ b/src/devices/storage/traditional.jd
@@ -0,0 +1,94 @@
+page.title=Traditional Storage
+@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>
+
+<img style="float: right; margin: 0px 15px 15px 15px;" src="images/ape_fwk_hal_extstor.png" alt="Android external storage HAL icon"/>
+
+<p>Android supports devices with traditional storage, which is defined to be a
+case-insensitive filesystem with immutable POSIX permission classes and modes.
+The notion of traditional storage encompasses emulated and portable storage.
+Portable storage is defined as any external storage that is not <a href="{@docRoot}devices/storage/adoptable.html">
+adopted</a> by the
+system and therefore not formatted and encrypted or tied to a specific device.
+Because traditional external storage offers minimal protection for stored data,
+system code should not store sensitive data on external storage. Specifically,
+configuration and log files should only be stored on internal storage where
+they can be effectively protected.</p>
+
+<h2 id="multi-user-external-storage">Multi-user external storage</h2>
+<p>Starting in Android 4.2, devices can support multiple users, and external
+storage must meet the following constraints:</p>
+<ul>
+<li>Each user must have their own isolated primary external storage, and
+must not have access to the primary external storage of other users.</li>
+<li>The <code>/sdcard</code> path must resolve to the correct user-specific
+primary external storage based on the user a process is running as.</li>
+<li>Storage for large OBB files in the <code>Android/obb</code> directory
+may be shared between multiple users as an optimization.</li>
+<li>Secondary external storage must not be writable by apps, except in
+package-specific directories as allowed by synthesized permissions.</li>
+</ul>
+<p>The default platform implementation of this feature leverages Linux kernel
+namespaces to create isolated mount tables for each Zygote-forked process,
+and then uses bind mounts to offer the correct user-specific primary external
+storage into that private namespace.</p>
+<p>At boot, the system mounts a single emulated external storage FUSE daemon
+at <code>EMULATED_STORAGE_SOURCE</code>, which is hidden from apps. After
+the Zygote forks, it bind mounts the appropriate user-specific subdirectory
+from under the FUSE daemon to <code>EMULATED_STORAGE_TARGET</code> so that
+external storage paths resolve correctly for the app. Because an app lacks
+accessible mount points for other users' storage, they can only access
+storage for the user it was started as.</p>
+<p>This implementation also uses the shared subtree kernel feature to
+propagate mount events from the default root namespace into app namespaces,
+which ensures that features like ASEC containers and OBB mounting continue
+working correctly. It does this by mounting the rootfs as shared, and then
+remounting it as slave after each Zygote namespace is created.</p>
+
+<h2 id="multiple-external-storage-devices">Multiple external storage devices</h2>
+<p>Starting in Android 4.4, multiple external storage devices are surfaced
+to developers through <code>Context.getExternalFilesDirs()</code>,
+<code>Context.getExternalCacheDirs()</code>, and
+<code>Context.getObbDirs()</code>.</p>
+</p>External storage devices surfaced through these APIs must be a
+semi-permanent part of the device (such as an SD card slot in a battery
+compartment). Developers expect data stored in these locations to be
+available over long periods of time. For this reason, transient storage
+devices (such as USB mass storage drives) should not be surfaced through
+these APIs.</p>
+<p>The <code>WRITE_EXTERNAL_STORAGE</code> permission must only grant write
+access to the primary external storage on a device. Apps must not be
+allowed to write to secondary external storage devices, except in their
+package-specific directories as allowed by synthesized
+permissions. Restricting writes in this way ensures the system can clean
+up files when applications are uninstalled.</p>
+
+<h2 id=support_usb_media>USB media support</h2>
+
+<p>Android 6.0 supports portable storage devices which are only connected to the
+device for a short period of time, like USB flash drives. When a user inserts a
+new portable device, the platform shows a notification to let them copy or
+manage the contents of that device.</p>
+
+<p>In Android 6.0, any device that is not adopted is considered portable. Because
+portable storage is connected for only a short time, the platform avoids heavy
+operations such as media scanning. Third-party apps must go through the <a href="https://developer.android.com/guide/topics/providers/document-provider.html">Storage Access Framework</a> to interact with files on portable storage; direct access is explicitly
+blocked for privacy and security reasons.</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
diff --git a/src/images/jack-library-file.png b/src/images/jack-library-file.png
new file mode 100644
index 0000000..b25dd85
--- /dev/null
+++ b/src/images/jack-library-file.png
Binary files differ
diff --git a/src/images/jack-overview.png b/src/images/jack-overview.png
new file mode 100644
index 0000000..74d396f
--- /dev/null
+++ b/src/images/jack-overview.png
Binary files differ
diff --git a/src/images/jill.png b/src/images/jill.png
new file mode 100644
index 0000000..0d9ba14
--- /dev/null
+++ b/src/images/jill.png
Binary files differ
diff --git a/src/images/pre-dex.png b/src/images/pre-dex.png
new file mode 100644
index 0000000..4d39700
--- /dev/null
+++ b/src/images/pre-dex.png
Binary files differ
diff --git a/src/source/jack.jd b/src/source/jack.jd
new file mode 100644
index 0000000..7abead7
--- /dev/null
+++ b/src/source/jack.jd
@@ -0,0 +1,357 @@
+page.title=Jack (Java Android Compiler Kit)
+@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>
+
+<h2 id=the_jack_toolchain>The Jack toolchain</h2>
+
+<p>Jack (Java Android Compiler Kit) is a new Android toolchain that compiles Java
+source into Android dex bytecode. It replaces the previous Android toolchain,
+which consists of multiple tools, such as javac, ProGuard, jarjar, and dx.</p>
+
+<p>The Jack toolchain provides the following advantages:</p>
+
+<ul>
+ <li> <strong>Completely open source</strong><br>
+Available in AOSP; partners are welcome to contribute.
+ <li> <strong>Speeds compilation time</strong><br>
+
+Jack has specific supports to reduce compilation time: pre-dexing, incremental
+compilation and a Jack compilation server.
+ <li> <strong>Handles shrinking, obfuscation, repackaging and multidex</strong><br>
+Using a separate package such as ProGuard is no longer necessary.
+</ul>
+
+<img src="{@docRoot}images/jack-overview.png" height="75%" width="75%" alt="Jack overview" />
+<p class="img-caption"><strong>Figure 1. </strong>Jack (Java Android Compiler Kit)</p>
+
+<h2 id=the_jack_library_format>The .jack library format</h2>
+
+<p>Jack has its own .jack file format, which contains the pre-compiled dex code
+for the library, allowing for faster compilation (pre-dex).</p>
+
+<img src="{@docRoot}images/jack-library-file.png" height="75%" width="75%" alt="Jack library file contents" />
+<p class="img-caption"><strong>Figure 2. </strong>Jack library file contents</p>
+
+<h2 id=jack_intermediate_library_linker_jill>Jack Intermediate Library Linker (Jill)</h2>
+
+<p>The Jill tool translates the existing .jar libraries into the new library
+format, as shown below.</p>
+
+<img src="{@docRoot}images/jill.png" alt="Importing existing .jar libraries using Jill" />
+<p class="img-caption"><strong>Figure 3. </strong>Workflow to import an existing .jar library</p>
+
+<h2 id=using_jack_in_your_android_build>Using Jack in your Android build</h2>
+
+<p>You don’t have to do anything differently to use Jack — just use your standard
+makefile commands to compile the tree or your project. Jack is the default
+Android build toolchain for M.</p>
+
+<p>The first time Jack is used, it launches a local Jack compilation server on
+your computer:</p>
+
+<ul>
+ <li> This server brings an intrinsic speedup, because it avoids launching a new host
+JRE JVM, loading Jack code, initializing Jack and warming up the JIT at each
+compilation. It also provides very good compilation times during small
+compilations (e.g. in incremental mode).
+ <li> The server is also a short-term solution to control the number of parallel Jack
+compilations, and so to avoid overloading your computer (memory or disk issue),
+because it limits the number of parallel compilations.
+</ul>
+
+<p>The Jack server shuts itself down after an idle time without any compilation.
+It uses two TCP ports on the localhost interface, and so is not available
+externally. All these parameters (number of parallel compilations, timeout,
+ports number, etc) can be modified by editing the<code> $HOME/.jack</code> file.</p>
+
+<h3 id=$home_jack_file>$HOME/.jack file</h3>
+
+<p>The <code>$HOME/.jack</code> file contains settings for Jack server variables, in a full bash syntax. </p>
+
+<p>Here are the available settings, with their definitions and default values:</p>
+
+<ul>
+ <li> <strong><code>SERVER=true</strong> </code>Enable the server feature of Jack.
+ <li> <strong><code>SERVER_PORT_SERVICE=8072</code>
+</strong>Set the TCP port number of the server for compilation purposes.
+ <li> <strong><code>SERVER_PORT_ADMIN=8073</code></strong>
+Set the TCP port number of the server for admin purposes.
+ <li> <strong><code>SERVER_COUNT=1</code></strong>
+Unused at present.
+ <li> <strong><code>SERVER_NB_COMPILE=4</code></strong>
+Maximum number of parallel compilations allowed.
+ <li> <strong><code>SERVER_TIMEOUT=60</code></strong>
+Number of idle seconds the server has to wait without any compilation before
+shutting itself down.
+ <li> <strong><code>SERVER_LOG=${SERVER_LOG:=$SERVER_DIR/jack-$SERVER_PORT_SERVICE.log}</code></strong>
+File where server logs are written. By default, this variable can be
+overloaded by an environment variable.
+ <li> <strong><code>JACK_VM_COMMAND=${JACK_VM_COMMAND:=java}</code></strong>
+The default command used to launch a JVM on the host. By default, this
+variable can be overloaded by environment variable.
+</ul>
+
+<h3 id=jack_troubleshooting>Jack troubleshooting</h3>
+
+<p><strong>If your computer becomes unresponsive during compilation or if you experience
+Jack compilations failing on “Out of memory error”</strong></p>
+
+<p>You can improve the situation by reducing the number of Jack simultaneous
+compilations by editing your<code> $HOME/.jack</code> and changing<code> SERVER_NB_COMPILE</code> to a lower value.</p>
+
+<p><strong>If your compilations are failing on “Cannot launch background server”</strong></p>
+
+<p>The most likely cause is TCP ports are already used on your computer. Try to
+change it by editing your <code>$HOME/.jack </code>(<code>SERVER_PORT_SERVICE</code> and <code>SERVER_PORT_ADMIN</code> variables).</p>
+
+<p>If it doesn’t solve the problem, please report and attach your compilation log
+and the Jack server log (see ‘Finding the Jack log’ below to know where to find
+the server log file). To unblock the situation, disable jack compilation server
+by editing your <code>$HOME/.jack</code> and changing <code>SERVER</code> to false. Unfortunately this will significantly slow down your compilation and
+may force you to launch <code>make -j</code> with load control (option "<code>-l</code>" of <code>make</code>). </p>
+
+<p><strong>If your compilation gets stuck without any progress</strong></p>
+
+<p>Please report this and give us the following additional information (where
+possible):</p>
+
+<ul>
+ <li> The command line at which you are stuck.
+ <li> The output of this command line.
+ <li> The result of executing <code>jack-admin server-stat</code>.
+ <li> The <code>$HOME/.jack</code> file.
+ <li> The content of the server log with the server state dumped. To get this —
+ <ul>
+ <li> Find the Jack background server process by running <code>jack-admin list-server</code>.
+ <li> Send a <code>kill -3</code> command to this server to dump its state into the log file.
+ <li> To locate the server log file, see ‘Finding the Jack log’ below.
+ </ul>
+ <li> The result of executing <code>ls -lR $TMPDIR/jack-$USER.</code>
+ <li> The result of running <code>ps j -U $USER.</code>
+</ul>
+
+<p>You should be able to unblock yourself by killing the Jack background server
+(use <code>jack-admin kill-server</code>), and then by removing its temporary directories contained in <code>jack-$USER</code> of your temporary directory (<code>/tmp</code> or <code>$TMPDIR</code>).</p>
+
+<p><strong>If you have any other issues </strong></p>
+
+<p>To report bugs or request features, please use our public issue tracker,
+available at <a href="http://b.android.com">http://b.android.com</a>, with the <a href="https://code.google.com/p/android/issues/entry?template=Jack%20bug%20report">Jack tool bug report</a> or <a href="https://code.google.com/p/android/issues/entry?template=Jack%20feature%20request">Jack tool feature request</a> templates. Please attach the Jack log to the bug report. </p>
+<table>
+ <tr>
+ <td><strong>Finding the Jack log</strong>
+<ul>
+ <li> If you ran a make command with a dist target, the Jack log is located at <code>$ANDROID_BUILD_TOP/out/dist/logs/jack-server.log</code>
+ <li> Otherwise you can find it in by running <code>jack-admin server-log</code>
+</ul>
+</td>
+ </tr>
+</table>
+
+<p>In case of reproducible Jack failures, you can get a more detailed log by
+setting one variable, as follows:</p>
+
+<pre class=prettyprint>
+$ export ANDROID_JACK_EXTRA_ARGS= "--verbose debug --sanity-checks on -D
+sched.runner=single-threaded"
+</pre>
+
+<p>Then use your standard makefile commands to compile the tree or your project
+and attach its standard output and error.</p>
+
+<p>To remove detailed build logs use:</p>
+
+<pre class=prettyprint>
+$ unset ANDROID_JACK_EXTRA_ARGS
+</pre>
+
+<h3 id=jack_limitations>Jack limitations</h3>
+
+<ul>
+ <li> The Jack server is mono-user by default, so can be only used by one user on a
+computer. If it is not the case, please, choose different port numbers for each
+user and adjust SERVER_NB_COMPILE accordingly. You can also disable the Jack
+server by setting SERVER=false in your $HOME/.jack.
+ <li> CTS compilation is slow due to current vm-tests-tf integration.
+ <li> Bytecode manipulation tools, like JaCoCo, are not supported.
+</ul>
+
+<h2 id=using_jack_features>Using Jack features</h2>
+
+<p>Jack supports Java programming language 1.7 and integrates additional features
+described below.</p>
+
+<h3 id=predexing>Predexing </h3>
+
+<p>When generating a JACK library file, the .dex of the library is generated and
+stored inside the .jack library file as a pre-dex. When compiling, JACK reuses
+the pre-dex from each library.</p>
+
+<p>All libraries are pre-dexed.</p>
+
+<img src="{@docRoot}images/pre-dex.png" height="75%" width="75%" alt="Jack libraries with pre-dex" />
+<p class="img-caption"><strong>Figure 4. </strong>Jack libraries with pre-dex</p>
+
+<h4 id=limitations>Limitations</h4>
+
+
+<p>Currently, JACK does not reuse the library pre-dex if
+shrinking/obfuscation/repackaging is used in the compilation.</p>
+
+<h3 id=incremental_compilation>Incremental compilation</h3>
+
+
+<p>Incremental compilation means that only components that were touched since the
+last compilation, and their dependencies, are recompiled. Incremental
+compilation can be significantly faster than a full compilation when changes
+are limited to only a limited set of components.</p>
+
+<h4 id=limitations>Limitations</h4>
+
+
+<p>Incremental compilation is deactivated when shrinking, obfuscation, repackaging
+or multi-dex legacy is enabled.</p>
+
+<h4 id=enabling_incremental_builds>Enabling incremental builds</h4>
+
+
+<p>Currently incremental compilation is not enabled by default. To enable
+incremental builds, add the following line to the Android.mk file of the
+project that you want to build incrementally:</p>
+
+<pre class=prettyprint>
+LOCAL_JACK_ENABLED := incremental
+</pre>
+
+<p class="note"><strong>Note:</strong> The first time that you build your project with Jack if some dependencies
+are not built, use <code>mma</code> to build them, and after that you can use the standard build command.</p>
+
+<h3 id=shrinking_and_obfuscation>Shrinking and Obfuscation</h3>
+
+<p>JACK has shrinking and obfuscation support and uses proguard configuration
+files to enable shrinking and obfuscation features. Here are the supported and
+ignored options:</p>
+
+<h4 id=supported_common_options>Supported common options</h4>
+
+
+<p>Common options include the following:</p>
+
+<ul>
+ <li> <code>@</code>
+ <li> <code>-include</code>
+ <li> <code>-basedirectory</code>
+ <li> <code>-injars</code>
+ <li> <code>-outjars // only 1 output jar supported</code>
+ <li> <code>-libraryjars</code>
+ <li> <code>-keep</code>
+ <li> <code>-keepclassmembers</code>
+ <li> <code>-keepclasseswithmembers</code>
+ <li> <code>-keepnames</code>
+ <li> <code>-keepclassmembernames</code>
+ <li> <code>-keepclasseswithmembernames</code>
+ <li> <code>-printseeds</code>
+</ul>
+
+<h4 id=supported_shrinking_options>Supported shrinking options</h4>
+
+
+<p>Shrinking options include the following:</p>
+
+<ul>
+ <li> <code>-dontshrink</code>
+</ul>
+
+<h4 id=supported_obfuscation_options>Supported obfuscation options</h4>
+
+
+<p>Obfuscation options include the following:</p>
+
+<ul>
+ <li> <code>-dontobfuscate</code>
+ <li> <code>-printmapping</code>
+ <li> <code>-applymapping</code>
+ <li> <code>-obfuscationdictionary</code>
+ <li> <code>-classobfuscationdictionary</code>
+ <li> <code>-packageobfuscationdictionary</code>
+ <li> <code>-useuniqueclassmembernames</code>
+ <li> <code>-dontusemixedcaseclassnames</code>
+ <li> <code>-keeppackagenames</code>
+ <li> <code>-flattenpackagehierarchy</code>
+ <li> <code>-repackageclasses</code>
+ <li> <code>-keepattributes</code>
+ <li> <code>-adaptclassstrings</code>
+</ul>
+
+<h4 id=ignored_options>Ignored options</h4>
+
+
+<p>Ignored options include the following:</p>
+
+<ul>
+ <li> <code>-dontoptimize // Jack does not optimize</code>
+ <li> <code>-dontpreverify // Jack does not preverify</code>
+ <li> <code>-skipnonpubliclibraryclasses</code>
+ <li> <code>-dontskipnonpubliclibraryclasses</code>
+ <li> <code>-dontskipnonpubliclibraryclassmembers</code>
+ <li> <code>-keepdirectories</code>
+ <li> <code>-target</code>
+ <li> <code>-forceprocessing</code>
+ <li> <code>-printusage</code>
+ <li> <code>-whyareyoukeeping</code>
+ <li> <code>-optimizations</code>
+ <li> <code>-optimizationpasses</code>
+ <li> <code>-assumenosideeffects</code>
+ <li> <code>-allowaccessmodification</code>
+ <li> <code>-mergeinterfacesaggressively</code>
+ <li> <code>-overloadaggressively</code>
+ <li> <code>-microedition</code>
+ <li> <code>-verbose</code>
+ <li> <code>-dontnote</code>
+ <li> <code>-dontwarn</code>
+ <li> <code>-ignorewarnings</code>
+ <li> <code>-printconfiguration</code>
+ <li> <code>-dump</code>
+</ul>
+
+<p class="note"><strong>Note:</strong> Other options will generate an error.</p>
+
+<h3 id=repackaging>Repackaging</h3>
+
+<p>JACK uses jarjar configuration files to do the repackaging.</p>
+
+<p class="note"><strong>Note:</strong> JACK is compatible with "rule" rule types, but is not compatible with "zap" or
+"keep" rule types. If you need "zap" or "keep" rule types please file a feature
+request with a description of how you use the feature in your app.</p>
+
+<h3 id=multidex_support>Multidex support</h3>
+
+
+<p>Since dex files are limited to 65K methods, apps with over 65K methods must be
+split into multiple dex files. (See <a href="http://developer.android.com/tools/building/multidex.html">‘Building Apps with Over 65K Methods’</a> for more information about multidex.)</p>
+
+<p>Jack offers native and legacy multidex support. </p>
+
