Chromium OS Factory Bundle

What's a factory bundle?

A factory bundle is an archive file containing all files you need to setup Chromium OS factory environment.

Here is a list of files in a typical factory bundle:

complete/
  complete_script_sample.sh
factory_shim/
  factory_install_shim.bin
firmware/
  chromeos-firmwareupdate
firmware_images/
  bios.bin
  ec.bin
  pd.bin
hwid/
  hwid_v3_bundle_SAMUS.sh
release_image/
  chromeos_9334.72.0_samus_recovery_stable-channel_mp-v3.bin
test_image/
  ChromeOS-test-R58-9334.72.0-samus.bin
toolkit/
  install_factory_toolkit.run
netboot/
  tftp/
    chrome-bot/
      samus/
        cmdline.sample
        vmlinuz
  dnsmasq.conf
  image.net.bin
setup/
  bin/
    cgpt
    futility
  lib/
    cros_image_common.sh
    shflags
  .default_board
  cros_docker.sh
  cros_payload
  edit_lsb_factory.sh
  extract_firmware_updater.sh
  factory_common.sh
  fmap.py
  make_factory_package.sh
  merge_factory_usbimg.sh
  mount_partition.sh
  netboot_firmware_settings.py
  NETBOOT.md
  pygpt
  README.md
  resize_image_fs.sh
MANIFEST.yaml
README

release_image/

There should be exactly one file in this folder, with arbitrary file name.

This file will be imported by Umpire as release image.
factory_installer will deploy release image into DUTs.

You can get release images from CPFE (select image type RECOVERY_IMAGE).

test_image/

There should be exactly one file in this folder, with arbitrary file name.

This file will be imported by Umpire as test image.
factory_installer will deploy test image into DUTs.

You can get test images from CPFE (select image type TEST_IMAGE_ARCHIVE).

toolkit/

There should be exactly one file in this folder, with arbitrary file name.

This file will be imported by Umpire as factory toolkit installer.
factory_installer will deploy factory toolkit into DUTs.
Goofy will try to update factory toolkit when running pytest sync_shopfloor.

You can get factory toolkit installers from CPFE (select image type FACTORY_IMAGE_ARCHIVE)

hwid/

There should be exactly one file in this folder, with arbitrary file name.

This file will be imported by Umpire as HWID bundle.
factory_installer will deploy HWID bundle into DUTs.
Goofy will try to update HWID bundle when running some specific pytests.

You can get HWID bundles from CPFE (select image type FACTORY_IMAGE_ARCHIVE).

firmware/

There could be at most one file in this folder, with arbitrary file name.

This file (if exists) will be imported by Umpire as firmware updater.
factory_installer will run firmware updater to flash firmware (EC, AP, and possibly PD) when imaging finished.
Goofy will try to update firmware when running pytest update_firmware.

You can get a firmware updater from a release image by running factory/setup/extract_firmware_updater.sh -i /path/to/release_image

complete/

There could be at most one file in this folder, with arbitrary file name.

This file (if exists) will be imported by Umpire as complete script.
factory_installer will run the complete script after firmware updater.

You can find a complete script template in factory/setup/complete_script_sample.sh.

firmware_images/

finalize_bundle will extract firmware images from firmware updater and put them into this folder.

factory_shim/

finalize_bundle will extract factory shim image from FACTORY_IMAGE_ARCHIVE, patch its server address, and put it into this folder.

netboot/

finalize_bundle will extract netboot firmware image.net.bin and netboot kernel vmlinuz from FACTORY_IMAGE_ARCHIVE, patch their server address, and put them into this folder.

Also, there will be two files, cmdline.sample and dnsmasq.conf, which are generated by finalize_bundle to help you setup TFTP service for netboot.

When importing a bundle:

netboot/image.net.bin will be imported as netboot_firmware.
netboot/tftp/chrome-bot/*/vmlinu* will be imported as netboot_kernel.
netboot/tftp/chrome-bot/*/cmdline will be imported as netboot_cmdline. (Note that cmdline.sample will not be imported)

setup/

This folder is extracted from FACTORY_IMAGE_ARCHIVE by finalize_bundle, contains many useful scripts, such as:

cros_docker.sh
extract_firmware_updater.sh
make_factory_package.sh
mount_partition.sh
netboot_firmware_settings.py
resize_image_fs.sh

Building a factory bundle

Import into factory server

If you just want a bundle for Factory Server to import, you can manually create an archive file (zip file or {gzip|bzip2|xz} compressed tarball) containing the following folders with corresponding files inside.

complete
firmware
hwid
release_image
test_image
toolkit

Or you can just use the partial update feature of Umpire for testing. No need to always create a factory bundle for network installation.

MANIFEST.yaml

