| 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> |
| Chris Lattner | 83273d5 | 2003-10-07 20:33:52 +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 | |
| 18 | The <tt>bugpoint</tt> tool is a generally useful tool for narrowing down |
| 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 |
| 21 | code generation. It aims to reduce testcases to something useful. For example, |
| 22 | if <tt><a href="gccas.html">gccas</a></tt> crashes while optimizing a file, it |
| 23 | will identify the optimization (or combination of optimizations) that causes the |
| 24 | 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] | 25 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 26 | <tt>bugpoint</tt> has been designed to be a useful tool without requiring any |
| 27 | hooks into the LLVM intrastructure at all. It works with any and all LLVM |
| 28 | passes and code generators, and does not need to "know" how they work. Because |
| 29 | of this, it may appear to do a lot of stupid things or miss obvious |
| 30 | simplifications. Remember, however, that computer time is much cheaper than |
| 31 | programmer time, so if it takes a long time to reduce a testcase it is still |
| 32 | worth it. :)<p> |
| 33 | |
| 34 | <a name="crashdebug"> |
| 35 | <h4>Automatic Mode Selection</h4> |
| 36 | |
| Chris Lattner | d1eb6f7 | 2003-10-18 20:36:15 +0000 | [diff] [blame] | 37 | <tt>bugpoint</tt> reads the specified list of <tt>.bc</tt> or <tt>.ll</tt> files |
| 38 | specified on the command-line and links them together. If any LLVM passes are |
| 39 | specified on the command line, it runs these passes on the resultant module. If |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 40 | any of the passes crash, or if they produce a malformed LLVM module, |
| 41 | <tt>bugpoint</tt> enters <a href="#crashdebug">crash debugging mode</a>.<p> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 42 | |
| Chris Lattner | d1eb6f7 | 2003-10-18 20:36:15 +0000 | [diff] [blame] | 43 | Otherwise, if the <a href="#opt_output"><tt>-output</tt></a> option was not |
| 44 | specified, <tt>bugpoint</tt> runs the initial program with the C backend (which |
| 45 | is assumed to generate good code) to generate a reference output. Once |
| 46 | <tt>bugpoint</tt> has a reference output to match, it tries executing the |
| 47 | original program with the <a href="#opt_run-">selected</a> code generator. If |
| 48 | the resultant output is different than the reference output, it exters <a |
| 49 | href="#codegendebug">code generator debugging mode</a>.<p> |
| 50 | |
| 51 | Otherwise, <tt>bugpoint</tt> runs the LLVM program after all of the LLVM passes |
| 52 | have been applied to it. If the executed program matches the reference output, |
| 53 | there is no problem <tt>bugpoint</tt> can debug. Otherwise, it enters <a |
| 54 | href="#miscompilationdebug">miscompilation debugging mode</a>.<p> |
| 55 | |
| 56 | <a name="crashdebug"> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 57 | <h4>Crash debugging mode</h4> |
| 58 | |
| Chris Lattner | d1eb6f7 | 2003-10-18 20:36:15 +0000 | [diff] [blame] | 59 | If an optimizer crashes, <tt>bugpoint</tt> will try a variety of techniques to |
| 60 | narrow down the list of passes and the code to a more manageable amount. First, |
| 61 | <tt>bugpoint</tt> figures out which combination of passes trigger the bug. This |
| 62 | is useful when debugging a problem exposed by <tt>gccas</tt> for example, |
| 63 | because it has over 30 optimization it runs.<p> |
| Misha Brukman | 3f71722 | 2003-10-16 18:14:43 +0000 | [diff] [blame] | 64 | |
| Chris Lattner | d1eb6f7 | 2003-10-18 20:36:15 +0000 | [diff] [blame] | 65 | Next, <tt>bugpoint</tt> tries removing functions from the module, to reduce the |
| 66 | size of the testcase to a reasonable amount. Usually it is able to get it down |
| 67 | to a single function for intraprocedural optimizations. Once the number of |
| 68 | functions has been reduced, it attempts to delete various edges in the control |
| 69 | flow graph, to reduce the size of the function as much as possible. Finally, |
| 70 | <tt>bugpoint</tt> deletes any individual LLVM instructions whose absense does |
| 71 | not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what |
| 72 | passes crash, give you a bytecode file, and give you instructions on how to |
| 73 | reproduce the failure with <tt><a href="opt.html">opt</a></tt> or |
| 74 | <tt><a href="analyze.html">analyze</a></tt>.<p> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 75 | |
| Chris Lattner | d1eb6f7 | 2003-10-18 20:36:15 +0000 | [diff] [blame] | 76 | <a name="codegendebug"> |
| 77 | <h4>Code generator debugging mode</h4> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 78 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 79 | The code generator debugger attempts to narrow down the amount of code that is |
| 80 | being miscompiled by the <a href="#opt_run-">selected</a> code generator. To do |
| 81 | this, it takes the LLVM program and partitions it into two pieces: one piece |
| 82 | which it compiles with the C backend (into a shared object), and one piece which |
| 83 | it runs with either the JIT or the static LLC compiler. It uses several |
| 84 | techniques to reduce the amount of code pushed through the LLVM code generator, |
| 85 | to reduce the potential scope of the problem. After it is finished, it emits |
| 86 | two bytecode files (the "test" [to be compiled with the code generator] and |
| 87 | "safe" [to be compiled with the C backend] modules), and instructions for |
| 88 | reproducing the problem. This module assume the C backend produces good |
| 89 | code.<p> |
| 90 | |
| 91 | If you are using this mode and get an error message that says "Non-instruction |
| 92 | is using an external function!", try using the <tt>-run-llc</tt> option instead |
| 93 | of the <tt>-run-jit</tt> option. This is due to an unimplemented feature in the |
| 94 | code generator debugging mode.<p> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 95 | |
| Chris Lattner | d1eb6f7 | 2003-10-18 20:36:15 +0000 | [diff] [blame] | 96 | <a name="miscompilationdebug"> |
| 97 | <h4>Miscompilation debugging mode</h4> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 98 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 99 | The miscompilation debugging mode works similarly to the code generator |
| 100 | debugging mode. It works by splitting the program into two pieces, running the |
| 101 | optimizations specified on one piece, relinking the program, then executing it. |
| 102 | It attempts to narrow down the list of passes to the one (or few) which are |
| 103 | causing the miscompilation, then reduce the portion of the program which is |
| 104 | being miscompiled. This module assumes that the selected code generator is |
| 105 | working properly.<p> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 106 | |
| 107 | |
| 108 | <h3>OPTIONS</h3> |
| 109 | |
| 110 | <ul> |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 111 | <li><tt>-additional-so <library.so></tt><br> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 112 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 113 | Use this option to specify .so files which must be loaded by the program |
| 114 | when it is run. This is useful if you are debugging programs which |
| 115 | depend on non-LLVM libraries (such as the X or curses libraries) to |
| 116 | run.<p> |
| 117 | |
| 118 | <li><tt>-args <arguments></tt><br> |
| 119 | All arguments specified after <tt>-args</tt> are passed into the |
| 120 | executed program when the program must be executed.<p> |
| 121 | |
| 122 | <li><tt>-disable-(adce,dce,final-cleanup,simplifycfg)</tt><br> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 123 | <tt>bugpoint</tt> uses several passes internally for cleanup routines to |
| John Criswell | 589d91f | 2003-10-16 20:15:17 +0000 | [diff] [blame] | 124 | reduce the size of the program. If you're trying to find a bug in one |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 125 | of these passes, <tt>bugpoint</tt> may crash. These options tell |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 126 | <tt>bugpoint</tt> not use the specified passes.<p> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 127 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 128 | <li> <tt>-help</tt><br> |
| 129 | Print a summary of command line options.<p> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 130 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 131 | <a name="opt_input"><li><tt>-input <filename></tt><br> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 132 | Specify the contents of <stdin> when the program must be executed. |
| 133 | <p> |
| 134 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 135 | <li> <tt>-load <plugin.so></tt><br> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 136 | Load the dynamic object plugin.so. This object should register new |
| 137 | optimization passes. Once loaded, the object will add new command line |
| 138 | options to enable various optimizations. To see the new complete list |
| 139 | of optimizations, use the -help and -load options together: |
| 140 | <p> |
| 141 | <tt>opt -load <plugin.so> -help</tt> |
| 142 | <p> |
| 143 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 144 | <a name="opt_output"><li><tt>-output <filename></tt><br> |
| 145 | Specify a reference output for the <stdout> file stream.<p> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 146 | |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 147 | <a name="opt_run-"><li><tt>-run-(int|jit|llc|cbe)</tt><br> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 148 | Specify which code generator <tt>bugpoint</tt> should use to run the |
| Chris Lattner | 5cd840c | 2003-10-18 20:54:37 +0000 | [diff] [blame^] | 149 | program. You may choose the interpreter, the JIT compiler, the static |
| 150 | native code compiler, or the C backend.<p> |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 151 | </ul> |
| 152 | |
| 153 | <h3>EXIT STATUS</h3> |
| 154 | |
| 155 | If <tt>bugpoint</tt> succeeds in finding a problem, it will exit with 0. |
| 156 | Otherwise, if an error occurs, it will exit with a non-zero value. |
| 157 | |
| 158 | <h3>SEE ALSO</h3> |
| John Criswell | 589d91f | 2003-10-16 20:15:17 +0000 | [diff] [blame] | 159 | <a href="opt.html"><tt>opt</tt></a>, |
| Chris Lattner | 1213bc7 | 2003-10-07 20:33:30 +0000 | [diff] [blame] | 160 | <a href="analyze.html"><tt>analyze</tt></a> |
| 161 | |
| 162 | <HR> |
| 163 | Maintained by the <a href="http://llvm.cs.uiuc.edu">LLVM Team</a>. |
| 164 | </body> |
| 165 | </html> |
| 166 | |