It's not necessary to do rounding for alloca operations when the requested
alignment is equal to the stack alignment.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@40004 91177308-0d34-0410-b5e6-96231b3b80d8
diff --git a/docs/Bugpoint.html b/docs/Bugpoint.html
new file mode 100644
index 0000000..bdfd313
--- /dev/null
+++ b/docs/Bugpoint.html
@@ -0,0 +1,244 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title>LLVM bugpoint tool: design and usage</title>
+ <link rel="stylesheet" href="llvm.css" type="text/css">
+</head>
+
+<div class="doc_title">
+ LLVM bugpoint tool: design and usage
+</div>
+
+<ul>
+ <li><a href="#desc">Description</a></li>
+ <li><a href="#design">Design Philosophy</a>
+ <ul>
+ <li><a href="#autoselect">Automatic Debugger Selection</a></li>
+ <li><a href="#crashdebug">Crash debugger</a></li>
+ <li><a href="#codegendebug">Code generator debugger</a></li>
+ <li><a href="#miscompilationdebug">Miscompilation debugger</a></li>
+ </ul></li>
+ <li><a href="#advice">Advice for using <tt>bugpoint</tt></a></li>
+</ul>
+
+<div class="doc_author">
+<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
+</div>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+<a name="desc">Description</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<p><tt>bugpoint</tt> narrows down the source of problems in LLVM tools and
+passes. It can be used to debug three types of failures: optimizer crashes,
+miscompilations by optimizers, or bad native code generation (including problems
+in the static and JIT compilers). It aims to reduce large test cases to small,
+useful ones. For example, if <tt>opt</tt> crashes while optimizing a
+file, it will identify the optimization (or combination of optimizations) that
+causes the crash, and reduce the file down to a small example which triggers the
+crash.</p>
+
+<p>For detailed case scenarios, such as debugging <tt>opt</tt>,
+<tt>llvm-ld</tt>, or one of the LLVM code generators, see <a
+href="HowToSubmitABug.html">How To Submit a Bug Report document</a>.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+<a name="design">Design Philosophy</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<p><tt>bugpoint</tt> is designed to be a useful tool without requiring any
+hooks into the LLVM infrastructure at all. It works with any and all LLVM
+passes and code generators, and does not need to "know" how they work. Because
+of this, it may appear to do stupid things or miss obvious
+simplifications. <tt>bugpoint</tt> is also designed to trade off programmer
+time for computer time in the compiler-debugging process; consequently, it may
+take a long period of (unattended) time to reduce a test case, but we feel it
+is still worth it. Note that <tt>bugpoint</tt> is generally very quick unless
+debugging a miscompilation where each test of the program (which requires
+executing it) takes a long time.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="autoselect">Automatic Debugger Selection</a>
+</div>
+
+<div class="doc_text">
+
+<p><tt>bugpoint</tt> reads each <tt>.bc</tt> or <tt>.ll</tt> file specified on
+the command line and links them together into a single module, called the test
+program. If any LLVM passes are specified on the command line, it runs these
+passes on the test program. If any of the passes crash, or if they produce
+malformed output (which causes the verifier to abort), <tt>bugpoint</tt> starts
+the <a href="#crashdebug">crash debugger</a>.</p>
+
+<p>Otherwise, if the <tt>-output</tt> option was not specified,
+<tt>bugpoint</tt> runs the test program with the C backend (which is assumed to
+generate good code) to generate a reference output. Once <tt>bugpoint</tt> has
+a reference output for the test program, it tries executing it with the
+selected code generator. If the selected code generator crashes,
+<tt>bugpoint</tt> starts the <a href="#crashdebug">crash debugger</a> on the
+code generator. Otherwise, if the resulting output differs from the reference
+output, it assumes the difference resulted from a code generator failure, and
+starts the <a href="#codegendebug">code generator debugger</a>.</p>
+
+<p>Finally, if the output of the selected code generator matches the reference
+output, <tt>bugpoint</tt> runs the test program after all of the LLVM passes
+have been applied to it. If its output differs from the reference output, it
+assumes the difference resulted from a failure in one of the LLVM passes, and
+enters the <a href="#miscompilationdebug">miscompilation debugger</a>.
+Otherwise, there is no problem <tt>bugpoint</tt> can debug.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="crashdebug">Crash debugger</a>
+</div>
+
+<div class="doc_text">
+
+<p>If an optimizer or code generator crashes, <tt>bugpoint</tt> will try as hard
+as it can to reduce the list of passes (for optimizer crashes) and the size of
+the test program. First, <tt>bugpoint</tt> figures out which combination of
+optimizer passes triggers the bug. This is useful when debugging a problem
+exposed by <tt>opt</tt>, for example, because it runs over 38 passes.</p>
+
+<p>Next, <tt>bugpoint</tt> tries removing functions from the test program, to
+reduce its size. Usually it is able to reduce a test program to a single
+function, when debugging intraprocedural optimizations. Once the number of
+functions has been reduced, it attempts to delete various edges in the control
+flow graph, to reduce the size of the function as much as possible. Finally,
+<tt>bugpoint</tt> deletes any individual LLVM instructions whose absence does
+not eliminate the failure. At the end, <tt>bugpoint</tt> should tell you what
+passes crash, give you a bitcode file, and give you instructions on how to
+reproduce the failure with <tt>opt</tt> or <tt>llc</tt>.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="codegendebug">Code generator debugger</a>
+</div>
+
+<div class="doc_text">
+
+<p>The code generator debugger attempts to narrow down the amount of code that
+is being miscompiled by the selected code generator. To do this, it takes the
+test program and partitions it into two pieces: one piece which it compiles
+with the C backend (into a shared object), and one piece which it runs with
+either the JIT or the static LLC compiler. It uses several techniques to
+reduce the amount of code pushed through the LLVM code generator, to reduce the
+potential scope of the problem. After it is finished, it emits two bitcode
+files (called "test" [to be compiled with the code generator] and "safe" [to be
+compiled with the C backend], respectively), and instructions for reproducing
+the problem. The code generator debugger assumes that the C backend produces
+good code.</p>
+
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+ <a name="miscompilationdebug">Miscompilation debugger</a>
+</div>
+
+<div class="doc_text">
+
+<p>The miscompilation debugger works similarly to the code generator debugger.
+It works by splitting the test program into two pieces, running the
+optimizations specified on one piece, linking the two pieces back together, and
+then executing the result. It attempts to narrow down the list of passes to
+the one (or few) which are causing the miscompilation, then reduce the portion
+of the test program which is being miscompiled. The miscompilation debugger
+assumes that the selected code generator is working properly.</p>
+
+</div>
+
+<!-- *********************************************************************** -->
+<div class="doc_section">
+ <a name="advice">Advice for using bugpoint</a>
+</div>
+<!-- *********************************************************************** -->
+
+<div class="doc_text">
+
+<tt>bugpoint</tt> can be a remarkably useful tool, but it sometimes works in
+non-obvious ways. Here are some hints and tips:<p>
+
+<ol>
+<li>In the code generator and miscompilation debuggers, <tt>bugpoint</tt> only
+ works with programs that have deterministic output. Thus, if the program
+ outputs <tt>argv[0]</tt>, the date, time, or any other "random" data,
+ <tt>bugpoint</tt> may misinterpret differences in these data, when output,
+ as the result of a miscompilation. Programs should be temporarily modified
+ to disable outputs that are likely to vary from run to run.
+
+<li>In the code generator and miscompilation debuggers, debugging will go
+ faster if you manually modify the program or its inputs to reduce the
+ runtime, but still exhibit the problem.
+
+<li><tt>bugpoint</tt> is extremely useful when working on a new optimization:
+ it helps track down regressions quickly. To avoid having to relink
+ <tt>bugpoint</tt> every time you change your optimization however, have
+ <tt>bugpoint</tt> dynamically load your optimization with the
+ <tt>-load</tt> option.
+
+<li><p><tt>bugpoint</tt> can generate a lot of output and run for a long period
+ of time. It is often useful to capture the output of the program to file.
+ For example, in the C shell, you can run:</p>
+
+<div class="doc_code">
+<p><tt>bugpoint ... |& tee bugpoint.log</tt></p>
+</div>
+
+ <p>to get a copy of <tt>bugpoint</tt>'s output in the file
+ <tt>bugpoint.log</tt>, as well as on your terminal.</p>
+
+<li><tt>bugpoint</tt> cannot debug problems with the LLVM linker. If
+ <tt>bugpoint</tt> crashes before you see its "All input ok" message,
+ you might try <tt>llvm-link -v</tt> on the same set of input files. If
+ that also crashes, you may be experiencing a linker bug.
+
+<li>If your program is <b>supposed</b> to crash, <tt>bugpoint</tt> will be
+ confused. One way to deal with this is to cause bugpoint to ignore the exit
+ code from your program, by giving it the <tt>-check-exit-code=false</tt>
+ option.
+
+<li><tt>bugpoint</tt> is useful for proactively finding bugs in LLVM.
+ Invoking <tt>bugpoint</tt> with the <tt>-find-bugs</tt> option will cause
+ the list of specified optimizations to be randomized and applied to the
+ program. This process will repeat until a bug is found or the user
+ kills <tt>bugpoint</tt>.
+
+</ol>
+
+</div>
+
+<!-- *********************************************************************** -->
+
+<hr>
+<address>
+ <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
+ src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
+ <a href="http://validator.w3.org/check/referer"><img
+ src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
+
+ <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
+ <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
+ Last modified: $Date$
+</address>
+
+</body>
+</html>