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