Automatic optimization bug bisector.

[mono.git] / tools / crash-bisector / README.md

diff --git a/tools/crash-bisector/README.md b/tools/crash-bisector/README.md
new file mode 100644 (file)
index 0000000..96424f5
--- /dev/null
+++ b/tools/crash-bisector/README.md
@@ -0,0 +1,51 @@
+# Crash Bisector
+
+It is often difficult finding a bug in an optimization pass.  The test
+case for which the optimization produces incorrect results or crashes
+the program might have thousands of methods compiled, and the bug
+might only show up in one or a handful of them.  It would be much
+easier if you knew which methods specifically trigger the bug.
+
+This tool automates the search for those methods.  Given some
+reasonable conditions it will find a (locally) minimal set of methods
+for which, if a given optimization is applied to them, a test case
+will fail or crash.
+
+You will need a test case for which Mono either crashes with your
+optimization, or returns a non-zero exit status.  The bisector will
+then run the test case without your optimization, gathering a list of
+all the methods that are compiled.  It will then start bisecting this
+list, applying the optimization to only one half of the methods,
+checking whether the test still fails.
+
+At some point bisecting will either terminate with a single method
+that still makes the test fail, or it will come to a point where a set
+of methods makes the test fail, but either half of that set will not.
+In that case it will start trying to remove smaller subsets of
+methods, until at some point no single method can be removed anymore,
+i.e., all the methods in the set must be optimized for the test to
+fail.
+
+## Usage
+
+You run it like so:
+
+    mono crash-bisector.exe --mono ../mini/mono-sgen --opt free-regions -- generics-sharing.2.exe
+
+Here the optimization is `free-regions` and the test case is
+`generics-sharing.2.exe`.
+
+Note that if the optimization you're debugging is turned on by default
+you'll have to pass a `-O` option to Mono to turn it off, like so:
+
+    mono crash-bisector.exe --mono ../mini/mono-sgen --opt intrins -- -O=-intrins generics-sharing.2.exe
+
+## Assumptions
+
+The bisector assumes that each run of your test case compiles the same
+methods, and that applying your optimization to some of them doesn't
+change which methods are compiled.
+
+The test case is assumed to succeed or fail deterministically.
+
+The optimization bug must also be deterministic.