README.md
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