Docs: Changes to source.android.com

  - 182097815 Devsite localized content from translation request 89fffe... by Android Partner Docs <noreply@android.com>
  - 182097813 Devsite localized content from translation request be8c28... by Android Partner Docs <noreply@android.com>
  - 182097355 Devsite localized content from translation request 4fe194... by Android Partner Docs <noreply@android.com>
  - 181865621 Fix typo in Retail Demo Mode page by Android Partner Docs <noreply@android.com>
  - 181807349 CDD: Remove redundant requirement on UMS/MTP from 7.7 by Android Partner Docs <noreply@android.com>
  - 181807212 CDD: Clarify the charging specs to refer when a USB type ... by Android Partner Docs <noreply@android.com>
  - 181804909 CDD: Relax CDD for activity switching. by Android Partner Docs <noreply@android.com>
  - 181804579 CDD: Clarify that the AOSP implementation of TEE is a pre... by Android Partner Docs <noreply@android.com>
  - 181804086  by Android Partner Docs <noreply@android.com>
  - 181767441 Devsite localized content from translation request d399d0... by Android Partner Docs <noreply@android.com>
  - 181767313 Devsite localized content from translation request 209cd7... by Android Partner Docs <noreply@android.com>
  - 181624191 Devsite localized content from translation request 66ed20... by Android Partner Docs <noreply@android.com>
  - 181624182 Devsite localized content from translation request 6766af... by Android Partner Docs <noreply@android.com>
  - 181624174 Devsite localized content from translation request 97607c... by Android Partner Docs <noreply@android.com>
  - 181488065 Update CTS/CTS-Verifier downloads for CTS-Jan-2018 Releases by Android Partner Docs <noreply@android.com>
  - 181482740 Break out the FAQs into a separate page now that A/B is i... by Christina Nguyen <cqn@google.com>
  - 181409586 Reverted the old cl/181349324 and re-did the changes usin... by Christina Nguyen <cqn@google.com>
  - 181388377 Devsite localized content from translation request a3ea97... by Android Partner Docs <noreply@android.com>
  - 181387974 Devsite localized content from translation request 70181e... by Android Partner Docs <noreply@android.com>
  - 181387712 Removing unused Git resources file (was previously remove... by Heidi von Markham <hvm@google.com>

PiperOrigin-RevId: 182097815
Change-Id: I4df35e68e1c85e2c29f0438820528f326b097cea

12 files changed, 435 insertions, 404 deletions

diff --git a/en/devices/_toc-tech.yaml b/en/devices/_toc-tech.yaml
index 43897c47..77e2419f 100644
--- a/en/devices/_toc-tech.yaml
+++ b/en/devices/_toc-tech.yaml
@@ -188,17 +188,23 @@ toc:
   - title: Reducing OTA Size
     path: /devices/tech/ota/reduce_size
   - title: A/B System Updates
-    path: /devices/tech/ota/ab_updates
-  - title: Implementing A/B Updates
-    path: /devices/tech/ota/ab_implement
+    section:
+    - title: Overview
+      path: /devices/tech/ota/ab/
+    - title: Implementing A/B Updates
+      path: /devices/tech/ota/ab/ab_implement
+    - title: Frequently Asked Questions
+      path: /devices/tech/ota/ab/ab_faqs
   - title: Non-A/B System Updates
-    path: /devices/tech/ota/nonab_updates
-  - title: Block-Based OTA
-    path: /devices/tech/ota/block
-  - title: Inside OTA Packages
-    path: /devices/tech/ota/inside_packages
-  - title: Device-Specific Code
-    path: /devices/tech/ota/device_code
+    section:
+    - title: Overview
+      path: /devices/tech/ota/nonab/
+    - title: Block-Based OTA
+      path: /devices/tech/ota/nonab/block
+    - title: Inside OTA Packages
+      path: /devices/tech/ota/nonab/inside_packages
+    - title: Device-Specific Code
+      path: /devices/tech/ota/nonab/device_code
 - title: Performance
   section:
   - title: Overview
diff --git a/en/devices/tech/display/retail-mode.html b/en/devices/tech/display/retail-mode.html
index 2928b88a..5e124735 100644
--- a/en/devices/tech/display/retail-mode.html
+++ b/en/devices/tech/display/retail-mode.html
@@ -53,7 +53,7 @@ be set.
 <h4 id="create-demo-app">Creating the demo application</h4>
 <p>
 Device owner apps do not need elevated privileges or pre-installation on the
-system image. They are mostly implmented like traditional apps, with the
+system image. They are mostly implemented like traditional apps, with the
 following differences:
 </p>
 <ul>
diff --git a/en/devices/tech/ota/ab/ab_faqs.html b/en/devices/tech/ota/ab/ab_faqs.html
new file mode 100644
index 00000000..ff978c36
--- /dev/null
+++ b/en/devices/tech/ota/ab/ab_faqs.html
@@ -0,0 +1,400 @@
+<html devsite>
+  <head>
+    <title>Frequently Asked Questions</title>
+    <meta name="project_path" value="/_project.yaml" />
+    <meta name="book_path" value="/_book.yaml" />
+  </head>
+  <body>
+  <!--
+      Copyright 2018 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.
+  -->
+
+
+      <h3>Has Google used A/B OTAs on any devices?</h3>
+
+        <p>
+          Yes. The marketing name for A/B updates is <em>seamless updates</em>.
+          Pixel and Pixel XL phones from October 2016 shipped with A/B, and
+          all Chromebooks use the same <code>update_engine</code>
+          implementation of A/B. The necessary platform code implementation is
+          public in Android 7.1 and higher.
+        </p>
+
+      <h3>Why are A/B OTAs better?</h3>
+
+      <p>A/B OTAs provide a better user experience when taking updates. Measurements
+      from monthly security updates show this feature has already proven a success: As
+      of May 2017, 95% of Pixel owners are running the latest security update after a
+      month compared to 87% of Nexus users, and Pixel users update sooner than Nexus
+      users. Failures to update blocks during an OTA no longer result in a device that
+      won't boot; until the new system image has successfully booted, Android retains
+      the ability to fall back to the previous working system image.</p>
+
+      <h3>How did A/B affect the 2016 Pixel partition sizes?</h3>
+
+      <p>The following table contains details on the shipping A/B configuration versus
+      the internally-tested non-A/B configuration:</p>
+
+      <table>
+        <tbody>
+          <tr>
+            <th>Pixel partition sizes</th>
+            <th width="33%">A/B</th>
+            <th width="33%">Non-A/B</th>
+          </tr>
+          <tr>
+            <td>Bootloader</td>
+            <td>50*2</td>
+            <td>50</td>
+          </tr>
+          <tr>
+            <td>Boot</td>
+            <td>32*2</td>
+            <td>32</td>
+          </tr>
+          <tr>
+            <td>Recovery</td>
+            <td>0</td>
+            <td>32</td>
+          </tr>
+          <tr>
+            <td>Cache</td>
+            <td>0</td>
+            <td>100</td>
+          </tr>
+          <tr>
+            <td>Radio</td>
+            <td>70*2</td>
+            <td>70</td>
+          </tr>
+          <tr>
+            <td>Vendor</td>
+            <td>300*2</td>
+            <td>300</td>
+          </tr>
+          <tr>
+            <td>System</td>
+            <td>2048*2</td>
+            <td>4096</td>
+          </tr>
+          <tr>
+            <td><strong>Total</strong></td>
+            <td><strong>5000</strong></td>
+            <td><strong>4680</strong></td>
+          </tr>
+        </tbody>
+      </table>
+
+      <p>A/B updates require an increase of only 320 MiB in flash, with a savings of
+      32MiB from removing the recovery partition and another 100MiB preserved by
+      removing the cache partition. This balances the cost of the B partitions for
+      the bootloader, the boot partition, and the radio partition. The vendor
+      partition doubled in size (the vast majority of the size increase). Pixel's
+      A/B system image is half the size of the original non-A/B system image.
+      </p>
+
+      <p>For the Pixel A/B and non-A/B variants tested internally (only A/B shipped),
+      the space used differed by only 320MiB. On a 32GiB device, this is just under
+      1%. For a 16GiB device this would be less than 2%, and for an 8GiB device almost
+      4% (assuming all three devices had the same system image).</p>
+
+      <h3>Why didn't you use SquashFS?</h3>
+
+      <p>We experimented with SquashFS but weren't able to achieve the performance
+      desired for a high-end device. We don't use or recommend SquashFS for handheld
+      devices.</p>
+
+      <p>More specifically, SquashFS provided about 50% size savings on the system
+      partition, but the overwhelming majority of the files that compressed well were
+      the precompiled .odex files. Those files had very high compression ratios
+      (approaching 80%), but the compression ratio for the rest of the system
+      partition was much lower. In addition, SquashFS in Android 7.0 raised the
+      following performance concerns:</p>
+
+      <ul>
+        <li>Pixel has very fast flash compared to earlier devices but not a huge
+          number of spare CPU cycles, so reading fewer bytes from flash but needing
+          more CPU for I/O was a potential bottleneck.</li>
+        <li>I/O changes that perform well on an artificial benchmark run on an
+          unloaded system sometimes don't work well on real-world use cases under
+          real-world load (such as crypto on Nexus 6).</li>
+        <li>Benchmarking showed 85% regressions in some places.</li>
+        </ul>
+
+      <p>As SquashFS matures and adds features to reduce CPU impact (such as a
+      whitelist of commonly-accessed files that shouldn't be compressed), we will
+      continue to evaluate it and offer recommendations to device manufacturers.</p>
+
+      <h3>How did you halve the size of the system partition without SquashFS?</h3>
+
+      <p>Applications are stored in .apk files, which are actually ZIP archives. Each
+      .apk file has inside it one or more .dex files containing portable Dalvik
+      bytecode. An .odex file (optimized .dex) lives separately from the .apk file
+      and can contain machine code specific to the device. If an .odex file is
+      available, Android can run applications at ahead-of-time compiled speeds
+      without having to wait for the code to be compiled each time the application is
+      launched. An .odex file isn't strictly necessary: Android can actually run the
+      .dex code directly via interpretation or Just-In-Time (JIT) compilation, but an
+      .odex file provides the best combination of launch speed and run-time speed if
+      space is available.</p>
+
+      <p>Example: For the installed-files.txt from a Nexus 6P running Android 7.1 with
+      a total system image size of 2628MiB (2755792836 bytes), the breakdown of the
+      largest contributors to overall system image size by file type is as follows:
+      </p>
+
+      <table>
+      <tbody>
+      <tr>
+      <td>.odex</td>
+      <td>1391770312 bytes</td>
+      <td>50.5%</td>
+      </tr>
+      <tr>
+      <td>.apk</td>
+      <td>846878259 bytes</td>
+      <td>30.7%</td>
+      </tr>
+      <tr>
+      <td>.so (native C/C++ code)</td>
+      <td>202162479 bytes</td>
+      <td>7.3%</td>
+      </tr>
+      <tr>
+      <td>.oat files/.art images</td>
+      <td>163892188 bytes</td>
+      <td>5.9%</td>
+      </tr>
+      <tr>
+      <td>Fonts</td>
+      <td>38952361 bytes</td>
+      <td>1.4%</td>
+      </tr>
+      <tr>
+      <td>icu locale data</td>
+      <td>27468687 bytes</td>
+      <td>0.9%</td>
+      </tr>
+      </tbody>
+      </table>
+
+      <p>These figures are similar for other devices too, so on Nexus/Pixel
+      devices, .odex files take up approximately half the system partition. This meant
+      we could continue to use ext4 but write the .odex files to the B partition
+      at the factory and then copy them to <code>/data</code> on first boot. The
+      actual storage used with ext4 A/B is identical to SquashFS A/B, because if we
+      had used SquashFS we would have shipped the preopted .odex files on system_a
+      instead of system_b.</p>
+
+      <h3>Doesn't copying .odex files to /data mean the space saved on /system is
+      lost on /data?</h3>
+
+      <p>Not exactly. On Pixel, most of the space taken by .odex files is for apps,
+      which typically exist on <code>/data</code>. These apps take Google Play
+      updates, so the .apk and .odex files on the system image are unused for most of
+      the life of the device. Such files can be excluded entirely and replaced by
+      small, profile-driven .odex files when the user actually uses each app (thus
+      requiring no space for apps the user doesn't use). For details, refer to the
+      Google I/O 2016 talk <a href="https://www.youtube.com/watch?v=fwMM6g7wpQ8">The
+      Evolution of Art</a>.</p>
+
+      <p>The comparison is difficult for a few key reasons:</p>
+      <ul>
+      <li>Apps updated by Google Play have always had their .odex files on
+      <code>/data</code> as soon as they receive their first update.</li>
+      <li>Apps the user doesn't run don't need an .odex file at all.</li>
+      <li>Profile-driven compilation generates smaller .odex files than ahead-of-time
+      compilation (because the former optimizes only performance-critical code).</li>
+      </ul>
+
+      <p>For details on the tuning options available to OEMs, see
+      <a href="/devices/tech/dalvik/configure.html">Configuring ART</a>.</p>
+
+      <h3>Aren't there two copies of the .odex files on /data?</h3>
+
+      <p>It's a little more complicated ... After the new system image has been
+      written, the new version of dex2oat is run against the new .dex files to
+      generate the new .odex files. This occurs while the old system is still running,
+      so the old and new .odex files are both on <code>/data</code> at the same time.
+      </p>
+
+      <p>The code in OtaDexoptService
+      (<code><a href="https://android.googlesource.com/platform/frameworks/base/+/nougat-mr1-release/services/core/java/com/android/server/pm/OtaDexoptService.java#200" class="external">frameworks/base/+/nougat-mr1-release/services/core/java/com/android/server/pm/OtaDexoptService.java#200</a></code>)
+      calls <code>getAvailableSpace</code> before optimizing each package to avoid
+      over-filling <code>/data</code>. Note that <em>available</em> here is still
+      conservative: it's the amount of space left <em>before</em> hitting the usual
+      system low space threshold (measured as both a percentage and a byte count). So
+      if <code>/data</code> is full, there won't be two copies of every .odex file.
+      The same code also has a BULK_DELETE_THRESHOLD: If the device gets that close
+      to filling the available space (as just described), the .odex files belonging to
+      apps that aren't used are removed. That's another case without two copies of
+      every .odex file.</p>
+
+      <p>In the worst case where <code>/data</code> is completely full, the update
+      waits until the device has rebooted into the new system and no longer needs the
+      old system's .odex files. The PackageManager handles this:
+      (<code><a href="https://android.googlesource.com/platform/frameworks/base/+/nougat-mr1-release/services/core/java/com/android/server/pm/PackageManagerService.java#7215" class="external">frameworks/base/+/nougat-mr1-release/services/core/java/com/android/server/pm/PackageManagerService.java#7215</a></code>). After the new system has
+      successfully booted, <code>installd</code>
+      (<code><a href="https://android.googlesource.com/platform/frameworks/native/+/nougat-mr1-release/cmds/installd/commands.cpp#2192" class="external">frameworks/native/+/nougat-mr1-release/cmds/installd/commands.cpp#2192</a></code>)
+      can remove the .odex files that were used by the old system, returning the
+      device back to the steady state where there's only one copy.</p>
+
+      <p>So, while it is possible that <code>/data</code> contains two copies of all
+      the .odex files, (a) this is temporary and (b) only occurs if you had plenty of
+      free space on <code>/data</code> anyway. Except during an update, there's only
+      one copy. And as part of ART's general robustness features, it will never fill
+      <code>/data</code> with .odex files anyway (because that would be a problem on a
+      non-A/B system too).</p>
+
+      <h3>Doesn't all this writing/copying increase flash wear?</h3>
+
+      <p>Only a small portion of flash is rewritten: a full Pixel system update
+      writes about 2.3GiB. (Apps are also recompiled, but that's true of non-A/B
+      too.) Traditionally, block-based full OTAs wrote a similar amount of data, so
+      flash wear rates should be similar.</p>
+
+      <h3>Does flashing two system partitions increase factory flashing time?</h3>
+
+      <p>No. Pixel didn't increase in system image size (it merely divided the space
+      across two partitions).</p>
+
+      <h3>Doesn't keeping .odex files on B make rebooting after factory data reset
+      slow?</h3>
+
+      <p>Yes. If you've actually used a device, taken an OTA, and performed a factory
+      data reset, the first reboot will be slower than it would otherwise be (1m40s vs
+      40s on a Pixel XL) because the .odex files will have been lost from B after the
+      first OTA and so can't be copied to <code>/data</code>. That's the trade-off.</p>
+
+      <p>Factory data reset should be a rare operation when compared to regular boot
+      so the time taken is less important. (This doesn't affect users or reviewers who
+      get their device from the factory, because in that case the B partition is
+      available.) Use of the JIT compiler means we don't need to recompile
+      <em>everything</em>, so it's not as bad as you might think. It's also possible
+      to mark apps as requiring ahead-of-time compilation using
+      <code>coreApp="true"</code> in the manifest:
+      (<code><a href="https://android.googlesource.com/platform/frameworks/base/+/nougat-mr1-release/packages/SystemUI/AndroidManifest.xml#23" class="external">frameworks/base/+/nougat-mr1-release/packages/SystemUI/AndroidManifest.xml#23</a></code>).
+      This is currently used by <code>system_server</code> because it's not allowed to
+      JIT for security reasons.</p>
+
+      <h3>Doesn't keeping .odex files on /data rather than /system make rebooting
+      after an OTA slow?</h3>
+
+      <p>No. As explained above, the new dex2oat is run while the old system image is
+      still running to generate the files that will be needed by the new system. The
+      update isn't considered available until that work has been done.</p>
+
+      <h3>Can (should) we ship a 32GiB A/B device? 16GiB? 8GiB?</h3>
+
+      <p>32GiB works well as it was proven on Pixel, and 320MiB out of 16GiB means a
+      reduction of 2%. Similarly, 320MiB out of 8GiB a reduction of 4%. Obviously
+      A/B would not be the recommended choice on devices with 4GiB, as the 320MiB
+      overhead is almost 10% of the total available space.</p>
+
+      <h3>Does AVB2.0 require A/B OTAs?</h3>
+
+      <p>No. Android <a href="/security/verifiedboot/">Verified Boot</a> has always
+      required block-based updates, but not necessarily A/B updates.</p>
+
+      <h3>Do A/B OTAs require AVB2.0?</h3>
+
+      <p>No.</p>
+
+      <h3>Do A/B OTAs break AVB2.0's rollback protection?</h3>
+
+      <p>No. There's some confusion here because if an A/B system fails to boot into
+      the new system image it will (after some number of retries determined by your
+      bootloader) automatically revert to the "previous" system image. The key point
+      here though is that "previous" in the A/B sense is actually still the "current"
+      system image. As soon as the device successfully boots a new image, rollback
+      protection kicks in and ensures that you can't go back. But until you've
+      actually successfully booted the new image, rollback protection doesn't
+      consider it to be the current system image.</p>
+
+      <h3>If you're installing an update while the system is running, isn't that
+      slow?</h3>
+
+      <p>With non-A/B updates, the aim is to install the update as quickly as
+      possible because the user is waiting and unable to use their device while the
+      update is applied. With A/B updates, the opposite is true; because the user is
+      still using their device, as little impact as possible is the goal, so the
+      update is deliberately slow. Via logic in the Java system update client (which
+      for Google is GmsCore, the core package provided by GMS), Android also attempts
+      to choose a time when the users aren't using their devices at all. The platform
+      supports pausing/resuming the update, and the client can use that to pause the
+      update if the user starts to use the device and resume it when the device is
+      idle again.</p>
+
+      <p>There are two phases while taking an OTA, shown clearly in the UI as
+      <em>Step 1 of 2</em> and <em>Step 2 of 2</em> under the progress bar. Step 1
+      corresponds with writing the data blocks, while step 2 is pre-compiling the
+      .dex files. These two phases are quite different in terms of performance
+      impact. The first phase is simple I/O. This requires little in the way of
+      resources (RAM, CPU, I/O) because it's just slowly copying blocks around.</p>
+
+      <p>The second phase runs dex2oat to precompile the new system image. This
+      obviously has less clear bounds on its requirements because it compiles actual
+      apps. And there's obviously much more work involved in compiling a large and
+      complex app than a small and simple app; whereas in phase 1 there are no disk
+      blocks that are larger or more complex than others.</p>
+
+      <p>The process is similar to when Google Play installs an app update in the
+      background before showing the <em>5 apps updated</em> notification, as has been
+      done for years.</p>
+
+      <h3>What if a user is actually waiting for the update?</h3>
+
+      <p>The current implementation in GmsCore doesn't distinguish between background
+      updates and user-initiated updates but may do so in the future. In the case
+      where the user explicitly asked for the update to be installed or is watching
+      the update progress screen, we'll prioritize the update work on the assumption
+      that they're actively waiting for it to finish.</p>
+
+      <h3>What happens if there's a failure to apply an update?</h3>
+
+      <p>With non-A/B updates, if an update failed to apply, the user was usually
+      left with an unusable device. The only exception was if the failure occurred
+      before an application had even started (because the package failed to verify,
+      say). With A/B updates, a failure to apply an update does not affect the
+      currently running system. The update can simply be retried later.</p>
+
+      <h3>Which systems on a chip (SoCs) support A/B?</h3>
+
+      <p>As of 2017-03-15, we have the following information:</p>
+      <table class="style0">
+      <tbody>
+      <tr>
+      <td></td>
+      <td><strong>Android 7.x Release</strong></td>
+      <td><strong>Android 8.x Release</strong></td>
+      </tr>
+      <tr>
+      <td><strong>Qualcomm</strong></td>
+      <td>Depending on OEM requests </td>
+      <td>All chipsets will get support</td>
+      </tr>
+      <tr>
+      <td><strong>Mediatek</strong></td>
+      <td>Depending on OEM requests</td>
+      <td>All chipsets will get support</td>
+      </tr>
+      </tbody>
+      </table>
+
+      <p>For details on schedules, check with your SoC contacts. For SoCs not listed
+      above, reach out to your SoC directly.</p>
+
+  </body>
+</html>
\ No newline at end of file
diff --git a/en/devices/tech/ota/ab_implement.html b/en/devices/tech/ota/ab/ab_implement.html
index 4470c978..14d43c08 100644
--- a/en/devices/tech/ota/ab_implement.html
+++ b/en/devices/tech/ota/ab/ab_implement.html
@@ -27,18 +27,19 @@ their bootloader implements the boot_control HAL and passes the
 <a href="#kernel">correct parameters</a> to the kernel.</p>
 
 
-<h2 id=bootcontrol>Implementing the boot control HAL</h2>
+<h2 id="bootcontrol">Implementing the boot control HAL</h2>
 <p>A/B-capable bootloaders must implement the <code>boot_control</code> HAL at
-<code><a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/boot_control.h" class="external">hardware/libhardware/include/hardware/boot_control.h</a></code>. You can test implementations using the
+<code><a href="https://android.googlesource.com/platform/hardware/libhardware/+/master/include/hardware/boot_control.h" class="external">hardware/libhardware/include/hardware/boot_control.h</a></code>.
+You can test implementations using the
 <code><a href="https://android.googlesource.com/platform/system/extras/+/master/bootctl/" class="external">system/extras/bootctl</a></code> utility and
 <code><a href="https://android.googlesource.com/platform/system/extras/+/refs/heads/master/tests/bootloader/" class="external">system/extras/tests/bootloader/</a></code>.
 </p>
 
 <p>You must also implement the state machine shown below:</p>
-<img src="images/ab-updates-state-machine.png">
+<img src="/devices/tech/ota/images/ab-updates-state-machine.png">
 <figcaption><strong>Figure 1.</strong> Bootloader state machine</figcaption>
 
-<h2 id=kernel>Setting up the kernel</h2>
+<h2 id="kernel">Setting up the kernel</h2>
 <p>To implement A/B system updates:</p>
 <ol>
 <li>Cherrypick the following kernel patch series (if needed):
@@ -139,7 +140,7 @@ named <code>a</code>, <code>b</code>, etc.): <code>boot_a</code>,
 <code>boot_b</code>, <code>system_a</code>, <code>system_b</code>,
 <code>vendor_a</code>, <code>vendor_b</code>.</p>
 
-<h3 id=cache>Cache</h3>
+<h3 id="cache">Cache</h3>
 
 <p>For non-A/B updates, the cache partition was used to store downloaded OTA
 packages and to stash blocks temporarily while applying updates. There was
@@ -150,7 +151,7 @@ stash blocks (because you're always writing to a partition that isn't currently
 used) and with streaming A/B there's no need to download the whole OTA package
 before applying it.</p>
 
-<h3 id=recovery>Recovery</h3>
+<h3 id="recovery">Recovery</h3>
 
 <p>The recovery RAM disk is now contained in the <code>boot.img</code> file.
 When going into recovery, the bootloader <strong>cannot</strong> put the
diff --git a/en/devices/tech/ota/ab_updates.html b/en/devices/tech/ota/ab/index.html
index 53a42846..c1b70856 100644
--- a/en/devices/tech/ota/ab_updates.html
+++ b/en/devices/tech/ota/ab/index.html
@@ -6,7 +6,7 @@
   </head>
   <body>
   <!--
-      Copyright 2017 The Android Open Source Project
+      Copyright 2018 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.
@@ -156,7 +156,7 @@
         </li>
         <li>
           Build process and OTA update package generation (described in
-          <a href="/devices/tech/ota/ab_implement.html">Implementing A/B
+          <a href="/devices/tech/ota/ab/ab_implement.html">Implementing A/B
           Updates</a>)
         </li>
       </ul>
@@ -612,381 +612,5 @@
           version.
         </p>
 
-    <h2 id="faq">Frequently asked questions</h2>
-
-      <h3>Has Google used A/B OTAs on any devices?</h3>
-
-        <p>
-          Yes. The marketing name for A/B updates is <em>seamless updates</em>.
-          Pixel and Pixel XL phones from October 2016 shipped with A/B, and
-          all Chromebooks use the same <code>update_engine</code>
-          implementation of A/B. The necessary platform code implementation is
-          public in Android 7.1 and higher.
-        </p>
-
-      <h3>Why are A/B OTAs better?</h3>
-
-      <p>A/B OTAs provide a better user experience when taking updates. Measurements
-      from monthly security updates show this feature has already proven a success: As
-      of May 2017, 95% of Pixel owners are running the latest security update after a
-      month compared to 87% of Nexus users, and Pixel users update sooner than Nexus
-      users. Failures to update blocks during an OTA no longer result in a device that
-      won't boot; until the new system image has successfully booted, Android retains
-      the ability to fall back to the previous working system image.</p>
-
-      <h3>How did A/B affect the 2016 Pixel partition sizes?</h3>
-
-      <p>The following table contains details on the shipping A/B configuration versus
-      the internally-tested non-A/B configuration:</p>
-
-      <table>
-        <tbody>
-          <tr>
-            <th>Pixel partition sizes</th>
-            <th width="33%">A/B</th>
-            <th width="33%">Non-A/B</th>
-          </tr>
-          <tr>
-            <td>Bootloader</td>
-            <td>50*2</td>
-            <td>50</td>
-          </tr>
-          <tr>
-            <td>Boot</td>
-            <td>32*2</td>
-            <td>32</td>
-          </tr>
-          <tr>
-            <td>Recovery</td>
-            <td>0</td>
-            <td>32</td>
-          </tr>
-          <tr>
-            <td>Cache</td>
-            <td>0</td>
-            <td>100</td>
-          </tr>
-          <tr>
-            <td>Radio</td>
-            <td>70*2</td>
-            <td>70</td>
-          </tr>
-          <tr>
-            <td>Vendor</td>
-            <td>300*2</td>
-            <td>300</td>
-          </tr>
-          <tr>
-            <td>System</td>
-            <td>2048*2</td>
-            <td>4096</td>
-          </tr>
-          <tr>
-            <td><strong>Total</strong></td>
-            <td><strong>5000</strong></td>
-            <td><strong>4680</strong></td>
-          </tr>
-        </tbody>
-      </table>
-
-      <p>A/B updates require an increase of only 320 MiB in flash, with a savings of
-      32MiB from removing the recovery partition and another 100MiB preserved by
-      removing the cache partition. This balances the cost of the B partitions for
-      the bootloader, the boot partition, and the radio partition. The vendor
-      partition doubled in size (the vast majority of the size increase). Pixel's
-      A/B system image is half the size of the original non-A/B system image.
-      </p>
-
-      <p>For the Pixel A/B and non-A/B variants tested internally (only A/B shipped),
-      the space used differed by only 320MiB. On a 32GiB device, this is just under
-      1%. For a 16GiB device this would be less than 2%, and for an 8GiB device almost
-      4% (assuming all three devices had the same system image).</p>
-
-      <h3>Why didn't you use SquashFS?</h3>
-
-      <p>We experimented with SquashFS but weren't able to achieve the performance
-      desired for a high-end device. We don't use or recommend SquashFS for handheld
-      devices.</p>
-
-      <p>More specifically, SquashFS provided about 50% size savings on the system
-      partition, but the overwhelming majority of the files that compressed well were
-      the precompiled .odex files. Those files had very high compression ratios
-      (approaching 80%), but the compression ratio for the rest of the system
-      partition was much lower. In addition, SquashFS in Android 7.0 raised the
-      following performance concerns:</p>
-
-      <ul>
-        <li>Pixel has very fast flash compared to earlier devices but not a huge
-          number of spare CPU cycles, so reading fewer bytes from flash but needing
-          more CPU for I/O was a potential bottleneck.</li>
-        <li>I/O changes that perform well on an artificial benchmark run on an
-          unloaded system sometimes don't work well on real-world use cases under
-          real-world load (such as crypto on Nexus 6).</li>
-        <li>Benchmarking showed 85% regressions in some places.</li>
-        </ul>
-
-      <p>As SquashFS matures and adds features to reduce CPU impact (such as a
-      whitelist of commonly-accessed files that shouldn't be compressed), we will
-      continue to evaluate it and offer recommendations to device manufacturers.</p>
-
-      <h3>How did you halve the size of the system partition without SquashFS?</h3>
-
-      <p>Applications are stored in .apk files, which are actually ZIP archives. Each
-      .apk file has inside it one or more .dex files containing portable Dalvik
-      bytecode. An .odex file (optimized .dex) lives separately from the .apk file
-      and can contain machine code specific to the device. If an .odex file is
-      available, Android can run applications at ahead-of-time compiled speeds
-      without having to wait for the code to be compiled each time the application is
-      launched. An .odex file isn't strictly necessary: Android can actually run the
-      .dex code directly via interpretation or Just-In-Time (JIT) compilation, but an
-      .odex file provides the best combination of launch speed and run-time speed if
-      space is available.</p>
-
-      <p>Example: For the installed-files.txt from a Nexus 6P running Android 7.1 with
-      a total system image size of 2628MiB (2755792836 bytes), the breakdown of the
-      largest contributors to overall system image size by file type is as follows:
-      </p>
-
-      <table>
-      <tbody>
-      <tr>
-      <td>.odex</td>
-      <td>1391770312 bytes</td>
-      <td>50.5%</td>
-      </tr>
-      <tr>
-      <td>.apk</td>
-      <td>846878259 bytes</td>
-      <td>30.7%</td>
-      </tr>
-      <tr>
-      <td>.so (native C/C++ code)</td>
-      <td>202162479 bytes</td>
-      <td>7.3%</td>
-      </tr>
-      <tr>
-      <td>.oat files/.art images</td>
-      <td>163892188 bytes</td>
-      <td>5.9%</td>
-      </tr>
-      <tr>
-      <td>Fonts</td>
-      <td>38952361 bytes</td>
-      <td>1.4%</td>
-      </tr>
-      <tr>
-      <td>icu locale data</td>
-      <td>27468687 bytes</td>
-      <td>0.9%</td>
-      </tr>
-      </tbody>
-      </table>
-
-      <p>These figures are similar for other devices too, so on Nexus/Pixel
-      devices, .odex files take up approximately half the system partition. This meant
-      we could continue to use ext4 but write the .odex files to the B partition
-      at the factory and then copy them to <code>/data</code> on first boot. The
-      actual storage used with ext4 A/B is identical to SquashFS A/B, because if we
-      had used SquashFS we would have shipped the preopted .odex files on system_a
-      instead of system_b.</p>
-
-      <h3>Doesn't copying .odex files to /data mean the space saved on /system is
-      lost on /data?</h3>
-
-      <p>Not exactly. On Pixel, most of the space taken by .odex files is for apps,
-      which typically exist on <code>/data</code>. These apps take Google Play
-      updates, so the .apk and .odex files on the system image are unused for most of
-      the life of the device. Such files can be excluded entirely and replaced by
-      small, profile-driven .odex files when the user actually uses each app (thus
-      requiring no space for apps the user doesn't use). For details, refer to the
-      Google I/O 2016 talk <a href="https://www.youtube.com/watch?v=fwMM6g7wpQ8">The
-      Evolution of Art</a>.</p>
-
-      <p>The comparison is difficult for a few key reasons:</p>
-      <ul>
-      <li>Apps updated by Google Play have always had their .odex files on
-      <code>/data</code> as soon as they receive their first update.</li>
-      <li>Apps the user doesn't run don't need an .odex file at all.</li>
-      <li>Profile-driven compilation generates smaller .odex files than ahead-of-time
-      compilation (because the former optimizes only performance-critical code).</li>
-      </ul>
-
-      <p>For details on the tuning options available to OEMs, see
-      <a href="/devices/tech/dalvik/configure.html">Configuring ART</a>.</p>
-
-      <h3>Aren't there two copies of the .odex files on /data?</h3>
-
-      <p>It's a little more complicated ... After the new system image has been
-      written, the new version of dex2oat is run against the new .dex files to
-      generate the new .odex files. This occurs while the old system is still running,
-      so the old and new .odex files are both on <code>/data</code> at the same time.
-      </p>
-
-      <p>The code in OtaDexoptService
-      (<code><a href="https://android.googlesource.com/platform/frameworks/base/+/nougat-mr1-release/services/core/java/com/android/server/pm/OtaDexoptService.java#200" class="external">frameworks/base/+/nougat-mr1-release/services/core/java/com/android/server/pm/OtaDexoptService.java#200</a></code>)
-      calls <code>getAvailableSpace</code> before optimizing each package to avoid
-      over-filling <code>/data</code>. Note that <em>available</em> here is still
-      conservative: it's the amount of space left <em>before</em> hitting the usual
-      system low space threshold (measured as both a percentage and a byte count). So
-      if <code>/data</code> is full, there won't be two copies of every .odex file.
-      The same code also has a BULK_DELETE_THRESHOLD: If the device gets that close
-      to filling the available space (as just described), the .odex files belonging to
-      apps that aren't used are removed. That's another case without two copies of
-      every .odex file.</p>
-
-      <p>In the worst case where <code>/data</code> is completely full, the update
-      waits until the device has rebooted into the new system and no longer needs the
-      old system's .odex files. The PackageManager handles this:
-      (<code><a href="https://android.googlesource.com/platform/frameworks/base/+/nougat-mr1-release/services/core/java/com/android/server/pm/PackageManagerService.java#7215" class="external">frameworks/base/+/nougat-mr1-release/services/core/java/com/android/server/pm/PackageManagerService.java#7215</a></code>). After the new system has
-      successfully booted, <code>installd</code>
-      (<code><a href="https://android.googlesource.com/platform/frameworks/native/+/nougat-mr1-release/cmds/installd/commands.cpp#2192" class="external">frameworks/native/+/nougat-mr1-release/cmds/installd/commands.cpp#2192</a></code>)
-      can remove the .odex files that were used by the old system, returning the
-      device back to the steady state where there's only one copy.</p>
-
-      <p>So, while it is possible that <code>/data</code> contains two copies of all
-      the .odex files, (a) this is temporary and (b) only occurs if you had plenty of
-      free space on <code>/data</code> anyway. Except during an update, there's only
-      one copy. And as part of ART's general robustness features, it will never fill
-      <code>/data</code> with .odex files anyway (because that would be a problem on a
-      non-A/B system too).</p>
-
-      <h3>Doesn't all this writing/copying increase flash wear?</h3>
-
-      <p>Only a small portion of flash is rewritten: a full Pixel system update
-      writes about 2.3GiB. (Apps are also recompiled, but that's true of non-A/B
-      too.) Traditionally, block-based full OTAs wrote a similar amount of data, so
-      flash wear rates should be similar.</p>
-
-      <h3>Does flashing two system partitions increase factory flashing time?</h3>
-
-      <p>No. Pixel didn't increase in system image size (it merely divided the space
-      across two partitions).</p>
-
-      <h3>Doesn't keeping .odex files on B make rebooting after factory data reset
-      slow?</h3>
-
-      <p>Yes. If you've actually used a device, taken an OTA, and performed a factory
-      data reset, the first reboot will be slower than it would otherwise be (1m40s vs
-      40s on a Pixel XL) because the .odex files will have been lost from B after the
-      first OTA and so can't be copied to <code>/data</code>. That's the trade-off.</p>
-
-      <p>Factory data reset should be a rare operation when compared to regular boot
-      so the time taken is less important. (This doesn't affect users or reviewers who
-      get their device from the factory, because in that case the B partition is
-      available.) Use of the JIT compiler means we don't need to recompile
-      <em>everything</em>, so it's not as bad as you might think. It's also possible
-      to mark apps as requiring ahead-of-time compilation using
-      <code>coreApp="true"</code> in the manifest:
-      (<code><a href="https://android.googlesource.com/platform/frameworks/base/+/nougat-mr1-release/packages/SystemUI/AndroidManifest.xml#23" class="external">frameworks/base/+/nougat-mr1-release/packages/SystemUI/AndroidManifest.xml#23</a></code>).
-      This is currently used by <code>system_server</code> because it's not allowed to
-      JIT for security reasons.</p>
-
-      <h3>Doesn't keeping .odex files on /data rather than /system make rebooting
-      after an OTA slow?</h3>
-
-      <p>No. As explained above, the new dex2oat is run while the old system image is
-      still running to generate the files that will be needed by the new system. The
-      update isn't considered available until that work has been done.</p>
-
-      <h3>Can (should) we ship a 32GiB A/B device? 16GiB? 8GiB?</h3>
-
-      <p>32GiB works well as it was proven on Pixel, and 320MiB out of 16GiB means a
-      reduction of 2%. Similarly, 320MiB out of 8GiB a reduction of 4%. Obviously
-      A/B would not be the recommended choice on devices with 4GiB, as the 320MiB
-      overhead is almost 10% of the total available space.</p>
-
-      <h3>Does AVB2.0 require A/B OTAs?</h3>
-
-      <p>No. Android <a href="/security/verifiedboot/">Verified Boot</a> has always
-      required block-based updates, but not necessarily A/B updates.</p>
-
-      <h3>Do A/B OTAs require AVB2.0?</h3>
-
-      <p>No.</p>
-
-      <h3>Do A/B OTAs break AVB2.0's rollback protection?</h3>
-
-      <p>No. There's some confusion here because if an A/B system fails to boot into
-      the new system image it will (after some number of retries determined by your
-      bootloader) automatically revert to the "previous" system image. The key point
-      here though is that "previous" in the A/B sense is actually still the "current"
-      system image. As soon as the device successfully boots a new image, rollback
-      protection kicks in and ensures that you can't go back. But until you've
-      actually successfully booted the new image, rollback protection doesn't
-      consider it to be the current system image.</p>
-
-      <h3>If you're installing an update while the system is running, isn't that
-      slow?</h3>
-
-      <p>With non-A/B updates, the aim is to install the update as quickly as
-      possible because the user is waiting and unable to use their device while the
-      update is applied. With A/B updates, the opposite is true; because the user is
-      still using their device, as little impact as possible is the goal, so the
-      update is deliberately slow. Via logic in the Java system update client (which
-      for Google is GmsCore, the core package provided by GMS), Android also attempts
-      to choose a time when the users aren't using their devices at all. The platform
-      supports pausing/resuming the update, and the client can use that to pause the
-      update if the user starts to use the device and resume it when the device is
-      idle again.</p>
-
-      <p>There are two phases while taking an OTA, shown clearly in the UI as
-      <em>Step 1 of 2</em> and <em>Step 2 of 2</em> under the progress bar. Step 1
-      corresponds with writing the data blocks, while step 2 is pre-compiling the
-      .dex files. These two phases are quite different in terms of performance
-      impact. The first phase is simple I/O. This requires little in the way of
-      resources (RAM, CPU, I/O) because it's just slowly copying blocks around.</p>
-
-      <p>The second phase runs dex2oat to precompile the new system image. This
-      obviously has less clear bounds on its requirements because it compiles actual
-      apps. And there's obviously much more work involved in compiling a large and
-      complex app than a small and simple app; whereas in phase 1 there are no disk
-      blocks that are larger or more complex than others.</p>
-
-      <p>The process is similar to when Google Play installs an app update in the
-      background before showing the <em>5 apps updated</em> notification, as has been
-      done for years.</p>
-
-      <h3>What if a user is actually waiting for the update?</h3>
-
-      <p>The current implementation in GmsCore doesn't distinguish between background
-      updates and user-initiated updates but may do so in the future. In the case
-      where the user explicitly asked for the update to be installed or is watching
-      the update progress screen, we'll prioritize the update work on the assumption
-      that they're actively waiting for it to finish.</p>
-
-      <h3>What happens if there's a failure to apply an update?</h3>
-
-      <p>With non-A/B updates, if an update failed to apply, the user was usually
-      left with an unusable device. The only exception was if the failure occurred
-      before an application had even started (because the package failed to verify,
-      say). With A/B updates, a failure to apply an update does not affect the
-      currently running system. The update can simply be retried later.</p>
-
-      <h3>Which systems on a chip (SoCs) support A/B?</h3>
-
-      <p>As of 2017-03-15, we have the following information:</p>
-      <table class="style0">
-      <tbody>
-      <tr>
-      <td></td>
-      <td><strong>Android 7.x Release</strong></td>
-      <td><strong>Android 8.x Release</strong></td>
-      </tr>
-      <tr>
-      <td><strong>Qualcomm</strong></td>
-      <td>Depending on OEM requests </td>
-      <td>All chipsets will get support</td>
-      </tr>
-      <tr>
-      <td><strong>Mediatek</strong></td>
-      <td>Depending on OEM requests</td>
-      <td>All chipsets will get support</td>
-      </tr>
-      </tbody>
-      </table>
-
-      <p>For details on schedules, check with your SoC contacts. For SoCs not listed
-      above, reach out to your SoC directly.</p>
-
   </body>
 </html>
diff --git a/en/devices/tech/ota/index.html b/en/devices/tech/ota/index.html
index 58737b5c..7b7db75f 100644
--- a/en/devices/tech/ota/index.html
+++ b/en/devices/tech/ota/index.html
@@ -45,8 +45,8 @@
         network. This is called <em>streaming A/B</em>. A/B updates are also
         know as <em>seamless updates</em>. For more information about OTA
         updates for A/B devices, see
-        <a href="/devices/tech/ota/ab_updates.html">A/B (Seamless) System
-          Update
+        <a href="/devices/tech/ota/ab/index.html">A/B (Seamless) System
+          Updates
         </a>.
       </p>
 
@@ -56,9 +56,9 @@
         Older devices have a special recovery partition containing the software
         needed to unpack a downloaded update package and apply the update to
         the other partitions. For more information, see
-        <a href="/devices/tech/ota/nonab_updates.html">Non-A/B System Updates
+        <a href="/devices/tech/ota/nonab/index.html">Non-A/B System Updates
         </a>.
       </p>
-    
+
   </body>
 </html>
diff --git a/en/devices/tech/ota/block.html b/en/devices/tech/ota/nonab/block.html
index 0306f5eb..d308aeb5 100644
--- a/en/devices/tech/ota/block.html
+++ b/en/devices/tech/ota/nonab/block.html
@@ -105,7 +105,7 @@ following differences:</p>
 size as full file OTA updates, and incremental updates can be just a few
 megabytes larger.</p>
 
-<img src="../images/ota_size_comparison.png" alt="comparison of OTA sizes">
+<img src="/devices/tech/images/ota_size_comparison.png" alt="comparison of OTA sizes">
 
 <p class="img-caption"><strong>Figure 1.</strong> Compare Nexus 6 OTA sizes
 between Android 5.0 and Android 5.1 releases (varying target build changes)</p>
diff --git a/en/devices/tech/ota/device_code.html b/en/devices/tech/ota/nonab/device_code.html
index 3b3d9d6c..3b3d9d6c 100644
--- a/en/devices/tech/ota/device_code.html
+++ b/en/devices/tech/ota/nonab/device_code.html
diff --git a/en/devices/tech/ota/nonab_updates.html b/en/devices/tech/ota/nonab/index.html
index 4fb8daf0..4fb8daf0 100644
--- a/en/devices/tech/ota/nonab_updates.html
+++ b/en/devices/tech/ota/nonab/index.html
diff --git a/en/devices/tech/ota/inside_packages.html b/en/devices/tech/ota/nonab/inside_packages.html
index 2cb23c00..7fef4438 100644
--- a/en/devices/tech/ota/inside_packages.html
+++ b/en/devices/tech/ota/nonab/inside_packages.html
@@ -89,7 +89,7 @@ arguments.) Unless otherwise noted, functions return <b>true</b> on success
 and <b>false</b> on error. If you want errors to abort execution of the
 script, use the <code>abort()</code> and/or <code>assert()</code> functions.
 The set of functions available in updater can also be extended to provide
-<a href="/devices/tech/ota/device_code.html">device-specific
+<a href="/devices/tech/ota/nonab/device_code.html">device-specific
 functionality</a>.
 
 <dl>
diff --git a/en/devices/tech/ota/sign_builds.html b/en/devices/tech/ota/sign_builds.html
index 06106755..22a9a358 100644
--- a/en/devices/tech/ota/sign_builds.html
+++ b/en/devices/tech/ota/sign_builds.html
@@ -57,7 +57,7 @@ the root of your Android tree:</p>
 <code class="devsite-terminal">mkdir ~/.android-certs</code>
 <code class="devsite-terminal">for x in releasekey platform shared media; do \
     ./development/tools/make_key ~/.android-certs/$x "$subject"; \
-done</code>
+  done</code>
 </pre>
 
 <p><code>$subject</code> should be changed to reflect your organization's
diff --git a/en/devices/tech/ota/tools.html b/en/devices/tech/ota/tools.html
index 4ad58d90..cf741c64 100644
--- a/en/devices/tech/ota/tools.html
+++ b/en/devices/tech/ota/tools.html
@@ -81,7 +81,7 @@ the new build.</p>
 update package is much smaller than the corresponding full update (about 1 MB
 instead of 60 MB).</p>
 <p class="note"><strong>Note:</strong> To generate a
-<a href="/devices/tech/ota/block.html">block-based OTA</a>
+<a href="/devices/tech/ota/nonab/block.html">block-based OTA</a>
 for subsequent updates, pass the <code>--block</code> option to
 <code>ota_from_target_files</code>.</p>
 <p>Distribute an incremental package only to devices running exactly the same
@@ -112,6 +112,6 @@ binary. The OTA package construction tools use the updater program (source in
 language that can do many installation tasks. You can substitute any other
 binary running on the device.</p>
 <p>For details on the updater binary, edify syntax, and builtin functions, see
-<a href="/devices/tech/ota/inside_packages.html">Inside OTA Packages</a>.
+<a href="/devices/tech/ota/nonab/inside_packages.html">Inside OTA Packages</a>.
   </body>
 </html>