From 009b1c42aa6266385f2c37e227516b24077e6dd7 Mon Sep 17 00:00:00 2001 From: Ed Schouten Date: Tue, 2 Jun 2009 17:52:33 +0000 Subject: Import LLVM, at r72732. --- docs/Bugpoint.html | 239 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 docs/Bugpoint.html (limited to 'docs/Bugpoint.html') diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html new file mode 100644 index 0000000000000..7b2679689534e --- /dev/null +++ b/docs/Bugpoint.html @@ -0,0 +1,239 @@ + + + + LLVM bugpoint tool: design and usage + + + +
+ LLVM bugpoint tool: design and usage +
+ + + +
+

Written by Chris Lattner

+
+ + +
+Description +
+ + +
+ +

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

+ +

For detailed case scenarios, such as debugging opt, +llvm-ld, or one of the LLVM code generators, see How To Submit a Bug Report document.

+ +
+ + +
+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 opt, 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 bitcode file, and give you instructions on how to +reproduce the failure with opt 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 bitcode +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 run:

    + +
    +

    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. bugpoint is useful for proactively finding bugs in LLVM. + Invoking bugpoint with the -find-bugs option will cause + the list of specified optimizations to be randomized and applied to the + program. This process will repeat until a bug is found or the user + kills bugpoint. + +
+ +
+ + + +
+
+ Valid CSS + Valid HTML 4.01 + + Chris Lattner
+ LLVM Compiler Infrastructure
+ Last modified: $Date: 2008-12-11 18:34:48 +0100 (Thu, 11 Dec 2008) $ +
+ + + -- cgit v1.2.3