| <html> |
| <title>LLVM: bugpoint tool</title> |
| |
| <body bgcolor=white> |
| |
| <center><h1>LLVM: <tt>bugpoint</tt> tool</h1></center> |
| <HR> |
| |
| <h3>NAME</h3> |
| <tt>bugpoint</tt> |
| |
| <h3>SYNOPSIS</h3> |
| <tt>bugpoint [options] [input llvm ll/bc files] [LLVM passes] --args <program arguments>...</tt> |
| |
| <img src="../Debugging.gif" width=444 height=314 align=right> |
| <h3>DESCRIPTION</h3> |
| |
| The <tt>bugpoint</tt> tool is a generally useful tool for narrowing down |
| problems in LLVM tools and passes. It can be used to debug three types of |
| failures: optimizer crashes, miscompilations by optimizers, or invalid native |
| code generation. It aims to reduce testcases to something useful. For example, |
| if <tt><a href="gccas.html">gccas</a></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> |
| |
| <tt>bugpoint</tt> reads the specified list of <tt>.bc</tt> or <tt>.ll</tt> files |
| specified on the command-line and links them together. If any LLVM passes are |
| specified on the command line, it runs these passes on the resultant module. If |
| any of the passes crash, or if they produce an LLVM module which is not |
| verifiable, <tt>bugpoint</tt> enters <a href="#crashdebug">crash debugging |
| mode</a>.<p> |
| |
| Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not |
| specified, <tt>bugpoint</tt> runs the initial 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 to match, it tries executing the |
| original program with the <a href="#opt_run-">selected</a> code generator. If |
| the resultant output is different than the reference output, it exters <a |
| href="#codegendebug">code generator debugging mode</a>.<p> |
| |
| Otherwise, <tt>bugpoint</tt> runs the LLVM program after all of the LLVM passes |
| have been applied to it. If the executed program matches the reference output, |
| there is no problem <tt>bugpoint</tt> can debug. Otherwise, it enters <a |
| href="#miscompilationdebug">miscompilation debugging mode</a>.<p> |
| |
| <a name="crashdebug"> |
| <h4>Crash debugging mode</h4> |
| |
| If an optimizer crashes, <tt>bugpoint</tt> will try a variety of techniques to |
| narrow down the list of passes and the code to a more manageable amount. First, |
| <tt>bugpoint</tt> figures out which combination of passes trigger the bug. This |
| is useful when debugging a problem exposed by <tt>gccas</tt> for example, |
| because it has over 30 optimization it runs.<p> |
| |
| Next, <tt>bugpoint</tt> tries removing functions from the module, to reduce the |
| size of the testcase to a reasonable amount. Usually it is able to get it down |
| to a single function for 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 absense does |
| not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what |
| passes crash, give you a bytecode file, and give you instructions on how to |
| reproduce the failure with <tt><a href="opt.html">opt</a></tt> or |
| <tt><a href="analyze.html">analyze</a></tt>.<p> |
| |
| <a name="codegendebug"> |
| <h4>Code generator debugging mode</h4> |
| |
| TODO |
| |
| <a name="miscompilationdebug"> |
| <h4>Miscompilation debugging mode</h4> |
| |
| TODO |
| |
| |
| <h3>OPTIONS</h3> |
| |
| <ul> |
| <li><tt>-args <arguments></tt> |
| <br> |
| All arguments specified after <tt>-args</tt> are passed into the |
| executed program when the program must be executed. |
| <p> |
| |
| <li><tt>-disable-(adce,dce,final-cleanup,simplifycfg)</tt> |
| <br> |
| <tt>bugpoint</tt> uses several passes internally for cleanup routines to |
| reduce the size of the program. If you're trying to find a bug in one |
| of these passes, <tt>bugpoint</tt> may crash. These options tell |
| <tt>bugpoint</tt> not use the specified passes. |
| <p> |
| |
| <li> <tt>-help</tt> |
| <br> |
| Print a summary of command line options. |
| <p> |
| |
| <a name="opt_input"><li><tt>-input <filename></tt> |
| <br> |
| Specify the contents of <stdin> when the program must be executed. |
| <p> |
| |
| <li> <tt>-load <plugin.so></tt> |
| <br> |
| Load the dynamic object plugin.so. This object should register new |
| optimization passes. Once loaded, the object will add new command line |
| options to enable various optimizations. To see the new complete list |
| of optimizations, use the -help and -load options together: |
| <p> |
| <tt>opt -load <plugin.so> -help</tt> |
| <p> |
| |
| <a name="opt_output"><li><tt>-output <filename></tt> |
| <br> |
| Specify a reference output for the <stdout> file stream. |
| <p> |
| |
| <a name="opt_run-"><li><tt>-run-(int|jit|llc|cbe)</tt> |
| <br> |
| Specify which code generator <tt>bugpoint</tt> should use to run the |
| program. |
| <p> |
| |
| </ul> |
| |
| <h3>EXIT STATUS</h3> |
| |
| If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0. |
| Otherwise, if an error occurs, it will exit with a non-zero value. |
| |
| <h3>SEE ALSO</h3> |
| <a href="opt.html"><tt>opt</tt></a>, |
| <a href="analyze.html"><tt>analyze</tt></a> |
| |
| <HR> |
| Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>. |
| </body> |
| </html> |
| |