How to submit an LLVM bug report
</div>
-<table border="0" width="100%">
-<tr>
-<td valign="top">
-
+<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>
<li><a href="#miscompilations">Miscompilations</a></li>
<li><a href="#codegen">Incorrect code generation (JIT and LLC)</a></li>
-
</ol>
-
-<div class="doc_text">
- <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
- <a href="http://misha.brukman.net">Misha Brukman</a></b></p>
+<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 align="right">
- <img src="Debugging.gif" alt="Debugging" width="444" height="314">
+<td class="right">
+ <img src="img/Debugging.gif" alt="Debugging" width="444" height="314">
</td>
</tr>
</table>
more easily.</p>
<p>Once you have a reduced test-case, go to <a
-href="http://llvm.cs.uiuc.edu/bugs/enter_bug.cgi">the LLVM Bug Tracking
+href="http://llvm.org/bugs/enter_bug.cgi">the LLVM Bug Tracking
System</a>, select the category in which the bug falls, and fill out the form
with the necessary details. The bug description should contain the following
information:</p>
<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. If you are running <tt><b>opt</b></tt> or
-<tt><b>analyze</b></tt> directly, and something crashes, jump to the section on
+assertion failure of some sort. If you are running <tt><b>opt</b></tt>
+directly, and something crashes, jump to the section on
<a href="#passes">bugs in LLVM passes</a>. Otherwise, the most important
piece of the puzzle is to figure out if it is the GCC-based front-end that is
buggy or if it's one of the LLVM tools that has problems.</p>
<tt><b>gccas</b></tt>, or <tt><b>gccld</b></tt>), run the
<tt><b>llvm-gcc</b></tt> command line as you were when the crash occurred, but
add a <tt>-v</tt> option to the command line. The compiler will print out a
-bunch of stuff, and should end with telling you that one of <tt><b>cc1</b></tt>,
-<tt><b>gccas</b></tt>, or <tt><b>gccld</b></tt> crashed.</p>
+bunch of stuff, and should end with telling you that one of
+<tt><b>cc1</b>/<b>cc1plus</b></tt>, <tt><b>gccas</b></tt>, or
+<tt><b>gccld</b></tt> crashed.</p>
<ul>
- <li>If <tt><b>cc1</b></tt> crashed, you found a problem with the front-end.
+ <li>If <tt><b>cc1</b></tt> or <tt><b>cc1plus</b></tt> crashed, you found a
+ problem with the front-end.
Jump ahead to the section on <a href="#front-end">front-end bugs</a>.</li>
<li>If <tt><b>gccas</b></tt> crashed, you found a bug in <a href="#gccas">one
behind a <tt><i>foo</i>.i</tt> file (containing preprocessed C source code) and
possibly <tt><i>foo</i>.s</tt> (containing LLVM assembly code), for each
compiled <tt><i>foo</i>.c</tt> file. Send us the <tt><i>foo</i>.i</tt> file,
-along with a brief description of the error it caused.</p>
+along with a brief description of the error it caused. A tool that might help
+you reduce a front-end testcase to a more manageable size is
+<a href="http://delta.tigris.org/">delta</a>.
+</p>
</div>
compilation, compile your test-case to a <tt>.s</tt> file with the
<tt>-save-temps</tt> option to <tt><b>llvm-gcc</b></tt>. Then run:</p>
-<pre>
- <b>gccas</b> -debug-pass=Arguments < /dev/null -o - > /dev/null
-</pre>
+<div class="doc_code">
+<p><tt><b>gccas</b> -debug-pass=Arguments < /dev/null -o - > /dev/null</tt></p>
+</div>
<p>... which will print a list of arguments, indicating the list of passes that
<tt><b>gccas</b></tt> runs. Once you have the input file and the list of
being linked together (the "<tt><b>llvm-gcc</b> -v</tt>" output should include
the full list of objects linked). Then run:</p>
-<pre>
- <b>llvm-as</b> < /dev/null > null.bc
- <b>gccld</b> -debug-pass=Arguments null.bc
-</pre><p>
+<div class="doc_code">
+<p><tt><b>llvm-as</b> < /dev/null > null.bc<br>
+<b>gccld</b> -debug-pass=Arguments null.bc</tt>
+</p>
+</div>
<p>... which will print a list of arguments, indicating the list of passes that
<tt><b>gccld</b></tt> runs. Once you have the input files and the list of
order to reduce the list of passes (which is probably large) and the input to
something tractable, use the <tt><b>bugpoint</b></tt> tool as follows:</p>
-<pre>
- <b>bugpoint</b> <input files> <list of passes>
-</pre><p>
+<div class="doc_code">
+<p><tt><b>bugpoint</b> <input files> <list of passes></tt></p>
+</div>
<p><tt><b>bugpoint</b></tt> will print a bunch of output as it reduces the
test-case, but it should eventually print something like this:</p>
-<pre>
- ...
- Emitted bytecode to 'bugpoint-reduced-simplified.bc'
-
- *** You can reproduce the problem with: opt bugpoint-reduced-simplified.bc -licm
-</pre>
+<div class="doc_code">
+<p><tt>
+...<br>
+Emitted bytecode to 'bugpoint-reduced-simplified.bc'<br>
+<br>
+*** You can reproduce the problem with: opt bugpoint-reduced-simplified.bc -licm<br>
+</tt></p>
+</div>
<p>Once you complete this, please send the LLVM bytecode file and the command
line to reproduce the problem to the llvmbugs mailing list.</p>
before defining them, etc.) which the verifier will check for after a pass
finishes its run.</p>
-<p>To debug a miscompilation, you should choose which program you wish to run
-the output through, e.g. C backend, the JIT, or LLC, and a selection of passes,
-one of which may be causing the error, and run, for example:</p>
+<p>If it looks like the LLVM compiler is miscompiling a program, the very first
+thing to check is to make sure it is not using undefined behavior. In
+particular, check to see if the program <a
+href="http://valgrind.kde.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>
-<pre>
- <b>bugpoint</b> -run-cbe [... optimization passes ...] file-to-test.bc
-</pre>
+<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 bytecode file as much as it can to assist
<p>To debug the JIT:</p>
+<div class="doc_code">
<pre>
- <b>bugpoint</b> -run-jit -output=[correct output file] [bytecodefile]
+bugpoint -run-jit -output=[correct output file] [bytecode 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>
- <b>bugpoint</b> -run-llc -output=[correct output file] [bytecodefile]
+bugpoint -run-llc -output=[correct output file] [bytecode 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 bytecode files: a <em>safe</em> file which can be compiled with the C
<ol>
- <li>Regenerate the shared object from the safe bytecode file:<br>
-
-<pre>
- <b>llvm-dis</b> -c safe.bc -o safe.c<br>
- <b>gcc</b> -shared safe.c -o safe.so
-</pre></li>
-
- <li>If debugging LLC, compile test bytecode native and link with the shared object:<br>
-
-<pre>
- <b>llc</b> test.bc -o test.s -f<br>
- gcc test.s safe.so -o test.llc<br>
- ./test.llc [program options]
-</pre></li>
-
- <li>If debugging the JIT, load the shared object and supply the test
-bytecode:
-
-<pre>
- <b>lli</b> -load=safe.so test.bc [program options]
-</pre></li>
+<li><p>Regenerate the shared object from the safe bytecode 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 bytecode 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
+ bytecode:</p>
+
+<div class="doc_code">
+<p><tt><b>lli</b> -load=safe.so test.bc [program options]</tt></p>
+</div></li>
</ol>
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.cs.uiuc.edu">The LLVM Compiler Infrastructure</a>
+ <a href="http://llvm.org">The LLVM Compiler Infrastructure</a>
<br>
Last modified: $Date$
</address>
projects / oota-llvm.git / blobdiff