Docs: Adding general OTA content, new images
Updating with comments from google doc (tbao and xi zhao)
Adding reference to options for ota_from_target_files
Adding feedback changes
Adding 2nd set of feedback changes
Adding 3rd set of feedback changes
Adding 4th set of feedback changes
Breaking content into multiple files, adding block ota, adjusting toc
Renamed .jd files, update TOC and document links
Adding in dougz's feedback on recovery images, split out 5x vs 4x and earlier
Minor text tweaks
Fixing merge conflict
Adding in dougz's comment
Setting 80 column width in all files
Adding feedback, moving up one level
Adding ota mailing list, cropped localized text image, teaser blub on tech/index, mailing list to community page (includes several edits to meet 80 character column limit)
Update mailing list verbiage, added feedback to builtin functions from tbao (in google doc)
Bug: 17884100
Change-Id: If162f17180853ef7e0b252f22eb360fb99b58f15
diff --git a/src/devices/tech/ota/index.jd b/src/devices/tech/ota/index.jd
new file mode 100755
index 0000000..a65418c
--- /dev/null
+++ b/src/devices/tech/ota/index.jd
@@ -0,0 +1,160 @@
+page.title=OTA Updates
+@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 devices in the field can receive and install over-the-air (OTA)
+updates to the system and application software. Devices have a special
+recovery partition with the software needed to unpack a downloaded update
+package and apply it to the rest of the system.</p>
+<p>This section describes the structure of these packages and the tools
+provided to build them. It is intended for developers who want to
+make the OTA update system work on new Android devices and those who are
+building update packages for use with released devices. OTA updates are
+designed to upgrade the underlying operating system and the read-only apps
+installed on the system partition; these updates do <i>not</i> affect
+applications installed by the user from Google Play.
+</p>
+<p>This section describes the OTA system as of the Android 5.x release. For
+help porting OTA-related code from older releases, see <a href="#migrating">
+Migrating from previous releases</a>.
+</p>
+
+<h2 id="android-device-layout">Android device layout</h2>
+<p>The flash space on an Android device typically contains the following
+partitions.</p>
+
+<dl>
+<dt>boot</dt>
+<dd>Contains the Linux kernel and a minimal root filesystem (loaded into a RAM
+disk). It mounts system and other partitions and starts the runtime located on
+the system partition.</dd>
+<dt>system</dt>
+<dd>Contains system applications and libraries that have source code available
+on Android Open Source Project (AOSP). During normal operation, this partition
+is mounted read-only; its contents change only during an OTA update.</dd>
+<dt>vendor</dt>
+<dd>Contains system applications and libraries that do <em>not</em> have
+source code available on Android Open Source Project (AOSP). During normal
+operation, this partition is mounted read-only; its contents change only
+during an OTA update.</dd>
+<dt>userdata</dt>
+<dd>Stores the data saved by applications installed by the user, etc. This
+partition is not normally touched by the OTA update process.</dd>
+<dt>cache</dt>
+<dd>Temporary holding area used by a few applications (accessing this
+partition requires special app permissions) and for storage of downloaded OTA
+update packages. Other programs use this space with the expectation that files
+can disappear at any time. Some OTA package installations may result in this
+partition being wiped completely.</dd>
+<dt>recovery</dt>
+<dd>Contains a second complete Linux system, including a kernel and the
+special recovery binary that reads a package and uses its contents to update
+the other partitions.</dd>
+<dt>misc</dt>
+<dd>Tiny partition used by recovery to stash some information away about what
+it's doing in case the device is restarted while the OTA package is being
+applied.</dd></dl>
+
+<h2 id="life-ota-update">Life of an OTA update</h2>
+<p>A typical OTA update contains the following steps:</p>
+<ol>
+<li>Device performs regular check in with OTA servers and is notified of the
+availability of an update, including the URL of the update package and a
+description string to show the user.</li>
+<li>Update downloads to a cache or data partition, and its cryptographic
+signature is verified against the certificates in
+<code>/system/etc/security/otacerts.zip</code>. User is prompted to install the
+update.</li>
+<li>Device reboots into recovery mode, in which the kernel and system in the
+recovery partition are booted instead of the kernel in the boot partition.</li>
+<li>Recovery binary is started by init. It finds command-line arguments in
+<code>/cache/recovery/command</code> that point it to the downloaded package.
+</li>
+<li>Recovery verifies the cryptographic signature of the package against the
+public keys in <code>/res/keys</code> (part of the RAM disk contained in the
+recovery partition).</li>
+<li>Data is pulled from the package and used to update the boot, system,
+and/or vendor partitions as necessary. One of the new files left on the system
+partition contains the contents of the new recovery partition.</li>
+<li>Device reboots normally. <ol style="list-style-type:lower-alpha">
+<li>The newly updated boot partition is loaded, and it mounts and starts
+executing binaries in the newly updated system partition.</li>
+<li>As part of normal startup, the system checks the contents of the recovery
+partition against the desired contents (which were previously stored as a file
+in <code>/system</code>). They are different, so the recovery partition is
+reflashed with the desired contents. (On subsequent boots, the recovery
+partition already contains the new contents, so no reflash is necessary.)</li>
+</ol></li>
+</ol>
+<p>The system update is complete!</p>
+
+<h2 id="migrating">Migrating from Previous Releases</h2>
+
+<p>When migrating from Android 2.3/3.0/4.0 release, the major change is the
+conversion of all the device-specific functionality from a set of C functions
+with predefined names to C++ objects. The following table lists the old
+functions and the new methods that serve a roughly equivalent purpose:</p>
+
+<table>
+<tbody>
+<tr>
+<th>C function</th>
+<th>C++ method</th>
+</tr>
+<tr>
+<td>device_recovery_start()</td>
+<td>Device::RecoveryStart()</td>
+</tr>
+<tr>
+<td>device_toggle_display()<br>
+device_reboot_now()<br>
+</td>
+<td>RecoveryUI::CheckKey()<br>
+(also RecoveryUI::IsKeyPressed())<br>
+</td>
+</tr>
+<tr>
+<td>device_handle_key()</td>
+<td>Device::HandleMenuKey()</td>
+</tr>
+<tr>
+<td>device_perform_action()</td>
+<td>Device::InvokeMenuItem()</td>
+</tr>
+<tr>
+<td>device_wipe_data()</td>
+<td>Device::WipeData()</td>
+</tr>
+<tr>
+<td>device_ui_init()</td>
+<td>ScreenRecoveryUI::Init()</td>
+</tr>
+</tbody>
+</table>
+
+<p>Conversion of old functions to new methods should be reasonably
+straightforward. Don't forget to add the new <code>make_device()</code>
+function to create and return an instance of your new Device subclass.</p>
\ No newline at end of file