docs/CommandGuide/bugpoint.html

   1 <html>
   2 <title>LLVM: bugpoint tool</title>
   3
   4 <body bgcolor=white>
   5
   6 <center><h1>LLVM: <tt>bugpoint</tt> tool</h1></center>
   7 <HR>
   8
   9 <h3>NAME</h3>
  10 <tt>bugpoint</tt>
  11
  12 <h3>SYNOPSIS</h3>
  13 <tt>bugpoint [options] [input llvm ll/bc files] [LLVM passes] --args &lt;program arguments&gt;...</tt>
  14
  15 <img src="../Debugging.gif" width=444 height=314 align=right>
  16 <h3>DESCRIPTION</h3>
  17
  18 The <tt>bugpoint</tt> tool is a generally useful tool for narrowing down
  19 problems in LLVM tools and passes.  It can be used to debug three types of
  20 failures: optimizer crashes, miscompilations by optimizers, or invalid native
  21 code generation.  It aims to reduce testcases to something useful.  For example,
  22 if <tt><a href="gccas.html">gccas</a></tt> crashes while optimizing a file, it
  23 will identify the optimization (or combination of optimizations) that causes the
  24 crash, and reduce the file down to a small example which triggers the crash.<p>
  25
  26 <tt>bugpoint</tt> reads the specified list of <tt>.bc</tt> or <tt>.ll</tt> files
  27 specified on the command-line and links them together.  If any LLVM passes are
  28 specified on the command line, it runs these passes on the resultant module.  If
  29 any of the passes crash, or if they produce an LLVM module which is not
  30 verifiable, <tt>bugpoint</tt> enters <a href="#crashdebug">crash debugging
  31 mode</a>.<p>
  32
  33 Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
  34 specified, <tt>bugpoint</tt> runs the initial program with the C backend (which
  35 is assumed to generate good code) to generate a reference output.  Once
  36 <tt>bugpoint</tt> has a reference output to match, it tries executing the
  37 original program with the <a href="#opt_run-">selected</a> code generator.  If
  38 the resultant output is different than the reference output, it exters <a
  39 href="#codegendebug">code generator debugging mode</a>.<p>
  40
  41 Otherwise, <tt>bugpoint</tt> runs the LLVM program after all of the LLVM passes
  42 have been applied to it.  If the executed program matches the reference output,
  43 there is no problem <tt>bugpoint</tt> can debug.  Otherwise, it enters <a
  44 href="#miscompilationdebug">miscompilation debugging mode</a>.<p>
  45
  46 <a name="crashdebug">
  47 <h4>Crash debugging mode</h4>
  48
  49 If an optimizer crashes, <tt>bugpoint</tt> will try a variety of techniques to
  50 narrow down the list of passes and the code to a more manageable amount.  First,
  51 <tt>bugpoint</tt> figures out which combination of passes trigger the bug.  This
  52 is useful when debugging a problem exposed by <tt>gccas</tt> for example,
  53 because it has over 30 optimization it runs.<p>
  54
  55 Next, <tt>bugpoint</tt> tries removing functions from the module, to reduce the
  56 size of the testcase to a reasonable amount.  Usually it is able to get it down
  57 to a single function for intraprocedural optimizations.  Once the number of
  58 functions has been reduced, it attempts to delete various edges in the control
  59 flow graph, to reduce the size of the function as much as possible.  Finally,
  60 <tt>bugpoint</tt> deletes any individual LLVM instructions whose absense does
  61 not eliminate the failure.  At the end, <tt>bugpoint</tt> should tell you what
  62 passes crash, give you a bytecode file, and give you instructions on how to
  63 reproduce the failure with <tt><a href="opt.html">opt</a></tt> or
  64 <tt><a href="analyze.html">analyze</a></tt>.<p>
  65
  66 <a name="codegendebug">
  67 <h4>Code generator debugging mode</h4>
  68
  69 TODO
  70
  71 <a name="miscompilationdebug">
  72 <h4>Miscompilation debugging mode</h4>
  73
  74 TODO
  75
  76
  77 <h3>OPTIONS</h3>
  78
  79 <ul>
  80         <li><tt>-args &lt;arguments&gt;</tt>
  81         <br>
  82         All arguments specified after <tt>-args</tt> are passed into the
  83         executed program when the program must be executed.
  84         <p>
  85
  86         <li><tt>-disable-(adce,dce,final-cleanup,simplifycfg)</tt>
  87         <br>
  88         <tt>bugpoint</tt> uses several passes internally for cleanup routines to
  89         reduce the size of the program.  If you're trying to find a bug in one
  90         of these passes, <tt>bugpoint</tt> may crash.  These options tell
  91         <tt>bugpoint</tt> not use the specified passes.
  92         <p>
  93
  94         <li> <tt>-help</tt>
  95         <br>
  96         Print a summary of command line options.
  97         <p>
  98
  99         <a name="opt_input"><li><tt>-input &lt;filename&gt;</tt>
 100         <br>
 101         Specify the contents of &lt;stdin&gt; when the program must be executed.
 102         <p>
 103
 104         <li> <tt>-load &lt;plugin.so&gt;</tt>
 105         <br>
 106         Load the dynamic object plugin.so.  This object should register new
 107         optimization passes.  Once loaded, the object will add new command line
 108         options to enable various optimizations.  To see the new complete list
 109         of optimizations, use the -help and -load options together:
 110         <p>
 111         <tt>opt -load  &lt;plugin.so&gt; -help</tt>
 112         <p>
 113
 114         <a name="opt_output"><li><tt>-output &lt;filename&gt;</tt>
 115         <br>
 116         Specify a reference output for the &lt;stdout&gt; file stream.
 117         <p>
 118
 119         <a name="opt_run-"><li><tt>-run-(int|jit|llc|cbe)</tt>
 120         <br>
 121         Specify which code generator <tt>bugpoint</tt> should use to run the
 122         program.
 123         <p>
 124
 125 </ul>
 126
 127 <h3>EXIT STATUS</h3>
 128
 129 If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0.
 130 Otherwise, if an error occurs, it will exit with a non-zero value.
 131
 132 <h3>SEE ALSO</h3>
 133 <a href="opt.html"><tt>opt</tt></a>,
 134 <a href="analyze.html"><tt>analyze</tt></a>
 135
 136 <HR>
 137 Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>.
 138 </body>
 139 </html>
 140