llvm/docs/HowToSubmitABug.rst

   1 ================================
   2 How to submit an LLVM bug report
   3 ================================
   4
   5 Introduction - Got bugs?
   6 ========================
   7
   8
   9 If you're working with LLVM and run into a bug, we definitely want to know
  10 about it.  This document describes what you can do to increase the odds of
  11 getting it fixed quickly.
  12
  13 🔒 If you believe that the bug is security related, please follow :ref:`report-security-issue`. 🔒
  14
  15 Basically you have to do two things at a minimum. First, decide whether the
  16 bug `crashes the compiler`_ or if the compiler is `miscompiling`_ the program
  17 (i.e., the compiler successfully produces an executable, but it doesn't run
  18 right). Based on what type of bug it is, follow the instructions in the
  19 linked section to narrow down the bug so that the person who fixes it will be
  20 able to find the problem more easily.
  21
  22 Once you have a reduced test-case, go to `the LLVM Bug Tracking System
  23 <https://github.com/llvm/llvm-project/issues>`_ and fill out the form with the
  24 necessary details (note that you don't need to pick a label, just use if you're
  25 not sure).  The bug description should contain the following information:
  26
  27 * All information necessary to reproduce the problem.
  28 * The reduced test-case that triggers the bug.
  29 * The location where you obtained LLVM (if not from our Git
  30   repository).
  31
  32 Thanks for helping us make LLVM better!
  33
  34 .. _crashes the compiler:
  35
  36 Crashing Bugs
  37 =============
  38
  39 More often than not, bugs in the compiler cause it to crash---often due to
  40 an assertion failure of some sort. The most important piece of the puzzle
  41 is to figure out if it is crashing in the Clang front-end or if it is one of
  42 the LLVM libraries (e.g. the optimizer or code generator) that has
  43 problems.
  44
  45 To figure out which component is crashing (the front-end, middle-end
  46 optimizer, or backend code generator), run the ``clang`` command line as you
  47 were when the crash occurred, but with the following extra command line
  48 options:
  49
  50 * ``-emit-llvm -Xclang -disable-llvm-passes``: If ``clang`` still crashes when
  51   passed these options (which disable the optimizer and code generator), then
  52   the crash is in the front-end. Jump ahead to :ref:`front-end bugs
  53   <frontend-crash>`.
  54
  55 * ``-emit-llvm``: If ``clang`` crashes with this option (which disables
  56   the code generator), you found a middle-end optimizer bug. Jump ahead to
  57   :ref:`middle-end bugs <middleend-crash>`.
  58
  59 * Otherwise, you have a backend code generator crash. Jump ahead to :ref:`code
  60   generator bugs <backend-crash>`.
  61
  62 .. _frontend-crash:
  63
  64 Front-end bugs
  65 --------------
  66
  67 On a ``clang`` crash, the compiler will dump a preprocessed file and a script
  68 to replay the ``clang`` command. For example, you should see something like
  69
  70 .. code-block:: text
  71
  72    PLEASE ATTACH THE FOLLOWING FILES TO THE BUG REPORT:
  73    Preprocessed source(s) and associated run script(s) are located at:
  74    clang: note: diagnostic msg: /tmp/foo-xxxxxx.c
  75    clang: note: diagnostic msg: /tmp/foo-xxxxxx.sh
  76
  77 The `creduce <https://github.com/csmith-project/creduce>`_ tool helps to
  78 reduce the preprocessed file down to the smallest amount of code that still
  79 replicates the problem. You're encouraged to use creduce to reduce the code
  80 to make the developers' lives easier. The
  81 ``clang/utils/creduce-clang-crash.py`` script can be used on the files
  82 that clang dumps to help with automating creating a test to check for the
  83 compiler crash.
  84
  85 `cvise <https://github.com/marxin/cvise>`_ is an alternative to ``creduce``.
  86
  87 .. _middleend-crash:
  88
  89 Middle-end optimization bugs
  90 ----------------------------
  91
  92 If you find that a bug crashes in the optimizer, compile your test-case to a
  93 ``.bc`` file by passing "``-emit-llvm -O1 -Xclang -disable-llvm-passes -c -o
  94 foo.bc``". The ``-O1`` is important because ``-O0`` adds the ``optnone``
  95 function attribute to all functions and many passes don't run on ``optnone``
  96 functions. Then run:
  97
  98 .. code-block:: bash
  99
 100    opt -O3 foo.bc -disable-output
 101
 102 If this doesn't crash, please follow the instructions for a :ref:`front-end
 103 bug <frontend-crash>`.
 104
 105 If this does crash, then you should be able to debug this with the following
 106 :doc:`bugpoint <Bugpoint>` command:
 107
 108 .. code-block:: bash
 109
 110    bugpoint foo.bc -O3
 111
 112 Run this, then file a bug with the instructions and reduced .bc
 113 files that bugpoint emits.
 114
 115 If bugpoint doesn't reproduce the crash, ``llvm-reduce`` is an alternative
 116 way to reduce LLVM IR. Create a script that repros the crash and run:
 117
 118 .. code-block:: bash
 119
 120    llvm-reduce --test=path/to/script foo.bc
 121
 122 which should produce reduced IR that reproduces the crash. Be warned the
 123 ``llvm-reduce`` is still fairly immature and may crash.
 124
 125 If none of the above work, you can get the IR before a crash by running the
 126 ``opt`` command with the ``--print-before-all --print-module-scope`` flags to
 127 dump the IR before every pass. Be warned that this is very verbose.
 128
 129 .. _backend-crash:
 130
 131 Backend code generator bugs
 132 ---------------------------
 133
 134 If you find a bug that crashes clang in the code generator, compile your
 135 source file to a .bc file by passing "``-emit-llvm -c -o foo.bc``" to
 136 clang (in addition to the options you already pass).  Once your have
 137 foo.bc, one of the following commands should fail:
 138
 139 #. ``llc foo.bc``
 140 #. ``llc foo.bc -relocation-model=pic``
 141 #. ``llc foo.bc -relocation-model=static``
 142
 143 If none of these crash, please follow the instructions for a :ref:`front-end
 144 bug<frontend-crash>`. If one of these do crash, you should be able to reduce
 145 this with one of the following :doc:`bugpoint <Bugpoint>` command lines (use
 146 the one corresponding to the command above that failed):
 147
 148 #. ``bugpoint -run-llc foo.bc``
 149 #. ``bugpoint -run-llc foo.bc --tool-args -relocation-model=pic``
 150 #. ``bugpoint -run-llc foo.bc --tool-args -relocation-model=static``
 151
 152 Please run this, then file a bug with the instructions and reduced .bc file
 153 that bugpoint emits.  If something goes wrong with bugpoint, please submit
 154 the "foo.bc" file and the option that llc crashes with.
 155
 156 .. _miscompiling:
 157
 158 Miscompilations
 159 ===============
 160
 161 If clang successfully produces an executable, but that executable doesn't run
 162 right, this is either a bug in the code or a bug in the compiler. The first
 163 thing to check is to make sure it is not using undefined behavior (e.g.
 164 reading a variable before it is defined). In particular, check to see if the
 165 program is clean under various `sanitizers
 166 <https://github.com/google/sanitizers>`_ (e.g. ``clang
 167 -fsanitize=undefined,address``) and `valgrind <http://valgrind.org/>`_. Many
 168 "LLVM bugs" that we have chased down ended up being bugs in the program being
 169 compiled, not LLVM.
 170
 171 Once you determine that the program itself is not buggy, you should choose
 172 which code generator you wish to compile the program with (e.g. LLC or the JIT)
 173 and optionally a series of LLVM passes to run.  For example:
 174
 175 .. code-block:: bash
 176
 177    bugpoint -run-llc [... optzn passes ...] file-to-test.bc --args -- [program arguments]
 178
 179 bugpoint will try to narrow down your list of passes to the one pass that
 180 causes an error, and simplify the bitcode file as much as it can to assist
 181 you. It will print a message letting you know how to reproduce the
 182 resulting error.
 183
 184 The :doc:`OptBisect <OptBisect>` page shows an alternative method for finding
 185 incorrect optimization passes.
 186
 187 Incorrect code generation
 188 =========================
 189
 190 Similarly to debugging incorrect compilation by mis-behaving passes, you
 191 can debug incorrect code generation by either LLC or the JIT, using
 192 ``bugpoint``. The process ``bugpoint`` follows in this case is to try to
 193 narrow the code down to a function that is miscompiled by one or the other
 194 method, but since for correctness, the entire program must be run,
 195 ``bugpoint`` will compile the code it deems to not be affected with the C
 196 Backend, and then link in the shared object it generates.
 197
 198 To debug the JIT:
 199
 200 .. code-block:: bash
 201
 202    bugpoint -run-jit -output=[correct output file] [bitcode file]  \
 203             --tool-args -- [arguments to pass to lli]              \
 204             --args -- [program arguments]
 205
 206 Similarly, to debug the LLC, one would run:
 207
 208 .. code-block:: bash
 209
 210    bugpoint -run-llc -output=[correct output file] [bitcode file]  \
 211             --tool-args -- [arguments to pass to llc]              \
 212             --args -- [program arguments]
 213
 214 **Special note:** if you are debugging MultiSource or SPEC tests that
 215 already exist in the ``llvm/test`` hierarchy, there is an easier way to
 216 debug the JIT, LLC, and CBE, using the pre-written Makefile targets, which
 217 will pass the program options specified in the Makefiles:
 218
 219 .. code-block:: bash
 220
 221    cd llvm/test/../../program
 222    make bugpoint-jit
 223
 224 At the end of a successful ``bugpoint`` run, you will be presented
 225 with two bitcode files: a *safe* file which can be compiled with the C
 226 backend and the *test* file which either LLC or the JIT
 227 mis-codegenerates, and thus causes the error.
 228
 229 To reproduce the error that ``bugpoint`` found, it is sufficient to do
 230 the following:
 231
 232 #. Regenerate the shared object from the safe bitcode file:
 233
 234    .. code-block:: bash
 235
 236       llc -march=c safe.bc -o safe.c
 237       gcc -shared safe.c -o safe.so
 238
 239 #. If debugging LLC, compile test bitcode native and link with the shared
 240    object:
 241
 242    .. code-block:: bash
 243
 244       llc test.bc -o test.s
 245       gcc test.s safe.so -o test.llc
 246       ./test.llc [program options]
 247
 248 #. If debugging the JIT, load the shared object and supply the test
 249    bitcode:
 250
 251    .. code-block:: bash
 252
 253       lli -load=safe.so test.bc [program options]