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
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>How to Update Debug Info: A Guide for LLVM Pass Authors — 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 Link Time Optimization: Design and Implementation" href="LinkTimeOptimization.html" />
<link rel="prev" title="How To Cross-Compile Clang/LLVM using Clang/LLVM" href="HowToCrossCompileLLVM.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="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="HowToCrossCompileLLVM.html" title="How To Cross-Compile Clang/LLVM using Clang/LLVM"
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="UserGuides.html" accesskey="U">User Guides</a> »</li>
<li class="nav-item nav-item-this"><a href="">How to Update Debug Info: A Guide for LLVM Pass Authors</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/HowToUpdateDebugInfo.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-update-debug-info-a-guide-for-llvm-pass-authors">
<h1>How to Update Debug Info: A Guide for LLVM Pass Authors<a class="headerlink" href="#how-to-update-debug-info-a-guide-for-llvm-pass-authors" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#introduction" id="id1">Introduction</a></p></li>
<li><p><a class="reference internal" href="#rules-for-updating-debug-locations" id="id2">Rules for updating debug locations</a></p>
<ul>
<li><p><a class="reference internal" href="#when-to-preserve-an-instruction-location" id="id3">When to preserve an instruction location</a></p></li>
<li><p><a class="reference internal" href="#when-to-merge-instruction-locations" id="id4">When to merge instruction locations</a></p></li>
<li><p><a class="reference internal" href="#when-to-drop-an-instruction-location" id="id5">When to drop an instruction location</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#rules-for-updating-debug-values" id="id6">Rules for updating debug values</a></p>
<ul>
<li><p><a class="reference internal" href="#deleting-an-ir-level-instruction" id="id7">Deleting an IR-level Instruction</a></p></li>
<li><p><a class="reference internal" href="#deleting-a-mir-level-machineinstr" id="id8">Deleting a MIR-level MachineInstr</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#how-to-automatically-convert-tests-into-debug-info-tests" id="id9">How to automatically convert tests into debug info tests</a></p>
<ul>
<li><p><a class="reference internal" href="#mutation-testing-for-ir-level-transformations" id="id10">Mutation testing for IR-level transformations</a></p>
<ul>
<li><p><a class="reference internal" href="#the-debugify-utility-pass" id="id11">The <code class="docutils literal notranslate"><span class="pre">debugify</span></code> utility pass</a></p></li>
<li><p><a class="reference internal" href="#using-debugify" id="id12">Using <code class="docutils literal notranslate"><span class="pre">debugify</span></code></a></p></li>
<li><p><a class="reference internal" href="#debugify-in-regression-tests" id="id13"><code class="docutils literal notranslate"><span class="pre">debugify</span></code> in regression tests</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#test-original-debug-info-preservation-in-optimizations" id="id14">Test original debug info preservation in optimizations</a></p></li>
<li><p><a class="reference internal" href="#mutation-testing-for-mir-level-transformations" id="id15">Mutation testing for MIR-level transformations</a></p></li>
<li><p><a class="reference internal" href="#using-lostdebuglocobserver" id="id16">Using LostDebugLocObserver</a></p></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="introduction">
<h2><a class="toc-backref" href="#id1">Introduction</a><a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>Certain kinds of code transformations can inadvertently result in a loss of
debug info, or worse, make debug info misrepresent the state of a program.</p>
<p>This document specifies how to correctly update debug info in various kinds of
code transformations, and offers suggestions for how to create targeted debug
info tests for arbitrary transformations.</p>
<p>For more on the philosophy behind LLVM debugging information, see
<a class="reference internal" href="SourceLevelDebugging.html"><span class="doc">Source Level Debugging with LLVM</span></a>.</p>
</div>
<div class="section" id="rules-for-updating-debug-locations">
<h2><a class="toc-backref" href="#id2">Rules for updating debug locations</a><a class="headerlink" href="#rules-for-updating-debug-locations" title="Permalink to this headline">¶</a></h2>
<div class="section" id="when-to-preserve-an-instruction-location">
<span id="whentopreservelocation"></span><h3><a class="toc-backref" href="#id3">When to preserve an instruction location</a><a class="headerlink" href="#when-to-preserve-an-instruction-location" title="Permalink to this headline">¶</a></h3>
<p>A transformation should preserve the debug location of an instruction if the
instruction either remains in its basic block, or if its basic block is folded
into a predecessor that branches unconditionally. The APIs to use are
<code class="docutils literal notranslate"><span class="pre">IRBuilder</span></code>, or <code class="docutils literal notranslate"><span class="pre">Instruction::setDebugLoc</span></code>.</p>
<p>The purpose of this rule is to ensure that common block-local optimizations
preserve the ability to set breakpoints on source locations corresponding to
the instructions they touch. Debugging, crash logs, and SamplePGO accuracy
would be severely impacted if that ability were lost.</p>
<p>Examples of transformations that should follow this rule include:</p>
<ul class="simple">
<li><p>Instruction scheduling. Block-local instruction reordering should not drop
source locations, even though this may lead to jumpy single-stepping
behavior.</p></li>
<li><p>Simple jump threading. For example, if block <code class="docutils literal notranslate"><span class="pre">B1</span></code> unconditionally jumps to
<code class="docutils literal notranslate"><span class="pre">B2</span></code>, <em>and</em> is its unique predecessor, instructions from <code class="docutils literal notranslate"><span class="pre">B2</span></code> can be
hoisted into <code class="docutils literal notranslate"><span class="pre">B1</span></code>. Source locations from <code class="docutils literal notranslate"><span class="pre">B2</span></code> should be preserved.</p></li>
<li><p>Peephole optimizations that replace or expand an instruction, like <code class="docutils literal notranslate"><span class="pre">(add</span> <span class="pre">X</span>
<span class="pre">X)</span> <span class="pre">=></span> <span class="pre">(shl</span> <span class="pre">X</span> <span class="pre">1)</span></code>. The location of the <code class="docutils literal notranslate"><span class="pre">shl</span></code> instruction should be the same
as the location of the <code class="docutils literal notranslate"><span class="pre">add</span></code> instruction.</p></li>
<li><p>Tail duplication. For example, if blocks <code class="docutils literal notranslate"><span class="pre">B1</span></code> and <code class="docutils literal notranslate"><span class="pre">B2</span></code> both
unconditionally branch to <code class="docutils literal notranslate"><span class="pre">B3</span></code> and <code class="docutils literal notranslate"><span class="pre">B3</span></code> can be folded into its
predecessors, source locations from <code class="docutils literal notranslate"><span class="pre">B3</span></code> should be preserved.</p></li>
</ul>
<p>Examples of transformations for which this rule <em>does not</em> apply include:</p>
<ul class="simple">
<li><p>LICM. E.g., if an instruction is moved from the loop body to the preheader,
the rule for <a class="reference internal" href="#whentodroplocation"><span class="std std-ref">dropping locations</span></a> applies.</p></li>
</ul>
<p>In addition to the rule above, a transformation should also preserve the debug
location of an instruction that is moved between basic blocks, if the
destination block already contains an instruction with an identical debug
location.</p>
<p>Examples of transformations that should follow this rule include:</p>
<ul class="simple">
<li><p>Moving instructions between basic blocks. For example, if instruction <code class="docutils literal notranslate"><span class="pre">I1</span></code>
in <code class="docutils literal notranslate"><span class="pre">BB1</span></code> is moved before <code class="docutils literal notranslate"><span class="pre">I2</span></code> in <code class="docutils literal notranslate"><span class="pre">BB2</span></code>, the source location of <code class="docutils literal notranslate"><span class="pre">I1</span></code>
can be preserved if it has the same source location as <code class="docutils literal notranslate"><span class="pre">I2</span></code>.</p></li>
</ul>
</div>
<div class="section" id="when-to-merge-instruction-locations">
<span id="whentomergelocation"></span><h3><a class="toc-backref" href="#id4">When to merge instruction locations</a><a class="headerlink" href="#when-to-merge-instruction-locations" title="Permalink to this headline">¶</a></h3>
<p>A transformation should merge instruction locations if it replaces multiple
instructions with a single merged instruction, <em>and</em> that merged instruction
does not correspond to any of the original instructions’ locations. The API to
use is <code class="docutils literal notranslate"><span class="pre">Instruction::applyMergedLocation</span></code>.</p>
<p>The purpose of this rule is to ensure that a) the single merged instruction
has a location with an accurate scope attached, and b) to prevent misleading
single-stepping (or breakpoint) behavior. Often, merged instructions are memory
accesses which can trap: having an accurate scope attached greatly assists in
crash triage by identifying the (possibly inlined) function where the bad
memory access occurred. This rule is also meant to assist SamplePGO by banning
scenarios in which a sample of a block containing a merged instruction is
misattributed to a block containing one of the instructions-to-be-merged.</p>
<p>Examples of transformations that should follow this rule include:</p>
<ul class="simple">
<li><p>Merging identical loads/stores which occur on both sides of a CFG diamond
(see the <code class="docutils literal notranslate"><span class="pre">MergedLoadStoreMotion</span></code> pass).</p></li>
<li><p>Merging identical loop-invariant stores (see the LICM utility
<code class="docutils literal notranslate"><span class="pre">llvm::promoteLoopAccessesToScalars</span></code>).</p></li>
<li><p>Peephole optimizations which combine multiple instructions together, like
<code class="docutils literal notranslate"><span class="pre">(add</span> <span class="pre">(mul</span> <span class="pre">A</span> <span class="pre">B)</span> <span class="pre">C)</span> <span class="pre">=></span> <span class="pre">llvm.fma.f32(A,</span> <span class="pre">B,</span> <span class="pre">C)</span></code>. Note that the location of
the <code class="docutils literal notranslate"><span class="pre">fma</span></code> does not exactly correspond to the locations of either the
<code class="docutils literal notranslate"><span class="pre">mul</span></code> or the <code class="docutils literal notranslate"><span class="pre">add</span></code> instructions.</p></li>
</ul>
<p>Examples of transformations for which this rule <em>does not</em> apply include:</p>
<ul class="simple">
<li><p>Block-local peepholes which delete redundant instructions, like
<code class="docutils literal notranslate"><span class="pre">(sext</span> <span class="pre">(zext</span> <span class="pre">i8</span> <span class="pre">%x</span> <span class="pre">to</span> <span class="pre">i16)</span> <span class="pre">to</span> <span class="pre">i32)</span> <span class="pre">=></span> <span class="pre">(zext</span> <span class="pre">i8</span> <span class="pre">%x</span> <span class="pre">to</span> <span class="pre">i32)</span></code>. The inner
<code class="docutils literal notranslate"><span class="pre">zext</span></code> is modified but remains in its block, so the rule for
<a class="reference internal" href="#whentopreservelocation"><span class="std std-ref">preserving locations</span></a> should apply.</p></li>
<li><p>Converting an if-then-else CFG diamond into a <code class="docutils literal notranslate"><span class="pre">select</span></code>. Preserving the
debug locations of speculated instructions can make it seem like a condition
is true when it’s not (or vice versa), which leads to a confusing
single-stepping experience. The rule for
<a class="reference internal" href="#whentodroplocation"><span class="std std-ref">dropping locations</span></a> should apply here.</p></li>
<li><p>Hoisting identical instructions which appear in several successor blocks into
a predecessor block (see <code class="docutils literal notranslate"><span class="pre">BranchFolder::HoistCommonCodeInSuccs</span></code>). In this
case there is no single merged instruction. The rule for
<a class="reference internal" href="#whentodroplocation"><span class="std std-ref">dropping locations</span></a> applies.</p></li>
</ul>
</div>
<div class="section" id="when-to-drop-an-instruction-location">
<span id="whentodroplocation"></span><h3><a class="toc-backref" href="#id5">When to drop an instruction location</a><a class="headerlink" href="#when-to-drop-an-instruction-location" title="Permalink to this headline">¶</a></h3>
<p>A transformation should drop debug locations if the rules for
<a class="reference internal" href="#whentopreservelocation"><span class="std std-ref">preserving</span></a> and
<a class="reference internal" href="#whentomergelocation"><span class="std std-ref">merging</span></a> debug locations do not apply. The API to
use is <code class="docutils literal notranslate"><span class="pre">Instruction::dropLocation()</span></code>.</p>
<p>The purpose of this rule is to prevent erratic or misleading single-stepping
behavior in situations in which an instruction has no clear, unambiguous
relationship to a source location.</p>
<p>To handle an instruction without a location, the DWARF generator
defaults to allowing the last-set location after a label to cascade forward, or
to setting a line 0 location with viable scope information if no previous
location is available.</p>
<p>See the discussion in the section about
<a class="reference internal" href="#whentomergelocation"><span class="std std-ref">merging locations</span></a> for examples of when the rule for
dropping locations applies.</p>
</div>
</div>
<div class="section" id="rules-for-updating-debug-values">
<h2><a class="toc-backref" href="#id6">Rules for updating debug values</a><a class="headerlink" href="#rules-for-updating-debug-values" title="Permalink to this headline">¶</a></h2>
<div class="section" id="deleting-an-ir-level-instruction">
<h3><a class="toc-backref" href="#id7">Deleting an IR-level Instruction</a><a class="headerlink" href="#deleting-an-ir-level-instruction" title="Permalink to this headline">¶</a></h3>
<p>When an <code class="docutils literal notranslate"><span class="pre">Instruction</span></code> is deleted, its debug uses change to <code class="docutils literal notranslate"><span class="pre">undef</span></code>. This is
a loss of debug info: the value of one or more source variables becomes
unavailable, starting with the <code class="docutils literal notranslate"><span class="pre">llvm.dbg.value(undef,</span> <span class="pre">...)</span></code>. When there is no
way to reconstitute the value of the lost instruction, this is the best
possible outcome. However, it’s often possible to do better:</p>
<ul class="simple">
<li><p>If the dying instruction can be RAUW’d, do so. The
<code class="docutils literal notranslate"><span class="pre">Value::replaceAllUsesWith</span></code> API transparently updates debug uses of the
dying instruction to point to the replacement value.</p></li>
<li><p>If the dying instruction cannot be RAUW’d, call <code class="docutils literal notranslate"><span class="pre">llvm::salvageDebugInfo</span></code> on
it. This makes a best-effort attempt to rewrite debug uses of the dying
instruction by describing its effect as a <code class="docutils literal notranslate"><span class="pre">DIExpression</span></code>.</p></li>
<li><p>If one of the <strong>operands</strong> of a dying instruction would become trivially
dead, use <code class="docutils literal notranslate"><span class="pre">llvm::replaceAllDbgUsesWith</span></code> to rewrite the debug uses of that
operand. Consider the following example function:</p></li>
</ul>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i16</span> <span class="vg">@foo</span><span class="p">(</span><span class="k">i16</span> <span class="nv">%a</span><span class="p">)</span> <span class="p">{</span>
<span class="nv">%b</span> <span class="p">=</span> <span class="k">sext</span> <span class="k">i16</span> <span class="nv">%a</span> <span class="k">to</span> <span class="k">i32</span>
<span class="nv">%c</span> <span class="p">=</span> <span class="k">and</span> <span class="k">i32</span> <span class="nv">%b</span><span class="p">,</span> <span class="m">15</span>
<span class="k">call</span> <span class="k">void</span> <span class="vg">@llvm.dbg.value</span><span class="p">(</span><span class="k">metadata</span> <span class="k">i32</span> <span class="nv">%c</span><span class="p">,</span> <span class="p">...)</span>
<span class="nv">%d</span> <span class="p">=</span> <span class="k">trunc</span> <span class="k">i32</span> <span class="nv">%c</span> <span class="k">to</span> <span class="k">i16</span>
<span class="k">ret</span> <span class="k">i16</span> <span class="nv">%d</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Now, here’s what happens after the unnecessary truncation instruction <code class="docutils literal notranslate"><span class="pre">%d</span></code> is
replaced with a simplified instruction:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i16</span> <span class="vg">@foo</span><span class="p">(</span><span class="k">i16</span> <span class="nv">%a</span><span class="p">)</span> <span class="p">{</span>
<span class="k">call</span> <span class="k">void</span> <span class="vg">@llvm.dbg.value</span><span class="p">(</span><span class="k">metadata</span> <span class="k">i32</span> <span class="k">undef</span><span class="p">,</span> <span class="p">...)</span>
<span class="nv">%simplified</span> <span class="p">=</span> <span class="k">and</span> <span class="k">i16</span> <span class="nv">%a</span><span class="p">,</span> <span class="m">15</span>
<span class="k">ret</span> <span class="k">i16</span> <span class="nv">%simplified</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Note that after deleting <code class="docutils literal notranslate"><span class="pre">%d</span></code>, all uses of its operand <code class="docutils literal notranslate"><span class="pre">%c</span></code> become
trivially dead. The debug use which used to point to <code class="docutils literal notranslate"><span class="pre">%c</span></code> is now <code class="docutils literal notranslate"><span class="pre">undef</span></code>,
and debug info is needlessly lost.</p>
<p>To solve this problem, do:</p>
<div class="highlight-cpp notranslate"><div class="highlight"><pre><span></span><span class="n">llvm</span><span class="o">::</span><span class="n">replaceAllDbgUsesWith</span><span class="p">(</span><span class="o">%</span><span class="n">c</span><span class="p">,</span> <span class="n">theSimplifiedAndInstruction</span><span class="p">,</span> <span class="p">...)</span>
</pre></div>
</div>
<p>This results in better debug info because the debug use of <code class="docutils literal notranslate"><span class="pre">%c</span></code> is preserved:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">i16</span> <span class="vg">@foo</span><span class="p">(</span><span class="k">i16</span> <span class="nv">%a</span><span class="p">)</span> <span class="p">{</span>
<span class="nv">%simplified</span> <span class="p">=</span> <span class="k">and</span> <span class="k">i16</span> <span class="nv">%a</span><span class="p">,</span> <span class="m">15</span>
<span class="k">call</span> <span class="k">void</span> <span class="vg">@llvm.dbg.value</span><span class="p">(</span><span class="k">metadata</span> <span class="k">i16</span> <span class="nv">%simplified</span><span class="p">,</span> <span class="p">...)</span>
<span class="k">ret</span> <span class="k">i16</span> <span class="nv">%simplified</span>
<span class="p">}</span>
</pre></div>
</div>
<p>You may have noticed that <code class="docutils literal notranslate"><span class="pre">%simplified</span></code> is narrower than <code class="docutils literal notranslate"><span class="pre">%c</span></code>: this is not
a problem, because <code class="docutils literal notranslate"><span class="pre">llvm::replaceAllDbgUsesWith</span></code> takes care of inserting the
necessary conversion operations into the DIExpressions of updated debug uses.</p>
</div>
<div class="section" id="deleting-a-mir-level-machineinstr">
<h3><a class="toc-backref" href="#id8">Deleting a MIR-level MachineInstr</a><a class="headerlink" href="#deleting-a-mir-level-machineinstr" title="Permalink to this headline">¶</a></h3>
<p>TODO</p>
</div>
</div>
<div class="section" id="how-to-automatically-convert-tests-into-debug-info-tests">
<h2><a class="toc-backref" href="#id9">How to automatically convert tests into debug info tests</a><a class="headerlink" href="#how-to-automatically-convert-tests-into-debug-info-tests" title="Permalink to this headline">¶</a></h2>
<div class="section" id="mutation-testing-for-ir-level-transformations">
<span id="irdebugify"></span><h3><a class="toc-backref" href="#id10">Mutation testing for IR-level transformations</a><a class="headerlink" href="#mutation-testing-for-ir-level-transformations" title="Permalink to this headline">¶</a></h3>
<p>An IR test case for a transformation can, in many cases, be automatically
mutated to test debug info handling within that transformation. This is a
simple way to test for proper debug info handling.</p>
<div class="section" id="the-debugify-utility-pass">
<h4><a class="toc-backref" href="#id11">The <code class="docutils literal notranslate"><span class="pre">debugify</span></code> utility pass</a><a class="headerlink" href="#the-debugify-utility-pass" title="Permalink to this headline">¶</a></h4>
<p>The <code class="docutils literal notranslate"><span class="pre">debugify</span></code> testing utility is just a pair of passes: <code class="docutils literal notranslate"><span class="pre">debugify</span></code> and
<code class="docutils literal notranslate"><span class="pre">check-debugify</span></code>.</p>
<p>The first applies synthetic debug information to every instruction of the
module, and the second checks that this DI is still available after an
optimization has occurred, reporting any errors/warnings while doing so.</p>
<p>The instructions are assigned sequentially increasing line locations, and are
immediately used by debug value intrinsics everywhere possible.</p>
<p>For example, here is a module before:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span><span class="k">define</span> <span class="k">void</span> <span class="vg">@f</span><span class="p">(</span><span class="k">i32</span><span class="p">*</span> <span class="nv">%x</span><span class="p">)</span> <span class="p">{</span>
<span class="nl">entry:</span>
<span class="nv">%x.addr</span> <span class="p">=</span> <span class="k">alloca</span> <span class="k">i32</span><span class="p">*,</span> <span class="k">align</span> <span class="m">8</span>
<span class="k">store</span> <span class="k">i32</span><span class="p">*</span> <span class="nv">%x</span><span class="p">,</span> <span class="k">i32</span><span class="p">**</span> <span class="nv">%x.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">8</span>
<span class="nv nv-Anonymous">%0</span> <span class="p">=</span> <span class="k">load</span> <span class="k">i32</span><span class="p">*,</span> <span class="k">i32</span><span class="p">**</span> <span class="nv">%x.addr</span><span class="p">,</span> <span class="k">align</span> <span class="m">8</span>
<span class="k">store</span> <span class="k">i32</span> <span class="m">10</span><span class="p">,</span> <span class="k">i32</span><span class="p">*</span> <span class="nv nv-Anonymous">%0</span><span class="p">,</span> <span class="k">align</span> <span class="m">4</span>
<span class="k">ret</span> <span class="k">void</span>
<span class="p">}</span>
</pre></div>
</div>
<p>and after running <code class="docutils literal notranslate"><span class="pre">opt</span> <span class="pre">-debugify</span></code>:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span>define void @f(i32* %x) !dbg !6 {
entry:
%x.addr = alloca i32*, align 8, !dbg !12
call void @llvm.dbg.value(metadata i32** %x.addr, metadata !9, metadata !DIExpression()), !dbg !12
store i32* %x, i32** %x.addr, align 8, !dbg !13
%0 = load i32*, i32** %x.addr, align 8, !dbg !14
call void @llvm.dbg.value(metadata i32* %0, metadata !11, metadata !DIExpression()), !dbg !14
store i32 10, i32* %0, align 4, !dbg !15
ret void, !dbg !16
}
!llvm.dbg.cu = !{!0}
!llvm.debugify = !{!3, !4}
!llvm.module.flags = !{!5}
!0 = distinct !DICompileUnit(language: DW_LANG_C, file: !1, producer: "debugify", isOptimized: true, runtimeVersion: 0, emissionKind: FullDebug, enums: !2)
!1 = !DIFile(filename: "debugify-sample.ll", directory: "/")
!2 = !{}
!3 = !{i32 5}
!4 = !{i32 2}
!5 = !{i32 2, !"Debug Info Version", i32 3}
!6 = distinct !DISubprogram(name: "f", linkageName: "f", scope: null, file: !1, line: 1, type: !7, isLocal: false, isDefinition: true, scopeLine: 1, isOptimized: true, unit: !0, retainedNodes: !8)
!7 = !DISubroutineType(types: !2)
!8 = !{!9, !11}
!9 = !DILocalVariable(name: "1", scope: !6, file: !1, line: 1, type: !10)
!10 = !DIBasicType(name: "ty64", size: 64, encoding: DW_ATE_unsigned)
!11 = !DILocalVariable(name: "2", scope: !6, file: !1, line: 3, type: !10)
!12 = !DILocation(line: 1, column: 1, scope: !6)
!13 = !DILocation(line: 2, column: 1, scope: !6)
!14 = !DILocation(line: 3, column: 1, scope: !6)
!15 = !DILocation(line: 4, column: 1, scope: !6)
!16 = !DILocation(line: 5, column: 1, scope: !6)
</pre></div>
</div>
</div>
<div class="section" id="using-debugify">
<h4><a class="toc-backref" href="#id12">Using <code class="docutils literal notranslate"><span class="pre">debugify</span></code></a><a class="headerlink" href="#using-debugify" title="Permalink to this headline">¶</a></h4>
<p>A simple way to use <code class="docutils literal notranslate"><span class="pre">debugify</span></code> is as follows:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ opt -debugify -pass-to-test -check-debugify sample.ll
</pre></div>
</div>
<p>This will inject synthetic DI to <code class="docutils literal notranslate"><span class="pre">sample.ll</span></code> run the <code class="docutils literal notranslate"><span class="pre">pass-to-test</span></code> and
then check for missing DI. The <code class="docutils literal notranslate"><span class="pre">-check-debugify</span></code> step can of course be
omitted in favor of more customizable FileCheck directives.</p>
<p>Some other ways to run debugify are available:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Same as the above example.</span>
$ opt -enable-debugify -pass-to-test sample.ll
<span class="c1"># Suppresses verbose debugify output.</span>
$ opt -enable-debugify -debugify-quiet -pass-to-test sample.ll
<span class="c1"># Prepend -debugify before and append -check-debugify -strip after</span>
<span class="c1"># each pass on the pipeline (similar to -verify-each).</span>
$ opt -debugify-each -O2 sample.ll
</pre></div>
</div>
<p>In order for <code class="docutils literal notranslate"><span class="pre">check-debugify</span></code> to work, the DI must be coming from
<code class="docutils literal notranslate"><span class="pre">debugify</span></code>. Thus, modules with existing DI will be skipped.</p>
<p><code class="docutils literal notranslate"><span class="pre">debugify</span></code> can be used to test a backend, e.g:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ opt -debugify < sample.ll <span class="p">|</span> llc -o -
</pre></div>
</div>
<p>There is also a MIR-level debugify pass that can be run before each backend
pass, see:
<a class="reference internal" href="#mirdebugify"><span class="std std-ref">Mutation testing for MIR-level transformations</span></a>.</p>
</div>
<div class="section" id="debugify-in-regression-tests">
<h4><a class="toc-backref" href="#id13"><code class="docutils literal notranslate"><span class="pre">debugify</span></code> in regression tests</a><a class="headerlink" href="#debugify-in-regression-tests" title="Permalink to this headline">¶</a></h4>
<p>The output of the <code class="docutils literal notranslate"><span class="pre">debugify</span></code> pass must be stable enough to use in regression
tests. Changes to this pass are not allowed to break existing tests.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Regression tests must be robust. Avoid hardcoding line/variable numbers in
check lines. In cases where this can’t be avoided (say, if a test wouldn’t
be precise enough), moving the test to its own file is preferred.</p>
</div>
</div>
</div>
<div class="section" id="test-original-debug-info-preservation-in-optimizations">
<span id="mirdebugify"></span><h3><a class="toc-backref" href="#id14">Test original debug info preservation in optimizations</a><a class="headerlink" href="#test-original-debug-info-preservation-in-optimizations" title="Permalink to this headline">¶</a></h3>
<p>In addition to automatically generating debug info, the checks provided by
the <code class="docutils literal notranslate"><span class="pre">debugify</span></code> utility pass can also be used to test the preservation of
pre-existing debug info metadata. It could be run as follows:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Run the pass by checking original Debug Info preservation.</span>
$ opt -verify-debuginfo-preserve -pass-to-test sample.ll
<span class="c1"># Check the preservation of original Debug Info after each pass.</span>
$ opt -verify-each-debuginfo-preserve -O2 sample.ll
</pre></div>
</div>
<p>Furthermore, there is a way to export the issues that have been found into
a JSON file as follows:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ opt -verify-debuginfo-preserve -verify-di-preserve-export<span class="o">=</span>sample.json -pass-to-test sample.ll
</pre></div>
</div>
<p>and then use the <code class="docutils literal notranslate"><span class="pre">llvm/utils/llvm-original-di-preservation.py</span></code> script
to generate an HTML page with the issues reported in a more human readable form
as follows:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llvm-original-di-preservation.py sample.json sample.html
</pre></div>
</div>
<p>Testing of original debug info preservation can be invoked from front-end level
as follows:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Test each pass.</span>
$ clang -Xclang -fverify-debuginfo-preserve -g -O2 sample.c
<span class="c1"># Test each pass and export the issues report into the JSON file.</span>
$ clang -Xclang -fverify-debuginfo-preserve -Xclang -fverify-debuginfo-preserve-export<span class="o">=</span>sample.json -g -O2 sample.c
</pre></div>
</div>
<p>Please do note that there are some known false positives, for source locations
and debug intrinsic checking, so that will be addressed as a future work.</p>
</div>
<div class="section" id="mutation-testing-for-mir-level-transformations">
<h3><a class="toc-backref" href="#id15">Mutation testing for MIR-level transformations</a><a class="headerlink" href="#mutation-testing-for-mir-level-transformations" title="Permalink to this headline">¶</a></h3>
<p>A variant of the <code class="docutils literal notranslate"><span class="pre">debugify</span></code> utility described in
<a class="reference internal" href="#irdebugify"><span class="std std-ref">Mutation testing for IR-level transformations</span></a> can be used
for MIR-level transformations as well: much like the IR-level pass,
<code class="docutils literal notranslate"><span class="pre">mir-debugify</span></code> inserts sequentially increasing line locations to each
<code class="docutils literal notranslate"><span class="pre">MachineInstr</span></code> in a <code class="docutils literal notranslate"><span class="pre">Module</span></code>. And the MIR-level <code class="docutils literal notranslate"><span class="pre">mir-check-debugify</span></code> is
similar to IR-level <code class="docutils literal notranslate"><span class="pre">check-debugify</span></code> pass.</p>
<p>For example, here is a snippet before:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span>name: test
body: |
bb.1 (%ir-block.0):
%0:_(s32) = IMPLICIT_DEF
%1:_(s32) = IMPLICIT_DEF
%2:_(s32) = G_CONSTANT i32 2
%3:_(s32) = G_ADD %0, %2
%4:_(s32) = G_SUB %3, %1
</pre></div>
</div>
<p>and after running <code class="docutils literal notranslate"><span class="pre">llc</span> <span class="pre">-run-pass=mir-debugify</span></code>:</p>
<div class="highlight-llvm notranslate"><div class="highlight"><pre><span></span>name: test
body: |
bb.0 (%ir-block.0):
%0:_(s32) = IMPLICIT_DEF debug-location !12
DBG_VALUE %0(s32), $noreg, !9, !DIExpression(), debug-location !12
%1:_(s32) = IMPLICIT_DEF debug-location !13
DBG_VALUE %1(s32), $noreg, !11, !DIExpression(), debug-location !13
%2:_(s32) = G_CONSTANT i32 2, debug-location !14
DBG_VALUE %2(s32), $noreg, !9, !DIExpression(), debug-location !14
%3:_(s32) = G_ADD %0, %2, debug-location !DILocation(line: 4, column: 1, scope: !6)
DBG_VALUE %3(s32), $noreg, !9, !DIExpression(), debug-location !DILocation(line: 4, column: 1, scope: !6)
%4:_(s32) = G_SUB %3, %1, debug-location !DILocation(line: 5, column: 1, scope: !6)
DBG_VALUE %4(s32), $noreg, !9, !DIExpression(), debug-location !DILocation(line: 5, column: 1, scope: !6)
</pre></div>
</div>
<p>By default, <code class="docutils literal notranslate"><span class="pre">mir-debugify</span></code> inserts <code class="docutils literal notranslate"><span class="pre">DBG_VALUE</span></code> instructions <strong>everywhere</strong>
it is legal to do so. In particular, every (non-PHI) machine instruction that
defines a register must be followed by a <code class="docutils literal notranslate"><span class="pre">DBG_VALUE</span></code> use of that def. If
an instruction does not define a register, but can be followed by a debug inst,
MIRDebugify inserts a <code class="docutils literal notranslate"><span class="pre">DBG_VALUE</span></code> that references a constant. Insertion of
<code class="docutils literal notranslate"><span class="pre">DBG_VALUE</span></code>’s can be disabled by setting <code class="docutils literal notranslate"><span class="pre">-debugify-level=locations</span></code>.</p>
<p>To run MIRDebugify once, simply insert <code class="docutils literal notranslate"><span class="pre">mir-debugify</span></code> into your <code class="docutils literal notranslate"><span class="pre">llc</span></code>
invocation, like:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Before some other pass.</span>
$ llc -run-pass<span class="o">=</span>mir-debugify,other-pass ...
<span class="c1"># After some other pass.</span>
$ llc -run-pass<span class="o">=</span>other-pass,mir-debugify ...
</pre></div>
</div>
<p>To run MIRDebugify before each pass in a pipeline, use
<code class="docutils literal notranslate"><span class="pre">-debugify-and-strip-all-safe</span></code>. This can be combined with <code class="docutils literal notranslate"><span class="pre">-start-before</span></code>
and <code class="docutils literal notranslate"><span class="pre">-start-after</span></code>. For example:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llc -debugify-and-strip-all-safe -run-pass<span class="o">=</span>... <other llc args>
$ llc -debugify-and-strip-all-safe -O1 <other llc args>
</pre></div>
</div>
<p>If you want to check it after each pass in a pipeline, use
<code class="docutils literal notranslate"><span class="pre">-debugify-check-and-strip-all-safe</span></code>. This can also be combined with
<code class="docutils literal notranslate"><span class="pre">-start-before</span></code> and <code class="docutils literal notranslate"><span class="pre">-start-after</span></code>. For example:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llc -debugify-check-and-strip-all-safe -run-pass<span class="o">=</span>... <other llc args>
$ llc -debugify-check-and-strip-all-safe -O1 <other llc args>
</pre></div>
</div>
<p>To check all debug info from a test, use <code class="docutils literal notranslate"><span class="pre">mir-check-debugify</span></code>, like:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llc -run-pass<span class="o">=</span>mir-debugify,other-pass,mir-check-debugify
</pre></div>
</div>
<p>To strip out all debug info from a test, use <code class="docutils literal notranslate"><span class="pre">mir-strip-debug</span></code>, like:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llc -run-pass<span class="o">=</span>mir-debugify,other-pass,mir-strip-debug
</pre></div>
</div>
<p>It can be useful to combine <code class="docutils literal notranslate"><span class="pre">mir-debugify</span></code>, <code class="docutils literal notranslate"><span class="pre">mir-check-debugify</span></code> and/or
<code class="docutils literal notranslate"><span class="pre">mir-strip-debug</span></code> to identify backend transformations which break in
the presence of debug info. For example, to run the AArch64 backend tests
with all normal passes “sandwiched” in between MIRDebugify and
MIRStripDebugify mutation passes, run:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ llvm-lit test/CodeGen/AArch64 -Dllc<span class="o">=</span><span class="s2">"llc -debugify-and-strip-all-safe"</span>
</pre></div>
</div>
</div>
<div class="section" id="using-lostdebuglocobserver">
<h3><a class="toc-backref" href="#id16">Using LostDebugLocObserver</a><a class="headerlink" href="#using-lostdebuglocobserver" title="Permalink to this headline">¶</a></h3>
<p>TODO</p>
</div>
</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="LinkTimeOptimization.html" title="LLVM Link Time Optimization: Design and Implementation"
>next</a> |</li>
<li class="right" >
<a href="HowToCrossCompileLLVM.html" title="How To Cross-Compile Clang/LLVM using Clang/LLVM"
>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="UserGuides.html" >User Guides</a> »</li>
<li class="nav-item nav-item-this"><a href="">How to Update Debug Info: A Guide for LLVM Pass Authors</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>
|
