diff options
Diffstat (limited to 'docs/Bugpoint.html')
| -rw-r--r-- | docs/Bugpoint.html | 250 |
1 files changed, 250 insertions, 0 deletions
diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html new file mode 100644 index 0000000000..bf75b5ba44 --- /dev/null +++ b/docs/Bugpoint.html @@ -0,0 +1,250 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>LLVM bugpoint tool: design and usage</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> + +<div class="doc_title"> + LLVM bugpoint tool: design and usage +</div> + +<ul> + <li><a href="#desc">Description</a></li> + <li><a href="#design">Design Philosophy</a> + <ul> + <li><a href="#autoselect">Automatic Debugger Selection</a></li> + <li><a href="#crashdebug">Crash debugger</a></li> + <li><a href="#codegendebug">Code generator debugger</a></li> + <li><a href="#miscompilationdebug">Miscompilation debugger</a></li> + </ul></li> + <li><a href="#advice">Advice for using <tt>bugpoint</tt></a></li> +</ul> + +<div class="doc_author"> +<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p> +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> +<a name="desc">Description</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p><tt>bugpoint</tt> narrows down the source of problems in LLVM tools and +passes. It can be used to debug three types of failures: optimizer crashes, +miscompilations by optimizers, or bad native code generation (including problems +in the static and JIT compilers). It aims to reduce large test cases to small, +useful ones. For example, if <tt>opt</tt> crashes while optimizing a +file, it will identify the optimization (or combination of optimizations) that +causes the crash, and reduce the file down to a small example which triggers the +crash.</p> + +<p>For detailed case scenarios, such as debugging <tt>opt</tt>, +<tt>llvm-ld</tt>, or one of the LLVM code generators, see <a +href="HowToSubmitABug.html">How To Submit a Bug Report document</a>.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> +<a name="design">Design Philosophy</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p><tt>bugpoint</tt> is designed to be a useful tool without requiring any +hooks into the LLVM infrastructure at all. It works with any and all LLVM +passes and code generators, and does not need to "know" how they work. Because +of this, it may appear to do stupid things or miss obvious +simplifications. <tt>bugpoint</tt> is also designed to trade off programmer +time for computer time in the compiler-debugging process; consequently, it may +take a long period of (unattended) time to reduce a test case, but we feel it +is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless +debugging a miscompilation where each test of the program (which requires +executing it) takes a long time.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="autoselect">Automatic Debugger Selection</a> +</div> + +<div class="doc_text"> + +<p><tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file specified on +the command line and links them together into a single module, called the test +program. If any LLVM passes are specified on the command line, it runs these +passes on the test program. If any of the passes crash, or if they produce +malformed output (which causes the verifier to abort), <tt>bugpoint</tt> starts +the <a href="#crashdebug">crash debugger</a>.</p> + +<p>Otherwise, if the <tt>-output</tt> option was not specified, +<tt>bugpoint</tt> runs the test program with the C backend (which is assumed to +generate good code) to generate a reference output. Once <tt>bugpoint</tt> has +a reference output for the test program, it tries executing it with the +selected code generator. If the selected code generator crashes, +<tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a> on the +code generator. Otherwise, if the resulting output differs from the reference +output, it assumes the difference resulted from a code generator failure, and +starts the <a href="#codegendebug">code generator debugger</a>.</p> + +<p>Finally, if the output of the selected code generator matches the reference +output, <tt>bugpoint</tt> runs the test program after all of the LLVM passes +have been applied to it. If its output differs from the reference output, it +assumes the difference resulted from a failure in one of the LLVM passes, and +enters the <a href="#miscompilationdebug">miscompilation debugger</a>. +Otherwise, there is no problem <tt>bugpoint</tt> can debug.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="crashdebug">Crash debugger</a> +</div> + +<div class="doc_text"> + +<p>If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard +as it can to reduce the list of passes (for optimizer crashes) and the size of +the test program. First, <tt>bugpoint</tt> figures out which combination of +optimizer passes triggers the bug. This is useful when debugging a problem +exposed by <tt>opt</tt>, for example, because it runs over 38 passes.</p> + +<p>Next, <tt>bugpoint</tt> tries removing functions from the test program, to +reduce its size. Usually it is able to reduce a test program to a single +function, when debugging intraprocedural optimizations. Once the number of +functions has been reduced, it attempts to delete various edges in the control +flow graph, to reduce the size of the function as much as possible. Finally, +<tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does +not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what +passes crash, give you a bitcode file, and give you instructions on how to +reproduce the failure with <tt>opt</tt> or <tt>llc</tt>.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="codegendebug">Code generator debugger</a> +</div> + +<div class="doc_text"> + +<p>The code generator debugger attempts to narrow down the amount of code that +is being miscompiled by the selected code generator. To do this, it takes the +test program and partitions it into two pieces: one piece which it compiles +with the C backend (into a shared object), and one piece which it runs with +either the JIT or the static LLC compiler. It uses several techniques to +reduce the amount of code pushed through the LLVM code generator, to reduce the +potential scope of the problem. After it is finished, it emits two bitcode +files (called "test" [to be compiled with the code generator] and "safe" [to be +compiled with the C backend], respectively), and instructions for reproducing +the problem. The code generator debugger assumes that the C backend produces +good code.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="miscompilationdebug">Miscompilation debugger</a> +</div> + +<div class="doc_text"> + +<p>The miscompilation debugger works similarly to the code generator debugger. +It works by splitting the test program into two pieces, running the +optimizations specified on one piece, linking the two pieces back together, and +then executing the result. It attempts to narrow down the list of passes to +the one (or few) which are causing the miscompilation, then reduce the portion +of the test program which is being miscompiled. The miscompilation debugger +assumes that the selected code generator is working properly.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="advice">Advice for using bugpoint</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in +non-obvious ways. Here are some hints and tips:<p> + +<ol> +<li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only + works with programs that have deterministic output. Thus, if the program + outputs <tt>argv[0]</tt>, the date, time, or any other "random" data, + <tt>bugpoint</tt> may misinterpret differences in these data, when output, + as the result of a miscompilation. Programs should be temporarily modified + to disable outputs that are likely to vary from run to run. + +<li>In the code generator and miscompilation debuggers, debugging will go + faster if you manually modify the program or its inputs to reduce the + runtime, but still exhibit the problem. + +<li><tt>bugpoint</tt> is extremely useful when working on a new optimization: + it helps track down regressions quickly. To avoid having to relink + <tt>bugpoint</tt> every time you change your optimization however, have + <tt>bugpoint</tt> dynamically load your optimization with the + <tt>-load</tt> option. + +<li><p><tt>bugpoint</tt> can generate a lot of output and run for a long period + of time. It is often useful to capture the output of the program to file. + For example, in the C shell, you can run:</p> + +<div class="doc_code"> +<p><tt>bugpoint ... |& tee bugpoint.log</tt></p> +</div> + + <p>to get a copy of <tt>bugpoint</tt>'s output in the file + <tt>bugpoint.log</tt>, as well as on your terminal.</p> + +<li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If + <tt>bugpoint</tt> crashes before you see its "All input ok" message, + you might try <tt>llvm-link -v</tt> on the same set of input files. If + that also crashes, you may be experiencing a linker bug. + +<li><tt>bugpoint</tt> is useful for proactively finding bugs in LLVM. + Invoking <tt>bugpoint</tt> with the <tt>-find-bugs</tt> option will cause + the list of specified optimizations to be randomized and applied to the + program. This process will repeat until a bug is found or the user + kills <tt>bugpoint</tt>. + +<li><p><tt>bugpoint</tt> does not understand the <tt>-O</tt> option + that is used to specify optimization level to <tt>opt</tt>. You + can use e.g.</p> + +<div class="doc_code"> +<p><tt>opt -O2 -debug-pass=Arguments foo.bc -disable-output</tt></p> +</div> + + <p>to get a list of passes that are used with <tt>-O2</tt> and + then pass this list to <tt>bugpoint</tt>.</p> + +</ol> + +</div> + +<!-- *********************************************************************** --> + +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> + + <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> + <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br> + Last modified: $Date$ +</address> + +</body> +</html> |