docs/Bugpoint.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   5   <title>LLVM: bugpoint tool</title>
   6   <link rel="stylesheet" href="llvm.css" type="text/css">
   7   <meta name="author" content="Chris Lattner">
   8   <meta name="description"
   9   content="A tool for automatic test case reduction">
  10 </head>
  11 <html>
  12
  13 <body>
  14 <center><h1>LLVM: <tt>bugpoint</tt> tool</h1></center>
  15 <HR>
  16
  17 <h3>NAME</h3>
  18 <tt>bugpoint</tt>
  19
  20 <h3>SYNOPSIS</h3>
  21 <tt>bugpoint [options] [input LLVM ll/bc files] [LLVM passes] --args &lt;program arguments&gt;...</tt>
  22
  23 <img src="img/Debugging.gif" width=444 height=314 align=right>
  24 <h3>DESCRIPTION</h3>
  25
  26 The <tt>bugpoint</tt> tool narrows down the source of
  27 problems in LLVM tools and passes.  It can be used to debug three types of
  28 failures: optimizer crashes, miscompilations by optimizers, or bad native
  29 code generation (including problems in the static and JIT compilers).  It aims
  30 to reduce large test cases to small, useful ones.  For example,
  31 if <tt><a href="CommandGuide/html/gccas.html">gccas</a></tt> crashes while optimizing a file, it
  32 will identify the optimization (or combination of optimizations) that causes the
  33 crash, and reduce the file down to a small example which triggers the crash.<p>
  34
  35 <a name="designphilosophy">
  36 <h4>Design Philosophy</h4>
  37
  38 <tt>bugpoint</tt> is designed to be a useful tool without requiring any
  39 hooks into the LLVM infrastructure at all.  It works with any and all LLVM
  40 passes and code generators, and does not need to "know" how they work.  Because
  41 of this, it may appear to do stupid things or miss obvious
  42 simplifications.  <tt>bugpoint</tt> is also designed to trade off programmer
  43 time for computer time in the compiler-debugging process; consequently, it may
  44 take a long period of (unattended) time to reduce a test case, but we feel it
  45 is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless
  46 debugging a miscompilation where each test of the program (which requires
  47 executing it) takes a long time.<p>
  48
  49 <a name="automaticdebuggerselection">
  50 <h4>Automatic Debugger Selection</h4>
  51
  52 <tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file
  53 specified on the command line and links them together into a single module,
  54 called the test program.  If any LLVM passes are
  55 specified on the command line, it runs these passes on the test program.  If
  56 any of the passes crash, or if they produce malformed output (which causes the
  57 verifier to abort),
  58 <tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a>.<p>
  59
  60 Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
  61 specified, <tt>bugpoint</tt> runs the test program with the C backend (which is
  62 assumed to generate good code) to generate a reference output.  Once
  63 <tt>bugpoint</tt> has a reference output for the test program, it tries
  64 executing it with the <a href="#opt_run-">selected</a> code generator.  If the
  65 selected code generator crashes, <tt>bugpoint</tt> starts the <a
  66 href="#crashdebug">crash debugger</a> on the code generator.  Otherwise, if the
  67 resulting output differs from the reference output, it assumes the difference
  68 resulted from a code generator failure, and starts the <a
  69 href="#codegendebug">code generator debugger</a>.<p>
  70
  71 Finally, if the output of the selected code generator matches the reference
  72 output, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
  73 have been applied to it.  If its output differs from the reference output, it
  74 assumes the difference resulted from a failure in one of the LLVM passes, and
  75 enters the <a href="#miscompilationdebug">miscompilation
  76 debugger</a>. Otherwise, there is no problem <tt>bugpoint</tt> can debug.<p>
  77
  78 <a name="crashdebug">
  79 <h4>Crash debugger</h4>
  80
  81 If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard as
  82 it can to reduce the list of passes (for optimizer crashes) and the size of the
  83 test program.  First, <tt>bugpoint</tt> figures out which combination of
  84 optimizer passes triggers the bug. This is useful when debugging a problem
  85 exposed by <tt>gccas</tt>, for example, because it runs over 38 passes.<p>
  86
  87 Next, <tt>bugpoint</tt> tries removing functions from the test program, to
  88 reduce its size.  Usually it is able to reduce a test program to a single
  89 function, when debugging intraprocedural optimizations.  Once the number of
  90 functions has been reduced, it attempts to delete various edges in the control
  91 flow graph, to reduce the size of the function as much as possible.  Finally,
  92 <tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
  93 not eliminate the failure.  At the end, <tt>bugpoint</tt> should tell you what
  94 passes crash, give you a bytecode file, and give you instructions on how to
  95 reproduce the failure with <tt><a href="CommandGuide/html/opt.html">opt</a></tt>, <tt><a
  96 href="CommandGuide/html/analyze.html">analyze</a></tt>, or <tt><a href="CommandGuide/html/llc.html">llc</a></tt>.<p>
  97
  98 <a name="codegendebug">
  99 <h4>Code generator debugger</h4>
 100
 101 <p>The code generator debugger attempts to narrow down the amount of code that
 102 is being miscompiled by the <a href="#opt_run-">selected</a> code generator.  To
 103 do this, it takes the test program and partitions it into two pieces: one piece
 104 which it compiles with the C backend (into a shared object), and one piece which
 105 it runs with either the JIT or the static LLC compiler.  It uses several
 106 techniques to reduce the amount of code pushed through the LLVM code generator,
 107 to reduce the potential scope of the problem.  After it is finished, it emits
 108 two bytecode files (called "test" [to be compiled with the code generator] and
 109 "safe" [to be compiled with the C backend], respectively), and instructions for
 110 reproducing the problem.  The code generator debugger assumes that the C backend
 111 produces good code.</p>
 112
 113 <a name="miscompilationdebug">
 114 <h4>Miscompilation debugger</h4>
 115
 116 The miscompilation debugger works similarly to the code generator
 117 debugger.  It works by splitting the test program into two pieces, running the
 118 optimizations specified on one piece, linking the two pieces back together,
 119 and then executing the result.
 120 It attempts to narrow down the list of passes to the one (or few) which are
 121 causing the miscompilation, then reduce the portion of the test program which is
 122 being miscompiled.  The miscompilation debugger assumes that the selected
 123 code generator is working properly.<p>
 124
 125 <a name="bugpoint notes">
 126 <h4>Advice for using <tt>bugpoint</tt></h4>
 127
 128 <tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
 129 non-obvious ways.  Here are some hints and tips:<p>
 130
 131 <ol>
 132 <li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
 133     works with programs that have deterministic output.  Thus, if the program
 134     outputs <tt>argv[0]</tt>, the date, time, or any other "random" data, <tt>bugpoint</tt> may
 135     misinterpret differences in these data, when output, as the result of a
 136     miscompilation.  Programs should be temporarily modified to disable
 137     outputs that are likely to vary from run to run.
 138
 139 <li>In the code generator and miscompilation debuggers, debugging will go
 140     faster if you manually modify the program or its inputs to reduce the
 141     runtime, but still exhibit the problem.
 142
 143 <li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
 144     it helps track down regressions quickly.  To avoid having to relink
 145     <tt>bugpoint</tt> every time you change your optimization however, have
 146     <tt>bugpoint</tt> dynamically load your optimization with the <a
 147     href="#opt_load"><tt>-load</tt></a> option.
 148
 149 <li><tt>bugpoint</tt> can generate a lot of output and run for a long period of
 150     time.  It is often useful to capture the output of the program to file.  For
 151     example, in the C shell, you can type:<br>
 152     <tt>bugpoint  ..... |&amp; tee bugpoint.log</tt>
 153     <br>to get a copy of <tt>bugpoint</tt>'s output in the file
 154     <tt>bugpoint.log</tt>, as well as on your terminal.
 155
 156 <li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If
 157     <tt>bugpoint</tt> crashes before you see its "All input ok" message,
 158     you might try <tt>llvm-link -v</tt> on the same set of input files. If
 159     that also crashes, you may be experiencing a linker bug.
 160
 161 <li>If your program is <b>supposed</b> to crash, <tt>bugpoint</tt> will be
 162     confused. One way to deal with this is to cause bugpoint to ignore the exit
 163     code from your program, by giving it the <tt>-check-exit-code=false</tt>
 164     option.
 165
 166 </ol>
 167
 168 <h3>OPTIONS</h3>
 169
 170 <ul>
 171         <li><tt>-additional-so &lt;library&gt;</tt><br>
 172     Load <tt>&lt;library&gt;</tt> into the test program whenever it is run.
 173     This is useful if you are debugging programs which depend on non-LLVM
 174     libraries (such as the X or curses libraries) to run.<p>
 175
 176         <li><tt>-args &lt;program args&gt;</tt><br>
 177         Pass all arguments specified after <tt>-args</tt> to the
 178         test program whenever it runs.  Note that if any of
 179         the <tt>&lt;program args&gt;</tt> start with a '-', you should use:
 180         <p>
 181         <tt>bugpoint &lt;bugpoint args&gt; -args -- &lt;program args&gt;</tt>
 182         <p>
 183         The "<tt>--</tt>" right after the <tt>-args</tt> option tells
 184         <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
 185         part of the <tt>-args</tt> option, not as options to <tt>bugpoint</tt>
 186         itself.<p>
 187
 188         <li><tt>-tool-args &lt;tool args&gt;</tt><br>
 189         Pass all arguments specified after <tt>-tool-args</tt> to the
 190         LLVM tool under test (llc, lli, etc.) whenever it runs.
 191         You should use this option in the following way:
 192         <p>
 193         <tt>bugpoint &lt;bugpoint args&gt; -tool-args -- &lt;tool args&gt;</tt>
 194         <p>
 195         The "<tt>--</tt>" right after the <tt>-tool-args</tt> option tells
 196         <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
 197         part of the <tt>-tool-args</tt> option, not as options to
 198         <tt>bugpoint</tt> itself. (See <tt>-args</tt>, above.)<p>
 199
 200         <li><tt>-check-exit-code={true,false}</tt><br>
 201     Assume a non-zero exit code or core dump from the test program is
 202     a failure. Defaults to true.<p>
 203
 204         <li><tt>-disable-{dce,simplifycfg}</tt><br>
 205     Do not run the specified passes to clean up and reduce the size of the
 206     test program. By default, <tt>bugpoint</tt> uses these passes internally
 207     when attempting to reduce test programs.  If you're trying to find
 208     a bug in one of these passes, <tt>bugpoint</tt> may crash.<p>
 209
 210         <li> <tt>-help</tt><br>
 211         Print a summary of command line options.<p>
 212
 213         <a name="opt_input"><li><tt>-input &lt;filename&gt;</tt><br>
 214         Open <tt>&lt;filename&gt;</tt> and redirect the standard input of the
 215     test program, whenever it runs, to come from that file.
 216         <p>
 217
 218         <a name="opt_load"><li> <tt>-load &lt;plugin&gt;</tt><br>
 219         Load the dynamic object <tt>&lt;plugin&gt;</tt> into <tt>bugpoint</tt>
 220     itself.  This object should register new
 221         optimization passes.  Once loaded, the object will add new command line
 222         options to enable various optimizations.  To see the new complete list
 223         of optimizations, use the -help and -load options together:
 224         <p>
 225         <tt>bugpoint -load &lt;plugin&gt; -help</tt>
 226         <p>
 227
 228         <a name="opt_output"><li><tt>-output &lt;filename&gt;</tt><br>
 229     Whenever the test program produces output on its standard output
 230     stream, it should match the contents of <tt>&lt;filename&gt;</tt>
 231     (the "reference output"). If you do not use this option,
 232     <tt>bugpoint</tt> will attempt to generate a reference output by
 233     compiling the program with the C backend and running it.<p>
 234
 235         <li><tt>-profile-info-file &lt;filename&gt;</tt><br>
 236     Profile file loaded by -profile-loader.<p>
 237
 238         <a name="opt_run-"><li><tt>-run-{int,jit,llc,cbe}</tt><br>
 239     Whenever the test program is compiled, <tt>bugpoint</tt> should generate
 240     code for it using the specified code generator.  These options allow
 241     you to choose the interpreter, the JIT compiler, the static native
 242     code compiler, or the C backend, respectively.<p>
 243 </ul>
 244
 245 <h3>EXIT STATUS</h3>
 246
 247 If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0.
 248 Otherwise, if an error occurs, it will exit with a non-zero value.
 249
 250 <HR>
 251 Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>.
 252 </body>
 253 </html>