From 00050c97025ac8ea0999f5c3d1f26e3af7aac9ff Mon Sep 17 00:00:00 2001 From: George Burgess IV Date: Tue, 5 Mar 2019 16:56:49 -0800 Subject: Swap READMEs to markdown Suggested by vapier@ in I7daf1cbe93f8809e469698d7772a6c68baf9e194 This ignores README.chromium, since I'm unsure if that's a special name that some tool somewhere relies on. I skimmed over all of these in gitiles (as you can probably tell by the 35 patch sets :) ) and fixed the issues that jumped out at me. I'm sure that some remain somewhere, but I think I got the majority of them. An attempt has been made to make all files roughly follow the rules here: https://github.com/google/styleguide/blob/gh-pages/docguide/style.md Note that not all of them have super meaningful introductions with ToCs/etc, but the rest should be relatively consistent with that guide. BUG=None TEST=Manual inspection Change-Id: I158048d972d49966e3b8ff1e07e5429928edb339 Reviewed-on: https://chromium-review.googlesource.com/1504893 Commit-Ready: George Burgess Tested-by: George Burgess Reviewed-by: George Burgess --- binary_search_tool/README.bisect | 217 ------------------ binary_search_tool/README.bisect.md | 248 +++++++++++++++++++++ binary_search_tool/README.pass_bisect | 77 ------- binary_search_tool/README.pass_bisect.md | 83 +++++++ binary_search_tool/README.testing | 80 ------- binary_search_tool/README.testing.md | 94 ++++++++ binary_search_tool/android/README.android | 191 ---------------- binary_search_tool/android/README.android.md | 209 +++++++++++++++++ binary_search_tool/cros_pkg/README.cros_pkg_triage | 185 --------------- .../cros_pkg/README.cros_pkg_triage.md | 193 ++++++++++++++++ binary_search_tool/ndk/README | 84 ------- binary_search_tool/ndk/README.md | 89 ++++++++ binary_search_tool/sysroot_wrapper/README | 28 --- binary_search_tool/sysroot_wrapper/README.md | 35 +++ 14 files changed, 951 insertions(+), 862 deletions(-) delete mode 100644 binary_search_tool/README.bisect create mode 100644 binary_search_tool/README.bisect.md delete mode 100644 binary_search_tool/README.pass_bisect create mode 100644 binary_search_tool/README.pass_bisect.md delete mode 100644 binary_search_tool/README.testing create mode 100644 binary_search_tool/README.testing.md delete mode 100644 binary_search_tool/android/README.android create mode 100644 binary_search_tool/android/README.android.md delete mode 100644 binary_search_tool/cros_pkg/README.cros_pkg_triage create mode 100644 binary_search_tool/cros_pkg/README.cros_pkg_triage.md delete mode 100644 binary_search_tool/ndk/README create mode 100644 binary_search_tool/ndk/README.md delete mode 100644 binary_search_tool/sysroot_wrapper/README create mode 100644 binary_search_tool/sysroot_wrapper/README.md (limited to 'binary_search_tool') diff --git a/binary_search_tool/README.bisect b/binary_search_tool/README.bisect deleted file mode 100644 index 49e0c085..00000000 --- a/binary_search_tool/README.bisect +++ /dev/null @@ -1,217 +0,0 @@ - -bisect.py is a wrapper around the general purpose -binary_search_state.py. It provides a user friendly interface for -bisecting various compilation errors. The 2 currently provided -methods of bisecting are ChromeOS package and object bisection. Each -method defines a default set of options to pass to -binary_search_state.py and allow the user to override these defaults -(see the "Overriding" section). - -** NOTE ** -All commands, examples, scripts, etc. are to be run from your chroot unless -stated otherwise. - -Bisection Methods: - -1) ChromeOS Package: - This method will bisect across all packages in a ChromeOS repository and find - the offending packages (according to your test script). This method takes the - following arguments: - - board: The board to bisect on. For example: daisy, falco, etc. - remote: The IP address of the physical machine you're using to test with. - - By default the ChromeOS package method will do a simple interactive test that - pings the machine and prompts the user if the machine is good. - - a) Setup: - The ChromeOS package method requires that you have three build trees: - - /build/${board}.bad - The build tree for your "bad" build - /build/${board}.good - The build tree for your "good" build - /build/${board}.work - A full copy of /build/${board}.bad - - b) Cleanup: - bisect.py does most cleanup for you, the only - thing required by the user is to cleanup all built images and the - three build trees made in /build/ - - c) Default Arguments: - --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' - --incremental - --prune - --file_args - - d) Additional Documentation: - See ./cros_pkg/README.cros_pkg_triage for full documentation of ChromeOS - package bisection. - - e) Examples: - i) Basic interactive test package bisection, on daisy board: - ./bisect.py package daisy 172.17.211.184 - - ii) Basic boot test package bisection, on daisy board: - ./bisect.py package daisy 172.17.211.184 -t cros_pkg/boot_test.sh - -2) ChromeOS Object: - This method will bisect across all objects in a ChromeOS package and find - the offending objects (according to your test script). This method takes the - following arguments: - - board: The board to bisect on. For example: daisy, falco, etc. - remote: The IP address of the physical machine you're using to test with. - package: The package to bisect with. For example: chromeos-chrome - dir: (Optional) the directory for your good/bad build trees. Defaults to - $BISECT_DIR or /tmp/sysroot_bisect. This value will set $BISECT_DIR - for all bisecting scripts. - - By default the ChromeOS object method will do a simple interactive test that - pings the machine and prompts the user if the machine is good. - - a) Setup: - The ChromeOS package method requires that you populate your good and bad set - of objects. sysroot_wrapper will automatically detect the BISECT_STAGE - variable and use this to populate emerged objects. Here is an example: - - # Defaults to /tmp/sysroot_bisect - export BISECT_DIR="/path/to/where/you/want/to/store/builds/" - - export BISECT_STAGE="POPULATE_GOOD" - ./switch_to_good_compiler.sh - emerge-${board} -C ${package_to_bisect} - emerge-${board} ${package_to_bisect} - - export BISECT_STAGE="POPULATE_BAD" - ./switch_to_bad_compiler.sh - emerge-${board} -C {package_to_bisect} - emerge-${board} ${package_to_bisect} - - b) Cleanup: - The user must clean up all built images and the populated object files. - - c) Default Arguments: - --get_initial_items='sysroot_wrapper/get_initial_items.sh' - --switch_to_good='sysroot_wrapper/switch_to_good.sh' - --switch_to_bad='sysroot_wrapper/switch_to_bad.sh' - --test_setup_script='sysroot_wrapper/test_setup.sh' - --test_script='sysroot_wrapper/interactive_test.sh' - --noincremental - --prune - --file_args - - d) Additional Documentation: - See ./sysroot_wrapper/README for full documentation of ChromeOS object file - bisecting. - - e) Examples: - i) Basic interactive test object bisection, on daisy board for - cryptohome package: - ./bisect.py object daisy 172.17.211.184 cryptohome - - ii) Basic boot test package bisection, on daisy board for cryptohome - package: - ./bisect.py object daisy 172.17.211.184 cryptohome \ - --test_script=sysroot_wrapper/boot_test.sh - -3) Android object: - NOTE: Because this isn't a ChromeOS bisection tool, the concept of a - chroot doesn't exist. Just run this tool from a normal shell. - - This method will bisect across all objects in the Android source tree and - find the offending objects (according to your test script). This method takes - the following arguments: - - android_src: The location of your android source tree - num_jobs: (Optional) The number of jobs to pass to make. This is dependent - on how many cores your machine has. A good number is probably - somewhere around 5 to 10. - device_id: (Optional) The serial code for the device you are testing on. - This is used to determine which device should be used in case - multiple devices are plugged into your computer. You can get - serial code for your device by running "adb devices". - dir: (Optional) the directory for your good/bad build trees. Defaults to - $BISECT_DIR or ~/ANDROID_BISECT/. This value will set $BISECT_DIR - for all bisecting scripts. - - By default the Android object method will do a simple interactive test that - pings the machine and prompts the user if the machine is good. - - a) Setup: - The Android object method requires that you populate your good and bad set - of objects. The Android compiler wrapper will automatically detect the - BISECT_STAGE variable and use this to populate emerged objects. Here is an - example: - - # Defaults to ~/ANDROID_BISECT/ - export BISECT_DIR="/path/to/where/you/want/to/store/builds/" - - export BISECT_STAGE="POPULATE_GOOD" - # Install the "good" compiler - ./switch_to_good_compiler.sh - make clean - make -j - - export BISECT_STAGE="POPULATE_BAD" - # Install the "bad" compiler - ./switch_to_bad_compiler.sh - make clean - make -j - - b) Cleanup: - The user must clean up all built images and the populated object files. - - c) Default Arguments: - --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/interactive_test.sh' - --incremental - --prune - --file_args - - d) Additional Documentation: - See ./android/README.android for full documentation of Android object file - bisecting. - - e) Examples: - i) Basic interactive test android bisection, where the android source is - at ~/android_src: - ./bisect.py android ~/android_src - - ii) Basic boot test android bisection, where the android source is at - ~/android_src, and 10 jobs will be used to build android: - ./bisect.py android ~/android_src --num_jobs=10 \ - --test_script=sysroot_wrapper/boot_test.sh - -Resuming: - bisect.py and binary_search_state.py offer the - ability to resume a bisection in case it was interrupted by a - SIGINT, power failure, etc. Every time the tool completes a - bisection iteration its state is saved to disk (usually to the file - "./bisect_driver.py.state"). If passed the --resume option, the tool - it will automatically detect the state file and resume from the last - completed iteration. - -Overriding: - You can run ./bisect.py --help or ./binary_search_state.py - --help for a full list of arguments that can be overriden. Here are - a couple of examples: - - Example 1 (do boot test instead of interactive test): - ./bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh - - Example 2 (do package bisector system test instead of interactive test, this - is used to test the bisecting tool itself -- see comments in - hash_test.sh for more details): - ./bisect.py package daisy 172.17.211.182 \ - --test_script=common/hash_test.sh --test_setup_script="" - - Example 3 (enable verbose mode, disable pruning, and disable verification): - ./bisect.py package daisy 172.17.211.182 \ - --verbose --prune=False --verify=False - diff --git a/binary_search_tool/README.bisect.md b/binary_search_tool/README.bisect.md new file mode 100644 index 00000000..74715ca0 --- /dev/null +++ b/binary_search_tool/README.bisect.md @@ -0,0 +1,248 @@ +# `bisect.py` + +`bisect.py` is a wrapper around the general purpose +`binary_search_state.py`. It provides a user friendly interface for +bisecting various compilation errors. The 2 currently provided +methods of bisecting are ChromeOS package and object bisection. Each +method defines a default set of options to pass to +`binary_search_state.py` and allow the user to override these defaults +(see the "Overriding" section). + +Please note that all commands, examples, scripts, etc. are to be run from your +chroot unless stated otherwise. + +## Bisection Methods + +### ChromeOS Package + +This method will bisect across all packages in a ChromeOS repository and find +the offending packages (according to your test script). This method takes the +following arguments: + +* board: The board to bisect on. For example: daisy, falco, etc. +* remote: The IP address of the physical machine you're using to test with. + +By default the ChromeOS package method will do a simple interactive test that +pings the machine and prompts the user if the machine is good. + +1. Setup: The ChromeOS package method requires that you have three build trees: + + ``` + /build/${board}.bad - The build tree for your "bad" build + /build/${board}.good - The build tree for your "good" build + /build/${board}.work - A full copy of /build/${board}.bad + ``` + +1. Cleanup: bisect.py does most cleanup for you, the only thing required by the + user is to cleanup all built images and the three build trees made in + `/build/` + +1. Default Arguments: + + ``` + --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' + --incremental + --prune + --file_args + ``` + +1. Additional Documentation: See `./cros_pkg/README.cros_pkg_triage` for full + documentation of ChromeOS package bisection. + +1. Examples: + + 1. Basic interactive test package bisection, on daisy board: + + ``` + ./bisect.py package daisy 172.17.211.184 + ``` + + 2. Basic boot test package bisection, on daisy board: + + ``` + ./bisect.py package daisy 172.17.211.184 -t cros_pkg/boot_test.sh + ``` + +### ChromeOS Object + +This method will bisect across all objects in a ChromeOS package and find +the offending objects (according to your test script). This method takes the +following arguments: + +* board: The board to bisect on. For example: daisy, falco, etc. +* remote: The IP address of the physical machine you're using to test with. +* package: The package to bisect with. For example: chromeos-chrome +* dir: (Optional) the directory for your good/bad build trees. Defaults to + $BISECT_DIR or /tmp/sysroot_bisect. This value will set $BISECT_DIR + for all bisecting scripts. + +By default the ChromeOS object method will do a simple interactive test that +pings the machine and prompts the user if the machine is good. + +1. Setup: The ChromeOS package method requires that you populate your good and + bad set of objects. `sysroot_wrapper` will automatically detect the + `BISECT_STAGE` variable and use this to populate emerged objects. Here is an + example: + + ``` + # Defaults to /tmp/sysroot_bisect + export BISECT_DIR="/path/to/where/you/want/to/store/builds/" + + export BISECT_STAGE="POPULATE_GOOD" + ./switch_to_good_compiler.sh + emerge-${board} -C ${package_to_bisect} + emerge-${board} ${package_to_bisect} + + export BISECT_STAGE="POPULATE_BAD" + ./switch_to_bad_compiler.sh + emerge-${board} -C {package_to_bisect} + emerge-${board} ${package_to_bisect} + ``` + +1. Cleanup: The user must clean up all built images and the populated object + files. + +1. Default Arguments: + + ``` + --get_initial_items='sysroot_wrapper/get_initial_items.sh' + --switch_to_good='sysroot_wrapper/switch_to_good.sh' + --switch_to_bad='sysroot_wrapper/switch_to_bad.sh' + --test_setup_script='sysroot_wrapper/test_setup.sh' + --test_script='sysroot_wrapper/interactive_test.sh' + --noincremental + --prune + --file_args + ``` + +1. Additional Documentation: See `./sysroot_wrapper/README` for full + documentation of ChromeOS object file bisecting. + +1. Examples: + + 1. Basic interactive test object bisection, on daisy board for cryptohome + package: `./bisect.py object daisy 172.17.211.184 cryptohome` + + 2. Basic boot test package bisection, on daisy board for cryptohome + package: `./bisect.py object daisy 172.17.211.184 cryptohome + --test_script=sysroot_wrapper/boot_test.sh` + +### Android object + +NOTE: Because this isn't a ChromeOS bisection tool, the concept of a + chroot doesn't exist. Just run this tool from a normal shell. + +This method will bisect across all objects in the Android source tree and +find the offending objects (according to your test script). This method takes +the following arguments: + +* `android_src`: The location of your android source tree + +* `num_jobs`: (Optional) The number of jobs to pass to make. This is dependent + on how many cores your machine has. A good number is probably somewhere + around 5 to 10. + +* `device_id`: (Optional) The serial code for the device you are testing on. + This is used to determine which device should be used in case multiple + devices are plugged into your computer. You can get serial code for your + device by running "adb devices". + +* `dir`: (Optional) the directory for your good/bad build trees. Defaults to + `$BISECT_DIR` or `~/ANDROID_BISECT/`. This value will set `$BISECT_DIR` for + all bisecting scripts. + + By default the Android object method will do a simple interactive test that + pings the machine and prompts the user if the machine is good. + +1. Setup: The Android object method requires that you populate your good and + bad set of objects. The Android compiler wrapper will automatically detect + the `BISECT_STAGE` variable and use this to populate emerged objects. Here + is an example: + + ``` + # Defaults to ~/ANDROID_BISECT/ + export BISECT_DIR="/path/to/where/you/want/to/store/builds/" + + export BISECT_STAGE="POPULATE_GOOD" + # Install the "good" compiler + ./switch_to_good_compiler.sh + make clean + make -j + + export BISECT_STAGE="POPULATE_BAD" + # Install the "bad" compiler + ./switch_to_bad_compiler.sh + make clean + make -j + ``` + +1. Cleanup: The user must clean up all built images and the populated object + files. + +1. Default Arguments: + + ``` + --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/interactive_test.sh' + --incremental + --prune + --file_args + ``` + +1. Additional Documentation: See `./android/README.android` for full + documentation of Android object file bisecting. + +1. Examples: + + 1. Basic interactive test android bisection, where the android source is at + ~/android_src: `./bisect.py android ~/android_src` + + 2. Basic boot test android bisection, where the android source is at + `~/android_src`, and 10 jobs will be used to build android: `./bisect.py + android ~/android_src --num_jobs=10 + --test_script=sysroot_wrapper/boot_test.sh` + +### Resuming + +`bisect.py` and `binary_search_state.py` offer the +ability to resume a bisection in case it was interrupted by a +SIGINT, power failure, etc. Every time the tool completes a +bisection iteration its state is saved to disk (usually to the file +`./bisect_driver.py.state`). If passed the --resume option, the tool +it will automatically detect the state file and resume from the last +completed iteration. + +### Overriding + +You can run `./bisect.py --help` or `./binary_search_state.py +--help` for a full list of arguments that can be overriden. Here are +a couple of examples: + +Example 1 (do boot test instead of interactive test): + +``` +./bisect.py package daisy 172.17.211.182 --test_script=cros_pkg/boot_test.sh +``` + +Example 2 (do package bisector system test instead of interactive test, this + is used to test the bisecting tool itself -- see comments in + hash_test.sh for more details): + +``` +./bisect.py package daisy 172.17.211.182 \ + --test_script=common/hash_test.sh --test_setup_script="" +``` + +Example 3 (enable verbose mode, disable pruning, and disable verification): + +``` +./bisect.py package daisy 172.17.211.182 + --verbose --prune=False --verify=False +``` diff --git a/binary_search_tool/README.pass_bisect b/binary_search_tool/README.pass_bisect deleted file mode 100644 index 3d419b26..00000000 --- a/binary_search_tool/README.pass_bisect +++ /dev/null @@ -1,77 +0,0 @@ -This document describes a feature for the bisection tool, which provides -pass and transformation level bisection for a bad object file. - -Before reading this document, please refer to README.bisect for general usage -of the bisection tool. - -The benefit of using pass level bisection is: -When building a bad object file, it can tell you which pass and transformation -in the compiler caused the error. - -Notice: This tool will only work for LLVM/clang, since it is using options - `-opt-bisect-limit` and `print-debug-counter` that only exist in LLVM. - -ARGUMENTS - - All the required arguments in object-file-level bisection tool are still - to be provided. In addition, you will need to add the following arguments: - - 1)--pass_bisect: enables pass level bisection - 2)--ir_diff: enables output of IR differences - - Please refer to `--help` or the examples below for details about how to use - them. - -HOW TO USE: ChromeOS - -TODO - Future work: Currently this only works for Android. - -HOW TO USE: Android - - 1) Prerequisite - - A general setup is still needed for Android, which means that you need - to populate good and bad set of objects with two versions of compilers. - - See the documentation in README.bisect for more detailed instructions. - - 2) Pass/Transformation Bisection - - If you do not wish to override the other arguments, this command should - be sufficient to do pass/transformation level bisection: - - ./bisect.py android PATH_TO_ANDROID_HOME_DIR - --pass_bisect=’android/generate_cmd.sh’ - --prune=False - --ir_diff - --verbose - - Where: - --pass_bisect: - Enables pass/transformation level bisection and with default - script to generate the command as ‘android/generate_cmd.sh’. - --prune: - For now, prune must be set to False to return only the first - bad item. - --ir_diff: - Optional argument to print out IR differences. - --verbose: - To show IR diff, verbose needs to be on. - - Other default arguments: - --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/interactive_test.sh' - --incremental - --prune - --file_args - - You can always override them if needed. See README.bisect for more - details. - - 3) Other features: - - Features such as resuming, number of jobs, and device id remain the - same as before. See README.bisect for more details. diff --git a/binary_search_tool/README.pass_bisect.md b/binary_search_tool/README.pass_bisect.md new file mode 100644 index 00000000..d03a563b --- /dev/null +++ b/binary_search_tool/README.pass_bisect.md @@ -0,0 +1,83 @@ +# Pass bisection + +This document describes a feature for the bisection tool, which provides +pass and transformation level bisection for a bad object file. + +Before reading this document, please refer to README.bisect for general usage +of the bisection tool. + +The benefit of using pass level bisection is: +When building a bad object file, it can tell you which pass and transformation +in the compiler caused the error. + +*Notice:* This tool will only work for LLVM/clang, since it is using options +`-opt-bisect-limit` and `print-debug-counter` that only exist in LLVM. + +## Arguments + +All the required arguments in object-file-level bisection tool are still +to be provided. In addition, you will need to add the following arguments: + +1. `--pass_bisect`: enables pass level bisection +2. `--ir_diff`: enables output of IR differences + +Please refer to `--help` or the examples below for details about how to use +them. + +## HOW TO USE: ChromeOS + +*TODO* - Future work: Currently this only works for Android. + +## HOW TO USE: Android + +1. Prerequisites: A general setup is still needed for Android, which means that + you need to populate good and bad set of objects with two versions of + compilers. + + See the documentation in `README.bisect.md` for more detailed instructions. + +1. Pass/Transformation Bisection: If you do not wish to override the other + arguments, this command should be sufficient to do pass/transformation level + bisection: + + ``` + ./bisect.py android PATH_TO_ANDROID_HOME_DIR + --pass_bisect=’android/generate_cmd.sh’ + --prune=False + --ir_diff + --verbose + ``` + + Where: + + ``` + --pass_bisect: + Enables pass/transformation level bisection and with default + script to generate the command as ‘android/generate_cmd.sh’. + --prune: + For now, prune must be set to False to return only the first + bad item. + --ir_diff: + Optional argument to print out IR differences. + --verbose: + To show IR diff, verbose needs to be on. + ``` + + Other default arguments: + + ``` + --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/interactive_test.sh' + --incremental + --prune + --file_args + ``` + + You can always override them if needed. See README.bisect for more + details. + +1. Other features: Features such as resuming, number of jobs, and device id + remain the same as before. See README.bisect for more details. diff --git a/binary_search_tool/README.testing b/binary_search_tool/README.testing deleted file mode 100644 index 6c81ab96..00000000 --- a/binary_search_tool/README.testing +++ /dev/null @@ -1,80 +0,0 @@ -This file explains how to set up and run the various kinds of bisection tests. - -The bisection tool comes with several sets of tests which you should -run after updating any of the bisection tool scripts OR after updating -the Android compiler wrapper (to make sure the wrapper will still work -correctly with bisection). - -Before you start. ----------------- - -Before you can run the tests, your PYTHONPATH environment variable -must be correct. This means that it must include both the -toolchain-utils directory and the binary_search_tool directory. The -easiest way to set it is: - -$ cd toolchain-utils -$ export PYTHONPATH=`pwd`:${PYTHONPATH} -$ cd binary_search_tool -$ export PYTHONPATH=`pwd`:${PYTHONPATH} - - -Running the unittests. ----------------------- - -To run the basic unit tests: - -$ cd toolchain-utils/binary_search_tool/test -$ ./binary_search_tool_tester.py - -Running the bisection tests, testing the compiler wrapper. ----------------------------------------------------------- - -If you want to run the bisection tests, and test the compiler wrapper -(to make sure the POPULATE_GOOD and POPULATE_BAD stages are still -working properly) you can do the following. - -If you are testing with the ANDROID COMPILER WRAPPER, you need to to some -preliminary setup: - -Set up the compiler wrapper to replace GCC: - - $ cd gcc-4.8* - $ sudo mv gcc gcc.real - $ sudo ln -s /prebuilts/clang/host/linux-x86/clang-3688880/bin/gcc gcc - -Move to the correct directory, then run the test script: - - $ cd toolchain-utils/binary_search_tool - $ ./run_bisect_test.py - - -If you are testing with the CHROMEOS COMPILER WRAPPER, you MUST run the -tests from INSIDE your CHROOT (but you don't need to do any special setup): - - $ cd - $ cros_sdk - $ cd ~/trunk/src/third_party/toolchain-utils - - Set up your PYTHONPATH: - - $ export PYTHONPATH=`pwd`:${PYTHONPATH} - $ cd binary_search_tool - $ export PYTHONPATH=`pwd`:${PYTHONPATH} - - Run the test script: - - $ ./run_bisect_test.py - - -Running the bisection tests, without testing the compiler wrapper. ------------------------------------------------------------------- - -$ cd toolchain-utils/binary_search_tool -$ ./full_bisect_test/run-test-nowrapper.sh diff --git a/binary_search_tool/README.testing.md b/binary_search_tool/README.testing.md new file mode 100644 index 00000000..139dc087 --- /dev/null +++ b/binary_search_tool/README.testing.md @@ -0,0 +1,94 @@ +# Testing the binary search tool + +This file explains how to set up and run the various kinds of bisection tests. + +The bisection tool comes with several sets of tests which you should +run after updating any of the bisection tool scripts OR after updating +the Android compiler wrapper (to make sure the wrapper will still work +correctly with bisection). + +## Before you start. + +Before you can run the tests, your PYTHONPATH environment variable +must be correct. This means that it must include both the +toolchain-utils directory and the `binary_search_tool` directory. The +easiest way to set it is: + +``` +$ cd toolchain-utils +$ export PYTHONPATH=`pwd`:${PYTHONPATH} +$ cd binary_search_tool +$ export PYTHONPATH=`pwd`:${PYTHONPATH} +``` + + +## Running the unittests. + +To run the basic unit tests: + +``` +$ cd toolchain-utils/binary_search_tool/test +$ ./binary_search_tool_tester.py +``` + +# Running the bisection tests, testing the compiler wrapper. + +If you want to run the bisection tests, and test the compiler wrapper +(to make sure the `POPULATE_GOOD` and `POPULATE_BAD` stages are still +working properly) you can do the following. + +If you are testing with the ANDROID COMPILER WRAPPER, you need to to some +preliminary setup: + +Set up the compiler wrapper to replace GCC: + +``` +$ cd gcc-4.8* +$ sudo mv gcc gcc.real +$ sudo ln -s \ + /prebuilts/clang/host/linux-x86/clang-3688880/bin/gcc gcc +``` + +Move to the correct directory, then run the test script: + +``` +$ cd toolchain-utils/binary_search_tool +$ ./run_bisect_test.py +``` + +If you are testing with the CHROMEOS COMPILER WRAPPER, you MUST run the +tests from INSIDE your CHROOT (but you don't need to do any special setup): + +``` +$ cd +$ cros_sdk +$ cd ~/trunk/src/third_party/toolchain-utils +``` + +Set up your `PYTHONPATH`: + +``` +$ export PYTHONPATH=`pwd`:${PYTHONPATH} +$ cd binary_search_tool +$ export PYTHONPATH=`pwd`:${PYTHONPATH} +``` + +Run the test script: + +``` +$ ./run_bisect_test.py +``` + + +## Running the bisection tests, without testing the compiler wrapper. + +``` +$ cd toolchain-utils/binary_search_tool +$ ./full_bisect_test/run-test-nowrapper.sh +``` diff --git a/binary_search_tool/android/README.android b/binary_search_tool/android/README.android deleted file mode 100644 index 6e79d48a..00000000 --- a/binary_search_tool/android/README.android +++ /dev/null @@ -1,191 +0,0 @@ - -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 - $ source build/envsetup.sh - $ lunch - $ cd /binary_search_tool/ - $ NUM_JOBS=10 ANDROID_SERIAL= \ - ./android/setup.sh - - 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: - - 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 ` - 2. `source build/envsetup.sh` - 3. `lunch ` - - 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 /binary_search_tool/` - 2. `NUM_JOBS= ANDROID_SERIAL= \ - android/setup.sh ` - - 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 new file mode 100644 index 00000000..9445dcbb --- /dev/null +++ b/binary_search_tool/android/README.android.md @@ -0,0 +1,209 @@ +# 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 + $ source build/envsetup.sh + $ lunch + $ cd /binary_search_tool/ + $ NUM_JOBS=10 ANDROID_SERIAL= \ + ./android/setup.sh + ``` + + 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 + source build/envsetup.sh + lunch + ``` + +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 /binary_search_tool/` + 2. `NUM_JOBS= ANDROID_SERIAL= + android/setup.sh ` + +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/cros_pkg/README.cros_pkg_triage b/binary_search_tool/cros_pkg/README.cros_pkg_triage deleted file mode 100644 index 5e285008..00000000 --- a/binary_search_tool/cros_pkg/README.cros_pkg_triage +++ /dev/null @@ -1,185 +0,0 @@ - -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 - - 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). diff --git a/binary_search_tool/cros_pkg/README.cros_pkg_triage.md b/binary_search_tool/cros_pkg/README.cros_pkg_triage.md new file mode 100644 index 00000000..17121dd7 --- /dev/null +++ b/binary_search_tool/cros_pkg/README.cros_pkg_triage.md @@ -0,0 +1,193 @@ +# CrOS'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, +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 + ``` + + 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`). diff --git a/binary_search_tool/ndk/README b/binary_search_tool/ndk/README deleted file mode 100644 index 324d1391..00000000 --- a/binary_search_tool/ndk/README +++ /dev/null @@ -1,84 +0,0 @@ - -This is an example bisection for an NDK build system. This example specifically -bisects the sample NDK Teapot app. All steps (setup and otherwise) for bisection -can be found in DO_BISECTION.sh. This shell script is meant to show the process -required to bisect a compiler problem in an arbitrary NDK app build system. - -There are three necessary setup steps to run this example: - - 1. Install the NDK (known to work with r12b) - a. See here for NDK: https://developer.android.com/ndk/index.html - b. Go here for older NDK downloads: https://github.com/android-ndk/ndk/wiki - - 2. Install the compiler wrapper provided with this repo. See - compiler_wrapper.py for more details. - a. Essentially you must go into the NDK source (or where you build system - stores its toolchain), rename your compilers to .real, and - create a symlink pointing to compiler_wrapper.py named - (where your compiler used to be). - b. If you're using the toolchains that come with the NDK they live at: - /toolchains//prebuilt//bin - example: - /toolchains/llvm/prebuilt/linux-x86_64/bin/clang - - 3. Plug in an Arm7 compatible Android device with usb debugging enabled. - a. This bisection example was tested with a Nexus 5X - b. It should be relatively simple to change the example to work with other - types of devices. Just change the scripts, and change PATCH1 to use a - different build flavor (like x86). See below for more details. - -This example contains two patches: - - PATCH1 - This is the necessary changes to the build system to make the - bisection easier. More specifically, it adds an arm7 build flavor to gradle. - By default, this project will build objects for all possible architectures and - package them into one big apk. These object files meant for another - architecture just sit there and don't actually execute. By adding a build - flavor for arm7, our compiler wrapper won't try to bisect object files meant - for another device. - - PATCH2 - This patch is what inserts the "compiler error". This is a simple - nullptr error in one of the source files, but it is meant to mimic bad code - generation. The result of the error is the app simply crashes immediately - after starting. - -Using another device architecture: - - If we want to bisect for an x86-64 device we first need to provide a arch - specific build flavor in our app/build.gradle file: - - create("x86-64") { - ndk.abiFilters.add("x86_64") - } - - We want to add this under the same "productFlavors" section that our arm7 - build flavor is in (see PATCH1). Now we should have the "installx86-64Debug" - task in our build system. We can use this to build and install an x86-64 - version of our app. - - Now we want to change our test_setup.sh script to run our new gradle task: - ./gradlew installx86-64Debug - - Keep in mind, these specific build flavors are not required. If your build - system makes these device specific builds difficult to implement, the - bisection tool will function perfectly fine without them. However, the - downside of not having targetting a single architecture is the bisection will - take longer (as it will need to search across more object files). - -Additional Documentation: - These are internal Google documents, if you are a developer external to - Google please ask whoever gave you this sample for access or copies to the - documentation. If you cannot gain access, the various READMEs paired with the - bisector should help you. - - * Ahmad's original presentation: - https://goto.google.com/zxdfyi - - * Bisection tool update design doc: - https://goto.google.com/zcwei - - * Bisection tool webpage: - https://goto.google.com/ruwpyi - - * Compiler wrapper webpage: - https://goto.google.com/xossn diff --git a/binary_search_tool/ndk/README.md b/binary_search_tool/ndk/README.md new file mode 100644 index 00000000..e41311a1 --- /dev/null +++ b/binary_search_tool/ndk/README.md @@ -0,0 +1,89 @@ +# NDK Bisection tool + +This is an example bisection for an NDK build system. This example specifically +bisects the sample NDK Teapot app. All steps (setup and otherwise) for bisection +can be found in `DO_BISECTION.sh`. This shell script is meant to show the +process required to bisect a compiler problem in an arbitrary NDK app build +system. + +There are three necessary setup steps to run this example: + +1. Install the NDK (known to work with r12b) + + 1. See here for NDK: https://developer.android.com/ndk/index.html + 2. Go here for older NDK downloads: https://github.com/android-ndk/ndk/wiki + +1. Install the compiler wrapper provided with this repo. See + compiler_wrapper.py for more details. + + 1. Essentially you must go into the NDK source (or where you build system + stores its toolchain), rename your compilers to .real, and + create a symlink pointing to compiler_wrapper.py named + (where your compiler used to be). + + 2. If you're using the toolchains that come with the NDK they live at: + `/toolchains//prebuilt//bin` + example: + `/toolchains/llvm/prebuilt/linux-x86_64/bin/clang` + +1. Plug in an Arm7 compatible Android device with usb debugging enabled. + + 1. This bisection example was tested with a Nexus 5X + + 2. It should be relatively simple to change the example to work with other + types of devices. Just change the scripts, and change PATCH1 to use a + different build flavor (like x86). See below for more details. + +This example contains two patches: + +`PATCH1` - This is the necessary changes to the build system to make the +bisection easier. More specifically, it adds an arm7 build flavor to gradle. +By default, this project will build objects for all possible architectures and +package them into one big apk. These object files meant for another +architecture just sit there and don't actually execute. By adding a build +flavor for arm7, our compiler wrapper won't try to bisect object files meant +for another device. + +`PATCH2` - This patch is what inserts the "compiler error". This is a simple +nullptr error in one of the source files, but it is meant to mimic bad code +generation. The result of the error is the app simply crashes immediately +after starting. + +## Using another device architecture + +If we want to bisect for an x86-64 device we first need to provide a arch +specific build flavor in our app/build.gradle file: + +``` +create("x86-64") { + ndk.abiFilters.add("x86_64") +} +``` + +We want to add this under the same "productFlavors" section that our arm7 +build flavor is in (see PATCH1). Now we should have the "installx86-64Debug" +task in our build system. We can use this to build and install an x86-64 +version of our app. + +Now we want to change our `test_setup.sh` script to run our new gradle task: +``` +./gradlew installx86-64Debug +``` + +Keep in mind, these specific build flavors are not required. If your build +system makes these device specific builds difficult to implement, the +bisection tool will function perfectly fine without them. However, the +downside of not having targetting a single architecture is the bisection will +take longer (as it will need to search across more object files). + +## Additional Documentation + +These are internal Google documents, if you are a developer external to +Google please ask whoever gave you this sample for access or copies to the +documentation. If you cannot gain access, the various READMEs paired with the +bisector should help you. + +* Ahmad's original presentation: https://goto.google.com/zxdfyi +* Bisection tool update design doc: https://goto.google.com/zcwei +* Bisection tool webpage: https://goto.google.com/ruwpyi +* Compiler wrapper webpage: https://goto.google.com/xossn diff --git a/binary_search_tool/sysroot_wrapper/README b/binary_search_tool/sysroot_wrapper/README deleted file mode 100644 index 599d700d..00000000 --- a/binary_search_tool/sysroot_wrapper/README +++ /dev/null @@ -1,28 +0,0 @@ -This is a set of scripts to use when triaging compiler problem by using -the bisecting functionality included in the sysroot_wrapper.hardened. -The only script that you need to create for your triaging problem is the -test_script.sh (The ones in this directory are here only as an example). - -Before running the binary searcher tool you will need to run the setup script: - -./sysroot_wrapper/setup.sh ${board} ${remote_ip} ${package} - -This setup script will ensure your $BISECT_DIR is properly populated and -generate a common variable script for the convenience of the scripts in -./sysroot_wrapper - -To run the binary searcher tool with these scripts, execute it like this: - -./binary_search_state.py --get_initial_items=./sysroot_wrapper/get_initial_items.sh --switch_to_good=./sysroot_wrapper/switch_to_good.sh --switch_to_bad=./sysroot_wrapper/switch_to_bad.sh --test_script=./sysroot_wrapper/test_script.sh --noincremental --file_args 2>&1 | tee /tmp/binary_search.log - -Finally once done you will want to run the cleanup script: - -./sysroot_wrapper/cleanup.sh - -For more information on how to use the sysroot_wrapper to do object file -triaging see: - -https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/bisecting-compiler-problems - - - diff --git a/binary_search_tool/sysroot_wrapper/README.md b/binary_search_tool/sysroot_wrapper/README.md new file mode 100644 index 00000000..89904a0b --- /dev/null +++ b/binary_search_tool/sysroot_wrapper/README.md @@ -0,0 +1,35 @@ +# Sysroot wrapper + +This is a set of scripts to use when triaging compiler problem by using +the bisecting functionality included in the `sysroot_wrapper.hardened`. +The only script that you need to create for your triaging problem is the +`test_script.sh` (The ones in this directory are here only as an example). + +Before running the binary searcher tool you will need to run the setup script: + +``` +./sysroot_wrapper/setup.sh ${board} ${remote_ip} ${package} +``` + +This setup script will ensure your `$BISECT_DIR` is properly populated and +generate a common variable script for the convenience of the scripts in +`./sysroot_wrapper` + +To run the binary searcher tool with these scripts, execute it like this: + +``` +./binary_search_state.py \ + --get_initial_items=./sysroot_wrapper/get_initial_items.sh \ + --switch_to_good=./sysroot_wrapper/switch_to_good.sh \ + --switch_to_bad=./sysroot_wrapper/switch_to_bad.sh \ + --test_script=./sysroot_wrapper/test_script.sh \ + --noincremental \ + --file_args \ + 2>&1 | tee /tmp/binary_search.log +``` + +Finally once done you will want to run the cleanup script: +`./sysroot_wrapper/cleanup.sh` + +For more information on how to use the `sysroot_wrapper` to do object file +triaging see: https://sites.google.com/a/google.com/chromeos-toolchain-team-home2/home/team-tools-and-scripts/bisecting-compiler-problems -- cgit v1.2.3