llvm.org GIT mirror llvm / 1a5ed97
update this for llvm-gcc4 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@34566 91177308-0d34-0410-b5e6-96231b3b80d8 Chris Lattner 12 years ago
1 changed file(s) with 100 addition(s) and 116 deletion(s). Raw diff Collapse all Expand all
1818
  • Crashing Bugs
  • 1919
    2020
  • Front-end bugs
  • 21
  • GCCAS bugs
  • 22
  • GCCLD bugs
  • 23
  • Bugs in LLVM passes
  • 21
  • Compile-time optimization bugs
  • 22
  • Code generator bugs
  • 2423
    2524
  • Miscompilations
  • 2625
  • Incorrect code generation (JIT and LLC)
  • 5049
    5150

    Basically you have to do two things at a minimum. First, decide whether the

    5251 bug crashes the compiler (or an LLVM pass), or if the
    53 compiler is miscompiling the program. Based on
    52 compiler is miscompiling the program (i.e., the
    53 compiler successfully produces an executable, but it doesn't run right). Based
    54 on
    5455 what type of bug it is, follow the instructions in the linked section to narrow
    5556 down the bug so that the person who fixes it will be able to find the problem
    5657 more easily.

    5758
    5859

    Once you have a reduced test-case, go to

    5960 href="http://llvm.org/bugs/enter_bug.cgi">the LLVM Bug Tracking
    60 System, select the category in which the bug falls, and fill out the form
    61 with the necessary details. The bug description should contain the following
    61 System and fill out the form with the necessary details (note that you don't
    62 need to pick a catagory, just use the "new-bugs" catagory if you're not sure).
    63 The bug description should contain the following
    6264 information:

    6365
    6466
    8082
    8183
    8284
    83

    More often than not, bugs in the compiler cause it to crash—often due to an

    84 assertion failure of some sort. If you are running opt
    85 directly, and something crashes, jump to the section on
    86 bugs in LLVM passes. Otherwise, the most important
    87 piece of the puzzle is to figure out if it is the GCC-based front-end that is
    88 buggy or if it's one of the LLVM tools that has problems.

    89
    90

    To figure out which program is crashing (the front-end,

    91 <tt>gccas, or gccld), run the
    85 <p>More often than not, bugs in the compiler cause it to crash—often due
    86 to an assertion failure of some sort. The most important
    87 piece of the puzzle is to figure out if it is crashing in the GCC front-end
    88 or if it is one of the LLVM libraries (e.g. the optimizer or code generator)
    89 that has problems.

    90
    91

    To figure out which component is crashing (the front-end,

    92 optimizer or code generator), run the
    9293 llvm-gcc command line as you were when the crash occurred, but
    93 add a -v option to the command line. The compiler will print out a
    94 bunch of stuff, and should end with telling you that one of
    95 cc1/cc1plus, gccas, or
    96 gccld crashed.

    94 with the following extra command line options:

    9795
    9896
    99
    100
  • If cc1 or cc1plus crashed, you found a
  • 101 problem with the front-end.
    102 Jump ahead to the section on front-end bugs.
    103
    104
  • If gccas crashed, you found a bug in one
  • 105 of the passes in gccas.
    106
    107
  • If gccld crashed, you found a bug in one
  • 108 of the passes in gccld.
    109
    110
  • Otherwise, something really weird happened. Email the list with what you
  • 111 have at this point.
    97
  • -O0 -emit-llvm: If llvm-gcc still crashes when
  • 98 passed these options (which disable the optimizer and code generator), then
    99 the crash is in the front-end. Jump ahead to the section on
    100 href="#front-end">front-end bugs.
    101
    102
  • -emit-llvm: If llvm-gcc crashes with this option
  • 103 (which disables the code generator), you found an optimizer bug. Jump ahead
    104 to compile-time optimization bugs.
    105
    106
  • Otherwise, you have a code generator crash. Jump ahead to
  • 107 href="#ct_codegen">code generator bugs.
    112108
    113109
    114110
    125121 llvm-gcc command that resulted in the crash, but add the
    126122 -save-temps option. The compiler will crash again, but it will leave
    127123 behind a foo.i file (containing preprocessed C source code) and
    128 possibly foo.s (containing LLVM assembly code) for each
    124 possibly foo.s for each
    129125 compiled foo.c file. Send us the foo.i file,
    130 along with a brief description of the error it caused.

    126 along with the options you passed to llvm-gcc, and a brief description of the
    127 error it caused.

    131128
    132129

    The delta tool helps to reduce the

    133130 preprocessed file down to the smallest amount of code that still replicates the
    140137
    141138
    142139
    143 GCCAS bugs
    144
    145
    146
    147
    148

    If you find that a bug crashes in the gccas stage of

    149 compilation, compile your test-case to a .s file with the
    150 -save-temps option to llvm-gcc. Then run:

    151
    152
    153

    gccas -debug-pass=Arguments < /dev/null -o - > /dev/null

    154
    155
    156

    ... which will print a list of arguments, indicating the list of passes that

    157 gccas runs. Once you have the input file and the list of
    158 passes, go to the section on debugging bugs in LLVM
    159 passes.>
    140 Compile-time optimization bugs>
    141
    142
    143
    144
    145

    If you find that a bug crashes in the optimizer, compile your test-case to a

    146 .bc file by passing "-emit-llvm -O0 -c -o foo.bc".
    147 Then run:

    148
    149
    150

    opt -std-compile-opts -debug-pass=Arguments foo.bc

    151 -disable-output

    152
    153
    154

    This command should do two things: it should print out a list of passes, and

    155 then it should crash in the same was as llvm-gcc. If it doesn't crash, please
    156 follow the instructions for a front-end bug.

    157
    158

    If this does crash, then you should be able to debug this with the following

    159 bugpoint command:

    160
    161
    162

    bugpoint foo.bc <list of passes printed by

    163 opt>

    164
    165
    166

    Please run this, then file a bug with the instructions and reduced .bc files

    167 that bugpoint emits. If something goes wrong with bugpoint, please submit the
    168 "foo.bc" file and the list of passes printed by opt.

    160169
    161170
    162171
    163172
    164173
    165 GCCLD bugs
    166
    167
    168
    169
    170

    If you find that a bug crashes in the gccld stage of

    171 compilation, gather all of the .o bytecode files and libraries that are
    172 being linked together (the "llvm-gcc -v" output should include
    173 the full list of objects linked). Then run:

    174
    175
    176

    llvm-as < /dev/null > null.bc

    177 gccld -debug-pass=Arguments null.bc
    178

    179
    180
    181

    ... which will print a list of arguments, indicating the list of passes that

    182 gccld runs. Once you have the input files and the list of
    183 passes, go to the section on debugging bugs in LLVM
    184 passes.

    185
    186
    187
    188
    189
    190 Bugs in LLVM passes
    191
    192
    193
    194
    195

    At this point, you should have some number of LLVM assembly files or bytecode

    196 files and a list of passes which crash when run on the specified input. In
    197 order to reduce the list of passes (which is probably large) and the input to
    198 something tractable, use the bugpoint tool as follows:

    199
    200
    201

    bugpoint <input files> <list of passes>

    202
    203
    204

    bugpoint will print a bunch of output as it reduces the

    205 test-case, but it should eventually print something like this:

    206
    207
    208

    209 ...
    210 Emitted bytecode to 'bugpoint-reduced-simplified.bc'
    211
    212 *** You can reproduce the problem with: opt bugpoint-reduced-simplified.bc -licm
    213

    214
    215
    216

    Once you complete this, please send the LLVM bytecode file and the command

    217 line to reproduce the problem to the llvmbugs mailing list.>
    174 Code generator bugs>
    175
    176
    177
    178
    179

    If you find a bug that crashes llvm-gcc in the code generator, compile your

    180 source file to a .bc file by passing "-emit-llvm -c -o foo.bc"
    181 to llvm-gcc (in addition to the options you already pass). Once your have
    182 foo.bc, one of the following commands should fail:

    183
    184
    185
  • llc foo.bc -f
  • 186
  • llc foo.bc -f -relocation-model=pic
  • 187
  • llc foo.bc -f -relocation-model=static
  • 188
    189
    190

    If none of these crash, please follow the instructions for a

    191 front-end bug. If one of these do crash, you should
    192 be able to reduce this with one of the following bugpoint command lines (use
    193 the one corresponding to the command above that failed):

    194
    195
    196
  • bugpoint -run-llc foo.bc --tool-args
  • 197
  • bugpoint -run-llc foo.bc --tool-args
  • 198 -relocation-model=pic
    199
  • bugpoint -run-llc foo.bc --tool-args
  • 200 -relocation-model=static
    201
    202
    203

    Please run this, then file a bug with the instructions and reduced .bc file

    204 that bugpoint emits. If something goes wrong with bugpoint, please submit the
    205 "foo.bc" file and the option that llc crashes with.

    218206
    219207
    220208
    226214
    227215
    228216
    229

    A miscompilation occurs when a pass does not correctly transform a program,

    230 thus producing errors that are only noticed during execution. This is different
    231 from producing invalid LLVM code (i.e., code not in SSA form, using values
    232 before defining them, etc.) which the verifier will check for after a pass
    233 finishes its run.

    234
    235

    If it looks like the LLVM compiler is miscompiling a program, the very first

    236 thing to check is to make sure it is not using undefined behavior. In
    237 particular, check to see if the program
    238 href="http://valgrind.kde.org/">valgrinds clean, passes purify, or some
    239 other memory checker tool. Many of the "LLVM bugs" that we have chased down
    240 ended up being bugs in the program being compiled, not LLVM.

    217

    If llvm-gcc successfully produces an executable, but that executable doesn't

    218 run right, this is either a bug in the code or a bug in the
    219 compiler. The first thing to check is to make sure it is not using undefined
    220 behavior (e.g. reading a variable before it is defined). In particular, check
    221 to see if the program valgrinds clean,
    222 passes purify, or some other memory checker tool. Many of the "LLVM bugs" that
    223 we have chased down ended up being bugs in the program being compiled, not
    224 LLVM.

    241225
    242226

    Once you determine that the program itself is not buggy, you should choose

    243227 which code generator you wish to compile the program with (e.g. C backend, the