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>

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: