diff options
Diffstat (limited to 'binary_search_tool/cros_pkg/README.cros_pkg_triage')
| -rw-r--r-- | binary_search_tool/cros_pkg/README.cros_pkg_triage | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/binary_search_tool/cros_pkg/README.cros_pkg_triage b/binary_search_tool/cros_pkg/README.cros_pkg_triage new file mode 100644 index 00000000..5e285008 --- /dev/null +++ b/binary_search_tool/cros_pkg/README.cros_pkg_triage @@ -0,0 +1,185 @@ + +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). |