diff options
| author | Dan Gohman <djg@cray.com> | 2007-07-18 16:29:46 +0000 |
|---|---|---|
| committer | Dan Gohman <djg@cray.com> | 2007-07-18 16:29:46 +0000 |
| commit | f17a25c88b892d30c2b41ba7ecdfbdfb2b4be9cc (patch) | |
| tree | ebb79ea1ee5e3bc1fdf38541a811a8b804f0679a /docs/HowToSubmitABug.html | |
| download | external_llvm-f17a25c88b892d30c2b41ba7ecdfbdfb2b4be9cc.zip external_llvm-f17a25c88b892d30c2b41ba7ecdfbdfb2b4be9cc.tar.gz external_llvm-f17a25c88b892d30c2b41ba7ecdfbdfb2b4be9cc.tar.bz2 | |
It's not necessary to do rounding for alloca operations when the requested
alignment is equal to the stack alignment.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@40004 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/HowToSubmitABug.html')
| -rw-r--r-- | docs/HowToSubmitABug.html | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/docs/HowToSubmitABug.html b/docs/HowToSubmitABug.html new file mode 100644 index 0000000..93e0d21 --- /dev/null +++ b/docs/HowToSubmitABug.html @@ -0,0 +1,355 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" + "http://www.w3.org/TR/html4/strict.dtd"> +<html> +<head> + <title>How to submit an LLVM bug report</title> + <link rel="stylesheet" href="llvm.css" type="text/css"> +</head> +<body> + +<div class="doc_title"> + How to submit an LLVM bug report +</div> + +<table class="layout" style="width: 90%" > +<tr class="layout"> + <td class="left"> +<ol> + <li><a href="#introduction">Introduction - Got bugs?</a></li> + <li><a href="#crashers">Crashing Bugs</a> + <ul> + <li><a href="#front-end">Front-end bugs</a> + <li><a href="#ct_optimizer">Compile-time optimization bugs</a> + <li><a href="#ct_codegen">Code generator bugs</a> + </ul></li> + <li><a href="#miscompilations">Miscompilations</a></li> + <li><a href="#codegen">Incorrect code generation (JIT and LLC)</a></li> +</ol> +<div class="doc_author"> + <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and + <a href="http://misha.brukman.net">Misha Brukman</a></p> +</div> +</td> +<td class="right"> + <img src="img/Debugging.gif" alt="Debugging" width="444" height="314"> +</td> +</tr> +</table> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="introduction">Introduction - Got bugs?</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>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.</p> + +<p>Basically you have to do two things at a minimum. First, decide whether the +bug <a href="#crashers">crashes the compiler</a> (or an LLVM pass), or if the +compiler is <a href="#miscompilations">miscompiling</a> 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.</p> + +<p>Once you have a reduced test-case, go to <a +href="http://llvm.org/bugs/enter_bug.cgi">the LLVM Bug Tracking +System</a> and fill out the form with the necessary details (note that you don't +need to pick a catagory, just use the "new-bugs" catagory if you're not sure). +The bug description should contain the following +information:</p> + +<ul> + <li>All information necessary to reproduce the problem.</li> + <li>The reduced test-case that triggers the bug.</li> + <li>The location where you obtained LLVM (if not from our Subversion + repository).</li> +</ul> + +<p>Thanks for helping us make LLVM better!</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="crashers">Crashing Bugs</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>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.</p> + +<p>To figure out which component is crashing (the front-end, +optimizer or code generator), run the +<tt><b>llvm-gcc</b></tt> command line as you were when the crash occurred, but +with the following extra command line options:</p> + +<ul> + <li><tt><b>-O0 -emit-llvm</b></tt>: If <tt>llvm-gcc</tt> still crashes when + passed these options (which disable the optimizer and code generator), then + the crash is in the front-end. Jump ahead to the section on <a + href="#front-end">front-end bugs</a>.</li> + + <li><tt><b>-emit-llvm</b></tt>: If <tt>llvm-gcc</tt> crashes with this option + (which disables the code generator), you found an optimizer bug. Jump ahead + to <a href="#ct_optimizer"> compile-time optimization bugs</a>.</li> + + <li>Otherwise, you have a code generator crash. Jump ahead to <a + href="#ct_codegen">code generator bugs</a>.</li> + +</ul> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="front-end">Front-end bugs</a> +</div> + +<div class="doc_text"> + +<p>If the problem is in the front-end, you should re-run the same +<tt>llvm-gcc</tt> command that resulted in the crash, but add the +<tt>-save-temps</tt> option. The compiler will crash again, but it will leave +behind a <tt><i>foo</i>.i</tt> file (containing preprocessed C source code) and +possibly <tt><i>foo</i>.s</tt> for each +compiled <tt><i>foo</i>.c</tt> file. Send us the <tt><i>foo</i>.i</tt> file, +along with the options you passed to llvm-gcc, and a brief description of the +error it caused.</p> + +<p>The <a href="http://delta.tigris.org/">delta</a> 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. <a +href="http://gcc.gnu.org/wiki/A_guide_to_testcase_reduction">This website</a> +has instructions on the best way to use delta.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="ct_optimizer">Compile-time optimization bugs</a> +</div> + +<div class="doc_text"> + +<p>If you find that a bug crashes in the optimizer, compile your test-case to a +<tt>.bc</tt> file by passing "<tt><b>-emit-llvm -O0 -c -o foo.bc</b></tt>". +Then run:</p> + +<div class="doc_code"> +<p><tt><b>opt</b> -std-compile-opts -debug-pass=Arguments foo.bc + -disable-output</tt></p> +</div> + +<p>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 <a href="#front-end">front-end bug</a>.</p> + +<p>If this does crash, then you should be able to debug this with the following +bugpoint command:</p> + +<div class="doc_code"> +<p><tt><b>bugpoint</b> foo.bc <list of passes printed by +<b>opt</b>></tt></p> +</div> + +<p>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 <b>opt</b>.</p> + +</div> + +<!-- ======================================================================= --> +<div class="doc_subsection"> + <a name="ct_codegen">Code generator bugs</a> +</div> + +<div class="doc_text"> + +<p>If you find a bug that crashes llvm-gcc in the code generator, compile your +source file to a .bc file by passing "<tt><b>-emit-llvm -c -o foo.bc</b></tt>" +to llvm-gcc (in addition to the options you already pass). Once your have +foo.bc, one of the following commands should fail:</p> + +<ol> +<li><tt><b>llc</b> foo.bc -f</tt></li> +<li><tt><b>llc</b> foo.bc -f -relocation-model=pic</tt></li> +<li><tt><b>llc</b> foo.bc -f -relocation-model=static</tt></li> +<li><tt><b>llc</b> foo.bc -f -enable-eh</tt></li> +<li><tt><b>llc</b> foo.bc -f -relocation-model=pic -enable-eh</tt></li> +<li><tt><b>llc</b> foo.bc -f -relocation-model=static -enable-eh</tt></li> +</ol> + +<p>If none of these crash, please follow the instructions for a +<a href="#front-end">front-end bug</a>. 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):</p> + +<ol> +<li><tt><b>bugpoint</b> -run-llc foo.bc</tt></li> +<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args + -relocation-model=pic</tt></li> +<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args + -relocation-model=static</tt></li> +<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args -enable-eh</tt></li> +<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args + -relocation-model=pic -enable-eh</tt></li> +<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args + -relocation-model=static -enable-eh</tt></li> +</ol> + +<p>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.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="miscompilations">Miscompilations</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>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 <a href="http://valgrind.org/">valgrind</a>s 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.</p> + +<p>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:</p> + +<div class="doc_code"> +<p><tt> +<b>bugpoint</b> -run-cbe [... optzn passes ...] file-to-test.bc --args -- [program arguments]</tt></p> +</div> + +<p><tt>bugpoint</tt> 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.</p> + +</div> + +<!-- *********************************************************************** --> +<div class="doc_section"> + <a name="codegen">Incorrect code generation</a> +</div> +<!-- *********************************************************************** --> + +<div class="doc_text"> + +<p>Similarly to debugging incorrect compilation by mis-behaving passes, you can +debug incorrect code generation by either LLC or the JIT, using +<tt>bugpoint</tt>. The process <tt>bugpoint</tt> 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, +<tt>bugpoint</tt> will compile the code it deems to not be affected with the C +Backend, and then link in the shared object it generates.</p> + +<p>To debug the JIT:</p> + +<div class="doc_code"> +<pre> +bugpoint -run-jit -output=[correct output file] [bitcode file] \ + --tool-args -- [arguments to pass to lli] \ + --args -- [program arguments] +</pre> +</div> + +<p>Similarly, to debug the LLC, one would run:</p> + +<div class="doc_code"> +<pre> +bugpoint -run-llc -output=[correct output file] [bitcode file] \ + --tool-args -- [arguments to pass to llc] \ + --args -- [program arguments] +</pre> +</div> + +<p><b>Special note:</b> if you are debugging MultiSource or SPEC tests that +already exist in the <tt>llvm/test</tt> 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:</p> + +<div class="doc_code"> +<p><tt> +cd llvm/test/../../program<br> +make bugpoint-jit +</tt></p> +</div> + +<p>At the end of a successful <tt>bugpoint</tt> run, you will be presented +with two bitcode files: a <em>safe</em> file which can be compiled with the C +backend and the <em>test</em> file which either LLC or the JIT +mis-codegenerates, and thus causes the error.</p> + +<p>To reproduce the error that <tt>bugpoint</tt> found, it is sufficient to do +the following:</p> + +<ol> + +<li><p>Regenerate the shared object from the safe bitcode file:</p> + +<div class="doc_code"> +<p><tt> +<b>llc</b> -march=c safe.bc -o safe.c<br> +<b>gcc</b> -shared safe.c -o safe.so +</tt></p> +</div></li> + +<li><p>If debugging LLC, compile test bitcode native and link with the shared + object:</p> + +<div class="doc_code"> +<p><tt> +<b>llc</b> test.bc -o test.s -f<br> +<b>gcc</b> test.s safe.so -o test.llc<br> +./test.llc [program options] +</tt></p> +</div></li> + +<li><p>If debugging the JIT, load the shared object and supply the test + bitcode:</p> + +<div class="doc_code"> +<p><tt><b>lli</b> -load=safe.so test.bc [program options]</tt></p> +</div></li> + +</ol> + +</div> + +<!-- *********************************************************************** --> +<hr> +<address> + <a href="http://jigsaw.w3.org/css-validator/check/referer"><img + src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a> + <a href="http://validator.w3.org/check/referer"><img + src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a> + + <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> + <a href="http://llvm.org">The LLVM Compiler Infrastructure</a> + <br> + Last modified: $Date$ +</address> + +</body> +</html> |