diff --git a/docs/CommandGuide/bugpoint.html b/docs/CommandGuide/bugpoint.html index 502bca56232..e9d0b587c9a 100644 --- a/docs/CommandGuide/bugpoint.html +++ b/docs/CommandGuide/bugpoint.html @@ -15,56 +15,67 @@

DESCRIPTION

-The bugpoint tool is a generally useful tool for narrowing down +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 invalid native -code generation. It aims to reduce test cases to something useful. For example, +code generation. 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 has been 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. Remember, however, that computer time is much cheaper than -programmer time, so if it takes a long time to reduce a test case it is still -worth it. :)

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

- +

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 +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 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 +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 to match, it tries executing the -original program with the selected code generator. If -the resultant output is different than the reference output, it enters code generator debugging mode.

+bugpoint has a reference output for the test program, it tries +executing it +with the selected code generator. If +the resulting output differs from the reference output, it assumes the +difference resulted from a code generator failure, and enters +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.

+Otherwise, 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 +miscompilation debugging mode. Otherwise, +there is no problem bugpoint can debug.

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, +If an optimizer crashes, bugpoint will try as hard as it can to +reduce the list of passes and the size of the test program. First, +bugpoint figures out which combination of passes triggers the bug. This +is useful when debugging a problem exposed by gccas, for example, because it runs over 30 optimizations.

Next, bugpoint tries removing functions from the module, to reduce the -size of the test case to a reasonable amount. Usually it is able to get it down -to a single function for intraprocedural optimizations. Once the number of +size of the test program. 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