1# CrOS's binary search tool 2 3`binary_search_state.py` is a general binary search triage tool that 4performs a binary search on a set of things to try to identify which 5thing or thing(s) in the set is 'bad'. `binary_search_state.py` assumes 6that the user has two sets, one where everything is known to be good, 7ane one which contains at least one bad item. `binary_search_state.py` 8then copies items from the good and bad sets into a working set and 9tests the result (good or bad). `binary_search_state.py` requires that 10a set of scripts be supplied to it for any particular job. For more 11information on `binary_search_state.py`, see 12 13https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage 14 15This particular set of scripts is designed to work wtih 16`binary_search_state.py` in order to find the bad package or set of 17packages in a ChromeOS build. 18 19 20## QUICKSTART 21 22After setting up your 3 build trees (see Prerequisites section), do the 23following: 24 25- Decide which test script to use (`boot_test.sh` or 26 `interactive_test.sh`) 27- Get the IP name or address of the chromebook you will use for testing. 28- Do the following inside your chroot: 29 30 ``` 31 $ cd ~/trunk/src/third_party/toolchain_utils/binary_search_tool 32 $ ./cros_pkg/setup.sh <board-to-test> <IP-name-or-address-of-chromebook> 33 ``` 34 35 If you chose the boot test, then: 36 37 ``` 38 $ python ./binary_search_state.py \ 39 --get_initial_items=cros_pkg/get_initial_items.sh \ 40 --switch_to_good=cros_pkg/switch_to_good.sh \ 41 --switch_to_bad=cros_pkg/switch_to_bad.sh \ 42 --test_setup_script=cros_pkg/test_setup.sh \ 43 --test_script=cros_pkg/boot_test.sh \ 44 --file_args \ 45 --prune 46 ``` 47 48 Otherwise, if you chose the interactive test, then: 49 50 ``` 51 $ python ./binary_search_state.py \ 52 --get_initial_items=cros_pkg/get_initial_items.sh \ 53 --switch_to_good=cros_pkg/switch_to_good.sh \ 54 --switch_to_bad=cros_pkg/switch_to_bad.sh \ 55 --test_setup_script=cros_pkg/test_setup.sh \ 56 --test_script=cros_pkg/interactive_test.sh \ 57 --file_args \ 58 --prune 59 ``` 60 61 Once you have completely finished doing the binary search/triage, 62 run the genereated cleanup script, to restore your chroot to the state 63 it was in before you ran the `setup.sh` script: 64 65 ``` 66 $ cros_pkg/${BOARD}_cleanup.sh 67 ``` 68 69 70## FILES AND SCRIPTS 71 72`boot_test.sh` - One of two possible test scripts used to determine 73 if the ChromeOS image built from the packages is good 74 or bad. This script tests to see if the image 75 booted, and requires no user intervention. 76 77`create_cleanup_script.py` - This is called by setup.sh, to 78 generate ${BOARD}_cleanup.sh, 79 which is supposed to be run by the user 80 after the binary search triage process is 81 finished, to undo the changes made by 82 setup.sh and return everything 83 to its original state. 84 85`get_initial_items.sh` - This script is used to determine the current 86 set of ChromeOS packages. 87 88`test_setup.sh` - This script will build and flash your image to the 89 remote machine. If the flash fails, this script will 90 help the user troubleshoot by flashing through usb or 91 by retrying the flash over ethernet. 92 93`interactive_test.sh` - One of two possible scripts used to determine 94 if the ChromeOS image built from the packages 95 is good or bad. This script requires user 96 interaction to determine if the image is 97 good or bad. 98 99`setup.sh` - This is the first script the user should call, after 100 taking care of the prerequisites. It sets up the 101 environment appropriately for running the ChromeOS 102 package binary search triage, and it generates two 103 necessary scripts (see below). 104 105`switch_to_bad.sh` - This script is used to copy packages from the 106 'bad' build tree into the work area. 107 108`switch_to_good.sh` - This script is used to copy packages from the 109 'good' build tree into the work area. 110 111 112## GENERATED SCRIPTS 113 114`common.sh` - contains basic environment variable definitions for 115 this binary search triage session. 116 117`${BOARD}_cleanup.sh` - script to undo all the changes made by 118 running setup.sh, and returning 119 everything to its original state. The user 120 should manually run this script once the 121 binary search triage process is over. 122 123## ASSUMPTIONS 124 125- There are two different ChromeOS builds, for the same board, with the 126 same set of ChromeOS packages. One build creates a good working ChromeOS 127 image and the other does not. 128 129- You have saved the complete build trees for both the good and bad builds. 130 131 132## PREREQUISITES FOR USING THESE SCRIPTS (inside the chroot) 133 134- The "good" build tree, for the board, is in /build/${board}.good 135 (e.g. /build/lumpy.good or /build/daisy.good). 136 137- The "bad" build tree is in /build/${board}.bad 138 (e.g. /build/lumpy.bad or /build/daisy.bad). 139 140- You made a complete copy of the "bad" build tree , and put it in 141 /build/${board}.work (e.g. /build/lumpy.work or /build/daisy.work. 142 The easiest way to do this is to use something similar to the 143 following set of commands (this example assumes the board is 144 'lumpy'): 145 146 ``` 147 $ cd /build 148 $ sudo tar -cvf lumpy.bad.tar lumpy.bad 149 $ sudo mv lumpy.bad lumpy.work 150 $ sudo tar -xvf lumpy.bad.tar 151 ``` 152 153 154## USING THESE SCRIPTS FOR BINARY TRIAGE OF PACKAGES 155 156To use these scripts, you must first run setup.sh, passing it two 157arguments (in order): the board for which you are building the image; 158and the name or ip address of the chromebook you want to use for 159testing your chromeos images. setup.sh will do the following: 160 161- Verify that your build trees are set up correctly (with good, bad and work). 162- Create a soft link for /build/${board} pointing to the work build tree. 163- Create the common.sh file that the other scripts passed to the binary triage 164 tool will need. 165- Create a cleanup script, ${board}_cleanup.sh, for you to run after you are 166 done with the binary triages, to undo all of these various changes that 167 setup.sh did. 168 169This set of scripts comes with two alternate test scripts. One test 170script, `boot_test.sh`, just checks to make sure that the image 171booted (i.e. responds to ping) and assumes that is enough. The other 172test script, `interactive_test.sh`, is interactive and asks YOU 173to tell it whether the image on the chromebook is ok or not (it 174prompts you and waits for a response). 175 176 177Once you have run `setup.sh` (and decided which test script you 178want to use) run the binary triage tool using these scripts to 179isolate/identify the bad package: 180 181``` 182~/trunk/src/third_party/toolchain_utils/binary_search_tool/binary_search_state.py \ 183 --get_initial_items=cros_pkg/get_initial_items.sh \ 184 --switch_to_good=cros_pkg/switch_to_good.sh \ 185 --switch_to_bad=cros_pkg/switch_to_bad.sh \ 186 --test_setup_script=cros_pkg/test_setup.sh \ 187 --test_script=cros_pkg/boots_test.sh \ # could use interactive_test.sh instead 188 --prune 189``` 190 191After you have finished running the tool and have identified the bad 192package(s), you will want to run the cleanup script that `setup.sh` 193generated (`cros_pkg/${BOARD}_cleanup.sh`). 194