To create a complete factory bundle, you need to run finalize_bundle. finalize_bundle takes a manifest file MANIFEST.yaml and produces a factory bundle.

Here is a template MANIFEST.yaml:

board: samus
project: samus
bundle_name: 20170628_dvt
server_url: http://12.34.56.78:8080/
firmware: local
release_image: 9334.72.0
test_image: 9334.72.0
toolkit: 9688.0.0

Field `board`

Board name.

Field `project`

The Public Code Name (can be found on Golden Eye), or the “Google Name”. Also should be same as the “Model Name” displayed in firmware screen (which is actually HWID), or reported on by command mosys platform model.

The project is made for projects sharing one board (overlay), especially for Zerg projects.

For example, the projects electro and basking both share images built using BOARD=reef, so you will set:

board: reef
project: electro

For projects having its own overlay, board and project may be same name. For example, pyro is using reef as reference design but it does have its own overlay, so you will need to set:

board: pyro
project: pyro

The project will be used to decide which HWID config file to use, and to find right firmware (and signing keys).

Field `bundle_name`

{YYYYMMDD}_{proto|evt|dvt|pvt}

Field `server_url`

http://{server ip}:{server port}/

finalize_bundle will inject this address into netboot firmware and factory shim.

This is an optional field.

Field `firmware`

There are two valid values:

local: User manually prepares a firmware updater in firmware/.
release_image: Use firmware updater in the release image.

This is an optional field. Default value is release_image.

Field `hwid`

There are two valid values:

real: There should be a real HWID bundle in hwid/.
none: finalize_bundle will create a dummy HWID bundle.

This is an optional field. Default value is real.

Field `release_image`

There are two kinds of valid values:

local: User manually prepares a release image in release_image/.
{xxxx.y.z}: Release image version for finalize_bundle to download. If there is already one file in release_image/, finalize_bundle will check whether the version matches or not.

Field `test_image`

There are two kinds of valid values:

local: User manually prepares a test image in test_image/.
{xxxx.y.z}: Test image version for finalize_bundle to download. If there is already one file in test_image/, finalize_bundle will check whether the version matches or not.

Field `toolkit`

There are two kinds of valid values:

local: User manually extracts FACTORY_IMAGE_ARCHIVE in bundle directory.
{xxxx.y.z}: FACTORY_IMAGE_ARCHIVE version for finalize_bundle to download. finalize_bundle will always download FACTORY_IMAGE_ARCHIVE if toolkit is set to non-local.

Non-local resources

Currently non-local resources can only be accessed by Google internally. Partners can only use local resources.

finalize_bundle

With MANIFEST.yaml, we can run finalize_bundle now.

We strongly recommend you to install lbzip2, which can help you reduce finalize_bundle execution time by a lot.

To get finalize_bundle, please checkout factory repository:

git clone https://chromium.googlesource.com/chromiumos/platform/factory

Create a directory with name factory_bundle_{board}_{bundle_name}:

mkdir factory_bundle_samus_20170628_dvt
cd factory_bundle_samus_20170628_dvt/

Prepare firmware updater if you want to use local firmware updater:

ln /path/to/chromeos-firmwareupdate firmware/

Prepare release image if you want to use local release image:

ln /path/to/chromeos_9334.72.0_samus_recovery_stable-channel_mp-v3.bin release_image/

Prepare test image if you want to use local test image:

tar -JxvC test_image/ </path/to/ChromeOS-test-R58-9334.72.0-samus.tar.xz

Extract factory zip (FACTORY_IMAGE_ARCHIVE) if you want to use a local one:

unzip /path/to/ChromeOS-factory-R61-9688.0.0-samus.zip

Prepare HWID bundle if you want to use local HWID bundle:

ln /path/to/hwid_v3_bundle_SAMUS.sh hwid/

Add your MANIFEST.yaml if you don't have it in factory zip or you want to use a new one:

cp /path/to/MANIFEST.yaml MANIFEST.yaml

Finally, run finalize_bundle:

/path/to/factory/bin/finalize_bundle .

After minutes, you will get a complete factory bundle. Cheers!

Easy Bundle Creation Service

Work In Progress

Chromium OS Factory Bundle

What's a factory bundle?

release_image/

test_image/

toolkit/

hwid/

firmware/

complete/

firmware_images/

factory_shim/

netboot/

setup/

Building a factory bundle

Import into factory server

MANIFEST.yaml

Field board

Field project

Field bundle_name

Field server_url

Field firmware

Field hwid

Field release_image

Field test_image

Field toolkit

Non-local resources

finalize_bundle

Easy Bundle Creation Service

Field `board`

Field `project`

Field `bundle_name`

Field `server_url`

Field `firmware`

Field `hwid`

Field `release_image`

Field `test_image`

Field `toolkit`