1# Pass bisection
2
3This document describes a feature for the bisection tool, which provides
4pass and transformation level bisection for a bad object file.
5
6Before reading this document, please refer to README.bisect for general usage
7of the bisection tool.
8
9The benefit of using pass level bisection is:
10When building a bad object file, it can tell you which pass and transformation
11in the compiler caused the error.
12
13*Notice:* This tool will only work for LLVM/clang, since it is using options
14`-opt-bisect-limit` and `print-debug-counter` that only exist in LLVM.
15
16## Arguments
17
18All the required arguments in object-file-level bisection tool are still
19to be provided. In addition, you will need to add the following arguments:
20
211. `--pass_bisect`: enables pass level bisection
222. `--ir_diff`: enables output of IR differences
23
24Please refer to `--help` or the examples below for details about how to use
25them.
26
27## HOW TO USE: ChromeOS
28
29*TODO* - Future work: Currently this only works for Android.
30
31## HOW TO USE: Android
32
331.  Prerequisites: A general setup is still needed for Android, which means that
34    you need to populate good and bad set of objects with two versions of
35    compilers.
36
37    See the documentation in `README.bisect.md` for more detailed instructions.
38
391.  Pass/Transformation Bisection: If you do not wish to override the other
40    arguments, this command should be sufficient to do pass/transformation level
41    bisection:
42
43    ```
44    ./run_bisect.py android PATH_TO_ANDROID_HOME_DIR
45                --pass_bisect=’android/generate_cmd.sh’
46                --prune=False
47                --ir_diff
48                --verbose
49    ```
50
51    Where:
52
53    ```
54    --pass_bisect:
55        Enables pass/transformation level bisection and with default
56        script to generate the command as ‘android/generate_cmd.sh’.
57    --prune:
58        For now, prune must be set to False to return only the first
59        bad item.
60    --ir_diff:
61        Optional argument to print out IR differences.
62    --verbose:
63        To show IR diff, verbose needs to be on.
64    ```
65
66    Other default arguments:
67
68    ```
69    --get_initial_items='android/get_initial_items.sh'
70    --switch_to_good='android/switch_to_good.sh'
71    --switch_to_bad='android/switch_to_bad.sh'
72    --test_setup_script='android/test_setup.sh'
73    --test_script='android/interactive_test.sh'
74    --incremental
75    --prune
76    --file_args
77    ```
78
79    You can always override them if needed. See README.bisect for more
80    details.
81
821.  Other features: Features such as resuming, number of jobs, and device id
83    remain the same as before. See README.bisect for more details.
84