From: Brian Gaeke Date: Thu, 1 Jul 2004 20:10:40 +0000 (+0000) Subject: bugpoint command guide has been designated a full-fledged "doc". X-Git-Url: http://plrg.eecs.uci.edu/git/?a=commitdiff_plain;h=74f470b20c2421b963035156edf3d7736e0d755c;p=oota-llvm.git bugpoint command guide has been designated a full-fledged "doc". git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@14544 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html new file mode 100644 index 00000000000..519e02d5277 --- /dev/null +++ b/docs/Bugpoint.html @@ -0,0 +1,249 @@ + +LLVM: bugpoint tool + + + +

LLVM: bugpoint tool

+
+ +

NAME

+bugpoint + +

SYNOPSIS

+bugpoint [options] [input LLVM ll/bc files] [LLVM passes] --args <program arguments>... + + +

DESCRIPTION

+ +The bugpoint 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 gccas 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.

+ + +

Design Philosophy

+ +bugpoint 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. bugpoint 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 bugpoint is generally very quick unless +debugging a miscompilation where each test of the program (which requires +executing it) takes a long time.

+ + +

Automatic Debugger Selection

+ +bugpoint reads each .bc or .ll 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), +bugpoint starts the crash debugger.

+ +Otherwise, if the -output option was not +specified, bugpoint runs the test program with the C backend (which is +assumed to generate good code) to generate a reference output. Once +bugpoint has a reference output for the test program, it tries +executing it with the selected code generator. If the +selected code generator crashes, bugpoint starts the crash debugger 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 code generator debugger.

+ +Finally, if the output of the selected code generator matches the reference +output, bugpoint 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 miscompilation +debugger. Otherwise, there is no problem bugpoint can debug.

+ + +

Crash debugger

+ +If an optimizer or code generator crashes, bugpoint will try as hard as +it can to reduce the list of passes (for optimizer crashes) and the size of the +test program. First, bugpoint figures out which combination of +optimizer passes triggers the bug. This is useful when debugging a problem +exposed by gccas, for example, because it runs over 38 passes.

+ +Next, bugpoint 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, +bugpoint deletes any individual LLVM instructions whose absence 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, analyze, or llc.

+ + +

Code generator debugger

+ +

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 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.

+ + +

Miscompilation debugger

+ +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.

+ + +

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:

+ +

    +
  1. In the code generator and miscompilation debuggers, bugpoint only + works with programs that have deterministic output. Thus, if the program + outputs argv[0], the date, time, or any other "random" data, bugpoint 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. + +
  2. 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. + +
  3. bugpoint is extremely useful when working on a new optimization: + it helps track down regressions quickly. To avoid having to relink + bugpoint every time you change your optimization however, have + bugpoint dynamically load your optimization with the -load option. + +
  4. bugpoint 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:
    + bugpoint ..... |& tee bugpoint.log +
    to get a copy of bugpoint's output in the file + bugpoint.log, as well as on your terminal. + +
  5. bugpoint cannot debug problems with the LLVM linker. If + bugpoint crashes before you see its "All input ok" message, + you might try llvm-link -v on the same set of input files. If + that also crashes, you may be experiencing a linker bug. + +
  6. If your program is supposed to crash, bugpoint 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 -check-exit-code=false + option. + +
+ +

OPTIONS

+ + + +

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. + +