X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FCommandGuide%2Fbugpoint.pod;h=12e32fbb2f5c4862ab316acdf0b4cbf542b16c37;hb=e45252efee1fde81bf5a796b0293fbe18ff4946a;hp=8474a9b08df0d2ad8e6f23b9da17c58c83cff51c;hpb=595d32e93b3dacc143ccbe2bcabe60dcf71a3bc3;p=oota-llvm.git diff --git a/docs/CommandGuide/bugpoint.pod b/docs/CommandGuide/bugpoint.pod index 8474a9b08df..12e32fbb2f5 100644 --- a/docs/CommandGuide/bugpoint.pod +++ b/docs/CommandGuide/bugpoint.pod @@ -6,8 +6,8 @@ bugpoint - automatic test case reduction tool =head1 SYNOPSIS -bugpoint [options] [input LLVM ll/bc files] [LLVM passes] --args -I ... +B [I] [I] [I] B<--args> +I =head1 DESCRIPTION @@ -15,140 +15,9 @@ B 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 B 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. - -=head2 Design Philosophy - -B 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. B 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 B is generally very quick unless debugging a miscompilation where -each test of the program (which requires executing it) takes a long time. - -=head2 Automatic Debugger Selection - -B reads each F<.bc> or F<.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), B starts the crash debugger. - -Otherwise, if the B<-output> option was not specified, B runs the test -program with the C backend (which is assumed to generate good code) to generate -a reference output. Once B has a reference output for the test -program, it tries executing it with the selected code generator. If the -selected code generator crashes, B starts the L 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 L. - -Finally, if the output of the selected code generator matches the reference -output, B 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 B can debug. - -=head2 Crash debugger - -If an optimizer or code generator crashes, B will try as hard as it -can to reduce the list of passes (for optimizer crashes) and the size of the -test program. First, B figures out which combination of optimizer -passes triggers the bug. This is useful when debugging a problem exposed by -B, for example, because it runs over 38 passes. - -Next, B 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, B -deletes any individual LLVM instructions whose absence does not eliminate the -failure. At the end, B should tell you what passes crash, give you a -bytecode file, and give you instructions on how to reproduce the failure with -B, B, or B. - -=head2 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 compiler (B). 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. - -=head2 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. - -=head2 Advice for using bugpoint - -B can be a remarkably useful tool, but it sometimes works in -non-obvious ways. Here are some hints and tips: - -=over - -=item * - -In the code generator and miscompilation debuggers, B only -works with programs that have deterministic output. Thus, if the program -outputs C, the date, time, or any other "random" data, B 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. - -=item * - -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. - -=item * - -B is extremely useful when working on a new optimization: it helps -track down regressions quickly. To avoid having to relink B every -time you change your optimization, make B dynamically load -your optimization by using the B<-load> option. - -=item * - -B 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 B's output in the file F, as well as on -your terminal. - -=item * - -B cannot debug problems with the LLVM linker. If B crashes -before you see its C message, you might try running C on the same set of input files. If that also crashes, you may be -experiencing a linker bug. - -=item * - -If your program is supposed to crash, B will be confused. One way to -deal with this is to cause B to ignore the exit code from your -program, by giving it the B<-check-exit-code=false> option. - -=back +For more information on the design and inner workings of B, as well as +advice for using bugpoint, see F in the LLVM +distribution. =head1 OPTIONS @@ -195,6 +64,17 @@ program. By default, B uses these passes internally when attempting to reduce test programs. If you're trying to find a bug in one of these passes, B may crash. +=item B<--enable-valgrind> + +Use valgrind to find faults in the optimization phase. This will allow +bugpoint to find otherwise asymptomatic problems caused by memory +mis-management. + +=item B<-find-bugs> + +Continually randomize the specified passes and run them on the test program +until a bug is found or the user kills B. + =item B<--help> Print a summary of command line options. @@ -213,6 +93,11 @@ optimizations, use the B<--help> and B<--load> options together; for example: bugpoint --load myNewPass.so --help +=item B<--mlimit> F + +Specifies an upper limit on memory usage of the optimization and codegen. Set +to zero to disable the limit. + =item B<--output> F Whenever the test program produces output on its standard output stream, it @@ -240,11 +125,10 @@ if an error occurs, it will exit with a non-zero value. =head1 SEE ALSO -L, L +L =head1 AUTHOR -Maintained by the LLVM Team (L). +Maintained by the LLVM Team (L). =cut -