the Chromium logo

The Chromium Projects
Chromium OS >

Firmware Update

WARNING: Remember to backup your original firmware! The flash memory contains

some device information that cannot be recovered if overwritten.

Glossary

cros_bundle_firmware

Summary

This is a tool for creating a firmware image and writing it to your board. It can handle the following tasks:

Usage

To create an image for a particular board, use:

cros_bundle_firmware -b <board> -o <filename>

This will generate an image <filename> for the board. The tool finds files it needs in /build/<board>/firmware, things like u-boot.bin, the device tree source files (in dts subdir) and so on. There are options to specify each of these manually if you want to, and this is what the ebuild does. However, it does make for a very long command line. If you are unsure what files it is picking up, use -v3.

By default cros_bundle_firmware is quiet. Unless there are warnings/errors, all you will see is progress, and a command prompt when done. Use -v2, -v3 or even -v4 to change that.

Things you can do with this tool, which involve adding options:

A full list of options is below, or use the --help flag.

Options

Usage: cros_bundle_firmware [options]
Options:
  -h, --help            show this help message and exit
  --add-config-str=ADD_CONFIG_STR
                        Add a /config string to the U-Boot fdt
  --add-config-int=ADD_CONFIG_INT
                        Add a /config integer to the U-Boot fdt
  -b BOARD, --board=BOARD
                        Board name to use (e.g. tegra2_kaen)
  --bootcmd=BOOTCMD     Set U-Boot boot command
  --bootsecure          Boot command is simple (no arguments) and not
                        interruptible
  -c BCT, --bct=BCT     Path to BCT source file: only one can be given
  -d FDT, --dt=FDT      Path to fdt binary blob .dtb file to use
  --bl1=EXYNOS_BL1      Exynos preboot (BL1) file
  --bl2=EXYNOS_BL2      Exynos Secondary Program Loader (SPL / BL2) file
  --hwid=HARDWARE_ID    Hardware ID string to use
  -B BMPBLK, --bmpblk=BMPBLK
                        Bitmap block to use
  -F FLASH_DEST, --flash=FLASH_DEST
                        Create a flasher to flash the device (spi, mmc)
  -k KEY, --key=KEY     Path to signing key directory (default to dev key)
  -I INCLUDEDIRS, --includedir=INCLUDEDIRS
                        Include directory to search for files
  -m, --map             Output a flash map summary
  -o OUTPUT, --output=OUTPUT
                        Filename of final output image
  -O OUTDIR, --outdir=OUTDIR
                        Path to directory to use for intermediate and output
                        files
  -p, --preserve        Preserve temporary output directory
  -P POSTLOAD, --postload=POSTLOAD
                        Path to post-load portion of U-Boot (u-boot-post.bin)
  -s, --small           Create/write only the signed U-Boot binary (not the
                        full image)
  -S SEABIOS, --seabios=SEABIOS
                        Legacy BIOS (SeaBIOS)
  -u UBOOT, --uboot=UBOOT
                        Executable bootloader file (U-Boot)
  -U UBOOT_FLASHER, --uboot-flasher=UBOOT_FLASHER
                        Executable bootloader file (U-Boot) to use for
                        flashing (defaults to the same as --uboot)
  -C COREBOOT, --coreboot=COREBOOT
                        Executable lowlevel init file (coreboot)
  -v VERBOSITY, --verbosity=VERBOSITY
                        Control verbosity: 0=silent, 1=progress, 3=full,
                        4=debug
  -w WRITE, --write=WRITE
                        Write firmware to device (usb, sd)

cros_write_firmware

If you already have an image, you can use this tool to write it to an SD card or over USB. However, you might find 'cros_bundle_firmware -w' more flexible.

cros_write_firmware -b daisy -i <image> -w sd:.

Updating your U-Boot to 2011.12 on Daisy

You can do this without USB download using an SD card if you like. Please follow these steps:

  1. Get an SD card and put it into your card reader. The contents of this will be overwritten.

  2. Get the latest source:

    $ repo sync

  3. Build everything

    $ cros build-packages --board daisy

    $ emerge-daisy chromeos-u-boot

    $ emerge-daisy sys-boot/chromeos-bootimage

  4. Write the firmware to your SD card (-F means to create an automatic flasher)

    $ cros_bundle_firmware --add-config-int load_env 1 -b daisy -w sd:. -F spi
# Add '-d exynos5250-snow' for snow

  5. Insert the SD card into your daisy board

  6. Hold down the button which is labelled T20_REC / FW_DEBUG / DFU_REC depending on whether you are using Servo 2, Daisy or Min-Servo.

  7. Press COLD_RST_L / KBC_RST / C_RST, then PWR_BUTTON to switch on, to boot from the SD card.

  8. When it starts up, you should see a console on your servo UART, and it will start flashing your board.

  9. When finished, type 'reset' into the terminal, or press COLD_RST_L / KBC_RST / C_RST again, then PWR_BUTTON to switch on.

Steps 8 can also be done via servod:

dut-control fw_up:on fw_up cold_reset:on cold_reset cold_reset:off cold_reset \
            pwr_button:press pwr_button sleep:2 pwr_button:release pwr_button \
            cold_reset:off cold_reset fw_up:off fw_up cpu_uart_en:on 

x86 Development Flow

Building from the firmware branch

The ToT is not guaranteed to build usable firmware for older boards, so it is often necessary to retrieve an old branch to do so. These steps were used to build the Link firmware from source:


repo init -u <internal-manifest-url> \
    --repo-url='https://chromium.googlesource.com/external/repo.git'
    -b firmware-link-2695.B 
repo sync
cros_workon-link start chromeos-base/chromeos-ec \
    sys-boot/chromeos-u-boot \
    chromeos-base/vboot_reference \
    chromeos-base/vboot_reference-firmware \
    sys-boot/chromeos-coreboot-link \
    sys-boot/chromeos-seabios \
    chromeos-base/chromeos-firmware-link
emerge-link chromeos-ec \
    vboot_reference-firmware \
    chromeos-u-boot \
    chromeos-coreboot-link \
    chromeos-bootimage

This should create image-link.bin in /build/link/firmware under the chroot.

Using flashrom

The flashrom command can be run from a root shell on the device, or it can be used from a development PC connected via servo. See here for more detailed instructions on usage.

Using the SPI flash emulator

The instructions in this section assume that you have a Dediprog EM100 hooked up to the system. This hardware allows for downloading a new firmware image to the board in mere seconds, rather than waiting a few minutes to reflash a physical SPI memory device.

To build a new firmware image, write it to your em100 and reset your link (using servo2):

$ USE=dev emerge-link chromeos-u-boot
$ cros_bundle_firmware -b link --bootcmd vboot_twostop -w em100

(the 'dev' flag reduces the 870KB of spew from the U-Boot ebuild, printing only warnings and errors)

If you want a U-Boot serial console, but don't want to coreboot to print out all its serial info, you can build a coreboot WITHOUT the USE=pcserial flag, and then:

$ cros_bundle_firmware -b link --add-node-enable console 1 --bootcmd vboot_twostop -w em100

This enables the console node in the device tree, thus turning on the serial console in U-Boot.