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
  miniomaha_engine.py
  miniomaha.py
  miniomaha_test.py
  mount_partition.sh
  netboot_firmware_settings.py
  NETBOOT.md
  pygpt
  README.md
  resize_image_fs.sh
  start_download_server.sh
MANIFEST.yaml
README
doc.zip
start_download_server.sh

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.

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

start_download_server.sh

This script file is only for Mini-Omaha backward compatibility. It will invoke make_factory_package.sh to prepare files for Mini-Omaha in the first time, and then start Mini-Omaha service.

Building a factory bundle

Build a factory bundle only for Umpire

If you just want a bundle for Umpire 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
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 `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/

start_download_server.sh

Building a factory bundle

Build a factory bundle only for Umpire

MANIFEST.yaml

Field board

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 `bundle_name`

Field `server_url`

Field `firmware`

Field `hwid`

Field `release_image`

Field `test_image`

Field `toolkit`