From f375e9a0924fd059792c6dccbb0412d5127bfc74 Mon Sep 17 00:00:00 2001 From: mike-m Date: Fri, 7 May 2010 00:28:04 +0000 Subject: Revert r103213. It broke several sections of live website. llvm-svn: 103219 --- llvm/docs/HowToSubmitABug.html | 347 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 347 insertions(+) create mode 100644 llvm/docs/HowToSubmitABug.html (limited to 'llvm/docs/HowToSubmitABug.html') diff --git a/llvm/docs/HowToSubmitABug.html b/llvm/docs/HowToSubmitABug.html new file mode 100644 index 00000000000..90efbe321b1 --- /dev/null +++ b/llvm/docs/HowToSubmitABug.html @@ -0,0 +1,347 @@ + + + + How to submit an LLVM bug report + + + + +
+ How to submit an LLVM bug report +
+ + + + + + +
+
    +
  1. Introduction - Got bugs?
    2. +
  2. Crashing Bugs +
    3. +
  3. Miscompilations
    4. +
  4. Incorrect code generation (JIT and LLC)
    5. +
+
+

Written by Chris Lattner and + Misha Brukman

+
+		 + Debugging +
+ + +
+ Introduction - Got bugs? +
+ + +
+ +

If you're working with LLVM and run into a bug, we definitely want to know +about it. This document describes what you can do to increase the odds of +getting it fixed quickly.

+ +

