1 2binary_search_state.py is a general binary search triage tool that 3performs a binary search on a set of things to try to identify which 4thing or thing(s) in the set is 'bad'. binary_search_state.py assumes 5that the user has two sets, one where everything is known to be good, 6and one which contains at least one bad item. binary_search_state.py 7then copies items from the good and bad sets into a working set and 8tests the result (good or bad). binary_search_state.py requires that 9a set of scripts be supplied to it for any particular job. For more 10information on binary_search_state.py, see 11 12https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/binary-searcher-tool-for-triage 13 14This particular set of scripts is designed to work wtih 15binary_search_state.py in order to find the bad object or set of 16bad objects in an Android build. 17 18 19QUICKSTART: 20 21After setting up your 2 build trees (see Prerequisites section), do the 22following: 23 24 - Decide which test script to use (boot_test.sh or 25 interactive_test.sh) 26 - Get the serial number for the Android device you will use for testing. 27 - Run the following: 28 29 $ cd <android_src> 30 $ source build/envsetup.sh 31 $ lunch <android_device_lunch_combo> 32 $ cd <path_to_toolchain_utils>/binary_search_tool/ 33 $ NUM_JOBS=10 ANDROID_SERIAL=<device_serial> \ 34 ./android/setup.sh <android_src> 35 36 If you chose the boot test, then: 37 TEST_SCRIPT=android/boot_test.sh 38 39 If you chose the interactive test, then: 40 TEST_SCRIPT=android/interactive_test.sh 41 42 Finally, run the binary search tool: 43 44 $ python ./binary_search_state.py \ 45 --get_initial_items=android/get_initial_items.sh \ 46 --switch_to_good=android/switch_to_good.sh \ 47 --switch_to_bad=android/switch_to_bad.sh \ 48 --test_setup_script=android/test_setup.sh \ 49 --test_script=$TEST_SCRIPT \ 50 --file_args \ 51 --prune 52 53 Once you have completely finished doing the binary search/triage, 54 run the cleanup script: 55 56 $ android/cleanup.sh 57 58 59 60FILES AND SCRIPTS: 61 62 Check the header comments for each script for more in depth documentation. 63 64 boot_test.sh - One of two possible test scripts used to determine 65 if the Android image built from the objects is good 66 or bad. This script tests to see if the image 67 booted, and requires no user intervention. 68 69 cleanup.sh - This is called after the binary search tool completes. This 70 script will clean up the common.sh file generated by setup.sh 71 72 get_initial_items.sh - This script is used to determine all Android objects 73 that will be bisected. 74 75 test_setup.sh - This script will build and flash your image to the 76 Android device. If the flash fails, this script will 77 help the user troubleshoot by trying to flash again or 78 by asking the user to manually flash it. 79 80 interactive_test.sh - One of two possible scripts used to determine 81 if the Android image built from the objects 82 is good or bad. This script requires user 83 interaction to determine if the image is 84 good or bad. 85 86 setup.sh - This is the first script the user should call, after 87 taking care of the prerequisites. It sets up the 88 environment appropriately for running the Android 89 object binary search triage, and it generates the 90 necessary common script (see below). 91 92 switch_to_bad.sh - This script is used to link objects from the 93 'bad' build tree into the work area. 94 95 switch_to_good.sh - This script is used to link objects from the 96 'good' build tree into the work area. 97 98 99GENERATED SCRIPTS: 100 101 common.sh - contains basic environment variable definitions for 102 this binary search triage session. 103 104ASSUMPTIONS: 105 106- There are two different Android builds, for the same board/lunch combo with 107 the same set of generated object files. One build creates a good working 108 Android image and the other does not. 109 110- The toolchain bug you are tracking down is not related to the linker. If the 111 linker is broken or generates bad code, this tool is unlikely to help you. 112 113 114PREREQUISITES FOR USING THESE SCRIPTS: 115 116 Step 1: Decide where to store each build tree 117 By default, each build tree is stored in "~/ANDROID_BISECT". However you 118 can override this by exporting BISECT_DIR set to whatever directory you 119 please. Keep in mind these build trees take dozens of gigabytes each. 120 121 Step 2: Setup your android build environment 122 1. `cd <android_src>` 123 2. `source build/envsetup.sh` 124 3. `lunch <android_device_lunch_combo>` 125 126 Step 3: Populate the good build tree 127 1. `make clean` 128 2. `export BISECT_STAGE=POPULATE_GOOD` 129 3. Install your "good" toolchain in Android, this will most likely be 130 the toolchain that comes preinstalled with the Android source. 131 4. Build all of Android: `make -j10`. The "-j" parameter depends on how 132 many cores your machine has. See Android documentation for more details. 133 134 Step 4: Populate the bad build tree 135 1. `make clean` 136 2. `export BISECT_STAGE=POPULATE_BAD` 137 3. Install your "bad" toolchain in Android. 138 4. Build all of Android again. 139 140 Step 5: Run the android setup script 141 1. `cd <path_to_toolchain_utils>/binary_search_tool/` 142 2. `NUM_JOBS=<jobs> ANDROID_SERIAL=<android_serial_num> \ 143 android/setup.sh <android_src>` 144 145 WARNING: It's important that you leave the full "out/" directory in your 146 Android source alone after Step 4. The binary search tool will 147 use this directory as a skeleton to build each test image while 148 triaging. 149 150USING THESE SCRIPTS FOR BINARY TRIAGE OF OBJECTS: 151 152To use these scripts, you must first run setup.sh, passing it the path to your 153Android source directory. setup.sh will do the following: 154 155 - Verify that your build trees are set up correctly (with good, bad). 156 - Verify that each build tree has the same contents. 157 - Verify that the android build environment (lunch, etc.) are setup in your 158 current shell. 159 - Create the common.sh file that the other scripts passed to the 160 binary triage tool will need. 161 162 163This set of scripts comes with two alternate test scripts. One test 164script, boot_test.sh, just checks to make sure that the image 165booted (wait for device to boot to home screen) and assumes that is enough. 166The other test script, interactive_test.sh, is interactive and asks YOU 167to tell it whether the image on the android device is ok or not (it 168prompts you and waits for a response). 169 170 171Once you have run setup.sh (and decided which test script you 172want to use) run the binary triage tool using these scripts to 173isolate/identify the bad object: 174 175./binary_search_state.py \ 176 --get_initial_items=android/get_initial_items.sh \ 177 --switch_to_good=android/switch_to_good.sh \ 178 --switch_to_bad=android/switch_to_bad.sh \ 179 --test_setup_script=android/test_setup.sh \ 180 --test_script=android/boot_test.sh \ # could use interactive_test.sh instead 181 --prune 182 183 184After you have finished running the tool and have identified the bad 185object(s), you will want to run the cleanup script (android/cleanup.sh). 186 187