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