"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>How to submit an LLVM bug report</title>
- <link rel="stylesheet" href="llvm.css" type="text/css">
+ <link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
<body>
-<div class="doc_title">
+<h1>
How to submit an LLVM bug report
-</div>
+</h1>
<table class="layout" style="width: 90%" >
<tr class="layout">
<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">
+<h2>
<a name="introduction">Introduction - Got bugs?</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<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
<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).
+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 CVS
+ <li>The location where you obtained LLVM (if not from our Subversion
repository).</li>
</ul>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="crashers">Crashing Bugs</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<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
</ul>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="front-end">Front-end bugs</a>
-</div>
+</h3>
-<div class="doc_text">
+<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
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="ct_optimizer">Compile-time optimization bugs</a>
-</div>
+</h3>
-<div class="doc_text">
+<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>".
</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
+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
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="ct_codegen">Code generator bugs</a>
-</div>
+</h3>
-<div class="doc_text">
+<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>"
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>
+<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
-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
</div>
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="miscompilations">Miscompilations</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<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
</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
+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">
+<h2>
<a name="codegen">Incorrect code generation</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Similarly to debugging incorrect compilation by mis-behaving passes, you can
debug incorrect code generation by either LLC or the JIT, using
<div class="doc_code">
<pre>
-bugpoint -run-jit -output=[correct output file] [bytecode file] \
- --tool-args -- [arguments to pass to lli] \
+bugpoint -run-jit -output=[correct output file] [bitcode file] \
+ --tool-args -- [arguments to pass to lli] \
--args -- [program arguments]
</pre>
</div>
<div class="doc_code">
<pre>
-bugpoint -run-llc -output=[correct output file] [bytecode file] \
- --tool-args -- [arguments to pass to llc] \
+bugpoint -run-llc -output=[correct output file] [bitcode file] \
+ --tool-args -- [arguments to pass to llc] \
--args -- [program arguments]
</pre>
</div>
</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
+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>
<ol>
-<li><p>Regenerate the shared object from the safe bytecode file:</p>
+<li><p>Regenerate the shared object from the safe bitcode file:</p>
<div class="doc_code">
<p><tt>
</tt></p>
</div></li>
-<li><p>If debugging LLC, compile test bytecode native and link with the shared
+<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>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
- bytecode:</p>
+ bitcode:</p>
<div class="doc_code">
<p><tt><b>lli</b> -load=safe.so test.bc [program options]</tt></p>
<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>
+ 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" alt="Valid HTML 4.01!" /></a>
+ 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>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a>
<br>
Last modified: $Date$
</address>