mirror of
https://github.com/c64scene-ar/llvm-6502.git
synced 2024-08-20 11:29:24 +00:00
5cd840c047
* Add info about codegen and miscompilation mode git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@9240 91177308-0d34-0410-b5e6-96231b3b80d8
167 lines
7.4 KiB
HTML
167 lines
7.4 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 is a generally useful tool for narrowing down
|
|
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 testcases to something useful. 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>
|
|
|
|
<tt>bugpoint</tt> has been designed to be a useful tool without requiring any
|
|
hooks into the LLVM intrastructure 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. Remember, however, that computer time is much cheaper than
|
|
programmer time, so if it takes a long time to reduce a testcase it is still
|
|
worth it. :)<p>
|
|
|
|
<a name="crashdebug">
|
|
<h4>Automatic Mode Selection</h4>
|
|
|
|
<tt>bugpoint</tt> reads the specified list of <tt>.bc</tt> or <tt>.ll</tt> files
|
|
specified on the command-line and links them together. If any LLVM passes are
|
|
specified on the command line, it runs these passes on the resultant module. If
|
|
any of the passes crash, or if they produce a malformed LLVM module,
|
|
<tt>bugpoint</tt> enters <a href="#crashdebug">crash debugging mode</a>.<p>
|
|
|
|
Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
|
|
specified, <tt>bugpoint</tt> runs the initial 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 to match, it tries executing the
|
|
original program with the <a href="#opt_run-">selected</a> code generator. If
|
|
the resultant output is different than the reference output, it exters <a
|
|
href="#codegendebug">code generator debugging mode</a>.<p>
|
|
|
|
Otherwise, <tt>bugpoint</tt> runs the LLVM program after all of the LLVM passes
|
|
have been applied to it. If the executed program matches the reference output,
|
|
there is no problem <tt>bugpoint</tt> can debug. Otherwise, it enters <a
|
|
href="#miscompilationdebug">miscompilation debugging mode</a>.<p>
|
|
|
|
<a name="crashdebug">
|
|
<h4>Crash debugging mode</h4>
|
|
|
|
If an optimizer crashes, <tt>bugpoint</tt> will try a variety of techniques to
|
|
narrow down the list of passes and the code to a more manageable amount. First,
|
|
<tt>bugpoint</tt> figures out which combination of passes trigger the bug. This
|
|
is useful when debugging a problem exposed by <tt>gccas</tt> for example,
|
|
because it has over 30 optimization it runs.<p>
|
|
|
|
Next, <tt>bugpoint</tt> tries removing functions from the module, to reduce the
|
|
size of the testcase to a reasonable amount. Usually it is able to get it down
|
|
to a single function for 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 absense 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 debugging mode</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 LLVM 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 (the "test" [to be compiled with the code generator] and
|
|
"safe" [to be compiled with the C backend] modules), and instructions for
|
|
reproducing the problem. This module assume the C backend produces good
|
|
code.<p>
|
|
|
|
If you are using this mode and get an error message that says "Non-instruction
|
|
is using an external function!", 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 debugging mode.<p>
|
|
|
|
<a name="miscompilationdebug">
|
|
<h4>Miscompilation debugging mode</h4>
|
|
|
|
The miscompilation debugging mode works similarly to the code generator
|
|
debugging mode. It works by splitting the program into two pieces, running the
|
|
optimizations specified on one piece, relinking the program, then executing it.
|
|
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 program which is
|
|
being miscompiled. This module assumes that the selected code generator is
|
|
working properly.<p>
|
|
|
|
|
|
<h3>OPTIONS</h3>
|
|
|
|
<ul>
|
|
<li><tt>-additional-so <library.so></tt><br>
|
|
|
|
Use this option to specify .so files which must be loaded by the program
|
|
when 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 <arguments></tt><br>
|
|
All arguments specified after <tt>-args</tt> are passed into the
|
|
executed program when the program must be executed.<p>
|
|
|
|
<li><tt>-disable-(adce,dce,final-cleanup,simplifycfg)</tt><br>
|
|
<tt>bugpoint</tt> uses several passes internally for cleanup routines to
|
|
reduce the size of the program. If you're trying to find a bug in one
|
|
of these passes, <tt>bugpoint</tt> may crash. These options tell
|
|
<tt>bugpoint</tt> not use the specified passes.<p>
|
|
|
|
<li> <tt>-help</tt><br>
|
|
Print a summary of command line options.<p>
|
|
|
|
<a name="opt_input"><li><tt>-input <filename></tt><br>
|
|
Specify the contents of <stdin> when the program must be executed.
|
|
<p>
|
|
|
|
<li> <tt>-load <plugin.so></tt><br>
|
|
Load the dynamic object plugin.so. 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>opt -load <plugin.so> -help</tt>
|
|
<p>
|
|
|
|
<a name="opt_output"><li><tt>-output <filename></tt><br>
|
|
Specify a reference output for the <stdout> file stream.<p>
|
|
|
|
<a name="opt_run-"><li><tt>-run-(int|jit|llc|cbe)</tt><br>
|
|
Specify which code generator <tt>bugpoint</tt> should use to run the
|
|
program. You may choose the interpreter, the JIT compiler, the static
|
|
native code compiler, or the C backend.<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>
|
|
|