v811_spc009/art/tools/bisection_search/README.md

Bisection Bug Search

Bisection Bug Search is a tool for finding compiler optimizations bugs. It accepts a program which exposes a bug by producing incorrect output and expected output for the program. It then attempts to narrow down the issue to a single method and optimization pass under the assumption that interpreter is correct.

Given methods in order M0..Mn finds smallest i such that compiling Mi and interpreting all other methods produces incorrect output. Then, given ordered optimization passes P0..Pl, finds smallest j such that compiling Mi with passes P0..Pj-1 produces expected output and compiling Mi with passes P0..Pj produces incorrect output. Prints Mi and Pj.

How to run Bisection Bug Search

There are two supported invocation modes:

1. Regular invocation, dalvikvm command is constructed internally:

    ./bisection_search.py -cp classes.dex --expected-output out_int --class Test
   

2. Raw-cmd invocation, dalvikvm command is accepted as an argument.

   Extra dalvikvm arguments will be placed on second position in the command by default. {ARGS} tag can be used to specify a custom position.

   If used in device mode, the command has to exec a dalvikvm instance. Bisection will fail if pid of the process started by raw-cmd is different than pid of runtime.

    ./bisection_search.py --raw-cmd='run.sh -cp classes.dex Test' --expected-retcode SUCCESS
    ./bisection_search.py --raw-cmd='/bin/sh art {ARGS} -cp classes.dex Test' --expected-retcode SUCCESS
   

Help:

bisection_search.py [-h] [-cp CLASSPATH] [--class CLASSNAME] [--lib LIB]
                         [--dalvikvm-option [OPT [OPT ...]]] [--arg [ARG [ARG ...]]]
                         [--image IMAGE] [--raw-cmd RAW_CMD]
                         [--64] [--device] [--device-serial DEVICE_SERIAL]
                         [--expected-output EXPECTED_OUTPUT]
                         [--expected-retcode {SUCCESS,TIMEOUT,ERROR}]
                         [--check-script CHECK_SCRIPT] [--logfile LOGFILE] [--cleanup]
                         [--timeout TIMEOUT] [--verbose]

Tool for finding compiler bugs. Either --raw-cmd or both -cp and --class are required.

optional arguments:
  -h, --help                                  show this help message and exit

dalvikvm command options:
  -cp CLASSPATH, --classpath CLASSPATH        classpath
  --class CLASSNAME                           name of main class
  --lib LIB                                   lib to use, default: libart.so
  --dalvikvm-option [OPT [OPT ...]]           additional dalvikvm option
  --arg [ARG [ARG ...]]                       argument passed to test
  --image IMAGE                               path to image
  --raw-cmd RAW_CMD                           bisect with this command, ignore other command options

bisection options:
  --64                                        x64 mode
  --device                                    run on device
  --device-serial DEVICE_SERIAL               device serial number, implies --device
  --expected-output EXPECTED_OUTPUT           file containing expected output
  --expected-retcode {SUCCESS,TIMEOUT,ERROR}  expected normalized return code
  --check-script CHECK_SCRIPT                 script comparing output and expected output
  --logfile LOGFILE                           custom logfile location
  --cleanup                                   clean up after bisecting
  --timeout TIMEOUT                           if timeout seconds pass assume test failed
  --verbose                                   enable verbose output