From 721c201bd55ffb73cb2ba8d39e0570fa38c44e15 Mon Sep 17 00:00:00 2001 From: dim Date: Wed, 15 Aug 2012 19:34:23 +0000 Subject: Vendor import of llvm trunk r161861: http://llvm.org/svn/llvm-project/llvm/trunk@161861 --- docs/Bugpoint.html | 239 ----------------------------------------------------- 1 file changed, 239 deletions(-) delete mode 100644 docs/Bugpoint.html (limited to 'docs/Bugpoint.html') diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html deleted file mode 100644 index d9cce0b..0000000 --- a/docs/Bugpoint.html +++ /dev/null @@ -1,239 +0,0 @@ - - - - - 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: 2011-10-31 12:21:59 +0100 (Mon, 31 Oct 2011) $ -
- - - -- cgit v1.1