README.md revision 0d0fd4a6bcf3b1223f1f5ed31d61aadfcfe79bc9 
1Bisection Bug Search
2====================
3
4Bisection Bug Search is a tool for finding compiler optimizations bugs. It
5accepts a program which exposes a bug by producing incorrect output and expected
6output for the program. It then attempts to narrow down the issue to a single
7method and optimization pass under the assumption that interpreter is correct.
8
9Given methods in order M0..Mn finds smallest i such that compiling Mi and
10interpreting all other methods produces incorrect output. Then, given ordered
11optimization passes P0..Pl, finds smallest j such that compiling Mi with passes
12P0..Pj-1 produces expected output and compiling Mi with passes P0..Pj produces
13incorrect output. Prints Mi and Pj.
14
15How to run Bisection Bug Search
16===============================
17
18There are two supported invocation modes:
19
201. Regular invocation, dalvikvm command is constructed internally:
21
22        ./bisection_search.py -cp classes.dex --expected-output out_int --class Test
23
242. Raw-cmd invocation, dalvikvm command is accepted as an argument. The command
25   has to start with an executable.
26
27   Extra dalvikvm arguments will be placed on second position in the command
28   by default. {ARGS} tag can be used to specify a custom position.
29
30        ./bisection_search.py --raw-cmd='run.sh -cp classes.dex Test' --expected-retcode SUCCESS
31        ./bisection_search.py --raw-cmd='/bin/sh art {ARGS} -cp classes.dex Test' --expected-retcode SUCCESS
32
33Help:
34
35    bisection_search.py [-h] [-cp CLASSPATH] [--class CLASSNAME] [--lib LIB]
36                             [--dalvikvm-option [OPT [OPT ...]]] [--arg [ARG [ARG ...]]]
37                             [--image IMAGE] [--raw-cmd RAW_CMD]
38                             [--64] [--device] [--device-serial DEVICE_SERIAL]
39                             [--expected-output EXPECTED_OUTPUT]
40                             [--expected-retcode {SUCCESS,TIMEOUT,ERROR}]
41                             [--check-script CHECK_SCRIPT] [--logfile LOGFILE] [--cleanup]
42                             [--timeout TIMEOUT] [--verbose]
43
44    Tool for finding compiler bugs. Either --raw-cmd or both -cp and --class are required.
45
46    optional arguments:
47      -h, --help                                  show this help message and exit
48
49    dalvikvm command options:
50      -cp CLASSPATH, --classpath CLASSPATH        classpath
51      --class CLASSNAME                           name of main class
52      --lib LIB                                   lib to use, default: libart.so
53      --dalvikvm-option [OPT [OPT ...]]           additional dalvikvm option
54      --arg [ARG [ARG ...]]                       argument passed to test
55      --image IMAGE                               path to image
56      --raw-cmd RAW_CMD                           bisect with this command, ignore other command options
57
58    bisection options:
59      --64                                        x64 mode
60      --device                                    run on device
61      --device-serial DEVICE_SERIAL               device serial number, implies --device
62      --expected-output EXPECTED_OUTPUT           file containing expected output
63      --expected-retcode {SUCCESS,TIMEOUT,ERROR}  expected normalized return code
64      --check-script CHECK_SCRIPT                 script comparing output and expected output
65      --logfile LOGFILE                           custom logfile location
66      --cleanup                                   clean up after bisecting
67      --timeout TIMEOUT                           if timeout seconds pass assume test failed
68      --verbose                                   enable verbose output
69