commit | 32d3316afb52b751db1733ee5857da406d01da9d | [log] [tgz] |
---|---|---|
author | Peter Shih <pihsun@chromium.org> | Fri Oct 13 08:10:07 2017 |
committer | chrome-bot <chrome-bot@chromium.org> | Fri Oct 13 21:45:16 2017 |
tree | 6b3c1543401fa880f529bcf26b4898f255764ef6 | |
parent | a39474d3200ff475a585c0dc99a550b04a831311 [diff] |
pytests: Fix shutdown pytest fail. * shutdown need timeout for event client, so it should use ThreadingEventClient. * ShutdownStep is now in test_object. * BlockingEventClient.wait should be EventClientBase.wait. BUG=b:67759465 TEST=make test TEST=manually run HaltStep and RebootStep on DUT. Change-Id: I5969f510e37a7dba86357700a29e3d5f1fed688f Reviewed-on: https://chromium-review.googlesource.com/718242 Commit-Ready: Pi-Hsun Shih <pihsun@chromium.org> Tested-by: Pi-Hsun Shih <pihsun@chromium.org> Reviewed-by: Wei-Han Chen <stimim@chromium.org>
This repository contains tools and utilities used for manufacturing solution. The Chromium OS reference factory software provides various imaging methods, test flow, and log collection pipeline for manufacturing Chrome devices. It is available as part of the public Chromium OS repository on chromium.org. This code is meant as a starting point, to modify and adapt to different projects.
The Chromium OS Factory Software Platform has three major components:
build_image test
).build_image base
).build_image base; mod_image_for_recovery
and can be downloaded directly from ChromeOS Buildbots or CPFE).cros_docker.sh
, with a web interface “Dome”.emerge-$BOARD factory
or make BOARD=$BOARD toolkit
inside factory repository).The basic steps are:
Under chroot, after setting up board, you have few different ways to build toolkit.
If you have only finished setup_board
, for the first time there are few dependencies you need to build before able to work on toolkits.
If you will need to build test images later, do a build_packages --board $BOARD
to get all dependency packages merged.
If you don't need to build full images (which may download huge files or build Chrome locally with very long time, another solution is to run following commands:
cros_workon --baord $BOARD start factory emerge-$BOARD factory-board factory --getbinpkg -j 16
The -j 16
means to merge in parallel, and should be changed to how many cores your machine has.
Once you have get dependency ready, there are two different ways to help you quickly get toolkit recompiled:
Using emerge. Simply run emerge-$BOARD factory
and find it in /build/$BOARD/usr/local/factory/bundle/toolkit/install_factory_toolkit.run
Build manually. In factory repo, run make BOARD=$BOARD toolkit
and find it in build/install_factory_toolkit.run
.
If you encounter build problems, try to update chroot and rebuild necessary dependencies by running build_packages --board $BOARD
then try again.
The toolkit can be installed into a Chromium OS test image, by either running that locally on a DUT, or apply to a test image directly as blow:
./install_factory_toolkit.run path/to/chromiumos_test_image.bin
Under chroot, after setting up board, you can get the test image by running following commands in trunk/src/scripts
:
build_packages --board $BOARD build_image --board $BOARD test
After image is built, you can flash it into an USB stick (assume your USB appears as sdX
):
# inside chroot cros flash usb:// path/to/chromiumos_test_image.bin # outside chroot sudo dd bs=4M if=path/to/image/chromiumos_test_image.bin of=/dev/sdX \ iflag=fullblock oflag=dsync
Under chroot, after setting up board, you can get the factory shim by running following commands in trunk/src/scripts
:
build_packages --board $BOARD build_image --board $BOARD factory_install
There are few options that you may want to change. The most important one is URL to factory server. You have to set that as CHROMEOS_AUSERVER
in dev_image/etc/lsb-factory
from first (stateful) partition. The utility setup/edit_lsb_factory.sh
can help that. For example, if your server will run in 192.168.200.1
and using default port 8080
:
setup/edit_lsb_factory -i path/to/factory_install_shim.bin
And inside editor, change CHROMEOS_AUSERVER
to:
CHROMEOS_AUSERVER=http://192.168.200.1:8080/update
After image is ready, you can flash it into an USB stick (assume your USB appears as sdX
):
# inside chroot cros flash usb:// path/to/factory_install_shim.bin # outside chroot sudo dd bs=4M if=path/to/image/factory_install_shim.bin of=/dev/sdX \ iflag=fullblock oflag=dsync
On boot, the factory shim displays a download status and downloads the image from the server. On completion, the shim reboots. If you are using legacy firmware (not Chrome OS firmware), you might need to remove the SD card to allow booting the newly-installed image.
After the image starts downloading and the status message turns green, you can remove the SD card—it is not needed after that point.
The API specification and details of each test are documented in the online Chromium OS Factory SDK.
You can build with latest source locally:
make doc
build/doc/index.html
For development and local testing, it is possible to boot the factory test image from a USB memory stick rather than using a network installation. The following steps sare optional:
test0000
if required.enable_dev_usb_boot
.chromeos-install
command.All of the methods will make sure the internal storage and firmware flash chip are having right contents. A typical factory installation places the factory test image in the first slot of Chrome OS image partitions (#2 and #3), and the release image in the second slot (#4 and #5).
Note: All imaging methods except pre-installation will try to update Main (AP) and EC firmware on target machine using a chromeos-firmwareupdate
updater program. If not specified, this will be pulled from the release (recovery) image (i.e., --release) you've provided.
If you need to use a special version that is different from the one combined in release image, add a --firmware PATH
option to make_factory_package.sh
command, or manually upload the updater file in Dome web UI.
Also, if you only want the DEV signed firmware (also known as unsigned), grab the updater.sh
from the ChromeOS-firmware-Rxx-yyyy.0.0-<BOARD>.tar.bz2
or firmware_from_source.tar.bz2
and assign its path to --firmware path/to/updater.sh
.
Otherwise (a “signed firmware” like PreMP signed or MP signed), you have to ask firmware engineer to upload right image, update ebuild files, get a new image built and signed, extract the firmware from it:
./setup/extract_firmware_updater.sh -i path/to/OS_IMAGE.bin
Then you can find a chromeos-firmwareupdate
file and use it for make_factory_package.sh
as --firmware path/to/chromeos-firmwareupdate
.
Also, if you are simply testing and no HWID bundle yet, change the --hwid PATH
to --hwid none
.
We support different imaging methods and here are the details:
The typical way is to install from Factory Server via network. To do that, you have to first setup the server.
The mini-Omaha is a python program in setup/
folder. You have to first prepare the payloads for it by command make_factory_package.sh
:
./setup/make_factory_package.sh \ --board=BOARD \ --test_image=path/to/chromiumos_test_image.bin \ --toolkit=path/to/install_factory_toolkit.run \ --release_image=path/to/chromiumos_image.bin \ --hwid=path/to/hwid_bundle.sh # Start the mini-Omaha server after package is ready. ./setup/miniomaha.py
If you have a prepared factory bundle, you can simply extract it and then run the script start_download_server.sh
in it. This will call make_factory_package.sh
and miniomaha.py
automatically:
/path/to/factory_bundle_board_20170101_evt/start_download_server.sh
If you want to try the edge-bleeding technology instead of mini-Omaha, fetch, install, and run the factory server by cros_docker.sh
command:
# Download factory server docker images. ./setup/cros_docker.sh pull # Install factory server docker images. ./setup/cros_docker.sh install # Create and start Dome containers. ./setup/cros_docker.sh run
After Dome containers started, open a browser to http://localhost:8000, follow the instruction to create a board, upload individual files to it or import a prepared bundle.
After factory server is setup, flash the Factory Install Shim to an USB stick and boot with it, select Install when you see a menu and proceed.
If the Netboot firmware image.net.bin
is available, flash the that to main (AP) SPI firmware and just boot. You will need to setup the network environment (details to be provided in future) so it can download a special kernel and then run same installer as [Boot from USB](#Boot-from-USB]. For more details, please refer to Netboot Setup.
To speed up the process, many factories will try to pre-flash the internal storage so no imaging process is needed. You can generate the disk image from a factory test image and a release (recovery) image using setup scripts.
To do that, use --diskimg
option in make_factory_package.sh
:
./setup/make_factory_package.sh --diskimg=disk_image.bin \ --board=BOARD \ --test_image=path/to/chromiumos_test_image.bin \ --toolkit=path/to/install_factory_toolkit.run \ --release_image=path/to/chromiumos_image.bin \ --hwid=path/to/hwid_bundle.sh
You can image directly to a device, or to a .bin file. Available options are:
--diskimg=XX
specifies the destination device or file--sectors=XX
specifies the number of sectors in the bin file--preserve
prevents wiping of the unused space for faster imagingIt is possible to install everything from same USB that boots system without network. This is helpful in proto builds if network is not ready, and if copy machine is not available. This is also known as the “RMA shim” since it is widely used in RMA (Return Materiel Authorization) flow:
To do that, use --usbimg
option in make_factory_package.sh
:
./make_factory_package.sh --usbimg=usb_image.bin \ --board=BOARD \ --factory_shim=path/to/factory_install_shim.bin \ --test_image=path/to/chromiumos_test_image.bin \ --toolkit=path/to/install_factory_toolkit.run \ --release_image=path/to/chromiumos_image.bin \ --hwid=path/to/hwid_bundle.sh
Flash the usb_image.bin
to a USB stick, boot it in with developer switch enabled in recovery mode, and then you will see the installation menu that can install directly from same USB stick without network.
The factory test image runs the series of pytests located at src/platform/factory/py/test/pytests/
(installed in /usr/local/factory/py/test/pytests/
on the DUT). The sequence of pytest cases are determined by test_lists
files under /usr/local/factory/py/test/test_lists/
. Status is logged to /var/log/factory.log
and more details can be found under /var/factory/*
.
After modifying the source code, you can run the following commands to push files to the DUT. The host machine and DUT must be on the same subnet.
./bin/goofy_remote DUT_IP_ADDRESS
For more information on how to add test cases, read Chromium OS Factory SDK.
Here are few resources you will want to dig into more details:
The new generation of factory server consists of few components: the backend Umpire and frontend Dome.
Umpire needs the software bits prepared in a defined structure as “Factory Bundle”.
The DUT Software (Goofy) and pytests can be localized. Read the Localization Guide for more information.
To help manufacturing line to track DUT status, and to retrieve information from shopfloor backends (for example serial number, vital product data, serial number, ... etc), ODM factory has to implement a XMLRPC web service following Shopfloor Service API.
Most projects will want to adjust the ordering and parameter of tests. This is controlled by a “test list” that will be read by the test harness “Goofy”. See Test Lists Document for more details.
Chrome OS devices are required to have an unique “hardware identifier (HWID)” when leaving factory. This is involved with component qualification, probing and verification. In factory there is a file controlling how HWID is generated. Read HWID Database User Guide for more details.
When running software on DUT for manufacturing, we may usually need to do something different from standard test images - for example disabling power-saving control, or starting some special services.
We have a set of scripting controlling this. See Init System for more details.
The layout of /usr/local/factory
, as installed on devices' stateful partitions, is as follows. Most of these files are installed from this repository, and follow this repository's directory structure.
bin/
: Symbolic links to executable scripts and Python modules.
build/
: Folder to contain build output artifacts.
devtools/
: Tools and scripts for developers.
doc/
: Document templates and resources.
go/
: Programs written in Go language.
init/
: Initialization of factory environment for Chrome OS.
misc/
: Miscellaneous resources used outside of Goofy
proto/
: Proto-buf schema definition.
setup/
: Scripts and programs for partner to setup the environment.
sh/
: Shell scripts.
py_pkg/
: Symbolic link to enable importing Python packages
py/
: Python source code in the cros.factory module and sub-modules.
board/
: Board-specific files (optional and only provided by board overlays, not this repository.) in board overlay:
board_setup_factory.sh
: A script to add board-specific arguments when starting the Goofy (the factory test harness).po/
: i18n resources.
Within the build root (/build/$BOARD
), /usr/local/factory/bundle
is a “pseudo-directory” for the factory bundle: it is masked with INSTALL_MASK
so it is not actually installed onto devices, but any files in this directory will be included in factory bundles built by Buildbot. For example, the shopfloor and mini-Omaha servers are placed into this directory.
Within board overlays, the chromeos-base/factory-board
package may overlay files into this directory structure.
For instance, a board overlay may install:
A board-specific test into /usr/local/factory/py/test/pytests
.
/usr/local/factory/bundle/README
to include a README in the factory bundle.
Any arbitrary board-specific file (e.g., a proprietary tool licensed only for use on a particular board) into /usr/local/factory/board
.
/usr/local/factory/board/board_setup_{factory,x}.sh
to customize Goofy or X arguments.