<li><a href="#passes">Bugs in LLVM passes</a>
</ul>
<li><a href="#miscompilations">Miscompilations</a>
+ <li><a href="#codegen">Incorrect code generation (JIT and LLC)</a>
- <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></b><p>
+ <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>
</ol><p></font>
</td><td valign=top align=right>
<img src="Debugging.gif" width=444 height=314>
<a name="front-end">Front-end bugs
</b></font></td></tr></table><ul>
-If the problem is in the front-end, pretty much the only thing you can do is
-preprocess the input (compile with the <tt>-E</tt> option) and send us the
-results. There is no good way to reduce source-level test-cases that I know
-of... if you do know, send me information and we can extend this section. :)<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> (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>
<!-- ======================================================================= -->
</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
</b></font></td></tr></table><ul>
If you find that a bug crashes in the <tt><b>gccas</b></tt> stage of
-compilation, compile your test-case to a <tt>.s</tt> file with the <tt>-S</tt>
-
option to <tt><b>llvm-gcc</b></tt>. Then run:<p>
+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
the full list of objects linked). Then run:<p>
<pre>
- <b>as</b> < /dev/null > null.bc
+ <b>llvm-as</b> < /dev/null > null.bc
<b>gccld</b> -debug-pass=Arguments null.bc
</pre><p>
<!-- *********************************************************************** -->
</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
-<a name="miscompilations">Miscompilations
+<a name="miscompilations">Miscompilations</a>
+</b></font></td></tr></table><ul>
+<!-- *********************************************************************** -->
+
+A miscompilation occurs when a pass does not correctly transform a program, thus
+producing errors that are only noticed during execution. This is different from
+producing invalid LLVM code (i.e., code not in SSA form, using values before
+defining them, etc.) which the verifier will check for after a pass finishes its
+run.<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:
+
+<pre>
+ <b>bugpoint</b> -run-cbe [... optimization passes ...] file-to-test.bc
+</pre>
+
+<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
+you. It will print a message letting you know how to reproduce the resulting
+error.
+
+<!-- *********************************************************************** -->
+</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
+<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
+<a name="codegen">Incorrect code generation</a>
</b></font></td></tr></table><ul>
<!-- *********************************************************************** -->
-Fortunately we haven't had to many miscompilations. Because of this, this
-section is a TODO. Basically, use bugpoint to track down the problem.<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>
+
+To debug the JIT:
+<pre>
+ <b>bugpoint</b> -run-jit -output=[correct output file] [bytecodefile]
+</pre>
+
+Similarly, to debug the LLC, one would run:
+<pre>
+ <b>bugpoint</b> -run-llc -output=[correct output file] [bytecodefile]
+</pre>
+
+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
+backend and the <em>test</em> file which either LLC or the JIT
+mis-codegenerates, and thus causes the error.<p>
+To reproduce the error that <tt>bugpoint</tt> found, it is sufficient to do the
+following:
+
+<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>
+ <p>
+ If debugging the JIT, load the shared object and supply the test bytecode:<br>
+<pre>
+ <b>lli</b> -load=safe.so test.bc [program options]
+</pre></li>
+</ol>
<!-- *********************************************************************** -->
</ul>
<address><a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
<!-- Created: Tue Aug 6 15:00:33 CDT 2002 -->
<!-- hhmts start -->
-Last modified: Fri May 23 09:48:53 CDT 2003
+Last modified: Tue Oct 14 15:57:47 CDT 2003
<!-- hhmts end -->
</font></body></html>
projects / oota-llvm.git / blobdiff