Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / d1eb6f7984075b39b26a29b75769637a62d9a9e6 / . / docs / CommandGuide / bugpoint.html
blob: 885a0e77bcf5729b79a56f121db759160aeff237 [file] [log] [blame]
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]1<html>
2<title>LLVM: bugpoint tool</title>
3
4<body bgcolor=white>
5
6<center><h1>LLVM: <tt>bugpoint</tt> tool</h1></center>
7<HR>
8
9<h3>NAME</h3>
10<tt>bugpoint</tt>
11
12<h3>SYNOPSIS</h3>
Chris Lattner83273d52003-10-07 20:33:52 +0000[diff] [blame]13<tt>bugpoint [options] [input llvm ll/bc files] [LLVM passes] --args &lt;program arguments&gt;...</tt>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]14
15<img src="../Debugging.gif" width=444 height=314 align=right>
16<h3>DESCRIPTION</h3>
17
18The <tt>bugpoint</tt> tool is a generally useful tool for narrowing down
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]19problems in LLVM tools and passes. It can be used to debug three types of
20failures: optimizer crashes, miscompilations by optimizers, or invalid native
21code generation. It aims to reduce testcases to something useful. For example,
22if <tt><a href="gccas.html">gccas</a></tt> crashes while optimizing a file, it
23will identify the optimization (or combination of optimizations) that causes the
24crash, and reduce the file down to a small example which triggers the crash.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]25
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]26<tt>bugpoint</tt> reads the specified list of <tt>.bc</tt> or <tt>.ll</tt> files
27specified on the command-line and links them together. If any LLVM passes are
28specified on the command line, it runs these passes on the resultant module. If
29any of the passes crash, or if they produce an LLVM module which is not
30verifiable, <tt>bugpoint</tt> enters <a href="#crashdebug">crash debugging
31mode</a>.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]32
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]33Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
34specified, <tt>bugpoint</tt> runs the initial program with the C backend (which
35is assumed to generate good code) to generate a reference output. Once
36<tt>bugpoint</tt> has a reference output to match, it tries executing the
37original program with the <a href="#opt_run-">selected</a> code generator. If
38the resultant output is different than the reference output, it exters <a
39href="#codegendebug">code generator debugging mode</a>.<p>
40
41Otherwise, <tt>bugpoint</tt> runs the LLVM program after all of the LLVM passes
42have been applied to it. If the executed program matches the reference output,
43there is no problem <tt>bugpoint</tt> can debug. Otherwise, it enters <a
44href="#miscompilationdebug">miscompilation debugging mode</a>.<p>
45
46<a name="crashdebug">
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]47<h4>Crash debugging mode</h4>
48
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]49If an optimizer crashes, <tt>bugpoint</tt> will try a variety of techniques to
50narrow down the list of passes and the code to a more manageable amount. First,
51<tt>bugpoint</tt> figures out which combination of passes trigger the bug. This
52is useful when debugging a problem exposed by <tt>gccas</tt> for example,
53because it has over 30 optimization it runs.<p>
Misha Brukman3f717222003-10-16 18:14:43 +0000[diff] [blame]54
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]55Next, <tt>bugpoint</tt> tries removing functions from the module, to reduce the
56size of the testcase to a reasonable amount. Usually it is able to get it down
57to a single function for intraprocedural optimizations. Once the number of
58functions has been reduced, it attempts to delete various edges in the control
59flow graph, to reduce the size of the function as much as possible. Finally,
60<tt>bugpoint</tt> deletes any individual LLVM instructions whose absense does
61not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what
62passes crash, give you a bytecode file, and give you instructions on how to
63reproduce the failure with <tt><a href="opt.html">opt</a></tt> or
64<tt><a href="analyze.html">analyze</a></tt>.<p>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]65
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]66<a name="codegendebug">
67<h4>Code generator debugging mode</h4>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]68
69TODO
70
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]71<a name="miscompilationdebug">
72<h4>Miscompilation debugging mode</h4>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]73
74TODO
75
76
77<h3>OPTIONS</h3>
78
79<ul>
80 <li><tt>-args &lt;arguments&gt;</tt>
81 <br>
82 All arguments specified after <tt>-args</tt> are passed into the
83 executed program when the program must be executed.
84 <p>
85
86 <li><tt>-disable-(adce,dce,final-cleanup,simplifycfg)</tt>
87 <br>
88 <tt>bugpoint</tt> uses several passes internally for cleanup routines to
John Criswell589d91f2003-10-16 20:15:17 +0000[diff] [blame]89 reduce the size of the program. If you're trying to find a bug in one
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]90 of these passes, <tt>bugpoint</tt> may crash. These options tell
91 <tt>bugpoint</tt> not use the specified passes.
92 <p>
93
94 <li> <tt>-help</tt>
95 <br>
96 Print a summary of command line options.
97 <p>
98
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]99 <a name="opt_input"><li><tt>-input &lt;filename&gt;</tt>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]100 <br>
101 Specify the contents of &lt;stdin&gt; when the program must be executed.
102 <p>
103
104 <li> <tt>-load &lt;plugin.so&gt;</tt>
105 <br>
106 Load the dynamic object plugin.so. This object should register new
107 optimization passes. Once loaded, the object will add new command line
108 options to enable various optimizations. To see the new complete list
109 of optimizations, use the -help and -load options together:
110 <p>
111 <tt>opt -load &lt;plugin.so&gt; -help</tt>
112 <p>
113
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]114 <a name="opt_output"><li><tt>-output &lt;filename&gt;</tt>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]115 <br>
116 Specify a reference output for the &lt;stdout&gt; file stream.
117 <p>
118
Chris Lattnerd1eb6f72003-10-18 20:36:15 +0000[diff] [blame^]119 <a name="opt_run-"><li><tt>-run-(int|jit|llc|cbe)</tt>
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]120 <br>
121 Specify which code generator <tt>bugpoint</tt> should use to run the
John Criswell589d91f2003-10-16 20:15:17 +0000[diff] [blame]122 program.
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]123 <p>
124
125</ul>
126
127<h3>EXIT STATUS</h3>
128
129If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0.
130Otherwise, if an error occurs, it will exit with a non-zero value.
131
132<h3>SEE ALSO</h3>
John Criswell589d91f2003-10-16 20:15:17 +0000[diff] [blame]133<a href="opt.html"><tt>opt</tt></a>,
Chris Lattner1213bc72003-10-07 20:33:30 +0000[diff] [blame]134<a href="analyze.html"><tt>analyze</tt></a>
135
136<HR>
137Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>.
138</body>
139</html>
140