'''WARNING: This page is still very much work in progress.'''

= Upgrader =
== Introduction ==
The upgrader sits in its own partition and applies any update that the client passed it. Those are applied after being validated, any failure stops the upgrade process and attempts a reboot in standard mode.

== Implementation ==
The upgrader will be run from the recovery partition.  The full set of requirements for the recovery partition will be specified [[Touch/Specs/RecoveryPartition|here]].  Here is the [[https://code-review.phablet.ubuntu.com/gitweb?p=CyanogenMod%2Fandroid_bootable_recovery.git;a=shortlog;h=refs%2Fheads%2Fphablet-4.4.2_r1|source code]] for the recovery partition upgrader (it is not on Launchpad).

When rebooted into the recovery/upgrader partition, the phone will trigger the upgrader. The upgrader will check for any pending update, if found, it'll validate the signature and unpack them sequentially, then apply them to the device, when applied, the file is removed. On failure, the device is rebooted into normal mode with any failed/unapplied update kept on the file system.

When started without a list of update, a recovery menu will be shown to the user, allowing them to perform a factory reset or update from eMMC (from similar gpg signed update files).

== Interface ==
A standard update will be triggered by the client by writting files into /android/cache/recovery/ and at the end, writing a list of basic commands into /android/cache/recovery/ubuntu_command.

The files that need to be copied are:
 * Any relevant keyring (.tar.xz + .tar.xz.asc), typically image-master, image-signing and device-signing (if present)
 * Any file that's part of the update (.tar.xz + .tar.xz.asc)

The proposed command file syntax is one command per line with "<command> <argument>" as the syntax.

An example ubuntu_command file for a full system update is as follow:
{{{
load_keyring image-master.tar.xz image-master.tar.xz.asc
load_keyring image-signing.tar.xz image-signing.tar.xz.asc
load_keyring device-signing.tar.xz device-signing.tar.xz.asc
format system
mount system
update ubuntu-20130600.full.tar.xz ubuntu-20130600.full.tar.xz.asc
update nexus4-20130600.full.tar.xz nexus4-20130600.full.tar.xz.asc
update version-20130600.tar.xz version-20130600.tar.xz.asc
unmount system
}}}

An example ubuntu_command file for a delta update is as follow:
{{{
load_keyring image-master.tar.xz image-master.tar.xz.asc
load_keyring image-signing.tar.xz image-signing.tar.xz.asc
load_keyring device-signing.tar.xz device-signing.tar.xz.asc
mount system
update ubuntu-20130601.delta-20130600.tar.xz ubuntu-20130601.delta-20130600.tar.xz.asc
update nexus4-20130601.delta-20130600.tar.xz nexus4-20130601.delta-20130600.tar.xz.asc
update version-20130601.tar.xz version-20130601.tar.xz.asc
unmount system
}}}

An example of a factory reset is as follow:
{{{
format data
}}}


The command file is processed sequentially, any failure will make it exit with a non-zero return code.