Google Git
Sign in
chromium / chromiumos / platform / firmware / refs/heads/stabilize-octopus-12371.15.B
commit6ef55ba31e8b2fb0c1bce59702284fb0257d45d9[log] [tgz]
authorHung-Te Lin <[email protected]>Fri May 24 08:06:27 2019
committerchrome-bot <[email protected]>Tue Jun 25 00:29:27 2019
tree499db0e528d098e271fe3bb60efb4ee64045703a
parent74a5b3868ecc68562964c8c8b4502f246fddf548 [diff]
Update OWNERS file

Update OWNERS with file syntax.

BUG=None
TEST=None

Change-Id: Ieb285f0a528498fb48bf091ce158a1c8ad52e008
Reviewed-on: https://chromium-review.googlesource.com/1628515
Tested-by: Hung-Te Lin <[email protected]>
Commit-Ready: ChromeOS CL Exonerator Bot <[email protected]>
Legacy-Commit-Queue: Commit Bot <[email protected]>
Reviewed-by: Simon Glass <[email protected]>
1 file changed
tree: 499db0e528d098e271fe3bb60efb4ee64045703a
  1. _docs/
  2. functest/
  3. pack/
  4. sbin/
  5. test/
  6. .gitignore
  7. COMMIT-QUEUE.ini
  8. LICENSE
  9. make_test_files.sh
  10. OWNERS
  11. pack_firmware.py
  12. pack_firmware_functest.py
  13. pack_firmware_unittest.py
  14. pack_firmware_utils.py
  15. PRESUBMIT.cfg
  16. README.md
README.md

ChromeOS Firmware Updater

This repository contains the firmware updater (chromeos-firmwareupdate) that will update firmware images related to verified boot, usually host (also known as AP, BIOS or MAIN) and EC (Embedded Controller).

Introduction

Auto update is one of the most important feature in Chrome OS. Updating firmware is one of the most complicated process, since all Chromebooks come with firmware that implemented verified boot and must be able to update in background silently.

Using Firmware Updater

The firmware updater was made as an self-extracting archive with firmware images, updating logic, even utility programs.

In all modes, updater will try to preserve a list of known firmware data, for example the VPD sections (RO_VPD, RW_VPD), and components in GBB section like HWID.

Update manually

Usually you can find the updater in /usr/sbin/chromeos-firmwareupdate on a Chrome OS device (or the rootfs partition of a disk image).

To look at its contents (firmware images and versions) in machine friendly way:

chromeos-firmwareupdate --manifest

Currently we also support a human readable form:

chromeos-firmwareupdate -V

Usually for people who wants to “update all my firmware to right states”, do:

chromeos-firmwareupdate --mode=recovery

The recovery mode will try to update RO+RW if your write protection is not enabled, otherwise only RW.

If your are not sure about write protection status but you only want RW to be updated, run:

chromeos-firmwareupdate --mode=recovery --wp=1

The --wp argument will override you real write protection status.

If your want everything (RO and RW) to be updated and would like the updater to check WP state for you:

chromeos-firmwareupdate --mode=factory

Simulating ChromeOS Auto Update

The ChromeOS Auto Update (update_engine) runs updater in a different way - a two-step trial process.

If you want to simulate and test that, do:

chromeos-firmwareupdate --mode=autoupdate --wp=1

Building Firmware Updater

The updater is provided by the virtual/chromeos-firmware package in Chromium OS source tree, which will be replaced and includes the chromeos-base/chromeos-firmware-${BOARD} package in private board overlays.

To build an updater locally, in chroot run:

emerge-${BOARD} chromeos-firmware-${BOARD}

If your board overlay has defined USE flags bootimage or cros_ec, chromeos-firwmare-${BOARD} package will add dependency to firmware and EC source packages (chromeos-bootimage and chromeos-ec), and have the firmware images in /build/${BOARD}/firmware/{image,ec}.bin.

In other words, you can remove bootimage and cros_ec in branches that you don't need firmware from source, for example the factory branches or ToT, especially if there are external partners who only has access to particular board private overlays. To do that, find the make.conf in board overlay and add USE="-bootimage -cros_ec".

