<!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> | |
<h1> | |
How to submit an LLVM bug report | |
</h1> | |
<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> | |
<!-- *********************************************************************** --> | |
<h2> | |
<a name="introduction">Introduction - Got bugs?</a> | |
</h2> | |
<!-- *********************************************************************** --> | |
<div> | |
<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 category, just use the "new-bugs" category 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> | |
<!-- *********************************************************************** --> | |
<h2> | |
<a name="crashers">Crashing Bugs</a> | |
</h2> | |
<!-- *********************************************************************** --> | |
<div> | |
<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> | |
<!-- ======================================================================= --> | |
<h3> | |
<a name="front-end">Front-end bugs</a> | |
</h3> | |
<div> | |
<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> | |
<!-- ======================================================================= --> | |
<h3> | |
<a name="ct_optimizer">Compile-time optimization bugs</a> | |
</h3> | |
<div> | |
<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 way 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> | |
<!-- ======================================================================= --> | |
<h3> | |
<a name="ct_codegen">Code generator bugs</a> | |
</h3> | |
<div> | |
<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</tt></li> | |
<li><tt><b>llc</b> foo.bc -relocation-model=pic</tt></li> | |
<li><tt><b>llc</b> foo.bc -relocation-model=static</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> | |
</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> | |
<!-- *********************************************************************** --> | |
<h2> | |
<a name="miscompilations">Miscompilations</a> | |
</h2> | |
<!-- *********************************************************************** --> | |
<div> | |
<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> | |
<!-- *********************************************************************** --> | |
<h2> | |
<a name="codegen">Incorrect code generation</a> | |
</h2> | |
<!-- *********************************************************************** --> | |
<div> | |
<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<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-blue" alt="Valid CSS"></a> | |
<a href="http://validator.w3.org/check/referer"><img | |
src="http://www.w3.org/Icons/valid-html401-blue" 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: 2011-06-07 16:03:13 -0400 (Tue, 07 Jun 2011) $ | |
</address> | |
</body> | |
</html> |