diff options
| -rw-r--r-- | docs/HowToSubmitABug.html | 345 | ||||
| -rw-r--r-- | docs/HowToSubmitABug.rst | 233 | ||||
| -rw-r--r-- | docs/userguides.rst | 3 |
3 files changed, 235 insertions, 346 deletions
diff --git a/docs/HowToSubmitABug.html b/docs/HowToSubmitABug.html deleted file mode 100644 index 39f8385..0000000 --- a/docs/HowToSubmitABug.html +++ /dev/null @@ -1,345 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" - "http://www.w3.org/TR/html4/strict.dtd"> -<html> -<head> - <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> - <title>How to submit an LLVM bug report</title> - <link rel="stylesheet" href="_static/llvm.css" type="text/css"> -</head> -<body> - -<h1> - How to submit an LLVM bug report -</h1> - -<table class="layout" style="width: 90%" > -<tr class="layout"> - <td class="left"> -<ol> - <li><a href="#introduction">Introduction - Got bugs?</a></li> - <li><a href="#crashers">Crashing Bugs</a> - <ul> - <li><a href="#front-end">Front-end bugs</a> - <li><a href="#ct_optimizer">Compile-time optimization bugs</a> - <li><a href="#ct_codegen">Code generator bugs</a> - </ul></li> - <li><a href="#miscompilations">Miscompilations</a></li> - <li><a href="#codegen">Incorrect code generation (JIT and LLC)</a></li> -</ol> -<div class="doc_author"> - <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and - <a href="http://misha.brukman.net">Misha Brukman</a></p> -</div> -</td> -</tr> -</table> - -<!-- *********************************************************************** --> -<h2> - <a name="introduction">Introduction - Got bugs?</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<p>If you're working with LLVM and run into a bug, we definitely want to know -about it. This document describes what you can do to increase the odds of -getting it fixed quickly.</p> - -<p>Basically you have to do two things at a minimum. First, decide whether the -bug <a href="#crashers">crashes the compiler</a> (or an LLVM pass), or if the -compiler is <a href="#miscompilations">miscompiling</a> the program (i.e., the -compiler successfully produces an executable, but it doesn't run right). Based -on -what type of bug it is, follow the instructions in the linked section to narrow -down the bug so that the person who fixes it will be able to find the problem -more easily.</p> - -<p>Once you have a reduced test-case, go to <a -href="http://llvm.org/bugs/enter_bug.cgi">the LLVM Bug Tracking -System</a> and fill out the form with the necessary details (note that you don't -need to pick a category, just use the "new-bugs" category if you're not sure). -The bug description should contain the following -information:</p> - -<ul> - <li>All information necessary to reproduce the problem.</li> - <li>The reduced test-case that triggers the bug.</li> - <li>The location where you obtained LLVM (if not from our Subversion - repository).</li> -</ul> - -<p>Thanks for helping us make LLVM better!</p> - -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="crashers">Crashing Bugs</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<p>More often than not, bugs in the compiler cause it to crash—often due -to an assertion failure of some sort. The most important -piece of the puzzle is to figure out if it is crashing in the GCC front-end -or if it is one of the LLVM libraries (e.g. the optimizer or code generator) -that has problems.</p> - -<p>To figure out which component is crashing (the front-end, -optimizer or code generator), run the -<tt><b>llvm-gcc</b></tt> command line as you were when the crash occurred, but -with the following extra command line options:</p> - -<ul> - <li><tt><b>-O0 -emit-llvm</b></tt>: If <tt>llvm-gcc</tt> still crashes when - passed these options (which disable the optimizer and code generator), then - the crash is in the front-end. Jump ahead to the section on <a - href="#front-end">front-end bugs</a>.</li> - - <li><tt><b>-emit-llvm</b></tt>: If <tt>llvm-gcc</tt> crashes with this option - (which disables the code generator), you found an optimizer bug. Jump ahead - to <a href="#ct_optimizer"> compile-time optimization bugs</a>.</li> - - <li>Otherwise, you have a code generator crash. Jump ahead to <a - href="#ct_codegen">code generator bugs</a>.</li> - -</ul> - -<!-- ======================================================================= --> -<h3> - <a name="front-end">Front-end bugs</a> -</h3> - -<div> - -<p>If the problem is in the front-end, you should re-run the same -<tt>llvm-gcc</tt> command that resulted in the crash, but add the -<tt>-save-temps</tt> option. The compiler will crash again, but it will leave -behind a <tt><i>foo</i>.i</tt> file (containing preprocessed C source code) and -possibly <tt><i>foo</i>.s</tt> for each -compiled <tt><i>foo</i>.c</tt> file. Send us the <tt><i>foo</i>.i</tt> file, -along with the options you passed to llvm-gcc, and a brief description of the -error it caused.</p> - -<p>The <a href="http://delta.tigris.org/">delta</a> tool helps to reduce the -preprocessed file down to the smallest amount of code that still replicates the -problem. You're encouraged to use delta to reduce the code to make the -developers' lives easier. <a -href="http://gcc.gnu.org/wiki/A_guide_to_testcase_reduction">This website</a> -has instructions on the best way to use delta.</p> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="ct_optimizer">Compile-time optimization bugs</a> -</h3> - -<div> - -<p>If you find that a bug crashes in the optimizer, compile your test-case to a -<tt>.bc</tt> file by passing "<tt><b>-emit-llvm -O0 -c -o foo.bc</b></tt>". -Then run:</p> - -<div class="doc_code"> -<p><tt><b>opt</b> -std-compile-opts -debug-pass=Arguments foo.bc - -disable-output</tt></p> -</div> - -<p>This command should do two things: it should print out a list of passes, and -then it should crash in the same way as llvm-gcc. If it doesn't crash, please -follow the instructions for a <a href="#front-end">front-end bug</a>.</p> - -<p>If this does crash, then you should be able to debug this with the following -bugpoint command:</p> - -<div class="doc_code"> -<p><tt><b>bugpoint</b> foo.bc <list of passes printed by -<b>opt</b>></tt></p> -</div> - -<p>Please run this, then file a bug with the instructions and reduced .bc files -that bugpoint emits. If something goes wrong with bugpoint, please submit the -"foo.bc" file and the list of passes printed by <b>opt</b>.</p> - -</div> - -<!-- ======================================================================= --> -<h3> - <a name="ct_codegen">Code generator bugs</a> -</h3> - -<div> - -<p>If you find a bug that crashes llvm-gcc in the code generator, compile your -source file to a .bc file by passing "<tt><b>-emit-llvm -c -o foo.bc</b></tt>" -to llvm-gcc (in addition to the options you already pass). Once your have -foo.bc, one of the following commands should fail:</p> - -<ol> -<li><tt><b>llc</b> foo.bc</tt></li> -<li><tt><b>llc</b> foo.bc -relocation-model=pic</tt></li> -<li><tt><b>llc</b> foo.bc -relocation-model=static</tt></li> -</ol> - -<p>If none of these crash, please follow the instructions for a -<a href="#front-end">front-end bug</a>. If one of these do crash, you should -be able to reduce this with one of the following bugpoint command lines (use -the one corresponding to the command above that failed):</p> - -<ol> -<li><tt><b>bugpoint</b> -run-llc foo.bc</tt></li> -<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args - -relocation-model=pic</tt></li> -<li><tt><b>bugpoint</b> -run-llc foo.bc --tool-args - -relocation-model=static</tt></li> -</ol> - -<p>Please run this, then file a bug with the instructions and reduced .bc file -that bugpoint emits. If something goes wrong with bugpoint, please submit the -"foo.bc" file and the option that llc crashes with.</p> - -</div> - -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="miscompilations">Miscompilations</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<p>If llvm-gcc successfully produces an executable, but that executable doesn't -run right, this is either a bug in the code or a bug in the -compiler. The first thing to check is to make sure it is not using undefined -behavior (e.g. reading a variable before it is defined). In particular, check -to see if the program <a href="http://valgrind.org/">valgrind</a>s clean, -passes purify, or some other memory checker tool. Many of the "LLVM bugs" that -we have chased down ended up being bugs in the program being compiled, not - LLVM.</p> - -<p>Once you determine that the program itself is not buggy, you should choose -which code generator you wish to compile the program with (e.g. LLC or the JIT) -and optionally a series of LLVM passes to run. For example:</p> - -<div class="doc_code"> -<p><tt> -<b>bugpoint</b> -run-llc [... optzn passes ...] file-to-test.bc --args -- [program arguments]</tt></p> -</div> - -<p><tt>bugpoint</tt> will try to narrow down your list of passes to the one pass -that causes an error, and simplify the bitcode file as much as it can to assist -you. It will print a message letting you know how to reproduce the resulting -error.</p> - -</div> - -<!-- *********************************************************************** --> -<h2> - <a name="codegen">Incorrect code generation</a> -</h2> -<!-- *********************************************************************** --> - -<div> - -<p>Similarly to debugging incorrect compilation by mis-behaving passes, you can -debug incorrect code generation by either LLC or the JIT, using -<tt>bugpoint</tt>. The process <tt>bugpoint</tt> follows in this case is to try -to narrow the code down to a function that is miscompiled by one or the other -method, but since for correctness, the entire program must be run, -<tt>bugpoint</tt> will compile the code it deems to not be affected with the C -Backend, and then link in the shared object it generates.</p> - -<p>To debug the JIT:</p> - -<div class="doc_code"> -<pre> -bugpoint -run-jit -output=[correct output file] [bitcode file] \ - --tool-args -- [arguments to pass to lli] \ - --args -- [program arguments] -</pre> -</div> - -<p>Similarly, to debug the LLC, one would run:</p> - -<div class="doc_code"> -<pre> -bugpoint -run-llc -output=[correct output file] [bitcode file] \ - --tool-args -- [arguments to pass to llc] \ - --args -- [program arguments] -</pre> -</div> - -<p><b>Special note:</b> if you are debugging MultiSource or SPEC tests that -already exist in the <tt>llvm/test</tt> hierarchy, there is an easier way to -debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which -will pass the program options specified in the Makefiles:</p> - -<div class="doc_code"> -<p><tt> -cd llvm/test/../../program<br> -make bugpoint-jit -</tt></p> -</div> - -<p>At the end of a successful <tt>bugpoint</tt> run, you will be presented -with two bitcode files: a <em>safe</em> file which can be compiled with the C -backend and the <em>test</em> file which either LLC or the JIT -mis-codegenerates, and thus causes the error.</p> - -<p>To reproduce the error that <tt>bugpoint</tt> found, it is sufficient to do -the following:</p> - -<ol> - -<li><p>Regenerate the shared object from the safe bitcode file:</p> - -<div class="doc_code"> -<p><tt> -<b>llc</b> -march=c safe.bc -o safe.c<br> -<b>gcc</b> -shared safe.c -o safe.so -</tt></p> -</div></li> - -<li><p>If debugging LLC, compile test bitcode native and link with the shared - object:</p> - -<div class="doc_code"> -<p><tt> -<b>llc</b> test.bc -o test.s<br> -<b>gcc</b> test.s safe.so -o test.llc<br> -./test.llc [program options] -</tt></p> -</div></li> - -<li><p>If debugging the JIT, load the shared object and supply the test - bitcode:</p> - -<div class="doc_code"> -<p><tt><b>lli</b> -load=safe.so test.bc [program options]</tt></p> -</div></li> - -</ol> - -</div> - -<!-- *********************************************************************** --> -<hr> -<address> - <a href="http://jigsaw.w3.org/css-validator/check/referer"><img - src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> - <a href="http://validator.w3.org/check/referer"><img - src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> - - <a href="mailto:sabre@nondot.org">Chris Lattner</a><br> - <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a> - <br> - Last modified: $Date$ -</address> - -</body> -</html> diff --git a/docs/HowToSubmitABug.rst b/docs/HowToSubmitABug.rst new file mode 100644 index 0000000..ff2d649 --- /dev/null +++ b/docs/HowToSubmitABug.rst @@ -0,0 +1,233 @@ +.. _how-to-submit-a-bug-report: + +================================ +How to submit an LLVM bug report +================================ + +.. sectionauthor:: Chris Lattner <sabre@nondot.org> and Misha Brukman <http://misha.brukman.net> + +Introduction - Got bugs? +======================== + + +If you're working with LLVM and run into a bug, we definitely want to know +about it. This document describes what you can do to increase the odds of +getting it fixed quickly. + +Basically you have to do two things at a minimum. First, decide whether +the bug `crashes the compiler`_ (or an LLVM pass), or if the +compiler is `miscompiling`_ the program (i.e., the +compiler successfully produces an executable, but it doesn't run right). +Based on what type of bug it is, follow the instructions in the linked +section to narrow down the bug so that the person who fixes it will be able +to find the problem more easily. + +Once you have a reduced test-case, go to `the LLVM Bug Tracking System +<http://llvm.org/bugs/enter_bug.cgi>`_ and fill out the form with the +necessary details (note that you don't need to pick a category, just use +the "new-bugs" category if you're not sure). The bug description should +contain the following information: + +* All information necessary to reproduce the problem. +* The reduced test-case that triggers the bug. +* The location where you obtained LLVM (if not from our Subversion + repository). + +Thanks for helping us make LLVM better! + +.. _crashes the compiler: + +Crashing Bugs +============= + +More often than not, bugs in the compiler cause it to crash---often due to +an assertion failure of some sort. The most important piece of the puzzle +is to figure out if it is crashing in the GCC front-end or if it is one of +the LLVM libraries (e.g. the optimizer or code generator) that has +problems. + +To figure out which component is crashing (the front-end, optimizer or code +generator), run the ``llvm-gcc`` command line as you were when the crash +occurred, but with the following extra command line options: + +* ``-O0 -emit-llvm``: If ``llvm-gcc`` still crashes when passed these + options (which disable the optimizer and code generator), then the crash + is in the front-end. Jump ahead to the section on :ref:`front-end bugs + <front-end>`. + +* ``-emit-llvm``: If ``llvm-gcc`` crashes with this option (which disables + the code generator), you found an optimizer bug. Jump ahead to + `compile-time optimization bugs`_. + +* Otherwise, you have a code generator crash. Jump ahead to `code + generator bugs`_. + +.. _front-end bug: +.. _front-end: + +Front-end bugs +-------------- + +If the problem is in the front-end, you should re-run the same ``llvm-gcc`` +command that resulted in the crash, but add the ``-save-temps`` option. +The compiler will crash again, but it will leave behind a ``foo.i`` file +(containing preprocessed C source code) and possibly ``foo.s`` for each +compiled ``foo.c`` file. Send us the ``foo.i`` file, along with the options +you passed to ``llvm-gcc``, and a brief description of the error it caused. + +The `delta <http://delta.tigris.org/>`_ tool helps to reduce the +preprocessed file down to the smallest amount of code that still replicates +the problem. You're encouraged to use delta to reduce the code to make the +developers' lives easier. `This website +<http://gcc.gnu.org/wiki/A_guide_to_testcase_reduction>`_ has instructions +on the best way to use delta. + +.. _compile-time optimization bugs: + +Compile-time optimization bugs +------------------------------ + +If you find that a bug crashes in the optimizer, compile your test-case to a +``.bc`` file by passing "``-emit-llvm -O0 -c -o foo.bc``". +Then run: + +.. code-block:: bash + + opt -std-compile-opts -debug-pass=Arguments foo.bc -disable-output + +This command should do two things: it should print out a list of passes, and +then it should crash in the same way as llvm-gcc. If it doesn't crash, please +follow the instructions for a `front-end bug`_. + +If this does crash, then you should be able to debug this with the following +bugpoint command: + +.. code-block:: bash + + bugpoint foo.bc <list of passes printed by opt> + +Please run this, then file a bug with the instructions and reduced .bc +files that bugpoint emits. If something goes wrong with bugpoint, please +submit the "foo.bc" file and the list of passes printed by ``opt``. + +.. _code generator bugs: + +Code generator bugs +------------------- + +If you find a bug that crashes llvm-gcc in the code generator, compile your +source file to a .bc file by passing "``-emit-llvm -c -o foo.bc``" to +llvm-gcc (in addition to the options you already pass). Once your have +foo.bc, one of the following commands should fail: + +#. ``llc foo.bc`` +#. ``llc foo.bc -relocation-model=pic`` +#. ``llc foo.bc -relocation-model=static`` + +If none of these crash, please follow the instructions for a `front-end +bug`_. If one of these do crash, you should be able to reduce this with +one of the following bugpoint command lines (use the one corresponding to +the command above that failed): + +#. ``bugpoint -run-llc foo.bc`` +#. ``bugpoint -run-llc foo.bc --tool-args -relocation-model=pic`` +#. ``bugpoint -run-llc foo.bc --tool-args -relocation-model=static`` + +Please run this, then file a bug with the instructions and reduced .bc file +that bugpoint emits. If something goes wrong with bugpoint, please submit +the "foo.bc" file and the option that llc crashes with. + +.. _miscompiling: + +Miscompilations +=============== + +If llvm-gcc successfully produces an executable, but that executable +doesn't run right, this is either a bug in the code or a bug in the +compiler. The first thing to check is to make sure it is not using +undefined behavior (e.g. reading a variable before it is defined). In +particular, check to see if the program `valgrind +<http://valgrind.org/>`_'s clean, passes purify, or some other memory +checker tool. Many of the "LLVM bugs" that we have chased down ended up +being bugs in the program being compiled, not LLVM. + +Once you determine that the program itself is not buggy, you should choose +which code generator you wish to compile the program with (e.g. LLC or the JIT) +and optionally a series of LLVM passes to run. For example: + +.. code-block:: bash + + bugpoint -run-llc [... optzn passes ...] file-to-test.bc --args -- [program arguments] + +bugpoint will try to narrow down your list of passes to the one pass that +causes an error, and simplify the bitcode file as much as it can to assist +you. It will print a message letting you know how to reproduce the +resulting error. + +Incorrect code generation +========================= + +Similarly to debugging incorrect compilation by mis-behaving passes, you +can debug incorrect code generation by either LLC or the JIT, using +``bugpoint``. The process ``bugpoint`` follows in this case is to try to +narrow the code down to a function that is miscompiled by one or the other +method, but since for correctness, the entire program must be run, +``bugpoint`` will compile the code it deems to not be affected with the C +Backend, and then link in the shared object it generates. + +To debug the JIT: + +.. code-block:: bash + + bugpoint -run-jit -output=[correct output file] [bitcode file] \ + --tool-args -- [arguments to pass to lli] \ + --args -- [program arguments] + +Similarly, to debug the LLC, one would run: + +.. code-block:: bash + + bugpoint -run-llc -output=[correct output file] [bitcode file] \ + --tool-args -- [arguments to pass to llc] \ + --args -- [program arguments] + +**Special note:** if you are debugging MultiSource or SPEC tests that +already exist in the ``llvm/test`` hierarchy, there is an easier way to +debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which +will pass the program options specified in the Makefiles: + +.. code-block:: bash + + cd llvm/test/../../program + make bugpoint-jit + +At the end of a successful ``bugpoint`` run, you will be presented +with two bitcode files: a *safe* file which can be compiled with the C +backend and the *test* file which either LLC or the JIT +mis-codegenerates, and thus causes the error. + +To reproduce the error that ``bugpoint`` found, it is sufficient to do +the following: + +#. Regenerate the shared object from the safe bitcode file: + + .. code-block:: bash + + llc -march=c safe.bc -o safe.c + gcc -shared safe.c -o safe.so + +#. If debugging LLC, compile test bitcode native and link with the shared + object: + + .. code-block:: bash + + llc test.bc -o test.s + gcc test.s safe.so -o test.llc + ./test.llc [program options] + +#. If debugging the JIT, load the shared object and supply the test + bitcode: + + .. code-block:: bash + + lli -load=safe.so test.bc [program options] diff --git a/docs/userguides.rst b/docs/userguides.rst index c7197ef..3a20514 100644 --- a/docs/userguides.rst +++ b/docs/userguides.rst @@ -15,6 +15,7 @@ User Guides Packaging HowToAddABuilder yaml2obj + HowToSubmitABug * `The LLVM Getting Started Guide <GettingStarted.html>`_ @@ -59,7 +60,7 @@ User Guides This describes new features, known bugs, and other limitations. -* `How to Submit A Bug Report <HowToSubmitABug.html>`_ +* :ref:`how-to-submit-a-bug-report` Instructions for properly submitting information about any bugs you run into in the LLVM system. |