2 <title>LLVM: bugpoint tool</title>
6 <center><h1>LLVM: <tt>bugpoint</tt> tool</h1></center>
13 <tt>bugpoint [options] [input LLVM ll/bc files] [LLVM passes] --args <program arguments>...</tt>
15 <img src="../Debugging.gif" width=444 height=314 align=right>
18 The <tt>bugpoint</tt> tool narrows down the source of
19 problems in LLVM tools and passes. It can be used to debug three types of
20 failures: optimizer crashes, miscompilations by optimizers, or invalid native
21 code generation. It aims to reduce large test cases to small, useful ones.
23 if <tt><a href="gccas.html">gccas</a></tt> crashes while optimizing a file, it
24 will identify the optimization (or combination of optimizations) that causes the
25 crash, and reduce the file down to a small example which triggers the crash.<p>
27 <a name="designphilosophy">
28 <h4>Design Philosophy</h4>
30 <tt>bugpoint</tt> has been designed to be a useful tool without requiring any
31 hooks into the LLVM infrastructure at all. It works with any and all LLVM
32 passes and code generators, and does not need to "know" how they work. Because
33 of this, it may appear to do a lot of stupid things or miss obvious
34 simplifications. <tt>bugpoint</tt> is also designed to trade off programmer
35 time for computer time in the compiler-debugging process; consequently, it may
36 take a long period of (unattended) time to reduce a test case, but we feel it
37 is still worth it. :-) <p>
39 <a name="automaticmodeselection">
40 <h4>Automatic Mode Selection</h4>
42 <tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file
43 specified on the command line and links them together into a single module,
44 called the test program. If any LLVM passes are
45 specified on the command line, it runs these passes on the test program. If
46 any 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>
49 Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not
50 specified, <tt>bugpoint</tt> runs the test program with the C backend (which
51 is assumed to generate good code) to generate a reference output. Once
52 <tt>bugpoint</tt> has a reference output for the test program, it tries
54 with the <a href="#opt_run-">selected</a> code generator. If
55 the resulting output differs from the reference output, it assumes the
56 difference resulted from a code generator failure, and enters
57 <a href="#codegendebug">code generator debugging mode</a>.<p>
59 Otherwise, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
60 have been applied to it. If its output differs from the reference output,
61 it assumes the difference resulted from a failure in one of the LLVM passes,
63 <a href="#miscompilationdebug">miscompilation debugging mode</a>. Otherwise,
64 there is no problem <tt>bugpoint</tt> can debug.<p>
67 <h4>Crash debugging mode</h4>
69 If an optimizer crashes, <tt>bugpoint</tt> will try as hard as it can to
70 reduce 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
72 is useful when debugging a problem exposed by <tt>gccas</tt>, for example,
73 because it runs over 30 optimizations.<p>
75 Next, <tt>bugpoint</tt> tries removing functions from the module, to reduce the
76 size of the test program. Usually it is able to reduce a test program
77 to a single function, when debugging intraprocedural optimizations. Once the
79 functions has been reduced, it attempts to delete various edges in the control
80 flow graph, to reduce the size of the function as much as possible. Finally,
81 <tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
82 not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what
83 passes crash, give you a bytecode file, and give you instructions on how to
84 reproduce the failure with <tt><a href="opt.html">opt</a></tt> or
85 <tt><a href="analyze.html">analyze</a></tt>.<p>
87 <a name="codegendebug">
88 <h4>Code generator debugging mode</h4>
90 The code generator debugger attempts to narrow down the amount of code that is
91 being miscompiled by the <a href="#opt_run-">selected</a> code generator. To do
92 this, it takes the LLVM program and partitions it into two pieces: one piece
93 which it compiles with the C backend (into a shared object), and one piece which
94 it runs with either the JIT or the static LLC compiler. It uses several
95 techniques to reduce the amount of code pushed through the LLVM code generator,
96 to reduce the potential scope of the problem. After it is finished, it emits
97 two 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
99 reproducing the problem. This module assume the C backend produces good
102 If you are using this mode and get an error message that says "Non-instruction
103 is using an external function!", try using the <tt>-run-llc</tt> option instead
104 of the <tt>-run-jit</tt> option. This is due to an unimplemented feature in the
105 code generator debugging mode.<p>
107 <a name="miscompilationdebug">
108 <h4>Miscompilation debugging mode</h4>
110 The miscompilation debugging mode works similarly to the code generator
111 debugging mode. It works by splitting the program into two pieces, running the
112 optimizations specified on one piece, relinking the program, then executing it.
113 It attempts to narrow down the list of passes to the one (or few) which are
114 causing the miscompilation, then reduce the portion of the program which is
115 being miscompiled. This module assumes that the selected code generator is
119 <a name="bugpoint notes">
120 <h4>Advice for using <tt>bugpoint</tt></h4>
122 <tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
123 non-obvious ways. Here are some hints and tips:<p>
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
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.
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.
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
139 <tt>bugpoint</tt> every time you change your optimization however, have
140 <tt>bugpoint</tt> dynamically load your optimization with the <a
141 href="#opt_load"><tt>-load</tt></a> option.
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
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>
156 <li><tt>-additional-so <library.so></tt><br>
157 Load <tt><library.so></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>
161 <li><tt>-args <program args></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><program args></tt> start with a '-', you should use:
166 <tt>bugpoint <bugpoint args> -args -- <program args></tt>
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>
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>
179 <li> <tt>-help</tt><br>
180 Print a summary of command line options.<p>
182 <a name="opt_input"><li><tt>-input <filename></tt><br>
183 Open <tt><filename></tt> and redirect the standard input of the
184 test program, whenever it runs, to come from that file.
187 <a name="opt_load"><li> <tt>-load <plugin.so></tt><br>
188 Load the dynamic object <tt><plugin.so></tt> into <tt>bugpoint</tt>
189 itself. This object should register new
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:
194 <tt>bugpoint -load <plugin.so> -help</tt>
197 <a name="opt_output"><li><tt>-output <filename></tt><br>
198 Whenever the test program produces output on its standard output
199 stream, it should match the contents of <tt><filename></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>
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>
213 If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0.
214 Otherwise, if an error occurs, it will exit with a non-zero value.
217 <a href="opt.html"><tt>opt</tt></a>,
218 <a href="analyze.html"><tt>analyze</tt></a>
221 Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>.