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