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