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
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Using the New Pass Manager — 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="User Guide for NVPTX Back-end" href="NVPTXUsage.html" />
<link rel="prev" title="JITLink and ORC’s ObjectLinkingLayer" href="JITLink.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="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="JITLink.html" title="JITLink and ORC’s ObjectLinkingLayer"
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="">Using the New Pass Manager</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/NewPassManager.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="using-the-new-pass-manager">
<h1>Using the New Pass Manager<a class="headerlink" href="#using-the-new-pass-manager" title="Permalink to this headline">¶</a></h1>
<div class="contents local topic" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#overview" id="id1">Overview</a></p></li>
<li><p><a class="reference internal" href="#adding-passes-to-a-pass-manager" id="id2">Adding Passes to a Pass Manager</a></p></li>
<li><p><a class="reference internal" href="#inserting-passes-into-default-pipelines" id="id3">Inserting Passes into Default Pipelines</a></p></li>
<li><p><a class="reference internal" href="#using-analyses" id="id4">Using Analyses</a></p></li>
<li><p><a class="reference internal" href="#implementing-analysis-invalidation" id="id5">Implementing Analysis Invalidation</a></p></li>
<li><p><a class="reference internal" href="#invoking-opt" id="id6">Invoking <code class="docutils literal notranslate"><span class="pre">opt</span></code></a></p></li>
<li><p><a class="reference internal" href="#status-of-the-new-and-legacy-pass-managers" id="id7">Status of the New and Legacy Pass Managers</a></p></li>
</ul>
</div>
<div class="section" id="overview">
<h2><a class="toc-backref" href="#id1">Overview</a><a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>For an overview of the new pass manager, see the <a class="reference external" href="https://blog.llvm.org/posts/2021-03-26-the-new-pass-manager/">blog post</a>.</p>
</div>
<div class="section" id="adding-passes-to-a-pass-manager">
<h2><a class="toc-backref" href="#id2">Adding Passes to a Pass Manager</a><a class="headerlink" href="#adding-passes-to-a-pass-manager" title="Permalink to this headline">¶</a></h2>
<p>For how to write a new PM pass, see <a class="reference internal" href="WritingAnLLVMNewPMPass.html"><span class="doc">this page</span></a>.</p>
<p>To add a pass to a new PM pass manager, the important thing is to match the
pass type and the pass manager type. For example, a <code class="docutils literal notranslate"><span class="pre">FunctionPassManager</span></code>
can only contain function passes:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">FunctionPassManager</span> <span class="n">FPM</span><span class="p">;</span>
<span class="c1">// InstSimplifyPass is a function pass</span>
<span class="n">FPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">InstSimplifyPass</span><span class="p">());</span>
</pre></div>
</div>
<p>If you want add a loop pass that runs on all loops in a function to a
<code class="docutils literal notranslate"><span class="pre">FunctionPassManager</span></code>, the loop pass must be wrapped in a function pass
adaptor that goes through all the loops in the function and runs the loop
pass on each one.</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">FunctionPassManager</span> <span class="n">FPM</span><span class="p">;</span>
<span class="c1">// LoopRotatePass is a loop pass</span>
<span class="n">FPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createFunctionToLoopPassAdaptor</span><span class="p">(</span><span class="n">LoopRotatePass</span><span class="p">()));</span>
</pre></div>
</div>
<p>The IR hierarchy in terms of the new PM is Module -> (CGSCC ->) Function ->
Loop, where going through a CGSCC is optional.</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">FunctionPassManager</span> <span class="n">FPM</span><span class="p">;</span>
<span class="c1">// loop -> function</span>
<span class="n">FPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createFunctionToLoopPassAdaptor</span><span class="p">(</span><span class="n">LoopFooPass</span><span class="p">()));</span>
<span class="n">CGSCCPassManager</span> <span class="n">CGPM</span><span class="p">;</span>
<span class="c1">// loop -> function -> cgscc</span>
<span class="n">CGPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createCGSCCToFunctionPassAdaptor</span><span class="p">(</span><span class="n">createFunctionToLoopPassAdaptor</span><span class="p">(</span><span class="n">LoopFooPass</span><span class="p">())));</span>
<span class="c1">// function -> cgscc</span>
<span class="n">CGPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createCGSCCToFunctionPassAdaptor</span><span class="p">(</span><span class="n">FunctionFooPass</span><span class="p">()));</span>
<span class="n">ModulePassManager</span> <span class="n">MPM</span><span class="p">;</span>
<span class="c1">// loop -> function -> module</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createModuleToFunctionPassAdaptor</span><span class="p">(</span><span class="n">createFunctionToLoopPassAdaptor</span><span class="p">(</span><span class="n">LoopFooPass</span><span class="p">())));</span>
<span class="c1">// function -> module</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createModuleToFunctionPassAdaptor</span><span class="p">(</span><span class="n">FunctionFooPass</span><span class="p">()));</span>
<span class="c1">// loop -> function -> cgscc -> module</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createModuleToCGSCCPassAdaptor</span><span class="p">(</span><span class="n">createCGSCCToFunctionPassAdaptor</span><span class="p">(</span><span class="n">createFunctionToLoopPassAdaptor</span><span class="p">(</span><span class="n">LoopFooPass</span><span class="p">()))));</span>
<span class="c1">// function -> cgscc -> module</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createModuleToCGSCCPassAdaptor</span><span class="p">(</span><span class="n">createCGSCCToFunctionPassAdaptor</span><span class="p">(</span><span class="n">FunctionFooPass</span><span class="p">())));</span>
</pre></div>
</div>
<p>A pass manager of a specific IR unit is also a pass of that kind. For
example, a <code class="docutils literal notranslate"><span class="pre">FunctionPassManager</span></code> is a function pass, meaning it can be
added to a <code class="docutils literal notranslate"><span class="pre">ModulePassManager</span></code>:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">ModulePassManager</span> <span class="n">MPM</span><span class="p">;</span>
<span class="n">FunctionPassManager</span> <span class="n">FPM</span><span class="p">;</span>
<span class="c1">// InstSimplifyPass is a function pass</span>
<span class="n">FPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">InstSimplifyPass</span><span class="p">());</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createModuleToFunctionPassAdaptor</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">FPM</span><span class="p">)));</span>
</pre></div>
</div>
<p>Generally you want to group CGSCC/function/loop passes together in a pass
manager, as opposed to adding adaptors for each pass to the containing upper
level pass manager. For example,</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">ModulePassManager</span> <span class="n">MPM</span><span class="p">;</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createModuleToFunctionPassAdaptor</span><span class="p">(</span><span class="n">FunctionPass1</span><span class="p">()));</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createModuleToFunctionPassAdaptor</span><span class="p">(</span><span class="n">FunctionPass2</span><span class="p">()));</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">run</span><span class="p">();</span>
</pre></div>
</div>
<p>will run <code class="docutils literal notranslate"><span class="pre">FunctionPass1</span></code> on each function in a module, then run
<code class="docutils literal notranslate"><span class="pre">FunctionPass2</span></code> on each function in the module. In contrast,</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">ModulePassManager</span> <span class="n">MPM</span><span class="p">;</span>
<span class="n">FunctionPassManager</span> <span class="n">FPM</span><span class="p">;</span>
<span class="n">FPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">FunctionPass1</span><span class="p">());</span>
<span class="n">FPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">FunctionPass2</span><span class="p">());</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">createModuleToFunctionPassAdaptor</span><span class="p">(</span><span class="n">std</span><span class="o">::</span><span class="n">move</span><span class="p">(</span><span class="n">FPM</span><span class="p">)));</span>
</pre></div>
</div>
<p>will run <code class="docutils literal notranslate"><span class="pre">FunctionPass1</span></code> and <code class="docutils literal notranslate"><span class="pre">FunctionPass2</span></code> on the first function in a
module, then run both passes on the second function in the module, and so on.
This is better for cache locality around LLVM data structures. This similarly
applies for the other IR types, and in some cases can even affect the quality
of optimization. For example, running all loop passes on a loop may cause a
later loop to be able to be optimized more than if each loop pass were run
separately.</p>
</div>
<div class="section" id="inserting-passes-into-default-pipelines">
<h2><a class="toc-backref" href="#id3">Inserting Passes into Default Pipelines</a><a class="headerlink" href="#inserting-passes-into-default-pipelines" title="Permalink to this headline">¶</a></h2>
<p>Rather than manually adding passes to a pass manager, the typical way of
creating a pass manager is to use a <code class="docutils literal notranslate"><span class="pre">PassBuilder</span></code> and call something like
<code class="docutils literal notranslate"><span class="pre">PassBuilder::buildPerModuleDefaultPipeline()</span></code> which creates a typical
pipeline for a given optimization level.</p>
<p>Sometimes either frontends or backends will want to inject passes into the
pipeline. For example, frontends may want to add instrumentation, and target
backends may want to add passes that lower custom intrinsics. For these
cases, <code class="docutils literal notranslate"><span class="pre">PassBuilder</span></code> exposes callbacks that allow injecting passes into
certain parts of the pipeline. For example,</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">PassBuilder</span> <span class="n">PB</span><span class="p">;</span>
<span class="n">PB</span><span class="p">.</span><span class="n">registerPipelineStartEPCallback</span><span class="p">([</span><span class="o">&</span><span class="p">](</span><span class="n">ModulePassManager</span> <span class="o">&</span><span class="n">MPM</span><span class="p">,</span>
<span class="n">PassBuilder</span><span class="o">::</span><span class="n">OptimizationLevel</span> <span class="n">Level</span><span class="p">)</span> <span class="p">{</span>
<span class="n">MPM</span><span class="p">.</span><span class="n">addPass</span><span class="p">(</span><span class="n">FooPass</span><span class="p">());</span>
<span class="p">};</span>
</pre></div>
</div>
<p>will add <code class="docutils literal notranslate"><span class="pre">FooPass</span></code> near the very beginning of the pipeline for pass
managers created by that <code class="docutils literal notranslate"><span class="pre">PassBuilder</span></code>. See the documentation for
<code class="docutils literal notranslate"><span class="pre">PassBuilder</span></code> for the various places that passes can be added.</p>
<p>If a <code class="docutils literal notranslate"><span class="pre">PassBuilder</span></code> has a corresponding <code class="docutils literal notranslate"><span class="pre">TargetMachine</span></code> for a backend, it
will call <code class="docutils literal notranslate"><span class="pre">TargetMachine::registerPassBuilderCallbacks()</span></code> to allow the
backend to inject passes into the pipeline. This is equivalent to the legacy
PM’s <code class="docutils literal notranslate"><span class="pre">TargetMachine::adjustPassManager()</span></code>.</p>
<p>Clang’s <code class="docutils literal notranslate"><span class="pre">BackendUtil.cpp</span></code> shows examples of a frontend adding (mostly
sanitizer) passes to various parts of the pipeline.
<code class="docutils literal notranslate"><span class="pre">AMDGPUTargetMachine::registerPassBuilderCallbacks()</span></code> is an example of a
backend adding passes to various parts of the pipeline.</p>
</div>
<div class="section" id="using-analyses">
<h2><a class="toc-backref" href="#id4">Using Analyses</a><a class="headerlink" href="#using-analyses" title="Permalink to this headline">¶</a></h2>
<p>LLVM provides many analyses that passes can use, such as a dominator tree.
Calculating these can be expensive, so the new pass manager has
infrastructure to cache analyses and reuse them when possible.</p>
<p>When a pass runs on some IR, it also receives an analysis manager which it can
query for analyses. Querying for an analysis will cause the manager to check if
it has already computed the result for the requested IR. If it already has and
the result is still valid, it will return that. Otherwise it will construct a
new result by calling the analysis’s <code class="docutils literal notranslate"><span class="pre">run()</span></code> method, cache it, and return it.
You can also ask the analysis manager to only return an analysis if it’s
already cached.</p>
<p>The analysis manager only provides analysis results for the same IR type as
what the pass runs on. For example, a function pass receives an analysis
manager that only provides function-level analyses. This works for many
passes which work on a fixed scope. However, some passes want to peek up or
down the IR hierarchy. For example, an SCC pass may want to look at function
analyses for the functions inside the SCC. Or it may want to look at some
immutable global analysis. In these cases, the analysis manager can provide a
proxy to an outer or inner level analysis manager. For example, to get a
<code class="docutils literal notranslate"><span class="pre">FunctionAnalysisManager</span></code> from a <code class="docutils literal notranslate"><span class="pre">CGSCCAnalysisManager</span></code>, you can call</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">FunctionAnalysisManager</span> <span class="o">&</span><span class="n">FAM</span> <span class="o">=</span>
<span class="n">AM</span><span class="p">.</span><span class="n">getResult</span><span class="o"><</span><span class="n">FunctionAnalysisManagerCGSCCProxy</span><span class="o">></span><span class="p">(</span><span class="n">InitialC</span><span class="p">,</span> <span class="n">CG</span><span class="p">)</span>
<span class="p">.</span><span class="n">getManager</span><span class="p">();</span>
</pre></div>
</div>
<p>and use <code class="docutils literal notranslate"><span class="pre">FAM</span></code> as a typical <code class="docutils literal notranslate"><span class="pre">FunctionAnalysisManager</span></code> that a function pass
would have access to. To get access to an outer level IR analysis, you can
call</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="k">const</span> <span class="k">auto</span> <span class="o">&</span><span class="n">MAMProxy</span> <span class="o">=</span>
<span class="n">AM</span><span class="p">.</span><span class="n">getResult</span><span class="o"><</span><span class="n">ModuleAnalysisManagerCGSCCProxy</span><span class="o">></span><span class="p">(</span><span class="n">InitialC</span><span class="p">,</span> <span class="n">CG</span><span class="p">);</span>
<span class="n">FooAnalysisResult</span> <span class="o">*</span><span class="n">AR</span> <span class="o">=</span> <span class="n">MAMProxy</span><span class="p">.</span><span class="n">getCachedResult</span><span class="o"><</span><span class="n">FooAnalysis</span><span class="o">></span><span class="p">(</span><span class="n">M</span><span class="p">);</span>
</pre></div>
</div>
<p>Getting direct access to an outer level IR analysis manager is not allowed.
This is to keep in mind potential future pass concurrency, for example
parallelizing function passes over different functions in a CGSCC or module.
Since passes can ask for a cached analysis result, allowing passes to trigger
outer level analysis computation could result in non-determinism if
concurrency was supported. Therefore a pass running on inner level IR cannot
change the state of outer level IR analyses. Another limitation is that outer
level IR analyses that are used must be immutable, or else they could be
invalidated by changes to inner level IR. Outer analyses unused by inner
passes can and often will be invalidated by changes to inner level IR. These
invalidations happen after the inner pass manager finishes, so accessing
mutable analyses would give invalid results.</p>
<p>The exception to the above is accessing function analyses in loop passes.
Loop passes inherently require modifying the function the loop is in, and
that includes some function analyses the loop analyses depend on. This
discounts future concurrency over separate loops in a function, but that’s a
tradeoff due to how tightly a loop and its function are coupled. To make sure
the function analyses loop passes use are valid, they are manually updated in
the loop passes to ensure that invalidation is not necessary. There is a set
of common function analyses that loop passes and analyses have access to
which is passed into loop passes as a <code class="docutils literal notranslate"><span class="pre">LoopStandardAnalysisResults</span></code>
parameter. Other function analyses are not accessible from loop passes.</p>
<p>As with any caching mechanism, we need some way to tell analysis managers
when results are no longer valid. Much of the analysis manager complexity
comes from trying to invalidate as few analysis results as possible to keep
compile times as low as possible.</p>
<p>There are two ways to deal with potentially invalid analysis results. One is
to simply force clear the results. This should generally only be used when
the IR that the result is keyed on becomes invalid. For example, a function
is deleted, or a CGSCC has become invalid due to call graph changes.</p>
<p>The typical way to invalidate analysis results is for a pass to declare what
types of analyses it preserves and what types it does not. When transforming
IR, a pass either has the option to update analyses alongside the IR
transformation, or tell the analysis manager that analyses are no longer
valid and should be invalidated. If a pass wants to keep some specific
analysis up to date, such as when updating it would be faster than
invalidating and recalculating it, the analysis itself may have methods to
update it for specific transformations, or there may be helper updaters like
<code class="docutils literal notranslate"><span class="pre">DomTreeUpdater</span></code> for a <code class="docutils literal notranslate"><span class="pre">DominatorTree</span></code>. Otherwise to mark some analysis
as no longer valid, the pass can return a <code class="docutils literal notranslate"><span class="pre">PreservedAnalyses</span></code> with the
proper analyses invalidated.</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="c1">// We've made no transformations that can affect any analyses.</span>
<span class="k">return</span> <span class="n">PreservedAnalyses</span><span class="o">::</span><span class="n">all</span><span class="p">();</span>
<span class="c1">// We've made transformations and don't want to bother to update any analyses.</span>
<span class="k">return</span> <span class="n">PreservedAnalyses</span><span class="o">::</span><span class="n">none</span><span class="p">();</span>
<span class="c1">// We've specifically updated the dominator tree alongside any transformations, but other analysis results may be invalid.</span>
<span class="n">PreservedAnalyses</span> <span class="n">PA</span><span class="p">;</span>
<span class="n">PA</span><span class="p">.</span><span class="n">preserve</span><span class="o"><</span><span class="n">DominatorAnalysis</span><span class="o">></span><span class="p">();</span>
<span class="k">return</span> <span class="n">PA</span><span class="p">;</span>
<span class="c1">// We haven't made any control flow changes, any analyses that only care about the control flow are still valid.</span>
<span class="n">PreservedAnalyses</span> <span class="n">PA</span><span class="p">;</span>
<span class="n">PA</span><span class="p">.</span><span class="n">preserveSet</span><span class="o"><</span><span class="n">CFGAnalyses</span><span class="o">></span><span class="p">();</span>
<span class="k">return</span> <span class="n">PA</span><span class="p">;</span>
</pre></div>
</div>
<p>The pass manager will call the analysis manager’s <code class="docutils literal notranslate"><span class="pre">invalidate()</span></code> method
with the pass’s returned <code class="docutils literal notranslate"><span class="pre">PreservedAnalyses</span></code>. This can be also done
manually within the pass:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="n">FooModulePass</span><span class="o">::</span><span class="n">run</span><span class="p">(</span><span class="n">Module</span><span class="o">&</span> <span class="n">M</span><span class="p">,</span> <span class="n">ModuleAnalysisManager</span><span class="o">&</span> <span class="n">AM</span><span class="p">)</span> <span class="p">{</span>
<span class="k">auto</span> <span class="o">&</span><span class="n">FAM</span> <span class="o">=</span> <span class="n">AM</span><span class="p">.</span><span class="n">getResult</span><span class="o"><</span><span class="n">FunctionAnalysisManagerModuleProxy</span><span class="o">></span><span class="p">(</span><span class="n">M</span><span class="p">).</span><span class="n">getManager</span><span class="p">();</span>
<span class="c1">// Invalidate all analysis results for function F</span>
<span class="n">FAM</span><span class="p">.</span><span class="n">invalidate</span><span class="p">(</span><span class="n">F</span><span class="p">,</span> <span class="n">PreservedAnalyses</span><span class="o">::</span><span class="n">none</span><span class="p">());</span>
<span class="c1">// Invalidate all analysis results</span>
<span class="n">AM</span><span class="p">.</span><span class="n">invalidate</span><span class="p">(</span><span class="n">M</span><span class="p">,</span> <span class="n">PreservedAnalyses</span><span class="o">::</span><span class="n">none</span><span class="p">());</span>
<span class="p">...</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This is especially important when a pass removes then adds a function. The
analysis manager may store a pointer to a function that has been deleted, and
if the pass creates a new function before invalidating analysis results, the
new function may be at the same address as the old one, causing invalid
cached results. This is also useful for being more precise about
invalidation. Selectively invalidating analysis results only for functions
modified in an SCC pass can allow more analysis results to remain. But except
for complex fine-grain invalidation with inner proxies, passes should
typically just return a proper <code class="docutils literal notranslate"><span class="pre">PreservedAnalyses</span></code> and let the pass manager
deal with proper invalidation.</p>
</div>
<div class="section" id="implementing-analysis-invalidation">
<h2><a class="toc-backref" href="#id5">Implementing Analysis Invalidation</a><a class="headerlink" href="#implementing-analysis-invalidation" title="Permalink to this headline">¶</a></h2>
<p>By default, an analysis is invalidated if <code class="docutils literal notranslate"><span class="pre">PreservedAnalyses</span></code> says that
analyses on the IR unit it runs on are not preserved (see
<code class="docutils literal notranslate"><span class="pre">AnalysisResultModel::invalidate()</span></code>). An analysis can implement
<code class="docutils literal notranslate"><span class="pre">invalidate()</span></code> to be more conservative when it comes to invalidation. For
example,</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">bool</span> <span class="n">FooAnalysisResult</span><span class="o">::</span><span class="n">invalidate</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">,</span> <span class="k">const</span> <span class="n">PreservedAnalyses</span> <span class="o">&</span><span class="n">PA</span><span class="p">,</span>
<span class="n">FunctionAnalysisManager</span><span class="o">::</span><span class="n">Invalidator</span> <span class="o">&</span><span class="p">)</span> <span class="p">{</span>
<span class="k">auto</span> <span class="n">PAC</span> <span class="o">=</span> <span class="n">PA</span><span class="p">.</span><span class="n">getChecker</span><span class="o"><</span><span class="n">FooAnalysis</span><span class="o">></span><span class="p">();</span>
<span class="c1">// the default would be:</span>
<span class="c1">// return !(PAC.preserved() || PAC.preservedSet<AllAnalysesOn<Function>>());</span>
<span class="k">return</span> <span class="o">!</span><span class="p">(</span><span class="n">PAC</span><span class="p">.</span><span class="n">preserved</span><span class="p">()</span> <span class="o">||</span> <span class="n">PAC</span><span class="p">.</span><span class="n">preservedSet</span><span class="o"><</span><span class="n">AllAnalysesOn</span><span class="o"><</span><span class="n">Function</span><span class="o">>></span><span class="p">()</span>
<span class="o">||</span> <span class="n">PAC</span><span class="p">.</span><span class="n">preservedSet</span><span class="o"><</span><span class="n">CFGAnalyses</span><span class="o">></span><span class="p">());</span>
<span class="p">}</span>
</pre></div>
</div>
<p>says that if the <code class="docutils literal notranslate"><span class="pre">PreservedAnalyses</span></code> specifically preserves
<code class="docutils literal notranslate"><span class="pre">FooAnalysis</span></code>, or if <code class="docutils literal notranslate"><span class="pre">PreservedAnalyses</span></code> preserves all analyses (implicit
in <code class="docutils literal notranslate"><span class="pre">PAC.preserved()</span></code>), or if <code class="docutils literal notranslate"><span class="pre">PreservedAnalyses</span></code> preserves all function
analyses, or <code class="docutils literal notranslate"><span class="pre">PreservedAnalyses</span></code> preserves all analyses that only care
about the CFG, the <code class="docutils literal notranslate"><span class="pre">FooAnalysisResult</span></code> should not be invalidated.</p>
<p>If an analysis is stateless and generally shouldn’t be invalidated, use the
following:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">bool</span> <span class="n">FooAnalysisResult</span><span class="o">::</span><span class="n">invalidate</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">,</span> <span class="k">const</span> <span class="n">PreservedAnalyses</span> <span class="o">&</span><span class="n">PA</span><span class="p">,</span>
<span class="n">FunctionAnalysisManager</span><span class="o">::</span><span class="n">Invalidator</span> <span class="o">&</span><span class="p">)</span> <span class="p">{</span>
<span class="c1">// Check whether the analysis has been explicitly invalidated. Otherwise, it's</span>
<span class="c1">// stateless and remains preserved.</span>
<span class="k">auto</span> <span class="n">PAC</span> <span class="o">=</span> <span class="n">PA</span><span class="p">.</span><span class="n">getChecker</span><span class="o"><</span><span class="n">FooAnalysis</span><span class="o">></span><span class="p">();</span>
<span class="k">return</span> <span class="o">!</span><span class="n">PAC</span><span class="p">.</span><span class="n">preservedWhenStateless</span><span class="p">();</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If an analysis depends on other analyses, those analyses also need to be
checked if they are invalidated:</p>
<div class="highlight-c++ notranslate"><div class="highlight"><pre><span></span><span class="kt">bool</span> <span class="n">FooAnalysisResult</span><span class="o">::</span><span class="n">invalidate</span><span class="p">(</span><span class="n">Function</span> <span class="o">&</span><span class="n">F</span><span class="p">,</span> <span class="k">const</span> <span class="n">PreservedAnalyses</span> <span class="o">&</span><span class="n">PA</span><span class="p">,</span>
<span class="n">FunctionAnalysisManager</span><span class="o">::</span><span class="n">Invalidator</span> <span class="o">&</span><span class="p">)</span> <span class="p">{</span>
<span class="k">auto</span> <span class="n">PAC</span> <span class="o">=</span> <span class="n">PA</span><span class="p">.</span><span class="n">getChecker</span><span class="o"><</span><span class="n">FooAnalysis</span><span class="o">></span><span class="p">();</span>
<span class="k">if</span> <span class="p">(</span><span class="o">!</span><span class="n">PAC</span><span class="p">.</span><span class="n">preserved</span><span class="p">()</span> <span class="o">&&</span> <span class="o">!</span><span class="n">PAC</span><span class="p">.</span><span class="n">preservedSet</span><span class="o"><</span><span class="n">AllAnalysesOn</span><span class="o"><</span><span class="n">Function</span><span class="o">>></span><span class="p">())</span>
<span class="k">return</span> <span class="nb">true</span><span class="p">;</span>
<span class="c1">// Check transitive dependencies.</span>
<span class="k">return</span> <span class="n">Inv</span><span class="p">.</span><span class="n">invalidate</span><span class="o"><</span><span class="n">BarAnalysis</span><span class="o">></span><span class="p">(</span><span class="n">F</span><span class="p">,</span> <span class="n">PA</span><span class="p">)</span> <span class="o">||</span>
<span class="n">Inv</span><span class="p">.</span><span class="n">invalidate</span><span class="o"><</span><span class="n">BazAnalysis</span><span class="o">></span><span class="p">(</span><span class="n">F</span><span class="p">,</span> <span class="n">PA</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Combining invalidation and analysis manager proxies results in some
complexity. For example, when we invalidate all analyses in a module pass,
we have to make sure that we also invalidate function analyses accessible via
any existing inner proxies. The inner proxy’s <code class="docutils literal notranslate"><span class="pre">invalidate()</span></code> first checks
if the proxy itself should be invalidated. If so, that means the proxy may
contain pointers to IR that is no longer valid, meaning that the inner proxy
needs to completely clear all relevant analysis results. Otherwise the proxy
simply forwards the invalidation to the inner analysis manager.</p>
<p>Generally for outer proxies, analysis results from the outer analysis manager
should be immutable, so invalidation shouldn’t be a concern. However, it is
possible for some inner analysis to depend on some outer analysis, and when
the outer analysis is invalidated, we need to make sure that dependent inner
analyses are also invalidated. This actually happens with alias analysis
results. Alias analysis is a function-level analysis, but there are
module-level implementations of specific types of alias analysis. Currently
<code class="docutils literal notranslate"><span class="pre">GlobalsAA</span></code> is the only module-level alias analysis and it generally is not
invalidated so this is not so much of a concern. See
<code class="docutils literal notranslate"><span class="pre">OuterAnalysisManagerProxy::Result::registerOuterAnalysisInvalidation()</span></code>
for more details.</p>
</div>
<div class="section" id="invoking-opt">
<h2><a class="toc-backref" href="#id6">Invoking <code class="docutils literal notranslate"><span class="pre">opt</span></code></a><a class="headerlink" href="#invoking-opt" title="Permalink to this headline">¶</a></h2>
<p>To use the legacy pass manager:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt -enable-new-pm<span class="o">=</span><span class="m">0</span> -pass1 -pass2 /tmp/a.ll -S
</pre></div>
</div>
<p>This will be removed once the legacy pass manager is deprecated and removed for
the optimization pipeline.</p>
<p>To use the new PM:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt -passes<span class="o">=</span><span class="s1">'pass1,pass2'</span> /tmp/a.ll -S
</pre></div>
</div>
<p>The new PM typically requires explicit pass nesting. For example, to run a
function pass, then a module pass, we need to wrap the function pass in a module
adaptor:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt -passes<span class="o">=</span><span class="s1">'function(no-op-function),no-op-module'</span> /tmp/a.ll -S
</pre></div>
</div>
<p>A more complete example, and <code class="docutils literal notranslate"><span class="pre">-debug-pass-manager</span></code> to show the execution
order:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt -passes<span class="o">=</span><span class="s1">'no-op-module,cgscc(no-op-cgscc,function(no-op-function,loop(no-op-loop))),function(no-op-function,loop(no-op-loop))'</span> /tmp/a.ll -S -debug-pass-manager
</pre></div>
</div>
<p>Improper nesting can lead to error messages such as</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt -passes<span class="o">=</span><span class="s1">'no-op-function,no-op-module'</span> /tmp/a.ll -S
opt: unknown <span class="k">function</span> pass <span class="s1">'no-op-module'</span>
</pre></div>
</div>
<p>The nesting is: module (-> cgscc) -> function -> loop, where the CGSCC nesting is optional.</p>
<p>There are a couple of special cases for easier typing:</p>
<ul class="simple">
<li><p>If the first pass is not a module pass, a pass manager of the first pass is
implicitly created</p>
<ul>
<li><p>For example, the following are equivalent</p></li>
</ul>
</li>
</ul>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt -passes<span class="o">=</span><span class="s1">'no-op-function,no-op-function'</span> /tmp/a.ll -S
$ opt -passes<span class="o">=</span><span class="s1">'function(no-op-function,no-op-function)'</span> /tmp/a.ll -S
</pre></div>
</div>
<ul class="simple">
<li><p>If there is an adaptor for a pass that lets it fit in the previous pass
manager, that is implicitly created</p>
<ul>
<li><p>For example, the following are equivalent</p></li>
</ul>
</li>
</ul>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt -passes<span class="o">=</span><span class="s1">'no-op-function,no-op-loop'</span> /tmp/a.ll -S
$ opt -passes<span class="o">=</span><span class="s1">'no-op-function,loop(no-op-loop)'</span> /tmp/a.ll -S
</pre></div>
</div>
<p>For a list of available passes and analyses, including the IR unit (module,
CGSCC, function, loop) they operate on, run</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt --print-passes
</pre></div>
</div>
<p>or take a look at <code class="docutils literal notranslate"><span class="pre">PassRegistry.def</span></code>.</p>
<p>To make sure an analysis named <code class="docutils literal notranslate"><span class="pre">foo</span></code> is available before a pass, add
<code class="docutils literal notranslate"><span class="pre">require<foo></span></code> to the pass pipeline. This adds a pass that simply requests
that the analysis is run. This pass is also subject to proper nesting. For
example, to make sure some function analysis is already computed for all
functions before a module pass:</p>
<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>$ opt -passes<span class="o">=</span><span class="s1">'function(require<my-function-analysis>),my-module-pass'</span> /tmp/a.ll -S
</pre></div>
</div>
</div>
<div class="section" id="status-of-the-new-and-legacy-pass-managers">
<h2><a class="toc-backref" href="#id7">Status of the New and Legacy Pass Managers</a><a class="headerlink" href="#status-of-the-new-and-legacy-pass-managers" title="Permalink to this headline">¶</a></h2>
<p>LLVM currently contains two pass managers, the legacy PM and the new PM. The
optimization pipeline (aka the middle-end) works with both the legacy PM and
the new PM, whereas the backend target-dependent code generation only works
with the legacy PM.</p>
<p>For the optimization pipeline, the new PM is the default PM. The legacy PM is
available for the optimization pipeline either by setting the CMake flag
<code class="docutils literal notranslate"><span class="pre">-DLLVM_ENABLE_NEW_PASS_MANAGER=OFF</span></code> when building LLVM, or by
various compiler/linker flags, e.g. <code class="docutils literal notranslate"><span class="pre">-flegacy-pass-manager</span></code> for <code class="docutils literal notranslate"><span class="pre">clang</span></code>.</p>
<p>There will be efforts to deprecate and remove the legacy PM for the
optimization pipeline in the future.</p>
<p>Some IR passes are considered part of the backend codegen pipeline even if
they are LLVM IR passes (whereas all MIR passes are codegen passes). This
includes anything added via <code class="docutils literal notranslate"><span class="pre">TargetPassConfig</span></code> hooks, e.g.
<code class="docutils literal notranslate"><span class="pre">TargetPassConfig::addCodeGenPrepare()</span></code>. As mentioned before, passes added
in <code class="docutils literal notranslate"><span class="pre">TargetMachine::adjustPassManager()</span></code> are part of the optimization
pipeline, and should have a corresponding line in
<code class="docutils literal notranslate"><span class="pre">TargetMachine::registerPassBuilderCallbacks()</span></code>.</p>
<p>Currently there are efforts to make the codegen pipeline work with the new
PM.</p>
</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="NVPTXUsage.html" title="User Guide for NVPTX Back-end"
>next</a> |</li>
<li class="right" >
<a href="JITLink.html" title="JITLink and ORC’s ObjectLinkingLayer"
>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="">Using the New Pass Manager</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>
|