Manipulating Firmware Updater Packages

The firmware updater packages lives in private board overlays: src/private-overlays/overlay-${BOARD}-private/chromeos-base/chromeos-firmware-${BOARD}/chromeos-firmware-${BOARD}-9999.ebuild. Find a template here in chromiumos-base/chromeos-firmware-null.

Usually there are few fields you have to fill:

CROS_FIRMWARE_MAIN_IMAGE

A reference to the Main (AP) firmware image, which usually comes from emerge-${BOARD} chromeos-booimage then /build/${BOARD}/firmware/image.bin.

Usually this implies both RO and RW. See CROS_FIRMWARE_MAIN_RW_IMAGE below for more information.

You have to run ebuild-${BOARD} chromeos-firmware-${BOARD}.ebuild manifest whenever you've changed the image files (CROS_FIRMWARE_*_IMAGE).

CROS_FIRMWARE_MAIN_RW_IMAGE

A reference to the Main (AP) firmware image and only used for RW sections.

If this value is set, CROS_FIRMWARE_MAIN_IMAGE will be used for RO and this will be used for RW.

CROS_FIRMWARE_EC_IMAGE

A reference to the Embedded Controller (EC) firmware image, which usually comes from emerge-${BOARD} chromeos-ec then /build/${BOARD}/firmware/ec.bin.

Technical Details

CROS_FIRMWARE_SCRIPT and packaging

The firmware updater is built by running pack_firmware.py, which collects firmware image files, and then archived by running shar, with a special bootstrap SFX script pack/sfx.sh.

Since the verified boot has been evolved with so much differences, we put the updating logic in different files according to the generation of firmware: pack/dist/updater*.sh. Most Chromebooks today should use updater5.sh.

Usually we will increase a “logic version” when the verified boot has been changed so much that the updater code for previous versions would almost won't work. Currently we have defined these versions (Use Developer Info page to find the mapping from board names to product names):

  • Version 1: (EOL) mario (CR48), using H2C BIOS.
  • Version 2: (EOL) alex and zgb.
  • Version 3: lumpy, stumpy, butterfly, stout, parrot.
  • Version 4: Everything after version 3 until now.
  • Version 5: Was created for vboot2, but now it's merged back to Version 4.

Starting from M70, we will migrate all projects to a newly native code based updater as “updater v5”. After that there won't be any versions. See go/updater5 for more details.

This will be mapped to what you should set in the CROS_FIRMWARE_SCRIPT value in ebuild files.

For details about package format, check pack/README.md.

Updater logic

Here's a detailed list of how each updater mode works:

Diagram

  • --mode=autoupdate: Invoked by update_engine when a payload is installed.

    1. Check if WP is enabled.
    2. If WP is enabled, update RW / inactive and exit. After system reboot. The update_engine will invoke chromeos-setgoodfirmware after 60 secs, which will update or mark booted RW firmware to active.
    3. If WP is disabled, check if the RO section is same as CROS_FIRMWARE_MAIN_IMAGE. If yes, go 2. Otherwise, do --mode=recovery.

  • --mode=recovery: Invoked by recovery shim after installed.

    1. Check if WP is enabled.
    2. If WP is enabled, update both RW/A, RW/B and exit.
    3. If WP is disabled, update whole image except reserved sections like VPD. This includes RO, RW/A, and RW/B.

Note in recovery mode, the HWID and flags in GBB are both preserved.

  • --mode=factory: A special recovery mode for factory initial imaging that always runs as wp=0 and NOT preserving GBB flags.
    1. Check if WP is enabled, and exit with failure if enabled.
    2. Update whole image except reserved sections (GBB, VPD). This includes RO, RW/A, and RW/B.

Note in factory mode, only HWID in GBB is preserved. The GBB flags will be changed because in factory process we need to overwrite the flags so we can ensure developer mode or other factory friendly settings were turned on in first boot.

  • --mode=legacy: A special mode that only updates RW_LEGACY.

  • --mode=output: A special mode for updater with multiple sets of images.

    1. Collect system information like model and white label tags.
    2. Apply patches like signing key blocks if available.
    3. Write images to given output folder (--output_dir).