1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>How to submit an LLVM bug report — LLVM 13 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="LLVM Bug Life Cycle" href="BugLifeCycle.html" />
<link rel="prev" title="Sphinx Quickstart Template" href="SphinxQuickstartTemplate.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="BugLifeCycle.html" title="LLVM Bug Life Cycle"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingInvolved.html" accesskey="U">Getting Involved</a> »</li>
<li class="nav-item nav-item-this"><a href="">How to submit an LLVM bug report</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/HowToSubmitABug.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="how-to-submit-an-llvm-bug-report">
<h1>How to submit an LLVM bug report<a class="headerlink" href="#how-to-submit-an-llvm-bug-report" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction-got-bugs">
<h2>Introduction - Got bugs?<a class="headerlink" href="#introduction-got-bugs" title="Permalink to this headline">¶</a></h2>
<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>🔒 If you believe that the bug is security related, please follow <a class="reference internal" href="Security.html#report-security-issue"><span class="std std-ref">How to report a security issue?</span></a>. 🔒</p>
<p>Basically you have to do two things at a minimum. First, decide whether the
bug <a class="reference internal" href="#crashes-the-compiler">crashes the compiler</a> or if the compiler is <a class="reference internal" href="#miscompiling">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 class="reference external" href="https://bugs.llvm.org/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 class="simple">
<li><p>All information necessary to reproduce the problem.</p></li>
<li><p>The reduced test-case that triggers the bug.</p></li>
<li><p>The location where you obtained LLVM (if not from our Git
repository).</p></li>
</ul>
<p>Thanks for helping us make LLVM better!</p>
</div>
<div class="section" id="crashing-bugs">
<span id="crashes-the-compiler"></span><h2>Crashing Bugs<a class="headerlink" href="#crashing-bugs" title="Permalink to this headline">¶</a></h2>
<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 Clang 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, middle-end
optimizer, or backend code generator), run the <code class="docutils literal notranslate"><span class="pre">clang</span></code> command line as you
were when the crash occurred, but with the following extra command line
options:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">-emit-llvm</span> <span class="pre">-Xclang</span> <span class="pre">-disable-llvm-passes</span></code>: If <code class="docutils literal notranslate"><span class="pre">clang</span></code> still crashes when
passed these options (which disable the optimizer and code generator), then
the crash is in the front-end. Jump ahead to <a class="reference internal" href="#frontend-crash"><span class="std std-ref">front-end bugs</span></a>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-emit-llvm</span></code>: If <code class="docutils literal notranslate"><span class="pre">clang</span></code> crashes with this option (which disables
the code generator), you found a middle-end optimizer bug. Jump ahead to
<a class="reference internal" href="#middleend-crash"><span class="std std-ref">middle-end bugs</span></a>.</p></li>
<li><p>Otherwise, you have a backend code generator crash. Jump ahead to <a class="reference internal" href="#backend-crash"><span class="std std-ref">code
generator bugs</span></a>.</p></li>
</ul>
<div class="section" id="front-end-bugs">
<span id="frontend-crash"></span><h3>Front-end bugs<a class="headerlink" href="#front-end-bugs" title="Permalink to this headline">¶</a></h3>
<p>On a <code class="docutils literal notranslate"><span class="pre">clang</span></code> crash, the compiler will dump a preprocessed file and a script
to replay the <code class="docutils literal notranslate"><span class="pre">clang</span></code> command. For example, you should see something like</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>PLEASE ATTACH THE FOLLOWING FILES TO THE BUG REPORT:
Preprocessed source(s) and associated run script(s) are located at:
clang: note: diagnostic msg: /tmp/foo-xxxxxx.c
clang: note: diagnostic msg: /tmp/foo-xxxxxx.sh
</pre></div>
</div>
<p>The <a class="reference external" href="https://github.com/csmith-project/creduce">creduce</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 creduce to reduce the code
to make the developers’ lives easier. The
<code class="docutils literal notranslate"><span class="pre">clang/utils/creduce-clang-crash.py</span></code> script can be used on the files
that clang dumps to help with automating creating a test to check for the
compiler crash.</p>
<p><a class="reference external" href="https://github.com/marxin/cvise">cvise</a> is an alternative to <code class="docutils literal notranslate"><span class="pre">creduce</span></code>.</p>
</div>
<div class="section" id="middle-end-optimization-bugs">
<span id="middleend-crash"></span><h3>Middle-end optimization bugs<a class="headerlink" href="#middle-end-optimization-bugs" title="Permalink to this headline">¶</a></h3>
<p>If you find that a bug crashes in the optimizer, compile your test-case to a
<code class="docutils literal notranslate"><span class="pre">.bc</span></code> file by passing “<code class="docutils literal notranslate"><span class="pre">-emit-llvm</span> <span class="pre">-O1</span> <span class="pre">-Xclang</span> <span class="pre">-disable-llvm-passes</span> <span class="pre">-c</span> <span class="pre">-o</span>
<span class="pre">foo.bc</span></code>”. The <code class="docutils literal notranslate"><span class="pre">-O1</span></code> is important because <code class="docutils literal notranslate"><span class="pre">-O0</span></code> adds the <code class="docutils literal notranslate"><span class="pre">optnone</span></code>
function attribute to all functions and many passes don’t run on <code class="docutils literal notranslate"><span class="pre">optnone</span></code>
functions. Then run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>opt -O3 foo.bc -disable-output
</pre></div>
</div>
<p>If this doesn’t crash, please follow the instructions for a <a class="reference internal" href="#frontend-crash"><span class="std std-ref">front-end
bug</span></a>.</p>
<p>If this does crash, then you should be able to debug this with the following
<a class="reference internal" href="Bugpoint.html"><span class="doc">bugpoint</span></a> command:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint foo.bc -O3
</pre></div>
</div>
<p>Run this, then file a bug with the instructions and reduced .bc
files that bugpoint emits.</p>
<p>If bugpoint doesn’t reproduce the crash, <code class="docutils literal notranslate"><span class="pre">llvm-reduce</span></code> is an alternative
way to reduce LLVM IR. Create a script that repros the crash and run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>llvm-reduce --test<span class="o">=</span>path/to/script foo.bc
</pre></div>
</div>
<p>which should produce reduced IR that reproduces the crash. Be warned the
<code class="docutils literal notranslate"><span class="pre">llvm-reduce</span></code> is still fairly immature and may crash.</p>
<p>If none of the above work, you can get the IR before a crash by running the
<code class="docutils literal notranslate"><span class="pre">opt</span></code> command with the <code class="docutils literal notranslate"><span class="pre">--print-before-all</span> <span class="pre">--print-module-scope</span></code> flags to
dump the IR before every pass. Be warned that this is very verbose.</p>
</div>
<div class="section" id="backend-code-generator-bugs">
<span id="backend-crash"></span><h3>Backend code generator bugs<a class="headerlink" href="#backend-code-generator-bugs" title="Permalink to this headline">¶</a></h3>
<p>If you find a bug that crashes clang in the code generator, compile your
source file to a .bc file by passing “<code class="docutils literal notranslate"><span class="pre">-emit-llvm</span> <span class="pre">-c</span> <span class="pre">-o</span> <span class="pre">foo.bc</span></code>” to
clang (in addition to the options you already pass). Once your have
foo.bc, one of the following commands should fail:</p>
<ol class="arabic simple">
<li><p><code class="docutils literal notranslate"><span class="pre">llc</span> <span class="pre">foo.bc</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">llc</span> <span class="pre">foo.bc</span> <span class="pre">-relocation-model=pic</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">llc</span> <span class="pre">foo.bc</span> <span class="pre">-relocation-model=static</span></code></p></li>
</ol>
<p>If none of these crash, please follow the instructions for a <a class="reference internal" href="#frontend-crash"><span class="std std-ref">front-end
bug</span></a>. If one of these do crash, you should be able to reduce
this with one of the following <a class="reference internal" href="Bugpoint.html"><span class="doc">bugpoint</span></a> command lines (use
the one corresponding to the command above that failed):</p>
<ol class="arabic simple">
<li><p><code class="docutils literal notranslate"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span> <span class="pre">--tool-args</span> <span class="pre">-relocation-model=pic</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">bugpoint</span> <span class="pre">-run-llc</span> <span class="pre">foo.bc</span> <span class="pre">--tool-args</span> <span class="pre">-relocation-model=static</span></code></p></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>
<div class="section" id="miscompilations">
<span id="miscompiling"></span><h2>Miscompilations<a class="headerlink" href="#miscompilations" title="Permalink to this headline">¶</a></h2>
<p>If clang 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 is clean under various <a class="reference external" href="https://github.com/google/sanitizers">sanitizers</a> (e.g. <code class="docutils literal notranslate"><span class="pre">clang</span>
<span class="pre">-fsanitize=undefined,address</span></code>) and <a class="reference external" href="http://valgrind.org/">valgrind</a>. Many
“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="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint -run-llc <span class="o">[</span>... optzn passes ...<span class="o">]</span> file-to-test.bc --args -- <span class="o">[</span>program arguments<span class="o">]</span>
</pre></div>
</div>
<p>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.</p>
<p>The <a class="reference internal" href="OptBisect.html"><span class="doc">OptBisect</span></a> page shows an alternative method for finding
incorrect optimization passes.</p>
</div>
<div class="section" id="incorrect-code-generation">
<h2>Incorrect code generation<a class="headerlink" href="#incorrect-code-generation" title="Permalink to this headline">¶</a></h2>
<p>Similarly to debugging incorrect compilation by mis-behaving passes, you
can debug incorrect code generation by either LLC or the JIT, using
<code class="docutils literal notranslate"><span class="pre">bugpoint</span></code>. The process <code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> 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,
<code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> 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="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint -run-jit -output<span class="o">=[</span>correct output file<span class="o">]</span> <span class="o">[</span>bitcode file<span class="o">]</span> <span class="se">\</span>
--tool-args -- <span class="o">[</span>arguments to pass to lli<span class="o">]</span> <span class="se">\</span>
--args -- <span class="o">[</span>program arguments<span class="o">]</span>
</pre></div>
</div>
<p>Similarly, to debug the LLC, one would run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>bugpoint -run-llc -output<span class="o">=[</span>correct output file<span class="o">]</span> <span class="o">[</span>bitcode file<span class="o">]</span> <span class="se">\</span>
--tool-args -- <span class="o">[</span>arguments to pass to llc<span class="o">]</span> <span class="se">\</span>
--args -- <span class="o">[</span>program arguments<span class="o">]</span>
</pre></div>
</div>
<p><strong>Special note:</strong> if you are debugging MultiSource or SPEC tests that
already exist in the <code class="docutils literal notranslate"><span class="pre">llvm/test</span></code> 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="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">cd</span> llvm/test/../../program
make bugpoint-jit
</pre></div>
</div>
<p>At the end of a successful <code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> 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 <code class="docutils literal notranslate"><span class="pre">bugpoint</span></code> found, it is sufficient to do
the following:</p>
<ol class="arabic">
<li><p>Regenerate the shared object from the safe bitcode file:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>llc -march<span class="o">=</span>c safe.bc -o safe.c
gcc -shared safe.c -o safe.so
</pre></div>
</div>
</li>
<li><p>If debugging LLC, compile test bitcode native and link with the shared
object:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>llc test.bc -o test.s
gcc test.s safe.so -o test.llc
./test.llc <span class="o">[</span>program options<span class="o">]</span>
</pre></div>
</div>
</li>
<li><p>If debugging the JIT, load the shared object and supply the test
bitcode:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>lli -load<span class="o">=</span>safe.so test.bc <span class="o">[</span>program options<span class="o">]</span>
</pre></div>
</div>
</li>
</ol>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="BugLifeCycle.html" title="LLVM Bug Life Cycle"
>next</a> |</li>
<li class="right" >
<a href="SphinxQuickstartTemplate.html" title="Sphinx Quickstart Template"
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="GettingInvolved.html" >Getting Involved</a> »</li>
<li class="nav-item nav-item-this"><a href="">How to submit an LLVM bug report</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
