mirror of
https://github.com/RPCS3/llvm-mirror.git
synced 2024-11-24 03:33:20 +01:00
229 lines
10 KiB
HTML
229 lines
10 KiB
HTML
<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="../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 invalid native
|
|
code generation. 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 a lot of 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. :-) <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,
|
|
<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 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>
|
|
|
|
Otherwise, <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 crashes, <tt>bugpoint</tt> will try as hard as it can to
|
|
reduce the list of passes and the size of the test program. First,
|
|
<tt>bugpoint</tt> figures out which combination of passes triggers the bug. This
|
|
is useful when debugging a problem exposed by <tt>gccas</tt>, for example,
|
|
because it runs over 25 optimizations.<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> or
|
|
<tt><a href="analyze.html">analyze</a></tt>.<p>
|
|
|
|
<a name="codegendebug">
|
|
<h4>Code generator debugger</h4>
|
|
|
|
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>
|
|
|
|
If you are using the code generator debugger and get an error message that
|
|
says "UNSUPPORTED: external function used as a global initializer!", try using
|
|
the <tt>-run-llc</tt> option instead of the <tt>-run-jit</tt> option. This is
|
|
due to an unimplemented feature in the code generator debugger.<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 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 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.
|
|
|
|
</ol>
|
|
|
|
<h3>OPTIONS</h3>
|
|
|
|
<ul>
|
|
<li><tt>-additional-so <library.so></tt><br>
|
|
Load <tt><library.so></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>-disable-{adce,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.so></tt><br>
|
|
Load the dynamic object <tt><plugin.so></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.so> -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>
|
|
|
|
<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>
|