Gitiles
Code Review Sign In
gerrit-public.fairphone.software / toolchain / llvm-project / 8ef235e2fc4862d80c8677532d6d1048114a9a61 / . / llvm / docs / CommandGuide / bugpoint.html
blob: 4787589ad28a8df7dc79a4e9e4a145fddf5836b2 [file] [log] [blame]
Chris Lattner54cddf732003-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>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]13<tt>bugpoint [options] [input LLVM ll/bc files] [LLVM passes] --args &lt;program arguments&gt;...</tt>
Chris Lattner54cddf732003-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
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]18The <tt>bugpoint</tt> tool narrows down the source of
Chris Lattnerb0ce7e22003-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
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]21code generation. It aims to reduce large test cases to small, useful ones.
22For example,
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]23if <tt><a href="gccas.html">gccas</a></tt> crashes while optimizing a file, it
24will identify the optimization (or combination of optimizations) that causes the
25crash, and reduce the file down to a small example which triggers the crash.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]26
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]27<a name="designphilosophy">
28<h4>Design Philosophy</h4>
29
Chris Lattner90f86a72003-10-19 17:27:12 +0000[diff] [blame]30<tt>bugpoint</tt> is designed to be a useful tool without requiring any
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]31hooks into the LLVM infrastructure at all. It works with any and all LLVM
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]32passes and code generators, and does not need to "know" how they work. Because
33of this, it may appear to do a lot of stupid things or miss obvious
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]34simplifications. <tt>bugpoint</tt> is also designed to trade off programmer
35time for computer time in the compiler-debugging process; consequently, it may
36take a long period of (unattended) time to reduce a test case, but we feel it
37is still worth it. :-) <p>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]38
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]39<a name="automaticdebuggerselection">
40<h4>Automatic Debugger Selection</h4>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]41
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]42<tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file
43specified on the command line and links them together into a single module,
44called the test program. If any LLVM passes are
45specified on the command line, it runs these passes on the test program. If
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]46any of the passes crash, or if they produce malformed output,
47<tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a>.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]48
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]49Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]50specified, <tt>bugpoint</tt> runs the test program with the C backend (which
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]51is assumed to generate good code) to generate a reference output. Once
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]52<tt>bugpoint</tt> has a reference output for the test program, it tries
53executing it
54with the <a href="#opt_run-">selected</a> code generator. If
55the resulting output differs from the reference output, it assumes the
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]56difference resulted from a code generator failure, and starts the
57<a href="#codegendebug">code generator debugger</a>.<p>
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]58
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]59Otherwise, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
60have been applied to it. If its output differs from the reference output,
61it assumes the difference resulted from a failure in one of the LLVM passes,
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]62and enters the
63<a href="#miscompilationdebug">miscompilation debugger</a>. Otherwise,
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]64there is no problem <tt>bugpoint</tt> can debug.<p>
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]65
66<a name="crashdebug">
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]67<h4>Crash debugger</h4>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]68
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]69If an optimizer crashes, <tt>bugpoint</tt> will try as hard as it can to
70reduce the list of passes and the size of the test program. First,
71<tt>bugpoint</tt> figures out which combination of passes triggers the bug. This
72is useful when debugging a problem exposed by <tt>gccas</tt>, for example,
Chris Lattner90f86a72003-10-19 17:27:12 +0000[diff] [blame]73because it runs over 25 optimizations.<p>
Misha Brukman488ccea2003-10-16 18:14:43 +0000[diff] [blame]74
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]75Next, <tt>bugpoint</tt> tries removing functions from the test program, to
76reduce its
77size. Usually it is able to reduce a test program
Brian Gaekeabe08a62003-10-19 17:20:15 +0000[diff] [blame]78to a single function, when debugging intraprocedural optimizations. Once the
79number of
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]80functions has been reduced, it attempts to delete various edges in the control
81flow graph, to reduce the size of the function as much as possible. Finally,
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]82<tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]83not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what
84passes crash, give you a bytecode file, and give you instructions on how to
85reproduce the failure with <tt><a href="opt.html">opt</a></tt> or
86<tt><a href="analyze.html">analyze</a></tt>.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]87
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]88<a name="codegendebug">
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]89<h4>Code generator debugger</h4>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]90
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]91The code generator debugger attempts to narrow down the amount of code that is
92being miscompiled by the <a href="#opt_run-">selected</a> code generator. To do
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]93this, it takes the test program and partitions it into two pieces: one piece
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]94which it compiles with the C backend (into a shared object), and one piece which
95it runs with either the JIT or the static LLC compiler. It uses several
96techniques to reduce the amount of code pushed through the LLVM code generator,
97to reduce the potential scope of the problem. After it is finished, it emits
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]98two bytecode files (called "test" [to be compiled with the code generator] and
99"safe" [to be compiled with the C backend] respectively), and instructions for
100reproducing the problem. The code generator debugger assumes that the C
101backend produces good code.<p>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]102
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]103If you are using the code generator debugger and get an error message that
104says "Non-instruction
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]105is using an external function!", try using the <tt>-run-llc</tt> option instead
106of the <tt>-run-jit</tt> option. This is due to an unimplemented feature in the
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]107code generator debugger.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]108
Chris Lattnerb0ce7e22003-10-18 20:36:15 +0000[diff] [blame]109<a name="miscompilationdebug">
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]110<h4>Miscompilation debugger</h4>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]111
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]112The miscompilation debugger works similarly to the code generator
113debugger. It works by splitting the test program into two pieces, running the
114optimizations specified on one piece, linking the two pieces back together,
115and then executing the result.
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]116It attempts to narrow down the list of passes to the one (or few) which are
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]117causing the miscompilation, then reduce the portion of the test program which is
118being miscompiled. The miscompilation debugger assumes that the selected
119code generator is working properly.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]120
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]121<a name="bugpoint notes">
122<h4>Advice for using <tt>bugpoint</tt></h4>
123
124<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
125non-obvious ways. Here are some hints and tips:<p>
126
127<ol>
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]128<li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]129 works with programs that have deterministic output. Thus, if the program
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]130 outputs the date, time, or any other "random" data, <tt>bugpoint</tt> may
131 misinterpret differences in these data, when output, as the result of a
132 miscompilation. Programs should be temporarily modified to disable
133 outputs that are likely to vary from run to run.
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]134
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]135<li>In the code generator and miscompilation debuggers, debugging will go
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]136 faster if you manually modify the program or its inputs to reduce the
137 runtime, but still exhibit the problem.
138
139<li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
140 it helps track down regressions quickly. To avoid having to relink
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]141 <tt>bugpoint</tt> every time you change your optimization however, have
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]142 <tt>bugpoint</tt> dynamically load your optimization with the <a
143 href="#opt_load"><tt>-load</tt></a> option.
144
145<li><tt>bugpoint</tt> can generate a lot of output and run for a long period of
146 time. It is often useful to capture the output of the program to file. For
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]147 example, in the C shell, you can type:<br>
148 <tt>bugpoint ..... |& tee bugpoint.log</tt>
149 <br>to get a copy of <tt>bugpoint</tt>'s output in the file
150 <tt>bugpoint.log</tt>, as well as on your terminal.<p>
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]151
Brian Gaeke33534d72003-10-19 17:30:36 +0000[diff] [blame]152<li><tt>bugpoint</tt> cannot debug problems with the linker. If
153 <tt>bugpoint</tt> crashes before you see its "All input ok" message,
154 you might try <tt>llvm-link -v</tt> on the same set of input files. If
155 that also crashes, you may be experiencing a linker bug.
156
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]157</ol>
158
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]159<h3>OPTIONS</h3>
160
161<ul>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]162 <li><tt>-additional-so &lt;library.so&gt;</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]163 Load <tt>&lt;library.so&gt;</tt> into the test program whenever it is run.
164 This is useful if you are debugging programs which depend on non-LLVM
165 libraries (such as the X or curses libraries) to run.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]166
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]167 <li><tt>-args &lt;program args&gt;</tt><br>
168 Pass all arguments specified after <tt>-args</tt> to the
169 test program whenever it runs. Note that if any of
170 the <tt>&lt;program args&gt;</tt> start with a '-', you should use:
Chris Lattner9d7eeb62003-10-18 20:57:23 +0000[diff] [blame]171 <p>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]172 <tt>bugpoint &lt;bugpoint args&gt; -args -- &lt;program args&gt;</tt>
Chris Lattner9d7eeb62003-10-18 20:57:23 +0000[diff] [blame]173 <p>
174 The "<tt>--</tt>" right after the <tt>-args</tt> option tells
175 <tt>bugpoint</tt> to consider any options starting with <tt>-</tt> to be
176 part of the <tt>-args</tt> option, not as options to <tt>bugpoint</tt>
177 itself.<p>
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]178
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]179 <li><tt>-disable-{adce,dce,final-cleanup,simplifycfg}</tt><br>
180 Do not run the specified passes to clean up and reduce the size of the
181 test program. By default, <tt>bugpoint</tt> uses these passes internally
182 when attempting to reduce test programs. If you're trying to find
183 a bug in one of these passes, <tt>bugpoint</tt> may crash.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]184
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]185 <li> <tt>-help</tt><br>
186 Print a summary of command line options.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]187
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]188 <a name="opt_input"><li><tt>-input &lt;filename&gt;</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]189 Open <tt>&lt;filename&gt;</tt> and redirect the standard input of the
190 test program, whenever it runs, to come from that file.
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]191 <p>
192
Chris Lattnerf0219402003-10-18 21:34:15 +0000[diff] [blame]193 <a name="opt_load"><li> <tt>-load &lt;plugin.so&gt;</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]194 Load the dynamic object <tt>&lt;plugin.so&gt;</tt> into <tt>bugpoint</tt>
195 itself. This object should register new
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]196 optimization passes. Once loaded, the object will add new command line
197 options to enable various optimizations. To see the new complete list
198 of optimizations, use the -help and -load options together:
199 <p>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]200 <tt>bugpoint -load &lt;plugin.so&gt; -help</tt>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]201 <p>
202
Chris Lattner4b3da852003-10-18 20:54:37 +0000[diff] [blame]203 <a name="opt_output"><li><tt>-output &lt;filename&gt;</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]204 Whenever the test program produces output on its standard output
205 stream, it should match the contents of <tt>&lt;filename&gt;</tt>
206 (the "reference output"). If you do not use this option,
207 <tt>bugpoint</tt> will attempt to generate a reference output by
208 compiling the program with the C backend and running it.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]209
Brian Gaeke8ef235e2003-10-19 17:35:35 +0000[diff] [blame^]210 <a name="opt_run-"><li><tt>-run-{int,jit,llc,cbe}</tt><br>
Brian Gaekec8cff0e2003-10-19 17:03:59 +0000[diff] [blame]211 Whenever the test program is compiled, <tt>bugpoint</tt> should generate
212 code for it using the specified code generator. These options allow
213 you to choose the interpreter, the JIT compiler, the static native
214 code compiler, or the C backend, respectively.<p>
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]215</ul>
216
217<h3>EXIT STATUS</h3>
218
219If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0.
220Otherwise, if an error occurs, it will exit with a non-zero value.
221
222<h3>SEE ALSO</h3>
John Criswell38458952003-10-16 20:15:17 +0000[diff] [blame]223<a href="opt.html"><tt>opt</tt></a>,
Chris Lattner54cddf732003-10-07 20:33:30 +0000[diff] [blame]224<a href="analyze.html"><tt>analyze</tt></a>
225
226<HR>
227Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>.
228</body>
229</html>