tools/crash-bisector/README.md

   1 # Crash Bisector
   2
   3 It is often difficult finding a bug in an optimization pass.  The test
   4 case for which the optimization produces incorrect results or crashes
   5 the program might have thousands of methods compiled, and the bug
   6 might only show up in one or a handful of them.  It would be much
   7 easier if you knew which methods specifically trigger the bug.
   8
   9 This tool automates the search for those methods.  Given some
  10 reasonable conditions it will find a (locally) minimal set of methods
  11 for which, if a given optimization is applied to them, a test case
  12 will fail or crash.
  13
  14 You will need a test case for which Mono either crashes with your
  15 optimization, or returns a non-zero exit status.  The bisector will
  16 then run the test case without your optimization, gathering a list of
  17 all the methods that are compiled.  It will then start bisecting this
  18 list, applying the optimization to only one half of the methods,
  19 checking whether the test still fails.
  20
  21 At some point bisecting will either terminate with a single method
  22 that still makes the test fail, or it will come to a point where a set
  23 of methods makes the test fail, but either half of that set will not.
  24 In that case it will start trying to remove smaller subsets of
  25 methods, until at some point no single method can be removed anymore,
  26 i.e., all the methods in the set must be optimized for the test to
  27 fail.
  28
  29 ## Usage
  30
  31 You run it like so:
  32
  33     mono crash-bisector.exe --mono ../mini/mono-sgen --opt free-regions -- generics-sharing.2.exe
  34
  35 Here the optimization is `free-regions` and the test case is
  36 `generics-sharing.2.exe`.
  37
  38 Note that if the optimization you're debugging is turned on by default
  39 you'll have to pass a `-O` option to Mono to turn it off, like so:
  40
  41     mono crash-bisector.exe --mono ../mini/mono-sgen --opt intrins -- -O=-intrins generics-sharing.2.exe
  42
  43 ## Assumptions
  44
  45 The bisector assumes that each run of your test case compiles the same
  46 methods, and that applying your optimization to some of them doesn't
  47 change which methods are compiled.
  48
  49 The test case is assumed to succeed or fail deterministically.
  50
  51 The optimization bug must also be deterministic.