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