bugpoint 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. :)
Automatic Mode Selection
bugpoint reads the specified list of .bc or .ll 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,
bugpoint enters crash debugging mode.
Otherwise, if the -output option was not specified, bugpoint runs the initial program with the C backend (which is assumed to generate good code) to generate a reference output. Once bugpoint has a reference output to match, it tries executing the original program with the selected code generator. If the resultant output is different than the reference output, it exters code generator debugging mode.
Otherwise, bugpoint 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 bugpoint can debug. Otherwise, it enters miscompilation debugging mode.
Next, bugpoint 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,
bugpoint deletes any individual LLVM instructions whose absense does
not eliminate the failure. At the end, bugpoint should tell you what
passes crash, give you a bytecode file, and give you instructions on how to
reproduce the failure with opt or
analyze.
If you are using this mode and get an error message that says "Non-instruction
is using an external function!", try using the -run-llc option instead
of the -run-jit option. This is due to an unimplemented feature in the
code generator debugging mode.
bugpoint .... -args -- (the arguments here)
The "--" right after the -args option tells
bugpoint to consider any options starting with - to be
part of the -args option, not as options to bugpoint
itself.
opt -load <plugin.so> -help
Crash debugging mode
If an optimizer crashes, bugpoint will try a variety of techniques to
narrow down the list of passes and the code to a more manageable amount. First,
bugpoint figures out which combination of passes trigger the bug. This
is useful when debugging a problem exposed by gccas for example,
because it has over 30 optimization it runs.Code generator debugging mode
The code generator debugger attempts to narrow down the amount of code that is
being miscompiled by the selected 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.Miscompilation debugging mode
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.Advice for using bugpoint
bugpoint can be a remarkably useful tool, but it sometimes works in
non-obvious ways. Here are some hints and tips:
bugpoint ..... |& tee bugpoint.logOPTIONS
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.
All arguments specified after -args are passed into the
executed program when the program must be executed. Note that if the
program takes an argument which starts with a '-', you should use:
bugpoint 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, bugpoint may crash. These options tell
bugpoint not use the specified passes.
Print a summary of command line options.
Specify the contents of <stdin> when the program must be executed.
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:
Specify a reference output for the <stdout> file stream.EXIT STATUS
If bugpoint succeeds in finding a problem, it will exit with 0.
Otherwise, if an error occurs, it will exit with a non-zero value.
SEE ALSO
opt,
analyze
Maintained by the LLVM Team.