README.md: Add more complete factory software intro. [chromiumos/platform/factory : master]
153 views
Skip to first unread message
ChromeOS Commit Bot (Gerrit)
Dec 1, 2016, 9:28:50 AM12/1/16
to Hung-Te Lin, Wei-Han Chen, Shun-Hsing Ou
ChromeOS Commit Bot merged this change.
README.md: Add more complete factory software intro. Merged information from http://dev.chromium.org/chromium-os/how-tos-and-troubleshooting/building-factory-test-images BUG=chromium:658752 TEST=none Change-Id: Iefa1e21ce2ae7716452e686c971a662a1057e33e Reviewed-on: https://chromium-review.googlesource.com/415768 Commit-Ready: Hung-Te Lin <hun...@chromium.org> Tested-by: Hung-Te Lin <hun...@chromium.org> Reviewed-by: Wei-Han Chen <sti...@chromium.org> --- M README.md 1 file changed, 230 insertions(+), 3 deletions(-)
diff --git a/README.md b/README.md index 137d2a4..374583e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,234 @@ -Google Chrome OS Factory Software Platform -========================================== -This repository contains tools and utilities used for manufacturing solution. +Google Chromium OS Factory Software Platform +============================================ +Overview +-------- +This repository contains tools and utilities used for manufacturing solution. +The Chromium OS reference factory software provides a sample factory install and +test flow 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: + * **DUT Software**: Everything runs on DUT (Device-under-test), including a + test harness, qualification, calibration and functional test programs, and + steps for finalization like battery cutoff or wiping. + * **Factory Server**: The bridge between DUT and partner's shopfloor service, + including imaging service, shopfloor proxy, and a management console. + * **Google Backend**: The solution for sending manufacturing logs back to + Google infrastructure. + +Terminology +----------- +* Test image: the Chromium OS test image (built by `build_image test`). +* Release image: the (usually signed) release image that end user is using + (built by `build_image base`). +* Recovery image: the (usually signed) release image with recovery installer + so it's in install-able form (built by `build_image base; + mod_image_for_recovery` and can be downloaded directly from ChromeOS + Buildbots or CPFE). +* Factory shim image: a special multi-purpose image that provides: + * Installation from USB (also known as RMA shim). + * Installation from remote server (mini-omaha). Also known as Factory Install + shim in this case. + * Reset or cutoff a device after OOBE. Also known as Reset Shim in this case. +* Factory toolkit: a self-extraction package that contains a set of python + programs, YAML/JSON configuration, and shell scripts that will install + itself into /usr/local/factory. This is also considered as the main "factory + test program" (build by `emerge-$BOARD chromeos-factory` or running `make + BOARD=$BOARD toolkit` inside factory repo). +* Factory Bundle: An archive containing everything: a release (recovery) image, + test image, factory shim image, factory toolkit, and few setup programs. + +Typical Factory Flow +-------------------- +The basic steps are: + +1. An initial/bootable version of the firmware for + [AP](http://www.chromium.org/chromium-os/2014-firmware-summit) (and + [EC](http://www.chromium.org/chromium-os/ec-development)) is pre-flashed + onto the SPI-ROM (and Chromium EC chip) before system assembly. +2. After system assembly, insert the Factory Install Shim USB stick. After the + device boots and the DEV mode screen displays, press Ctrl-U to boot from USB. + The shim contacts a mini-Omaha server to request an install image. + The netboot version of firmware also supports booting and installing from a + network location using tftp, without a USB stick. +3. The factory toolkit, test image, signed release image, and AP/EC firmware are + installed or updated. Included on disk are two full Chrome OS images: the + test image and the shipping image. +4. The system automatically reboots using the test image and and begins + manufacturing tests. This test suite is based on [pytest](py/pytests). The + software supports sequencing tests, configuration, firmware and configuration + updates, reboots, and other events in a configurable sequence. +5. Functional, Run-In, and manual tests run as configured. Upon completion, + results are displayed on the screen. Results are also available as an + electronic pass/fail record with detailed logs for uploading to the shopfloor + server. +6. The test image and test code are automatically erased, leaving the release + image as bootable in the "finalization" step. +7. On failure, the system continues running subsequent tests and reports + failures on completion. Alternatively you can configure it to halt on failure + at specific break points. For details, see the Options class in + src/platform/factory/py/test/factory.py and generic test lists under + src/platform/factory/py/test/test_lists/* . +8. The factory image and test image can be combined into an SSD image and imaged + onto the internal drive before assembly. The first time the device boots, the + sequence starts at step 4 above, using the factory test image. + +Building Factory Toolkit +------------------------ +Under chroot, after [setting up +board](http://dev.chromium.org/chromium-os/developer-guide), you have two ways +to get factory toolkit. + +1. Using emerge. Simply run `emerge chromeos-factory` and find it in + `/build/$BOARD/usr/local/factory/bundle/toolkit/install_factory_toolkit.run` + +2. 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` and 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 + +Building Test Image +------------------- +Under chroot, after [setting up +board](http://dev.chromium.org/chromium-os/developer-guide), you can get the +factory shim by running following commands in `trunk/src/scripts`: + + build_packages + build_image test + +After image is built, you can flash it into an USB stick (assume your USB +appears as `sdX`): + + # outside chroot + cros flash usb:// chromiumos_test_shim.bin + + # outside chroot + sudo dd bs=4M if=/path/to/image/chromiumos_test_shim.bin of=/dev/sdX \ + iflag=fullblock oflag=dsync + +Building Factory (Install) Shim +------------------------------- +Under chroot, after [setting up +board](http://dev.chromium.org/chromium-os/developer-guide), you can get the +factory shim by running following commands in `trunk/src/scripts`: + + build_packages + build_image factory_install + +There are few options that you may want to change. Run +`setup/edit_lsb_factory.sh` to get more information. + +After image is built, you can flash it into an USB stick (assume your USB +appears as `sdX`): + + # outside chroot + cros flash usb:// chromiumos_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. + +Building an SSD image +--------------------- +To pre-image the machines rather than image them over the network, you can +generate the disk image from a factory test image and a release image. + +A generic factory package can be built from a release image and a factory image: + + ./make_factory_package.sh --diskimg=ssd_image.bin \ + --test=/path/to/chromiumos_test_image.bin \ + --factory_toolkit=/path/to/install_factory_toolkit.run \ + --release=/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 imaging + +Booting your (factory) test image via USB +----------------------------------------- +For development and local testing, it is possible to boot the factory test image +from a USB memory stick rather than using a network install. The following steps +are optional: + +1. Copy the test image to USB storage. +2. On your device, switch to developer mode. For most recent devices, this is + done by pressing Esc-F3-Power (F3 is the refresh key on top row) then press + Ctrl-D when the screen said that your need to insert a recovery USB stick, + and press ENTER when the screen asked you to do. +3. After system reboot, enter VT2 by pressing Ctrl-Alt-F2 (F2 is the right-arrow + key on top row). +3. Log in as root with password `test0000` if required. +4. Run the following command: `sudo chromeos-firmwareupdate --mode=todev` +5. Insert the USB memory stick and press Ctrl-U at the dev mode warning + screen. You can also enter VT2 and install the image to SSD using the + `chromeos-install` command. + +Preparing a factory package set +------------------------------- +By default, a factory installation places the factory test image in the first +slot of Chrome OS image partitions ([#2 and #3](http://www.chromium.org/chromium-os/chromiumos-design-docs/disk-format#TOC-Drive-partitions)), +and the release image in the second slot (#4 and #5). + +You can build a generic factory package from a release image and a factory image +as follows: + + # (cros-chroot) + ~/trunk/src/scripts/make_factory_package.sh \ + --test=/path/to/chromiumos_test_image.bin \ + --factory_toolkit=path/to/install_factory_toolkit.run \ + --release=/path/to/chromiumos_image.bin \ + --hwid=/path/to/hwid_bundle.sh + +Modifying factory test image or adding test cases +------------------------------------------------- +The factory test image runs the series of [pytests](py/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. + +1. Enter chroot. +2. Update factory source code on DUT: + + ./bin/goofy_remote DUT_IP_ADDRESS + +For more information on adding test cases, build the **Chromium OS Factory SDK +documentation**: + +1. Enter chroot. +2. Build the SDK documentation + + make doc + +3. Open the following file in a browser window: + + build/doc/index.html + +Developer Notes +--------------- 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.
To view, visit this change. To unsubscribe, visit settings.
Reply all
Reply to author
Forward
0 new messages