[llvm-commits] CVS: llvm/docs/Bugpoint.html
Brian Gaeke
gaeke at cs.uiuc.edu
Thu Jul 1 15:12:05 PDT 2004
Changes in directory llvm/docs:
Bugpoint.html added (r1.1)
---
Log message:
bugpoint command guide has been designated a full-fledged "doc".
---
Diffs of the changes: (+249 -0)
Index: llvm/docs/Bugpoint.html
diff -c /dev/null llvm/docs/Bugpoint.html:1.1
*** /dev/null Thu Jul 1 15:10:50 2004
--- llvm/docs/Bugpoint.html Thu Jul 1 15:10:40 2004
***************
*** 0 ****
--- 1,249 ----
+ <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="../img/Debugging.gif" width=444 height=314 align=right>
+ <h3>DESCRIPTION</h3>
+
+ The <tt>bugpoint</tt> tool narrows down the source of
+ problems in LLVM tools and passes. It can be used to debug three types of
+ failures: optimizer crashes, miscompilations by optimizers, or bad native
+ code generation (including problems in the static and JIT compilers). It aims
+ to reduce large test cases to small, useful ones. 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>
+
+ <a name="designphilosophy">
+ <h4>Design Philosophy</h4>
+
+ <tt>bugpoint</tt> is designed to be a useful tool without requiring any
+ hooks into the LLVM infrastructure at all. It works with any and all LLVM
+ passes and code generators, and does not need to "know" how they work. Because
+ of this, it may appear to do stupid things or miss obvious
+ simplifications. <tt>bugpoint</tt> is also designed to trade off programmer
+ time for computer time in the compiler-debugging process; consequently, it may
+ take a long period of (unattended) time to reduce a test case, but we feel it
+ is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless
+ debugging a miscompilation where each test of the program (which requires
+ executing it) takes a long time.<p>
+
+ <a name="automaticdebuggerselection">
+ <h4>Automatic Debugger Selection</h4>
+
+ <tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file
+ specified on the command line and links them together into a single module,
+ called the test program. If any LLVM passes are
+ specified on the command line, it runs these passes on the test program. If
+ any of the passes crash, or if they produce malformed output (which causes the
+ verifier to abort),
+ <tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a>.<p>
+
+ Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
+ specified, <tt>bugpoint</tt> runs the test 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 for the test program, it tries
+ executing it with the <a href="#opt_run-">selected</a> code generator. If the
+ selected code generator crashes, <tt>bugpoint</tt> starts the <a
+ href="#crashdebug">crash debugger</a> on the code generator. Otherwise, if the
+ resulting output differs from the reference output, it assumes the difference
+ resulted from a code generator failure, and starts the <a
+ href="#codegendebug">code generator debugger</a>.<p>
+
+ Finally, if the output of the selected code generator matches the reference
+ output, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
+ have been applied to it. If its output differs from the reference output, it
+ assumes the difference resulted from a failure in one of the LLVM passes, and
+ enters the <a href="#miscompilationdebug">miscompilation
+ debugger</a>. Otherwise, there is no problem <tt>bugpoint</tt> can debug.<p>
+
+ <a name="crashdebug">
+ <h4>Crash debugger</h4>
+
+ If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard as
+ it can to reduce the list of passes (for optimizer crashes) and the size of the
+ test program. First, <tt>bugpoint</tt> figures out which combination of
+ optimizer passes triggers the bug. This is useful when debugging a problem
+ exposed by <tt>gccas</tt>, for example, because it runs over 38 passes.<p>
+
+ Next, <tt>bugpoint</tt> tries removing functions from the test program, to
+ reduce its size. Usually it is able to reduce a test program to a single
+ function, when debugging 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 absence 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>, <tt><a
+ href="analyze.html">analyze</a></tt>, or <tt><a href="llc.html">llc</a></tt>.<p>
+
+ <a name="codegendebug">
+ <h4>Code generator debugger</h4>
+
+ <p>The code generator debugger attempts to narrow down the amount of code that
+ is being miscompiled by the <a href="#opt_run-">selected</a> code generator. To
+ do this, it takes the test program and partitions it into two pieces: one piece
+ which it compiles with the C backend (into a shared object), and one piece which
+ it runs with either the JIT or the static LLC compiler. It uses several
+ techniques to reduce the amount of code pushed through the LLVM code generator,
+ to reduce the potential scope of the problem. After it is finished, it emits
+ two bytecode files (called "test" [to be compiled with the code generator] and
+ "safe" [to be compiled with the C backend], respectively), and instructions for
+ reproducing the problem. The code generator debugger assumes that the C backend
+ produces good code.</p>
+
+ <a name="miscompilationdebug">
+ <h4>Miscompilation debugger</h4>
+
+ The miscompilation debugger works similarly to the code generator
+ debugger. It works by splitting the test program into two pieces, running the
+ optimizations specified on one piece, linking the two pieces back together,
+ and then executing the result.
+ It attempts to narrow down the list of passes to the one (or few) which are
+ causing the miscompilation, then reduce the portion of the test program which is
+ being miscompiled. The miscompilation debugger assumes that the selected
+ code generator is working properly.<p>
+
+ <a name="bugpoint notes">
+ <h4>Advice for using <tt>bugpoint</tt></h4>
+
+ <tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
+ non-obvious ways. Here are some hints and tips:<p>
+
+ <ol>
+ <li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
+ works with programs that have deterministic output. Thus, if the program
+ outputs <tt>argv[0]</tt>, the date, time, or any other "random" data, <tt>bugpoint</tt> may
+ misinterpret differences in these data, when output, as the result of a
+ miscompilation. Programs should be temporarily modified to disable
+ outputs that are likely to vary from run to run.
+
+ <li>In the code generator and miscompilation debuggers, debugging will go
+ faster if you manually modify the program or its inputs to reduce the
+ runtime, but still exhibit the problem.
+
+ <li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
+ it helps track down regressions quickly. To avoid having to relink
+ <tt>bugpoint</tt> every time you change your optimization however, have
+ <tt>bugpoint</tt> dynamically load your optimization with the <a
+ href="#opt_load"><tt>-load</tt></a> option.
+
+ <li><tt>bugpoint</tt> can generate a lot of output and run for a long period of
+ time. It is often useful to capture the output of the program to file. For
+ example, in the C shell, you can type:<br>
+ <tt>bugpoint ..... |& tee bugpoint.log</tt>
+ <br>to get a copy of <tt>bugpoint</tt>'s output in the file
+ <tt>bugpoint.log</tt>, as well as on your terminal.
+
+ <li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If
+ <tt>bugpoint</tt> crashes before you see its "All input ok" message,
+ you might try <tt>llvm-link -v</tt> on the same set of input files. If
+ that also crashes, you may be experiencing a linker bug.
+
+ <li>If your program is <b>supposed</b> to crash, <tt>bugpoint</tt> will be
+ confused. One way to deal with this is to cause bugpoint to ignore the exit
+ code from your program, by giving it the <tt>-check-exit-code=false</tt>
+ option.
+
+ </ol>
+
+ <h3>OPTIONS</h3>
+
+ <ul>
+ <li><tt>-additional-so <library></tt><br>
+ Load <tt><library></tt> into the test program whenever it is run.
+ This is useful if you are debugging programs which depend on non-LLVM
+ libraries (such as the X or curses libraries) to run.<p>
+
+ <li><tt>-args <program args></tt><br>
+ Pass all arguments specified after <tt>-args</tt> to the
+ test program whenever it runs. Note that if any of
+ the <tt><program args></tt> start with a '-', you should use:
+ <p>
+ <tt>bugpoint <bugpoint args> -args -- <program args></tt>
+ <p>
+ The "<tt>--</tt>" right after the <tt>-args</tt> option tells
+ <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
+ part of the <tt>-args</tt> option, not as options to <tt>bugpoint</tt>
+ itself.<p>
+
+ <li><tt>-tool-args <tool args></tt><br>
+ Pass all arguments specified after <tt>-tool-args</tt> to the
+ LLVM tool under test (llc, lli, etc.) whenever it runs.
+ You should use this option in the following way:
+ <p>
+ <tt>bugpoint <bugpoint args> -tool-args -- <tool args></tt>
+ <p>
+ The "<tt>--</tt>" right after the <tt>-tool-args</tt> option tells
+ <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
+ part of the <tt>-tool-args</tt> option, not as options to
+ <tt>bugpoint</tt> itself. (See <tt>-args</tt>, above.)<p>
+
+ <li><tt>-check-exit-code={true,false}</tt><br>
+ Assume a non-zero exit code or core dump from the test program is
+ a failure. Defaults to true.<p>
+
+ <li><tt>-disable-{dce,simplifycfg}</tt><br>
+ Do not run the specified passes to clean up and reduce the size of the
+ test program. By default, <tt>bugpoint</tt> uses these passes internally
+ when attempting to reduce test programs. If you're trying to find
+ a bug in one of these passes, <tt>bugpoint</tt> may crash.<p>
+
+ <li> <tt>-help</tt><br>
+ Print a summary of command line options.<p>
+
+ <a name="opt_input"><li><tt>-input <filename></tt><br>
+ Open <tt><filename></tt> and redirect the standard input of the
+ test program, whenever it runs, to come from that file.
+ <p>
+
+ <a name="opt_load"><li> <tt>-load <plugin></tt><br>
+ Load the dynamic object <tt><plugin></tt> into <tt>bugpoint</tt>
+ itself. 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>bugpoint -load <plugin> -help</tt>
+ <p>
+
+ <a name="opt_output"><li><tt>-output <filename></tt><br>
+ Whenever the test program produces output on its standard output
+ stream, it should match the contents of <tt><filename></tt>
+ (the "reference output"). If you do not use this option,
+ <tt>bugpoint</tt> will attempt to generate a reference output by
+ compiling the program with the C backend and running it.<p>
+
+ <li><tt>-profile-info-file <filename></tt><br>
+ Profile file loaded by -profile-loader.<p>
+
+ <a name="opt_run-"><li><tt>-run-{int,jit,llc,cbe}</tt><br>
+ Whenever the test program is compiled, <tt>bugpoint</tt> should generate
+ code for it using the specified code generator. These options allow
+ you to choose the interpreter, the JIT compiler, the static native
+ code compiler, or the C backend, respectively.<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>
More information about the llvm-commits
mailing list