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 narrows down the source of
  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 large test cases to small, useful ones.
  22 For example,
  23 if <tt><a href="gccas.html">gccas</a></tt> crashes while optimizing a file, it
  24 will identify the optimization (or combination of optimizations) that causes the
  25 crash, and reduce the file down to a small example which triggers the crash.<p>
  26
  27 <a name="designphilosophy">
  28 <h4>Design Philosophy</h4>
  29
  30 <tt>bugpoint</tt> is designed to be a useful tool without requiring any
  31 hooks into the LLVM infrastructure at all.  It works with any and all LLVM
  32 passes and code generators, and does not need to "know" how they work.  Because
  33 of this, it may appear to do a lot of stupid things or miss obvious
  34 simplifications.  <tt>bugpoint</tt> is also designed to trade off programmer
  35 time for computer time in the compiler-debugging process; consequently, it may
  36 take a long period of (unattended) time to reduce a test case, but we feel it
  37 is still worth it. :-) <p>
  38
  39 <a name="automaticmodeselection">
  40 <h4>Automatic Mode Selection</h4>
  41
  42 <tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file
  43 specified on the command line and links them together into a single module,
  44 called the test program.  If any LLVM passes are
  45 specified on the command line, it runs these passes on the test program.  If
  46 any of the passes crash, or if they produce a malformed LLVM module,
  47 <tt>bugpoint</tt> enters <a href="#crashdebug">crash debugging mode</a>.<p>
  48
  49 Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
  50 specified, <tt>bugpoint</tt> runs the test program with the C backend (which
  51 is assumed to generate good code) to generate a reference output.  Once
  52 <tt>bugpoint</tt> has a reference output for the test program, it tries
  53 executing it
  54 with the <a href="#opt_run-">selected</a> code generator.  If
  55 the resulting output differs from the reference output, it assumes the
  56 difference resulted from a code generator failure, and enters
  57 <a href="#codegendebug">code generator debugging mode</a>.<p>
  58
  59 Otherwise, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
  60 have been applied to it.  If its output differs from the reference output,
  61 it assumes the difference resulted from a failure in one of the LLVM passes,
  62 and enters
  63 <a href="#miscompilationdebug">miscompilation debugging mode</a>. Otherwise,
  64 there is no problem <tt>bugpoint</tt> can debug.<p>
  65
  66 <a name="crashdebug">
  67 <h4>Crash debugging mode</h4>
  68
  69 If an optimizer crashes, <tt>bugpoint</tt> will try as hard as it can to
  70 reduce the list of passes and the size of the test program.  First,
  71 <tt>bugpoint</tt> figures out which combination of passes triggers the bug. This
  72 is useful when debugging a problem exposed by <tt>gccas</tt>, for example,
  73 because it runs over 25 optimizations.<p>
  74
  75 Next, <tt>bugpoint</tt> tries removing functions from the module, to reduce the
  76 size of the test program.  Usually it is able to reduce a test program
  77 to a single function, when debugging intraprocedural optimizations.  Once the
  78 number of
  79 functions has been reduced, it attempts to delete various edges in the control
  80 flow graph, to reduce the size of the function as much as possible.  Finally,
  81 <tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
  82 not eliminate the failure.  At the end, <tt>bugpoint</tt> should tell you what
  83 passes crash, give you a bytecode file, and give you instructions on how to
  84 reproduce the failure with <tt><a href="opt.html">opt</a></tt> or
  85 <tt><a href="analyze.html">analyze</a></tt>.<p>
  86
  87 <a name="codegendebug">
  88 <h4>Code generator debugging mode</h4>
  89
  90 The code generator debugger attempts to narrow down the amount of code that is
  91 being miscompiled by the <a href="#opt_run-">selected</a> code generator.  To do
  92 this, it takes the LLVM program and partitions it into two pieces: one piece
  93 which it compiles with the C backend (into a shared object), and one piece which
  94 it runs with either the JIT or the static LLC compiler.  It uses several
  95 techniques to reduce the amount of code pushed through the LLVM code generator,
  96 to reduce the potential scope of the problem.  After it is finished, it emits
  97 two bytecode files (the "test" [to be compiled with the code generator] and
  98 "safe" [to be compiled with the C backend] modules), and instructions for
  99 reproducing the problem.  This module assume the C backend produces good
 100 code.<p>
 101
 102 If you are using this mode and get an error message that says "Non-instruction
 103 is using an external function!", try using the <tt>-run-llc</tt> option instead
 104 of the <tt>-run-jit</tt> option.  This is due to an unimplemented feature in the
 105 code generator debugging mode.<p>
 106
 107 <a name="miscompilationdebug">
 108 <h4>Miscompilation debugging mode</h4>
 109
 110 The miscompilation debugging mode works similarly to the code generator
 111 debugging mode.  It works by splitting the program into two pieces, running the
 112 optimizations specified on one piece, relinking the program, then executing it.
 113 It attempts to narrow down the list of passes to the one (or few) which are
 114 causing the miscompilation, then reduce the portion of the program which is
 115 being miscompiled.  This module assumes that the selected code generator is
 116 working properly.<p>
 117
 118
 119 <a name="bugpoint notes">
 120 <h4>Advice for using <tt>bugpoint</tt></h4>
 121
 122 <tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
 123 non-obvious ways.  Here are some hints and tips:<p>
 124
 125 <ol>
 126 <li>In code generator and miscompilation debugging modes, <tt>bugpoint</tt> only
 127     works with programs that have deterministic output.  Thus, if the program
 128     outputs the date, time, or any other "random" data, <tt>bugpoint</tt> may
 129     misinterpret differences in these data, when output, as the result of a
 130     miscompilation.  Programs should be temporarily modified to disable
 131     outputs that are likely to vary from run to run.
 132
 133 <li>In code generator and miscompilation debugging modes, debugging will go
 134     faster if you manually modify the program or its inputs to reduce the
 135     runtime, but still exhibit the problem.
 136
 137 <li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
 138     it helps track down regressions quickly.  To avoid having to relink
 139     <tt>bugpoint</tt> every time you change your optimization however, have
 140     <tt>bugpoint</tt> dynamically load your optimization with the <a
 141     href="#opt_load"><tt>-load</tt></a> option.
 142
 143 <li><tt>bugpoint</tt> can generate a lot of output and run for a long period of
 144     time.  It is often useful to capture the output of the program to file.  For
 145     example, in the C shell, you can type:<br>
 146     <tt>bugpoint  ..... |& tee bugpoint.log</tt>
 147     <br>to get a copy of <tt>bugpoint</tt>'s output in the file
 148     <tt>bugpoint.log</tt>, as well as on your terminal.<p>
 149
 150 </ol>
 151
 152
 153 <h3>OPTIONS</h3>
 154
 155 <ul>
 156         <li><tt>-additional-so &lt;library.so&gt;</tt><br>
 157     Load <tt>&lt;library.so&gt;</tt> into the test program whenever it is run.
 158     This is useful if you are debugging programs which depend on non-LLVM
 159     libraries (such as the X or curses libraries) to run.<p>
 160
 161         <li><tt>-args &lt;program args&gt;</tt><br>
 162         Pass all arguments specified after <tt>-args</tt> to the
 163         test program whenever it runs.  Note that if any of
 164         the <tt>&lt;program args&gt;</tt> start with a '-', you should use:
 165         <p>
 166         <tt>bugpoint &lt;bugpoint args&gt; -args -- &lt;program args&gt;</tt>
 167         <p>
 168         The "<tt>--</tt>" right after the <tt>-args</tt> option tells
 169         <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
 170         part of the <tt>-args</tt> option, not as options to <tt>bugpoint</tt>
 171         itself.<p>
 172
 173         <li><tt>-disable-{adce,dce,final-cleanup,simplifycfg}</tt><br>
 174     Do not run the specified passes to clean up and reduce the size of the
 175     test program. By default, <tt>bugpoint</tt> uses these passes internally
 176     when attempting to reduce test programs.  If you're trying to find
 177     a bug in one of these passes, <tt>bugpoint</tt> may crash.<p>
 178
 179         <li> <tt>-help</tt><br>
 180         Print a summary of command line options.<p>
 181
 182         <a name="opt_input"><li><tt>-input &lt;filename&gt;</tt><br>
 183         Open <tt>&lt;filename&gt;</tt> and redirect the standard input of the
 184     test program, whenever it runs, to come from that file.
 185         <p>
 186
 187         <a name="opt_load"><li> <tt>-load &lt;plugin.so&gt;</tt><br>
 188         Load the dynamic object <tt>&lt;plugin.so&gt;</tt> into <tt>bugpoint</tt>
 189     itself.  This object should register new
 190         optimization passes.  Once loaded, the object will add new command line
 191         options to enable various optimizations.  To see the new complete list
 192         of optimizations, use the -help and -load options together:
 193         <p>
 194         <tt>bugpoint -load &lt;plugin.so&gt; -help</tt>
 195         <p>
 196
 197         <a name="opt_output"><li><tt>-output &lt;filename&gt;</tt><br>
 198     Whenever the test program produces output on its standard output
 199     stream, it should match the contents of <tt>&lt;filename&gt;</tt>
 200     (the "reference output"). If you do not use this option,
 201     <tt>bugpoint</tt> will attempt to generate a reference output by
 202     compiling the program with the C backend and running it.<p>
 203
 204         <a name="opt_run-"><li><tt>-run-{int|jit|llc|cbe}</tt><br>
 205     Whenever the test program is compiled, <tt>bugpoint</tt> should generate
 206     code for it using the specified code generator.  These options allow
 207     you to choose the interpreter, the JIT compiler, the static native
 208     code compiler, or the C backend, respectively.<p>
 209 </ul>
 210
 211 <h3>EXIT STATUS</h3>
 212
 213 If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0.
 214 Otherwise, if an error occurs, it will exit with a non-zero value.
 215
 216 <h3>SEE ALSO</h3>
 217 <a href="opt.html"><tt>opt</tt></a>,
 218 <a href="analyze.html"><tt>analyze</tt></a>
 219
 220 <HR>
 221 Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>.
 222 </body>
 223 </html>