Merge "Add invoke-custom bytecode and format changes."
diff --git a/src/index.jd b/src/index.jd
index b104013..c07f0b5 100644
--- a/src/index.jd
+++ b/src/index.jd
@@ -44,6 +44,15 @@
<div class="col-8">
<h3>What's New</h3>
+<h4>Background App Compilation in A/B System Updates</h4>
+
+<p>Examples for
+<strong><a href="{@docRoot}devices/tech/dalvik/configure.html#other_odex">installing</a></strong> and
+<strong><a href="{@docRoot}devices/tech/ota/ab_updates.html#configuration">configuring</a></strong>
+<code>otapreopt_script</code> have been added to explain how to use this tool
+for optimizing user apps so they are ready to run after the device reboots
+during an A/B system update.</p>
+
<h4>February Android Security Bulletin</h4>
<p>The <strong><a href="{@docRoot}security/bulletin/2017-02-01.html">February
2017 Android Security Bulletin</a></strong> has been published along with links
@@ -77,12 +86,6 @@
href="{@docRoot}security/bulletin/2016-12-01.html">December 2016 Public
Security Bulletin</a></strong>.</p>
-<h4>USB headset specification</h4>
-<p>New guidelines for creating
-<strong><a href="{@docRoot}devices/accessories/headset/usb-headset-spec.html">USB
-headsets</a></strong> have been published, and other headset documentation has
-been updated and reorganized.</p>
-
<h4>dalvik.annotation.MethodParameters</h4>
<p>A <code>dalvik.annotation.MethodParameters</code> annotation has been added
to AOSP after Android 7.1 that is optional and can be used to provide parameter
diff --git a/src/source/building-kernels.jd b/src/source/building-kernels.jd
index 527618a..a211b37 100644
--- a/src/source/building-kernels.jd
+++ b/src/source/building-kernels.jd
@@ -42,6 +42,18 @@
<th>Build configuration</th>
</tr>
<tr>
+ <td>marlin</td>
+ <td>device/google/marlin-kernel</td>
+ <td>kernel/msm</td>
+ <td>marlin_defconfig</td>
+ </tr>
+ <tr>
+ <td>sailfish</td>
+ <td>device/google/marlin-kernel</td>
+ <td>kernel/msm</td>
+ <td>marlin_defconfig</td>
+ </tr>
+ <tr>
<td>hikey</td>
<td>device/linaro/hikey-kernel</td>
<td>kernel/hikey-linaro</td>
@@ -209,7 +221,8 @@
<li>The <code>goldfish</code> project contains the kernel sources for the
emulated platforms.</li>
<li>The <code>msm</code> project has the sources for ADP1, ADP2, Nexus One,
-Nexus 4, Nexus 5, Nexus 6, Nexus 5X, Nexus 6P, Nexus 7 (2013), and can be used
+Nexus 4, Nexus 5, Nexus 6, Nexus 5X, Nexus 6P, Nexus 7 (2013), Pixel,
+and Pixel XL, and can be used
as a starting point for work on Qualcomm MSM chipsets.</li>
<li>The <code>omap</code> project is used for PandaBoard and Galaxy Nexus,
and can be used as a starting point for work on TI OMAP chipsets.</li>
diff --git a/src/source/running.jd b/src/source/running.jd
index 69d97de..45e6c9a 100644
--- a/src/source/running.jd
+++ b/src/source/running.jd
@@ -37,105 +37,131 @@
</code></pre>
<h2 id="booting-into-fastboot-mode">Booting into fastboot mode</h2>
-<p>During a cold boot of a device, use the following key combinations to boot
-into fastboot mode, which is a mode in the bootloader that can be used to flash
-the device:</p>
+<p><em>Fastboot</em> is a bootloader mode in which you can flash a device.
+During a cold boot of a device, use the following key combinations to boot into
+fastboot mode:</p>
<table>
<thead>
<tr>
+<th>Codename</th>
<th>Device</th>
<th>Keys</th>
</tr>
</thead>
<tbody>
<tr>
+<td>marlin</td><td>Pixel XL</td>
+<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
+</tr>
+<tr>
+<td>sailfish</td>
+<td>Pixel</td>
+<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
+</tr>
+<tr>
+<td>hikey</td>
<td>hikey</td>
<td>Link pins 1 - 2 and 5 - 6 of J15</td>
</tr>
<tr>
<td>angler</td>
+<td>Nexus 6P</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>bullhead</td>
+<td>Nexus 5X</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>shamu</td>
+<td>Nexus 6</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>fugu</td>
+<td>Nexus Player</td>
<td>Press and hold <em>Power</em></td>
</tr>
<tr>
<td>volantis</td>
+<td>Nexus 9</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>hammerhead</td>
+<td>Nexus 5</td>
<td>Press and hold both <em>Volume Up</em> and <em>Volume Down</em>, then press
and hold <em>Power</em></td>
</tr>
<tr>
<td>flo</td>
+<td>Nexus 7</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>deb</td>
+<td>Nexus 7 3G</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>manta</td>
+<td>Nexus 10</td>
<td>Press and hold both <em>Volume Up</em> and <em>Volume Down</em>, then press
and hold <em>Power</em></td>
</tr>
<tr>
<td>mako</td>
+<td>Nexus 4</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>grouper</td>
+<td>Nexus 7 (2012)</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>tilapia</td>
+<td>Nexus 7 3G (2012)</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>phantasm</td>
+<td>Nexus Q</td>
<td>Power the device, cover it with one hand after the LEDs light up and until
they turn red</td>
</tr>
<tr>
<td>maguro</td>
+<td>Galaxy Nexus GSM</td>
<td>Press and hold both <em>Volume Up</em> and <em>Volume Down</em>, then press
and hold <em>Power</em></td>
</tr>
<tr>
<td>toro</td>
+<td>Galaxy Nexus (Verizon)</td>
<td>Press and hold both <em>Volume Up</em> and <em>Volume Down</em>, then press
and hold <em>Power</em></td>
</tr>
<tr>
<td>toroplus</td>
+<td>Galaxy Nexus (Sprint)</td>
<td>Press and hold both <em>Volume Up</em> and <em>Volume Down</em>, then press
and hold <em>Power</em></td>
</tr>
<tr>
-<td>panda</td>
-<td>Press and hold <em>Input</em>, then press <em>Power</em></td>
-</tr>
-<tr>
<td>wingray</td>
+<td>Motorola Xoom</td>
<td>Press and hold <em>Volume Down</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>crespo</td>
+<td>Nexus S</td>
<td>Press and hold <em>Volume Up</em>, then press and hold <em>Power</em></td>
</tr>
<tr>
<td>crespo4g</td>
+<td>Nexus SG</td>
<td>Press and hold <em>Volume Up</em>, then press and hold <em>Power</em></td>
</tr>
</tbody>
@@ -145,99 +171,106 @@
<h2 id="unlocking-the-bootloader">Unlocking the bootloader</h2>
-<p>It's possible to flash a custom system only if the bootloader allows it, and
-the bootloader is locked by default. You can unlock the bootloader, but be aware
-that doing so deletes the user data for privacy reasons (the unlock operation
-needs to run only once). After unlocking, all data on the device is erased, i.e.
-both the applications' private data and the shared data that is accessible over
-USB, including photos and movies. Be sure to back up any precious files before
-unlocking the bootloader.</p>
+<p>You can flash a custom system only if the bootloader allows it, and the
+bootloader is locked by default. You can unlock the bootloader, but doing so
+deletes user data for privacy reasons. After unlocking, <em>all</em> data on the
+device is erased, i.e. both application private data and shared data accessible
+over USB (including photos and movies). Before attempting to unlock the
+bootloader, be sure to back up any important files on the device.</p>
-<p>With the device in fastboot mode, unlock the bootloader using:</p>
+<p>You need to unlock the bootloader only once, and you can re-lock it if
+necessary.</p>
-<pre>
-$ fastboot oem unlock
-</pre>
+<h3>Unlocking recent devices</h3>
+<p>All Nexus and Pixel devices released since 2014 (starting with Nexus 6 and
+Nexus 9) have factory reset protection and require a multi-step process to
+unlock the bootloader.</p>
-<p>The procedure must be confirmed on-screen.</p>
+<ol>
+<li>Enable OEM unlocking on the device:
+<ol style="list-style-type:lower-alpha">
+<li>In Settings, tap <strong>About phone</strong>, then tap <strong>Build
+number</strong> seven (7) times.</li>
+<li>When you see the message "You are a developer", tap the back button.</li>
+<li>Tap <strong>Developer options</strong> and enable
+<strong>OEM unlocking</strong> and <strong>USB debugging</strong>.
+(If OEM unlocking is disabled, connect to the Internet so the device can check
+in at least once. If it remains disabled, your device may be SIM locked by your
+carrier and the bootloader cannot be unlocked.)</li></ol></li>
+<li>Reboot into the bootloader and use fastboot to unlock it.
+<ul>
+<li>For new devices (2015 and later): <code>$ fastboot flashing unlock</code>
+</li>
+<li>For older devices (2014 and earlier): <code>$ fastboot oem
+unlock</code></li></ul>
+You must confirm the unlock onscreen.</li></ol>
-<p>On Nexus 10, after unlocking the bootloader, the internal storage remains
-unformatted. You can format the device using:</p>
-
-<pre>
-$ fastboot format cache
+<p class="note"><strong>Note</strong> On Nexus 10, after unlocking the
+bootloader, the internal storage remains unformatted. You can format the device
+using:
+<pre><code>$ fastboot format cache
$ fastboot format userdata
-</pre>
+</code></pre></p>
-<p>To re-lock the bootloader, use:</p>
+<h3 id="relocking-the-bootloader">Re-locking the bootloader</h3>
+<p>To re-lock the bootloader:</p>
+<ul>
+<li>For new devices (2015 and later): <code>$ fastboot flashing lock</code></li>
+<li>For older devices (2014 and earlier): <code>$ fastboot oem lock</code></li>
+</ul>
-<pre>$ fastboot oem lock
-</pre>
-
-<p class="note"><strong>Note</strong>: Re-locking the bootloading on a Motorola Xoom
-erases user data (including the shared USB data).</p>
+<p class="note"><strong>Note</strong>: Re-locking the bootloading on a Motorola
+Xoom erases user data (including the shared USB data).</p>
<h2 id="flash-unlock">Using Flash Unlock</h2>
-<p>
-Android 7.0 introduces a new system API, <code>getFlashLockState()</code>, to
-transmit bootloader state.
-</p>
-
-<p>
-Android 7.0 added the following system API that returns the bootloader’s lock
-status on compliant devices:
-</p>
+<p>Android 7.0 includes a new system API, <code>getFlashLockState()</code>, to
+transmit bootloader state, as well as the following system API that returns the
+bootloader’s lock status on compliant devices:</p>
<pre>
PersistentDataBlockManager.getFlashLockState()
</pre>
<table>
- <tr>
- <th>Return value</th>
- <th>Conditions</th>
- </tr>
- <tr>
- <td><code>FLASH_LOCK_UNKNOWN</code>
- </td>
- <td>Returned only by devices upgrading to Android 7.0 that have not supported
+<tr>
+<th>Return value</th>
+<th>Conditions</th>
+</tr>
+<tr>
+<td><code>FLASH_LOCK_UNKNOWN</code>
+</td>
+<td><p>Returned only by devices upgrading to Android 7.0 that have not supported
bootloader changes required to get the flash lock status if they support
-flashing lock/unlock capability.
-<p>
-New Android 7.0 devices must be in either <code>FLASH_LOCK_LOCKED</code> or <code>FLASH_LOCK_UNLOCKED</code> state.
-If a device is upgrading to Android 7.0 and does not support flashing unlock/lock
-capability, then it should simply return <code>FLASH_LOCK_LOCKED</code> state.
- </td>
- </tr>
- <tr>
- <td><code>FLASH_LOCK_LOCKED</code>
- </td>
- <td>Should be returned by any device that does not support flashing
+flashing lock/unlock capability.</p>
+<p>New Android 7.0 devices must be in either <code>FLASH_LOCK_LOCKED</code> or
+<code>FLASH_LOCK_UNLOCKED</code> state. If a device is upgrading to Android 7.0
+and does not support flashing unlock/lock capability, it should simply return
+<code>FLASH_LOCK_LOCKED</code> state.</p>
+</td>
+</tr>
+<tr>
+<td><code>FLASH_LOCK_LOCKED</code>
+</td>
+<td>Should be returned by any device that does not support flashing
lock/unlock (i.e. the device is always locked), or any device that does support
flashing lock/unlock and is in the locked state.
- </td>
- </tr>
- <tr>
- <td><code>FLASH_LOCK_UNLOCKED</code>
- </td>
- <td>Returned by any device that supports flashing lock/unlock and is
+</td>
+</tr>
+<tr>
+<td><code>FLASH_LOCK_UNLOCKED</code>
+</td>
+<td>Returned by any device that supports flashing lock/unlock and is
currently in the unlocked state.
- </td>
- </tr>
+</td>
+</tr>
</table>
<h3 id="examples-and-source">Examples and source</h3>
-<p>
-In the Android 7.0 release, the Android Open Source Project (AOSP) contains a reference
-implementation that returns a value based on the <code>ro.boot.flash.locked
-</code>boot property.
-</p>
-
-<p>
-The code lives in:
-</p>
+<p>AOSP contains a reference implementation that returns a value based on the
+<code>ro.boot.flash.locked</code> boot property. The code lives in the following
+directories:</p>
<pre>
frameworks/base/services/core/java/com/android/server/PersistentDataBlockService.java
@@ -245,149 +278,147 @@
</pre>
<h3 id="validation">Validation</h3>
-<p>
-Manufacturers should test the values returned by devices with locked and
-unlocked bootloaders.
-</p>
+<p>Manufacturers should test the values returned by devices with locked and
+unlocked bootloaders.</p>
<h2 id="selecting-device-build">Selecting a device build</h2>
<p>The recommended builds for devices are available from the lunch menu,
accessed when running the <code>lunch</code> command with no arguments. You can
-download factory images and binaries for Nexus devices from developers.google.com:</p>
+download factory images and binaries for Nexus devices from
+developers.google.com:</p>
<ul>
-<li><a href="https://developers.google.com/android/nexus/blobs-preview">Preview binaries (blobs)</a></li>
-<li><a href="https://developers.google.com/android/nexus/images">Factory images for released devices</a></li>
-<li><a href="https://developers.google.com/android/nexus/drivers">Support binaries (drivers) for release devices</a></li>
+<li><a href="https://developers.google.com/android/nexus/blobs-preview">Preview
+binaries (blobs)</a></li>
+<li><a href="https://developers.google.com/android/nexus/images">Factory images
+for released devices</a></li>
+<li><a href="https://developers.google.com/android/nexus/drivers">Support
+binaries (drivers) for release devices</a></li>
</ul>
-<p>See <a href="building.html#obtaining-proprietary-binaries">Obtaining
-proprietary binaries</a> for more details and <a
-href="requirements.html#binaries">Device binaries requirements</a> for other
-resources.</p>
+<p>For details and additional resources, see
+<a href="building.html#obtaining-proprietary-binaries">Obtaining proprietary
+binaries</a> and <a href="requirements.html#binaries">Device binaries
+requirements</a>.</p>
<table>
<thead>
<tr>
- <th>Device</th>
+<th>Device</th>
<th>Code name</th>
<th>Build configuration</th>
</tr>
</thead>
<tbody>
<tr>
- <td>Pixel XL</td>
+<td>Pixel XL</td>
<td>marlin</td>
<td>aosp_marlin-userdebug</td>
</tr>
<tr>
- <td>Pixel</td>
+<td>Pixel</td>
<td>sailfish</td>
<td>aosp_sailfish-userdebug</td>
- </tr>
+</tr>
<tr>
- <td>HiKey</td>
+<td>HiKey</td>
<td>hikey</td>
<td>hikey-userdebug</td>
</tr>
<tr>
- <td>Nexus 6P</td>
+<td>Nexus 6P</td>
<td>angler</td>
<td>aosp_angler-userdebug</td>
</tr>
<tr>
- <td>Nexus 5X</td>
+<td>Nexus 5X</td>
<td>bullhead</td>
<td>aosp_bullhead-userdebug</td>
</tr>
<tr>
- <td>Nexus 6</td>
+<td>Nexus 6</td>
<td>shamu</td>
<td>aosp_shamu-userdebug</td>
</tr>
<tr>
- <td>Nexus Player</td>
+<td>Nexus Player</td>
<td>fugu</td>
<td>aosp_fugu-userdebug</td>
</tr>
<tr>
- <td>Nexus 9</td>
+<td>Nexus 9</td>
<td>volantis (flounder)</td>
<td>aosp_flounder-userdebug</td>
</tr>
<tr>
- <td>Nexus 5 (GSM/LTE)</td>
+<td>Nexus 5 (GSM/LTE)</td>
<td>hammerhead</td>
<td>aosp_hammerhead-userdebug</td>
</tr>
<tr>
- <td>Nexus 7 (Wi-Fi)</td>
+<td>Nexus 7 (Wi-Fi)</td>
<td>razor (flo)</td>
<td>aosp_flo-userdebug</td>
</tr>
<tr>
- <td>Nexus 7 (Mobile)</td>
+<td>Nexus 7 (Mobile)</td>
<td>razorg (deb)</td>
<td>aosp_deb-userdebug</td>
</tr>
<tr>
- <td>Nexus 10</td>
+<td>Nexus 10</td>
<td>mantaray (manta)</td>
<td>full_manta-userdebug</td>
</tr>
<tr>
- <td>Nexus 4</td>
+<td>Nexus 4</td>
<td>occam (mako)</td>
<td>full_mako-userdebug</td>
</tr>
<tr>
- <td>Nexus 7 (Wi-Fi)</td>
+<td>Nexus 7 (Wi-Fi)</td>
<td>nakasi (grouper)</td>
<td>full_grouper-userdebug</td>
</tr>
<tr>
- <td>Nexus 7 (Mobile)</td>
+<td>Nexus 7 (Mobile)</td>
<td>nakasig (tilapia)</td>
<td>full_tilapia-userdebug</td>
</tr>
<tr>
- <td>Galaxy Nexus (GSM/HSPA+)</td>
+<td>Galaxy Nexus (GSM/HSPA+)</td>
<td>yakju (maguro)</td>
<td>full_maguro-userdebug</td>
</tr>
<tr>
- <td>Galaxy Nexus (Verizon)</td>
+<td>Galaxy Nexus (Verizon)</td>
<td>mysid (toro)</td>
<td>aosp_toro-userdebug</td>
</tr>
<tr>
- <td>Galaxy Nexus (Experimental)</td>
+<td>Galaxy Nexus (Experimental)</td>
<td>mysidspr (toroplus)</td>
<td>aosp_toroplus-userdebug</td>
</tr>
<tr>
- <td>PandaBoard (Archived)</td>
-<td>panda</td>
-<td>aosp_panda-userdebug</td>
-</tr>
-<tr>
- <td>Motorola Xoom (U.S. Wi-Fi)</td>
+<td>Motorola Xoom (U.S. Wi-Fi)</td>
<td>wingray</td>
<td>full_wingray-userdebug</td>
</tr>
<tr>
- <td>Nexus S</td>
+<td>Nexus S</td>
<td>soju (crespo)</td>
<td>full_crespo-userdebug</td>
</tr>
<tr>
- <td>Nexus S 4G</td>
+<td>Nexus S 4G</td>
<td>sojus (crespo4g)</td>
<td>full_crespo4g-userdebug</td>
</tr>
</tbody>
</table>
+
<p class="note"><b>Note</b>: Do not use Android 4.1.1 on a Nexus 7 originally
sold with Android 4.1.2 or newer.</p>
@@ -395,7 +426,7 @@
<p>You can flash an entire Android system in a single command; doing so verifies
the system being flashed is compatible with the installed bootloader and radio,
-writes the boot, recovery, and system partitions together, and then reboots the
+writes the boot, recovery, and system partitions together, then reboots the
system. Flashing also erases all user data, similarly to <code>fastboot oem
unlock</code>.</p>
@@ -406,7 +437,7 @@
$ adb reboot bootloader
</pre>
-<p>Once the device is in fastboot mode, run:</p>
+<p>After the device is in fastboot mode, run:</p>
<pre>
$ fastboot flashall -w
@@ -416,14 +447,15 @@
device; this is useful for your first time flashing a particular device but is
otherwise unnecessary.</p>
-<p class="note"><strong>Note</strong>: Filesystems created via fastboot on Motorola Xoom
-do not function optimally. We recommend re-creating filesystems through
-recovery, using: <code>$ adb reboot recovery</code>. While in recovery, open the
-menu (press Power + Volume Up), wipe the cache partition, then wipe data.</p>
+<p class="note"><strong>Note</strong>: Filesystems created via fastboot on
+Motorola Xoom do not function optimally. We recommend re-creating filesystems
+through recovery, using: <code>$ adb reboot recovery</code>. While in recovery,
+open the menu (press Power + Volume Up), wipe the cache partition, then wipe
+data.</p>
-<h2 id="restoring-devices-to-factory-state">Restoring devices to
-factory state</h2>
+<h2 id="restoring-devices-to-factory-state">Restoring devices to factory
+state</h2>
<p>Factory images for Nexus 5, Nexus 10, Nexus 4, Nexus Q, Nexus 7, Galaxy Nexus
(GSM/HSPA+ "yakju" and "takju", and CDMA/LTE "mysid" and "mysidspr"), Nexus S,
