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.
25
26   Extra dalvikvm arguments will be placed on second position in the command
27   by default. {ARGS} tag can be used to specify a custom position.
28
29   If used in device mode, the command has to exec a dalvikvm instance. Bisection
30   will fail if pid of the process started by raw-cmd is different than pid of runtime.
31
32        ./bisection_search.py --raw-cmd='run.sh -cp classes.dex Test' --expected-retcode SUCCESS
33        ./bisection_search.py --raw-cmd='/bin/sh art {ARGS} -cp classes.dex Test' --expected-retcode SUCCESS
34
35Help:
36
37    bisection_search.py [-h] [-cp CLASSPATH] [--class CLASSNAME] [--lib LIB]
38                             [--dalvikvm-option [OPT [OPT ...]]] [--arg [ARG [ARG ...]]]
39                             [--image IMAGE] [--raw-cmd RAW_CMD]
40                             [--64] [--device] [--device-serial DEVICE_SERIAL]
41                             [--expected-output EXPECTED_OUTPUT]
42                             [--expected-retcode {SUCCESS,TIMEOUT,ERROR}]
43                             [--check-script CHECK_SCRIPT] [--logfile LOGFILE] [--cleanup]
44                             [--timeout TIMEOUT] [--verbose]
45
46    Tool for finding compiler bugs. Either --raw-cmd or both -cp and --class are required.
47
48    optional arguments:
49      -h, --help                                  show this help message and exit
50
51    dalvikvm command options:
52      -cp CLASSPATH, --classpath CLASSPATH        classpath
53      --class CLASSNAME                           name of main class
54      --lib LIB                                   lib to use, default: libart.so
55      --dalvikvm-option [OPT [OPT ...]]           additional dalvikvm option
56      --arg [ARG [ARG ...]]                       argument passed to test
57      --image IMAGE                               path to image
58      --raw-cmd RAW_CMD                           bisect with this command, ignore other command options
59
60    bisection options:
61      --64                                        x64 mode
62      --device                                    run on device
63      --device-serial DEVICE_SERIAL               device serial number, implies --device
64      --expected-output EXPECTED_OUTPUT           file containing expected output
65      --expected-retcode {SUCCESS,TIMEOUT,ERROR}  expected normalized return code
66      --check-script CHECK_SCRIPT                 script comparing output and expected output
67      --logfile LOGFILE                           custom logfile location
68      --cleanup                                   clean up after bisecting
69      --timeout TIMEOUT                           if timeout seconds pass assume test failed
70      --verbose                                   enable verbose output
71