"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM bugpoint tool: design and usage</title>
- <link rel="stylesheet" href="llvm.css" type="text/css">
+ <link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
-<div class="doc_title">
+<h1>
LLVM bugpoint tool: design and usage
-</div>
+</h1>
<ul>
<li><a href="#desc">Description</a></li>
<li><a href="#miscompilationdebug">Miscompilation debugger</a></li>
</ul></li>
<li><a href="#advice">Advice for using <tt>bugpoint</tt></a></li>
+ <li><a href="#notEnough">What to do when <tt>bugpoint</tt> isn't enough</a></li>
</ul>
<div class="doc_author">
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="desc">Description</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p><tt>bugpoint</tt> narrows down the source of problems in LLVM tools and
passes. It can be used to debug three types of failures: optimizer crashes,
causes the crash, and reduce the file down to a small example which triggers the
crash.</p>
-<p>For detailed case scenarios, such as debugging <tt>opt</tt>,
-<tt>llvm-ld</tt>, or one of the LLVM code generators, see <a
-href="HowToSubmitABug.html">How To Submit a Bug Report document</a>.</p>
+<p>For detailed case scenarios, such as debugging <tt>opt</tt>, or one of the
+LLVM code generators, see <a href="HowToSubmitABug.html">How To Submit a Bug
+Report document</a>.</p>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="design">Design Philosophy</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p><tt>bugpoint</tt> is designed to be a useful tool without requiring any
hooks into the LLVM infrastructure at all. It works with any and all LLVM
debugging a miscompilation where each test of the program (which requires
executing it) takes a long time.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="autoselect">Automatic Debugger Selection</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p><tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file specified on
the command line and links them together into a single module, called the test
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="crashdebug">Crash debugger</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard
as it can to reduce the list of passes (for optimizer crashes) and the size of
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="codegendebug">Code generator debugger</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>The code generator debugger attempts to narrow down the amount of code that
is being miscompiled by the selected code generator. To do this, it takes the
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="miscompilationdebug">Miscompilation debugger</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>The miscompilation debugger works similarly to the code generator debugger.
It works by splitting the test program into two pieces, running the
</div>
+</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="advice">Advice for using bugpoint</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
non-obvious ways. Here are some hints and tips:<p>
you might try <tt>llvm-link -v</tt> on the same set of input files. If
that also crashes, you may be experiencing a linker bug.
-<li>If your program is <b>supposed</b> to crash, <tt>bugpoint</tt> will be
- confused. One way to deal with this is to cause bugpoint to ignore the exit
- code from your program, by giving it the <tt>-check-exit-code=false</tt>
- option.
-
<li><tt>bugpoint</tt> is useful for proactively finding bugs in LLVM.
Invoking <tt>bugpoint</tt> with the <tt>-find-bugs</tt> option will cause
the list of specified optimizations to be randomized and applied to the
program. This process will repeat until a bug is found or the user
kills <tt>bugpoint</tt>.
-
</ol>
+</div>
+<!-- *********************************************************************** -->
+<h2>
+ <a name="notEnough">What to do when bugpoint isn't enough</a>
+</h2>
+<!-- *********************************************************************** -->
+
+<div>
+
+<p>Sometimes, <tt>bugpoint</tt> is not enough. In particular, InstCombine and
+TargetLowering both have visitor structured code with lots of potential
+transformations. If the process of using bugpoint has left you with
+still too much code to figure out and the problem seems
+to be in instcombine, the following steps may help. These same techniques
+are useful with TargetLowering as well.</p>
+
+<p>Turn on <tt>-debug-only=instcombine</tt> and see which transformations
+within instcombine are firing by selecting out lines with "<tt>IC</tt>"
+in them.</p>
+
+<p>At this point, you have a decision to make. Is the number
+of transformations small enough to step through them using a debugger?
+If so, then try that.</p>
+
+<p>If there are too many transformations, then a source modification
+approach may be helpful.
+In this approach, you can modify the source code of instcombine
+to disable just those transformations that are being performed on your
+test input and perform a binary search over the set of transformations.
+One set of places to modify are the "<tt>visit*</tt>" methods of
+<tt>InstCombiner</tt> (<I>e.g.</I> <tt>visitICmpInst</tt>) by adding a
+"<tt>return false</tt>" as the first line of the method.</p>
+
+<p>If that still doesn't remove enough, then change the caller of
+<tt>InstCombiner::DoOneIteration</tt>, <tt>InstCombiner::runOnFunction</tt>
+to limit the number of iterations.</p>
+
+<p>You may also find it useful to use "<tt>-stats</tt>" now to see what parts
+of instcombine are firing. This can guide where to put additional reporting
+code.</p>
+
+<p>At this point, if the amount of transformations is still too large, then
+inserting code to limit whether or not to execute the body of the code
+in the visit function can be helpful. Add a static counter which is
+incremented on every invocation of the function. Then add code which
+simply returns false on desired ranges. For example:</p>
+
+<div class="doc_code">
+<p><tt>static int calledCount = 0;</tt></p>
+<p><tt>calledCount++;</tt></p>
+<p><tt>DEBUG(if (calledCount < 212) return false);</tt></p>
+<p><tt>DEBUG(if (calledCount > 217) return false);</tt></p>
+<p><tt>DEBUG(if (calledCount == 213) return false);</tt></p>
+<p><tt>DEBUG(if (calledCount == 214) return false);</tt></p>
+<p><tt>DEBUG(if (calledCount == 215) return false);</tt></p>
+<p><tt>DEBUG(if (calledCount == 216) return false);</tt></p>
+<p><tt>DEBUG(dbgs() << "visitXOR calledCount: " << calledCount
+ << "\n");</tt></p>
+<p><tt>DEBUG(dbgs() << "I: "; I->dump());</tt></p>
+</div>
+
+<p>could be added to <tt>visitXOR</tt> to limit <tt>visitXor</tt> to being
+applied only to calls 212 and 217. This is from an actual test case and raises
+an important point---a simple binary search may not be sufficient, as
+transformations that interact may require isolating more than one call.
+In TargetLowering, use <tt>return SDNode();</tt> instead of
+<tt>return false;</tt>.</p>
+
+<p>Now that that the number of transformations is down to a manageable
+number, try examining the output to see if you can figure out which
+transformations are being done. If that can be figured out, then
+do the usual debugging. If which code corresponds to the transformation
+being performed isn't obvious, set a breakpoint after the call count
+based disabling and step through the code. Alternatively, you can use
+"printf" style debugging to report waypoints.</p>
+
</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>
+ 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">LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
projects / oota-llvm.git / blobdiff