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.