Basically you have to do two things at a minimum. First, decide whether the +bug crashes the compiler (or an LLVM pass), or if the +compiler is miscompiling the program (i.e., the +compiler successfully produces an executable, but it doesn't run right). Based +on +what type of bug it is, follow the instructions in the linked section to narrow +down the bug so that the person who fixes it will be able to find the problem +more easily.

+ +

Once you have a reduced test-case, go to the LLVM Bug Tracking +System and fill out the form with the necessary details (note that you don't +need to pick a category, just use the "new-bugs" category if you're not sure). +The bug description should contain the following +information:

+ + + +

Thanks for helping us make LLVM better!

+ +
+ + +
+ Crashing Bugs +
+ + +
+ +

More often than not, bugs in the compiler cause it to crash—often due +to an assertion failure of some sort. The most important +piece of the puzzle is to figure out if it is crashing in the GCC front-end +or if it is one of the LLVM libraries (e.g. the optimizer or code generator) +that has problems.

+ +

To figure out which component is crashing (the front-end, +optimizer or code generator), run the +llvm-gcc command line as you were when the crash occurred, but +with the following extra command line options:

+ + + +
+ + +
+ Front-end bugs +
+ +
+ +

If the problem is in the front-end, you should re-run the same +llvm-gcc command that resulted in the crash, but add the +-save-temps option. The compiler will crash again, but it will leave +behind a foo.i file (containing preprocessed C source code) and +possibly foo.s for each +compiled foo.c file. Send us the foo.i file, +along with the options you passed to llvm-gcc, and a brief description of the +error it caused.

+ +

The delta tool helps to reduce the +preprocessed file down to the smallest amount of code that still replicates the +problem. You're encouraged to use delta to reduce the code to make the +developers' lives easier. This website +has instructions on the best way to use delta.

+ +
+ + +
+ Compile-time optimization bugs +
+ +
+ +

If you find that a bug crashes in the optimizer, compile your test-case to a +.bc file by passing "-emit-llvm -O0 -c -o foo.bc". +Then run:

+ +
+

opt -std-compile-opts -debug-pass=Arguments foo.bc + -disable-output

+
+ +

This command should do two things: it should print out a list of passes, and +then it should crash in the same was as llvm-gcc. If it doesn't crash, please +follow the instructions for a front-end bug.

+ +

If this does crash, then you should be able to debug this with the following +bugpoint command:

+ +
+

bugpoint foo.bc <list of passes printed by +opt>

+
+ +

Please run this, then file a bug with the instructions and reduced .bc files +that bugpoint emits. If something goes wrong with bugpoint, please submit the +"foo.bc" file and the list of passes printed by opt.

+ +
+ + +
+ Code generator bugs +
+ +
+ +

If you find a bug that crashes llvm-gcc in the code generator, compile your +source file to a .bc file by passing "-emit-llvm -c -o foo.bc" +to llvm-gcc (in addition to the options you already pass). Once your have +foo.bc, one of the following commands should fail:

+ +
    +
  1. llc foo.bc
    2. +
  2. llc foo.bc -relocation-model=pic
    3. +
  3. llc foo.bc -relocation-model=static
    4. +
+ +

If none of these crash, please follow the instructions for a +front-end bug. If one of these do crash, you should +be able to reduce this with one of the following bugpoint command lines (use +the one corresponding to the command above that failed):

+ +
    +
  1. bugpoint -run-llc foo.bc
    2. +
  2. bugpoint -run-llc foo.bc --tool-args + -relocation-model=pic
    3. +
  3. bugpoint -run-llc foo.bc --tool-args + -relocation-model=static
    4. +
+ +

Please run this, then file a bug with the instructions and reduced .bc file +that bugpoint emits. If something goes wrong with bugpoint, please submit the +"foo.bc" file and the option that llc crashes with.

+ +
+ + +
+ Miscompilations +
+ + +
+ +

If llvm-gcc successfully produces an executable, but that executable doesn't +run right, this is either a bug in the code or a bug in the +compiler. The first thing to check is to make sure it is not using undefined +behavior (e.g. reading a variable before it is defined). In particular, check +to see if the program valgrinds clean, +passes purify, or some other memory checker tool. Many of the "LLVM bugs" that +we have chased down ended up being bugs in the program being compiled, not + LLVM.

+ +

Once you determine that the program itself is not buggy, you should choose +which code generator you wish to compile the program with (e.g. C backend, the +JIT, or LLC) and optionally a series of LLVM passes to run. For example:

+ +
+

+bugpoint -run-cbe [... optzn passes ...] file-to-test.bc --args -- [program arguments]

+
+ +

bugpoint will try to narrow down your list of passes to the one pass +that causes an error, and simplify the bitcode file as much as it can to assist +you. It will print a message letting you know how to reproduce the resulting +error.

+ +
+ + +
+ Incorrect code generation +
+ + +
+ +

Similarly to debugging incorrect compilation by mis-behaving passes, you can +debug incorrect code generation by either LLC or the JIT, using +bugpoint. The process bugpoint follows in this case is to try +to narrow the code down to a function that is miscompiled by one or the other +method, but since for correctness, the entire program must be run, +bugpoint will compile the code it deems to not be affected with the C +Backend, and then link in the shared object it generates.

+ +

To debug the JIT:

+ +
+
+bugpoint -run-jit -output=[correct output file] [bitcode file]  \
+         --tool-args -- [arguments to pass to lli]              \
+         --args -- [program arguments]
+
+
+ +

Similarly, to debug the LLC, one would run:

+ +
+
+bugpoint -run-llc -output=[correct output file] [bitcode file]  \
+         --tool-args -- [arguments to pass to llc]              \
+         --args -- [program arguments]
+
+
+ +

Special note: if you are debugging MultiSource or SPEC tests that +already exist in the llvm/test hierarchy, there is an easier way to +debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which +will pass the program options specified in the Makefiles:

+ +
+

+cd llvm/test/../../program
+make bugpoint-jit +

+
+ +

At the end of a successful bugpoint run, you will be presented +with two bitcode files: a safe file which can be compiled with the C +backend and the test file which either LLC or the JIT +mis-codegenerates, and thus causes the error.

+ +

To reproduce the error that bugpoint found, it is sufficient to do +the following:

+ +
    + +

  1. Regenerate the shared object from the safe bitcode file:

    + +
    +

    +llc -march=c safe.bc -o safe.c
    +gcc -shared safe.c -o safe.so +

    +
    2. + +

  2. If debugging LLC, compile test bitcode native and link with the shared + object:

    + +
    +

    +llc test.bc -o test.s
    +gcc test.s safe.so -o test.llc
    +./test.llc [program options] +

    +
    3. + +

  3. If debugging the JIT, load the shared object and supply the test + bitcode:

    + +
    +

    lli -load=safe.so test.bc [program options]

    +
    4. + +
+ +
+ + +
+
+ Valid CSS + Valid HTML 4.01 + + Chris Lattner
+ The LLVM Compiler Infrastructure +
+ Last modified: $Date$ +
+ + + -- cgit v1.2.3