diff options
author | Zhizhou Yang <zhizhouy@google.com> | 2018-09-17 15:42:04 -0700 |
---|---|---|
committer | chrome-bot <chrome-bot@chromium.org> | 2018-09-19 15:40:42 -0700 |
commit | 8c95dfc94ad3b0e93a6d7e9637af2e0dcad3db13 (patch) | |
tree | ea8d075f07050b8d635f07adfc0f1b6799f3165d /binary_search_tool | |
parent | 6f7acfe655ed82355582cbd4f4130de9c25b22cb (diff) | |
download | toolchain-utils-8c95dfc94ad3b0e93a6d7e9637af2e0dcad3db13.tar.gz |
bisect tool: Add README file for pass level bisection
Added a readme file for the user to know how to use the bisection tool
for pass/transformation level debugging.
Also added some description of default script generate_cmd.sh under
android specific directory.
BUG=chromium:878954
TEST=None
Change-Id: I1d683704e0e4de9f7d1874632c2c241e3aea4fb9
Reviewed-on: https://chromium-review.googlesource.com/1229253
Commit-Ready: ChromeOS CL Exonerator Bot <chromiumos-cl-exonerator@appspot.gserviceaccount.com>
Tested-by: Zhizhou Yang <zhizhouy@google.com>
Reviewed-by: Caroline Tice <cmtice@chromium.org>
Reviewed-by: George Burgess <gbiv@chromium.org>
Diffstat (limited to 'binary_search_tool')
-rw-r--r-- | binary_search_tool/README.pass_bisect | 77 | ||||
-rw-r--r-- | binary_search_tool/android/README.android | 9 |
2 files changed, 84 insertions, 2 deletions
diff --git a/binary_search_tool/README.pass_bisect b/binary_search_tool/README.pass_bisect new file mode 100644 index 00000000..3d419b26 --- /dev/null +++ b/binary_search_tool/README.pass_bisect @@ -0,0 +1,77 @@ +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/android/README.android b/binary_search_tool/android/README.android index 9e518f60..6e79d48a 100644 --- a/binary_search_tool/android/README.android +++ b/binary_search_tool/android/README.android @@ -11,9 +11,10 @@ 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 +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. +bad objects in an Android build. Furthermore, it can also help find +the bad compiler pass and transformation when building that bad object. QUICKSTART: @@ -95,6 +96,10 @@ FILES AND SCRIPTS: 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: |