B2G/Updating

This page intends to help engineers set up an environment for updating B2G devices. It focuses on low-level details of the updating tools and omits many higher-level topics. The higher-level issues are covered in XXX other doc.

Updating is the process of (i) on a build host, building incremental update packages from old version(s) to a new version; (ii) on the client, finding the right update to download; (iii) downloading the update; (iv) applying the update to existing files on the device. Each of these items are covered below.

Types of updates

B2G phones can update the entire system through FOTA updates. The technology behind FOTA updates is shared with the Android project. The areas that can be implemented through FOTA updates include the system partition, kernel, modem baseband, recovery image used for updating, or any other file on the device.

B2G can also update just the Gecko and Gaia files on device, through a mechanism we call Gecko/Gaia OTA updates. All of the Gecko and Gaia files are in the /system/b2g directory on the device. They compromise the core Gecko runtime and the device's user interface.

FOTA updates

• B2G is FOTA-client-neutral, but we recommend GOTA, and that's what's discussed here
• update.zip and update-script
• mar wrapping and signing
• librecovery, recovery image

Gecko/Gaia OTA updates

• update.mar and update.xml
• mar signing
• same technology used by Firefox for Desktop
• update binary

Building updates for multiple software versions

• Initially, use the gecko-update-full target to generate a complete update MAR for the last successful b2g build. This will place the MAR in $GECKO_OBJDIR/dist/b2g-update/b2g-gecko-update.mar:

$ ./build.sh gecko-update-full
$ cp $GECKO_OBJDIR/dist/b2g-update/b2g-gecko-update.mar <dest>

• For a complete FOTA update.zip, use the standard AOSP build hooks:
  • Make sure the kernel binary is in the appropriate place under vendor to enable boot image, recovery image, and update.zip generation
  • Copy the update.zip that lives under out/target/product/$DEVICE/*.zip

• To generate an incremental MAR update, you simply need two complete update MARs to generate it from. Pass their paths to the gecko MAR generation tool:

$ ./tools/update-tools/build-gecko-mar.py --from $FROM_MAR --to $TO_MAR $DEST_MAR

• TODO: generate FOTA incremental zip
• TODO: signing packages
• this doc covers "linear updates"; can generate more if desired

Hosting updates (respectively, polling for updates on the client side)

• interaction of server tools with build tools
  • The build server uploads two files to the update server: the update.mar file and the application.ini. For GOTA updates, the build server then kicks off a local script on the update server that generates update.xml based on these files. For FOTA updates, update.xml generation is manual.
• layout of packages and manifests hosted on the server
  • For GOTA updates, all .mar and application.ini files reside in a single directory that corresponds to the update channel (e.g., /data/update-channels/beta for the beta update channel); update.xml points to the newest copies of these files.
  • For FOTA updates, only a single .mar, .ini, and update.xml file exist in a folder which corresponds to 'linear update' url (see below), e.g., /data/update-channels/beta/$PRODUCT/$VERSION/$BUILDID.
• (for "linear updates") how a client finds one and only one update
  • When linear updates are enabled, the update url on the phone is set to http://host/%CHANNEL%/%PRODUCT_MODEL%/%VERSION%/%BUILD_ID%/update.xml. Thus, each build has a unique update url, and only one update is ever posted to that location. Thus, a phone cannot skip updates, and must apply, in sequence, every update that has been posted.
  • In our testing, we have used a combination of linear updates and normal udpates; we use normal updates (which allow users to download only the most recent update) for GOTA updates, but switch to linear updates for FOTA updates, so that users cannot skip FOTA updates. Performing this switch requires that the last GOTA update before a FOTA update contain an update url change, from e.g., http://host/beta/update.xml to http://host/%CHANNEL%/%PRODUCT_MODEL%/%VERSION%/%BUILD_ID%/update.xml.

Downloading and applying updates

• poll for update manifest (update.xml)
• download signed mar
• verify, stage for being applied
• invoke updater