| |
| binary_search_state.py is a general binary search triage tool that |
| performs a binary search on a set of things to try to identify which |
| thing or thing(s) in the set is 'bad'. binary_search_state.py assumes |
| that the user has two sets, one where everything is known to be good, |
| ane one which contains at least one bad item. binary_search_state.py |
| then copies items from the good and bad sets into a working set and |
| tests the result (good or bad). binary_search_state.py requires that |
| a set of scripts be supplied to it for any particular job. For more |
| information on binary_search_state.py, see |
| |
| https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage |
| |
| This particular set of scripts is designed to work wtih |
| binary_search_state.py in order to find the bad package or set of |
| packages in a ChromeOS build. |
| |
| |
| QUICKSTART: |
| |
| After setting up your 3 build trees (see Prerequisites section), do the |
| following: |
| |
| - Decide which test script to use (boot_test.sh or |
| interactive_test.sh) |
| - Get the IP name or address of the chromebook you will use for testing. |
| - Do the following inside your chroot: |
| |
| $ cd ~/trunk/src/third_party/toolchain_utils/binary_search_tool |
| $ ./cros_pkg/setup.sh <board-to-test> <IP-name-or-address-of-chromebook> |
| |
| If you chose the boot test, then: |
| |
| $ python ./binary_search_state.py \ |
| --get_initial_items=cros_pkg/get_initial_items.sh \ |
| --switch_to_good=cros_pkg/switch_to_good.sh \ |
| --switch_to_bad=cros_pkg/switch_to_bad.sh \ |
| --test_setup_script=cros_pkg/test_setup.sh \ |
| --test_script=cros_pkg/boot_test.sh \ |
| --file_args \ |
| --prune |
| |
| Otherwise, if you chose the interactive test, then: |
| |
| $ python ./binary_search_state.py \ |
| --get_initial_items=cros_pkg/get_initial_items.sh \ |
| --switch_to_good=cros_pkg/switch_to_good.sh \ |
| --switch_to_bad=cros_pkg/switch_to_bad.sh \ |
| --test_setup_script=cros_pkg/test_setup.sh \ |
| --test_script=cros_pkg/interactive_test.sh \ |
| --file_args \ |
| --prune |
| |
| Once you have completely finished doing the binary search/triage, |
| run the genereated cleanup script, to restore your chroot to the state |
| it was in before you ran the setup.sh script: |
| |
| $ cros_pkg/${BOARD}_cleanup.sh |
| |
| |
| |
| FILES AND SCRIPTS: |
| |
| boot_test.sh - One of two possible test scripts used to determine |
| if the ChromeOS image built from the packages is good |
| or bad. This script tests to see if the image |
| booted, and requires no user intervention. |
| |
| create_cleanup_script.py - This is called by setup.sh, to |
| generate ${BOARD}_cleanup.sh, |
| which is supposed to be run by the user |
| after the binary search triage process is |
| finished, to undo the changes made by |
| setup.sh and return everything |
| to its original state. |
| |
| get_initial_items.sh - This script is used to determine the current |
| set of ChromeOS packages. |
| |
| test_setup.sh - This script will build and flash your image to the |
| remote machine. If the flash fails, this script will |
| help the user troubleshoot by flashing through usb or |
| by retrying the flash over ethernet. |
| |
| interactive_test.sh - One of two possible scripts used to determine |
| if the ChromeOS image built from the packages |
| is good or bad. This script requires user |
| interaction to determine if the image is |
| good or bad. |
| |
| setup.sh - This is the first script the user should call, after |
| taking care of the prerequisites. It sets up the |
| environment appropriately for running the ChromeOS |
| package binary search triage, and it generates two |
| necessary scripts (see below). |
| |
| switch_to_bad.sh - This script is used to copy packages from the |
| 'bad' build tree into the work area. |
| |
| switch_to_good.sh - This script is used to copy packages from the |
| good' build tree into the work area. |
| |
| |
| GENERATED SCRIPTS: |
| |
| common.sh - contains basic environment variable definitions for |
| this binary search triage session. |
| |
| ${BOARD}_cleanup.sh - script to undo all the changes made by |
| running setup.sh, and returning |
| everything to its original state. The user |
| should manually run this script once the |
| binary search triage process is over. |
| |
| ASSUMPTIONS: |
| |
| - There are two different ChromeOS builds, for the same board, with the |
| same set of ChromeOS packages. One build creates a good working ChromeOS |
| image and the other does not. |
| |
| - You have saved the complete build trees for both the good and bad builds. |
| |
| |
| PREREQUISITES FOR USING THESE SCRIPTS (inside the chroot): |
| |
| - The "good" build tree, for the board, is in /build/${board}.good |
| (e.g. /build/lumpy.good or /build/daisy.good). |
| |
| - The "bad" build tree is in /build/${board}.bad |
| (e.g. /build/lumpy.bad or /build/daisy.bad). |
| |
| - You made a complete copy of the "bad" build tree , and put it in |
| /build/${board}.work (e.g. /build/lumpy.work or /build/daisy.work. |
| The easiest way to do this is to use something similar to the |
| following set of commands (this example assumes the board is |
| 'lumpy'): |
| |
| $ cd /build |
| $ sudo tar -cvf lumpy.bad.tar lumpy.bad |
| $ sudo mv lumpy.bad lumpy.work |
| $ sudo tar -xvf lumpy.bad.tar |
| |
| |
| USING THESE SCRIPTS FOR BINARY TRIAGE OF PACKAGES: |
| |
| To use these scripts, you must first run setup.sh, passing it two |
| arguments (in order): the board for which you are building the image; |
| and the name or ip address of the chromebook you want to use for |
| testing your chromeos images. setup.sh will do the following: |
| |
| - Verify that your build trees are set up correctly (with good, bad |
| and work). |
| - Create a soft link for /build/${board} pointing to the work build |
| tree. |
| - Create the common.sh file that the other scripts passed to the |
| binary triage tool will need. |
| - Create a cleanup script, ${board}_cleanup.sh, for you to |
| run after you are done with the binary triages, to undo all of these |
| various changes that setup.sh did. |
| |
| |
| This set of scripts comes with two alternate test scripts. One test |
| script, boot_test.sh, just checks to make sure that the image |
| booted (i.e. responds to ping) and assumes that is enough. The other |
| test script, interactive_test.sh, is interactive and asks YOU |
| to tell it whether the image on the chromebook is ok or not (it |
| prompts you and waits for a response). |
| |
| |
| Once you have run setup.sh (and decided which test script you |
| want to use) run the binary triage tool using these scripts to |
| isolate/identify the bad package: |
| |
| ~/trunk/src/third_party/toolchain_utils/binary_search_tool/binary_search_state.py \ |
| --get_initial_items=cros_pkg/get_initial_items.sh \ |
| --switch_to_good=cros_pkg/switch_to_good.sh \ |
| --switch_to_bad=cros_pkg/switch_to_bad.sh \ |
| --test_setup_script=cros_pkg/test_setup.sh \ |
| --test_script=cros_pkg/boots_test.sh \ # could use interactive_test.sh instead |
| --prune |
| |
| |
| After you have finished running the tool and have identified the bad |
| package(s), you will want to run the cleanup script that setup.sh |
| generated (cros_pkg/${BOARD}_cleanup.sh). |