1 page.title=OTA Updates 2 @jd:body 3 4 <!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 20 <div id="qv-wrapper"> 21 <div id="qv"> 22 <h2>In this document</h2> 23 <ol id="auto-toc"> 24 </ol> 25 </div> 26 </div> 27 28 <p>Android devices in the field can receive and install over-the-air (OTA) 29 updates to the system and application software. Devices have a special 30 recovery partition with the software needed to unpack a downloaded update 31 package and apply it to the rest of the system.</p> 32 <p>This section describes the structure of these packages and the tools 33 provided to build them. It is intended for developers who want to 34 make the OTA update system work on new Android devices and those who are 35 building update packages for use with released devices. OTA updates are 36 designed to upgrade the underlying operating system and the read-only apps 37 installed on the system partition; these updates do <i>not</i> affect 38 applications installed by the user from Google Play. 39 </p> 40 <p>This section describes the OTA system as of the Android 5.x release. For 41 help porting OTA-related code from older releases, see <a href="#migrating"> 42 Migrating from previous releases</a>. 43 </p> 44 45 <h2 id="android-device-layout">Android device layout</h2> 46 <p>The flash space on an Android device typically contains the following 47 partitions.</p> 48 49 <dl> 50 <dt>boot</dt> 51 <dd>Contains the Linux kernel and a minimal root filesystem (loaded into a RAM 52 disk). It mounts system and other partitions and starts the runtime located on 53 the system partition.</dd> 54 <dt>system</dt> 55 <dd>Contains system applications and libraries that have source code available 56 on Android Open Source Project (AOSP). During normal operation, this partition 57 is mounted read-only; its contents change only during an OTA update.</dd> 58 <dt>vendor</dt> 59 <dd>Contains system applications and libraries that do <em>not</em> have 60 source code available on Android Open Source Project (AOSP). During normal 61 operation, this partition is mounted read-only; its contents change only 62 during an OTA update.</dd> 63 <dt>userdata</dt> 64 <dd>Stores the data saved by applications installed by the user, etc. This 65 partition is not normally touched by the OTA update process.</dd> 66 <dt>cache</dt> 67 <dd>Temporary holding area used by a few applications (accessing this 68 partition requires special app permissions) and for storage of downloaded OTA 69 update packages. Other programs use this space with the expectation that files 70 can disappear at any time. Some OTA package installations may result in this 71 partition being wiped completely.</dd> 72 <dt>recovery</dt> 73 <dd>Contains a second complete Linux system, including a kernel and the 74 special recovery binary that reads a package and uses its contents to update 75 the other partitions.</dd> 76 <dt>misc</dt> 77 <dd>Tiny partition used by recovery to stash some information away about what 78 it's doing in case the device is restarted while the OTA package is being 79 applied.</dd></dl> 80 81 <h2 id="life-ota-update">Life of an OTA update</h2> 82 <p>A typical OTA update contains the following steps:</p> 83 <ol> 84 <li>Device performs regular check in with OTA servers and is notified of the 85 availability of an update, including the URL of the update package and a 86 description string to show the user.</li> 87 <li>Update downloads to a cache or data partition, and its cryptographic 88 signature is verified against the certificates in 89 <code>/system/etc/security/otacerts.zip</code>. User is prompted to install the 90 update.</li> 91 <li>Device reboots into recovery mode, in which the kernel and system in the 92 recovery partition are booted instead of the kernel in the boot partition.</li> 93 <li>Recovery binary is started by init. It finds command-line arguments in 94 <code>/cache/recovery/command</code> that point it to the downloaded package. 95 </li> 96 <li>Recovery verifies the cryptographic signature of the package against the 97 public keys in <code>/res/keys</code> (part of the RAM disk contained in the 98 recovery partition).</li> 99 <li>Data is pulled from the package and used to update the boot, system, 100 and/or vendor partitions as necessary. One of the new files left on the system 101 partition contains the contents of the new recovery partition.</li> 102 <li>Device reboots normally. <ol style="list-style-type:lower-alpha"> 103 <li>The newly updated boot partition is loaded, and it mounts and starts 104 executing binaries in the newly updated system partition.</li> 105 <li>As part of normal startup, the system checks the contents of the recovery 106 partition against the desired contents (which were previously stored as a file 107 in <code>/system</code>). They are different, so the recovery partition is 108 reflashed with the desired contents. (On subsequent boots, the recovery 109 partition already contains the new contents, so no reflash is necessary.)</li> 110 </ol></li> 111 </ol> 112 <p>The system update is complete!</p> 113 114 <h2 id="migrating">Migrating from Previous Releases</h2> 115 116 <p>When migrating from Android 2.3/3.0/4.0 release, the major change is the 117 conversion of all the device-specific functionality from a set of C functions 118 with predefined names to C++ objects. The following table lists the old 119 functions and the new methods that serve a roughly equivalent purpose:</p> 120 121 <table> 122 <tbody> 123 <tr> 124 <th>C function</th> 125 <th>C++ method</th> 126 </tr> 127 <tr> 128 <td>device_recovery_start()</td> 129 <td>Device::RecoveryStart()</td> 130 </tr> 131 <tr> 132 <td>device_toggle_display()<br> 133 device_reboot_now()<br> 134 </td> 135 <td>RecoveryUI::CheckKey()<br> 136 (also RecoveryUI::IsKeyPressed())<br> 137 </td> 138 </tr> 139 <tr> 140 <td>device_handle_key()</td> 141 <td>Device::HandleMenuKey()</td> 142 </tr> 143 <tr> 144 <td>device_perform_action()</td> 145 <td>Device::InvokeMenuItem()</td> 146 </tr> 147 <tr> 148 <td>device_wipe_data()</td> 149 <td>Device::WipeData()</td> 150 </tr> 151 <tr> 152 <td>device_ui_init()</td> 153 <td>ScreenRecoveryUI::Init()</td> 154 </tr> 155 </tbody> 156 </table> 157 158 <p>Conversion of old functions to new methods should be reasonably 159 straightforward. Don't forget to add the new <code>make_device()</code> 160 function to create and return an instance of your new Device subclass.</p>
