diff options
Diffstat (limited to 'binary_search_tool/android')
| -rw-r--r-- | binary_search_tool/android/README.android | 186 | ||||
| -rw-r--r-- | binary_search_tool/android/README.android.md | 209 | ||||
| -rwxr-xr-x | binary_search_tool/android/switch_to_bad.sh | 2 | ||||
| -rwxr-xr-x | binary_search_tool/android/switch_to_good.sh | 2 |
4 files changed, 188 insertions, 211 deletions
diff --git a/binary_search_tool/android/README.android b/binary_search_tool/android/README.android new file mode 100644 index 00000000..9e518f60 --- /dev/null +++ b/binary_search_tool/android/README.android @@ -0,0 +1,186 @@ + +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, +and 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 object or set of +bad objects in an Android build. + + +QUICKSTART: + +After setting up your 2 build trees (see Prerequisites section), do the +following: + + - Decide which test script to use (boot_test.sh or + interactive_test.sh) + - Get the serial number for the Android device you will use for testing. + - Run the following: + + $ cd <android_src> + $ source build/envsetup.sh + $ lunch <android_device_lunch_combo> + $ cd <path_to_toolchain_utils>/binary_search_tool/ + $ NUM_JOBS=10 ANDROID_SERIAL=<device_serial> \ + ./android/setup.sh <android_src> + + If you chose the boot test, then: + TEST_SCRIPT=android/boot_test.sh + + If you chose the interactive test, then: + TEST_SCRIPT=android/interactive_test.sh + + Finally, run the binary search tool: + + $ python ./binary_search_state.py \ + --get_initial_items=android/get_initial_items.sh \ + --switch_to_good=android/switch_to_good.sh \ + --switch_to_bad=android/switch_to_bad.sh \ + --test_setup_script=android/test_setup.sh \ + --test_script=$TEST_SCRIPT \ + --file_args \ + --prune + + Once you have completely finished doing the binary search/triage, + run the cleanup script: + + $ android/cleanup.sh + + + +FILES AND SCRIPTS: + + Check the header comments for each script for more in depth documentation. + + boot_test.sh - One of two possible test scripts used to determine + if the Android image built from the objects is good + or bad. This script tests to see if the image + booted, and requires no user intervention. + + cleanup.sh - This is called after the binary search tool completes. This + script will clean up the common.sh file generated by setup.sh + + get_initial_items.sh - This script is used to determine all Android objects + that will be bisected. + + test_setup.sh - This script will build and flash your image to the + Android device. If the flash fails, this script will + help the user troubleshoot by trying to flash again or + by asking the user to manually flash it. + + interactive_test.sh - One of two possible scripts used to determine + if the Android image built from the objects + 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 Android + object binary search triage, and it generates the + necessary common script (see below). + + switch_to_bad.sh - This script is used to link objects from the + 'bad' build tree into the work area. + + switch_to_good.sh - This script is used to link objects from the + 'good' build tree into the work area. + + +GENERATED SCRIPTS: + + common.sh - contains basic environment variable definitions for + this binary search triage session. + +ASSUMPTIONS: + +- There are two different Android builds, for the same board/lunch combo with + the same set of generated object files. One build creates a good working + Android image and the other does not. + +- The toolchain bug you are tracking down is not related to the linker. If the + linker is broken or generates bad code, this tool is unlikely to help you. + + +PREREQUISITES FOR USING THESE SCRIPTS: + + Step 1: Decide where to store each build tree + By default, each build tree is stored in "~/ANDROID_BISECT". However you + can override this by exporting BISECT_DIR set to whatever directory you + please. Keep in mind these build trees take dozens of gigabytes each. + + Step 2: Setup your android build environment + 1. `cd <android_src>` + 2. `source build/envsetup.sh` + 3. `lunch <android_device_lunch_combo>` + + Step 3: Populate the good build tree + 1. `make clean` + 2. `export BISECT_STAGE=POPULATE_GOOD` + 3. Install your "good" toolchain in Android, this will most likely be + the toolchain that comes preinstalled with the Android source. + 4. Build all of Android: `make -j10`. The "-j" parameter depends on how + many cores your machine has. See Android documentation for more details. + + Step 4: Populate the bad build tree + 1. `make clean` + 2. `export BISECT_STAGE=POPULATE_BAD` + 3. Install your "bad" toolchain in Android. + 4. Build all of Android again. + + Step 5: Run the android setup script + 1. `cd <path_to_toolchain_utils>/binary_search_tool/` + 2. `NUM_JOBS=<jobs> ANDROID_SERIAL=<android_serial_num> \ + android/setup.sh <android_src>` + + WARNING: It's important that you leave the full "out/" directory in your + Android source alone after Step 4. The binary search tool will + use this directory as a skeleton to build each test image while + triaging. + +USING THESE SCRIPTS FOR BINARY TRIAGE OF OBJECTS: + +To use these scripts, you must first run setup.sh, passing it the path to your +Android source directory. setup.sh will do the following: + + - Verify that your build trees are set up correctly (with good, bad). + - Verify that each build tree has the same contents. + - Verify that the android build environment (lunch, etc.) are setup in your + current shell. + - Create the common.sh file that the other scripts passed to the + binary triage tool will need. + + +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 (wait for device to boot to home screen) 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 android device 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 object: + +./binary_search_state.py \ + --get_initial_items=android/get_initial_items.sh \ + --switch_to_good=android/switch_to_good.sh \ + --switch_to_bad=android/switch_to_bad.sh \ + --test_setup_script=android/test_setup.sh \ + --test_script=android/boot_test.sh \ # could use interactive_test.sh instead + --prune + + +After you have finished running the tool and have identified the bad +object(s), you will want to run the cleanup script (android/cleanup.sh). + diff --git a/binary_search_tool/android/README.android.md b/binary_search_tool/android/README.android.md deleted file mode 100644 index 9445dcbb..00000000 --- a/binary_search_tool/android/README.android.md +++ /dev/null @@ -1,209 +0,0 @@ -# Android's binary search tool - -`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, -and 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 with -`binary_search_state.py` in order to find the bad object or set of -bad objects in an Android build. Furthermore, it can also help find -the bad compiler pass and transformation when building that bad object. - - -## QUICKSTART - -After setting up your 2 build trees (see Prerequisites section), do the -following: - -- Decide which test script to use (`boot_test.sh` or - `interactive_test.sh`) -- Get the serial number for the Android device you will use for testing. -- Run the following: - - ``` - $ cd <android_src> - $ source build/envsetup.sh - $ lunch <android_device_lunch_combo> - $ cd <path_to_toolchain_utils>/binary_search_tool/ - $ NUM_JOBS=10 ANDROID_SERIAL=<device_serial> \ - ./android/setup.sh <android_src> - ``` - - If you chose the boot test, then: - - ``` - TEST_SCRIPT=android/boot_test.sh - ``` - - If you chose the interactive test, then: - - ``` - TEST_SCRIPT=android/interactive_test.sh - ``` - - Finally, run the binary search tool: - - ``` - $ python ./binary_search_state.py \ - --get_initial_items=android/get_initial_items.sh \ - --switch_to_good=android/switch_to_good.sh \ - --switch_to_bad=android/switch_to_bad.sh \ - --test_setup_script=android/test_setup.sh \ - --test_script=$TEST_SCRIPT \ - --file_args \ - --prune - ``` - - Once you have completely finished doing the binary search/triage, - run the cleanup script: - - ``` - $ android/cleanup.sh - ``` - - -## FILES AND SCRIPTS - -Check the header comments for each script for more in depth documentation. - -`boot_test.sh` - One of two possible test scripts used to determine - if the Android image built from the objects is good - or bad. This script tests to see if the image - booted, and requires no user intervention. - -`cleanup.sh` - This is called after the binary search tool completes. This - script will clean up the common.sh file generated by setup.sh - -`get_initial_items.sh` - This script is used to determine all Android objects - that will be bisected. - -`test_setup.sh` - This script will build and flash your image to the - Android device. If the flash fails, this script will - help the user troubleshoot by trying to flash again or - by asking the user to manually flash it. - -`interactive_test.sh` - One of two possible scripts used to determine - if the Android image built from the objects - 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 Android - object binary search triage, and it generates the - necessary common script (see below). - -`switch_to_bad.sh` - This script is used to link objects from the - 'bad' build tree into the work area. - -`switch_to_good.sh` - This script is used to link objects from the - 'good' build tree into the work area. - -`generate_cmd.sh` - This script will generate another temporary script, which - contains the command line options to build the bad object - file again with pass/transformation level limit. - - -## GENERATED SCRIPTS - -`common.sh` - contains basic environment variable definitions for - this binary search triage session. - -## ASSUMPTIONS - -- There are two different Android builds, for the same board/lunch combo with - the same set of generated object files. One build creates a good working - Android image and the other does not. - -- The toolchain bug you are tracking down is not related to the linker. If the - linker is broken or generates bad code, this tool is unlikely to help you. - - -PREREQUISITES FOR USING THESE SCRIPTS: - -1. Decide where to store each build tree - By default, each build tree is stored in `~/ANDROID_BISECT`. However you - can override this by exporting `BISECT_DIR` set to whatever directory you - please. Keep in mind these build trees take dozens of gigabytes each. - -2. Setup your android build environment - - ``` - cd <android_src> - source build/envsetup.sh - lunch <android_device_lunch_combo> - ``` - -3. Populate the good build tree - - 1. `make clean` - 2. `export BISECT_STAGE=POPULATE_GOOD` - 3. Install your "good" toolchain in Android, this will most likely be - the toolchain that comes preinstalled with the Android source. - 4. Build all of Android: `make -j10`. The "-j" parameter depends on how - many cores your machine has. See Android documentation for more details. - -4. Populate the bad build tree - - 1. `make clean` - 2. `export BISECT_STAGE=POPULATE_BAD` - 3. Install your "bad" toolchain in Android. - 4. Build all of Android again. - -5. Run the android setup script - - 1. `cd <path_to_toolchain_utils>/binary_search_tool/` - 2. `NUM_JOBS=<jobs> ANDROID_SERIAL=<android_serial_num> - android/setup.sh <android_src>` - -WARNING: It's important that you leave the full `out/` directory in your - Android source alone after Step 4. The binary search tool will - use this directory as a skeleton to build each test image while - triaging. - -## USING THESE SCRIPTS FOR BINARY TRIAGE OF OBJECTS - -To use these scripts, you must first run setup.sh, passing it the path to your -Android source directory. setup.sh will do the following: - -- Verify that your build trees are set up correctly (with good, bad). -- Verify that each build tree has the same contents. -- Verify that the android build environment (lunch, etc.) are setup in your - current shell. -- Create the common.sh file that the other scripts passed to the - binary triage tool will need. - - -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 (wait for device to boot to home screen) 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 android device 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 object: - -``` -./binary_search_state.py \ - --get_initial_items=android/get_initial_items.sh \ - --switch_to_good=android/switch_to_good.sh \ - --switch_to_bad=android/switch_to_bad.sh \ - --test_setup_script=android/test_setup.sh \ - --test_script=android/boot_test.sh \ # could use interactive_test.sh instead - --prune -``` - -After you have finished running the tool and have identified the bad -object(s), you will want to run the cleanup script (android/cleanup.sh). diff --git a/binary_search_tool/android/switch_to_bad.sh b/binary_search_tool/android/switch_to_bad.sh index d44f9f13..f746b628 100755 --- a/binary_search_tool/android/switch_to_bad.sh +++ b/binary_search_tool/android/switch_to_bad.sh @@ -18,7 +18,7 @@ source android/common.sh OBJ_LIST_FILE=$1 # Symlink from BAD obj to working tree. -SWITCH_CMD="ln -sf ${BISECT_BAD_BUILD}/{} {}; touch {};" +SWITCH_CMD="ln -f ${BISECT_BAD_BUILD}/{} {}; touch {};" overall_status=0 diff --git a/binary_search_tool/android/switch_to_good.sh b/binary_search_tool/android/switch_to_good.sh index 557553c3..1c046c3f 100755 --- a/binary_search_tool/android/switch_to_good.sh +++ b/binary_search_tool/android/switch_to_good.sh @@ -17,7 +17,7 @@ source android/common.sh OBJ_LIST_FILE=$1 # Symlink from GOOD obj to working tree. -SWITCH_CMD="ln -sf ${BISECT_GOOD_BUILD}/{} {}; touch {};" +SWITCH_CMD="ln -f ${BISECT_GOOD_BUILD}/{} {}; touch {};" overall_status=0 |