• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2                      "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
6  <title>Writing an LLVM Pass</title>
7  <link rel="stylesheet" href="llvm.css" type="text/css">
8</head>
9<body>
10
11<h1>
12  Writing an LLVM Pass
13</h1>
14
15<ol>
16  <li><a href="#introduction">Introduction - What is a pass?</a></li>
17  <li><a href="#quickstart">Quick Start - Writing hello world</a>
18    <ul>
19    <li><a href="#makefile">Setting up the build environment</a></li>
20    <li><a href="#basiccode">Basic code required</a></li>
21    <li><a href="#running">Running a pass with <tt>opt</tt></a></li>
22    </ul></li>
23  <li><a href="#passtype">Pass classes and requirements</a>
24     <ul>
25     <li><a href="#ImmutablePass">The <tt>ImmutablePass</tt> class</a></li>
26     <li><a href="#ModulePass">The <tt>ModulePass</tt> class</a>
27        <ul>
28        <li><a href="#runOnModule">The <tt>runOnModule</tt> method</a></li>
29        </ul></li>
30     <li><a href="#CallGraphSCCPass">The <tt>CallGraphSCCPass</tt> class</a>
31        <ul>
32        <li><a href="#doInitialization_scc">The <tt>doInitialization(CallGraph
33                                           &amp;)</tt> method</a></li>
34        <li><a href="#runOnSCC">The <tt>runOnSCC</tt> method</a></li>
35        <li><a href="#doFinalization_scc">The <tt>doFinalization(CallGraph
36                                           &amp;)</tt> method</a></li>
37        </ul></li>
38     <li><a href="#FunctionPass">The <tt>FunctionPass</tt> class</a>
39        <ul>
40        <li><a href="#doInitialization_mod">The <tt>doInitialization(Module
41                                            &amp;)</tt> method</a></li>
42        <li><a href="#runOnFunction">The <tt>runOnFunction</tt> method</a></li>
43        <li><a href="#doFinalization_mod">The <tt>doFinalization(Module
44                                            &amp;)</tt> method</a></li>
45        </ul></li>
46     <li><a href="#LoopPass">The <tt>LoopPass</tt> class</a>
47        <ul>
48        <li><a href="#doInitialization_loop">The <tt>doInitialization(Loop *,
49                                            LPPassManager &amp;)</tt> method</a></li>
50        <li><a href="#runOnLoop">The <tt>runOnLoop</tt> method</a></li>
51        <li><a href="#doFinalization_loop">The <tt>doFinalization()
52                                            </tt> method</a></li>
53        </ul></li>
54     <li><a href="#RegionPass">The <tt>RegionPass</tt> class</a>
55        <ul>
56        <li><a href="#doInitialization_region">The <tt>doInitialization(Region *,
57                                            RGPassManager &amp;)</tt> method</a></li>
58        <li><a href="#runOnRegion">The <tt>runOnRegion</tt> method</a></li>
59        <li><a href="#doFinalization_region">The <tt>doFinalization()
60                                            </tt> method</a></li>
61        </ul></li>
62     <li><a href="#BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
63        <ul>
64        <li><a href="#doInitialization_fn">The <tt>doInitialization(Function
65                                             &amp;)</tt> method</a></li>
66        <li><a href="#runOnBasicBlock">The <tt>runOnBasicBlock</tt>
67                                       method</a></li>
68        <li><a href="#doFinalization_fn">The <tt>doFinalization(Function
69                                         &amp;)</tt> method</a></li>
70        </ul></li>
71     <li><a href="#MachineFunctionPass">The <tt>MachineFunctionPass</tt>
72                                        class</a>
73        <ul>
74        <li><a href="#runOnMachineFunction">The
75            <tt>runOnMachineFunction(MachineFunction &amp;)</tt> method</a></li>
76        </ul></li>
77     </ul>
78  <li><a href="#registration">Pass Registration</a>
79     <ul>
80     <li><a href="#print">The <tt>print</tt> method</a></li>
81     </ul></li>
82  <li><a href="#interaction">Specifying interactions between passes</a>
83     <ul>
84     <li><a href="#getAnalysisUsage">The <tt>getAnalysisUsage</tt>
85                                     method</a></li>
86     <li><a href="#AU::addRequired">The <tt>AnalysisUsage::addRequired&lt;&gt;</tt> and <tt>AnalysisUsage::addRequiredTransitive&lt;&gt;</tt> methods</a></li>
87     <li><a href="#AU::addPreserved">The <tt>AnalysisUsage::addPreserved&lt;&gt;</tt> method</a></li>
88     <li><a href="#AU::examples">Example implementations of <tt>getAnalysisUsage</tt></a></li>
89     <li><a href="#getAnalysis">The <tt>getAnalysis&lt;&gt;</tt> and
90<tt>getAnalysisIfAvailable&lt;&gt;</tt> methods</a></li>
91     </ul></li>
92  <li><a href="#analysisgroup">Implementing Analysis Groups</a>
93     <ul>
94     <li><a href="#agconcepts">Analysis Group Concepts</a></li>
95     <li><a href="#registerag">Using <tt>RegisterAnalysisGroup</tt></a></li>
96     </ul></li>
97  <li><a href="#passStatistics">Pass Statistics</a>
98  <li><a href="#passmanager">What PassManager does</a>
99    <ul>
100    <li><a href="#releaseMemory">The <tt>releaseMemory</tt> method</a></li>
101    </ul></li>
102  <li><a href="#registering">Registering dynamically loaded passes</a>
103    <ul>
104      <li><a href="#registering_existing">Using existing registries</a></li>
105      <li><a href="#registering_new">Creating new registries</a></li>
106    </ul></li>
107  <li><a href="#debughints">Using GDB with dynamically loaded passes</a>
108    <ul>
109    <li><a href="#breakpoint">Setting a breakpoint in your pass</a></li>
110    <li><a href="#debugmisc">Miscellaneous Problems</a></li>
111    </ul></li>
112  <li><a href="#future">Future extensions planned</a>
113    <ul>
114    <li><a href="#SMP">Multithreaded LLVM</a></li>
115    </ul></li>
116</ol>
117
118<div class="doc_author">
119  <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
120  <a href="mailto:jlaskey@mac.com">Jim Laskey</a></p>
121</div>
122
123<!-- *********************************************************************** -->
124<h2>
125  <a name="introduction">Introduction - What is a pass?</a>
126</h2>
127<!-- *********************************************************************** -->
128
129<div>
130
131<p>The LLVM Pass Framework is an important part of the LLVM system, because LLVM
132passes are where most of the interesting parts of the compiler exist.  Passes
133perform the transformations and optimizations that make up the compiler, they
134build the analysis results that are used by these transformations, and they are,
135above all, a structuring technique for compiler code.</p>
136
137<p>All LLVM passes are subclasses of the <tt><a
138href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a></tt>
139class, which implement functionality by overriding virtual methods inherited
140from <tt>Pass</tt>.  Depending on how your pass works, you should inherit from
141the <tt><a href="#ModulePass">ModulePass</a></tt>, <tt><a
142href="#CallGraphSCCPass">CallGraphSCCPass</a></tt>, <tt><a
143href="#FunctionPass">FunctionPass</a></tt>, or <tt><a
144href="#LoopPass">LoopPass</a></tt>, or <tt><a
145href="#RegionPass">RegionPass</a></tt>, or <tt><a
146href="#BasicBlockPass">BasicBlockPass</a></tt> classes, which gives the system
147more information about what your pass does, and how it can be combined with
148other passes.  One of the main features of the LLVM Pass Framework is that it
149schedules passes to run in an efficient way based on the constraints that your
150pass meets (which are indicated by which class they derive from).</p>
151
152<p>We start by showing you how to construct a pass, everything from setting up
153the code, to compiling, loading, and executing it.  After the basics are down,
154more advanced features are discussed.</p>
155
156</div>
157
158<!-- *********************************************************************** -->
159<h2>
160  <a name="quickstart">Quick Start - Writing hello world</a>
161</h2>
162<!-- *********************************************************************** -->
163
164<div>
165
166<p>Here we describe how to write the "hello world" of passes.  The "Hello" pass
167is designed to simply print out the name of non-external functions that exist in
168the program being compiled.  It does not modify the program at all, it just
169inspects it.  The source code and files for this pass are available in the LLVM
170source tree in the <tt>lib/Transforms/Hello</tt> directory.</p>
171
172<!-- ======================================================================= -->
173<h3>
174  <a name="makefile">Setting up the build environment</a>
175</h3>
176
177<div>
178
179  <p>First, configure and build LLVM.  This needs to be done directly inside the
180  LLVM source tree rather than in a separate objects directory.
181  Next, you need to create a new directory somewhere in the LLVM source
182  base.  For this example, we'll assume that you made
183  <tt>lib/Transforms/Hello</tt>.  Finally, you must set up a build script
184  (Makefile) that will compile the source code for the new pass.  To do this,
185  copy the following into <tt>Makefile</tt>:</p>
186  <hr>
187
188<div class="doc_code"><pre>
189# Makefile for hello pass
190
191# Path to top level of LLVM hierarchy
192LEVEL = ../../..
193
194# Name of the library to build
195LIBRARYNAME = Hello
196
197# Make the shared library become a loadable module so the tools can
198# dlopen/dlsym on the resulting library.
199LOADABLE_MODULE = 1
200
201# Include the makefile implementation stuff
202include $(LEVEL)/Makefile.common
203</pre></div>
204
205<p>This makefile specifies that all of the <tt>.cpp</tt> files in the current
206directory are to be compiled and linked together into a shared object
207<tt>$(LEVEL)/Debug+Asserts/lib/Hello.so</tt> that can be dynamically loaded by
208the <tt>opt</tt> or <tt>bugpoint</tt> tools via their <tt>-load</tt> options.
209If your operating system uses a suffix other than .so (such as windows or
210Mac OS/X), the appropriate extension will be used.</p>
211
212<p>If you are used CMake to build LLVM, see
213<a href="CMake.html#passdev">Developing an LLVM pass with CMake</a>.</p>
214
215<p>Now that we have the build scripts set up, we just need to write the code for
216the pass itself.</p>
217
218</div>
219
220<!-- ======================================================================= -->
221<h3>
222  <a name="basiccode">Basic code required</a>
223</h3>
224
225<div>
226
227<p>Now that we have a way to compile our new pass, we just have to write it.
228Start out with:</p>
229
230<div class="doc_code">
231<pre>
232<b>#include</b> "<a href="http://llvm.org/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
233<b>#include</b> "<a href="http://llvm.org/doxygen/Function_8h-source.html">llvm/Function.h</a>"
234<b>#include</b> "<a href="http://llvm.org/doxygen/raw__ostream_8h.html">llvm/Support/raw_ostream.h</a>"
235</pre>
236</div>
237
238<p>Which are needed because we are writing a <tt><a
239href="http://llvm.org/doxygen/classllvm_1_1Pass.html">Pass</a></tt>,
240we are operating on <tt><a
241href="http://llvm.org/doxygen/classllvm_1_1Function.html">Function</a></tt>'s,
242and we will be doing some printing.</p>
243
244<p>Next we have:</p>
245
246<div class="doc_code">
247<pre>
248<b>using namespace llvm;</b>
249</pre>
250</div>
251
252<p>... which is required because the functions from the include files
253live in the llvm namespace.</p>
254
255<p>Next we have:</p>
256
257<div class="doc_code">
258<pre>
259<b>namespace</b> {
260</pre>
261</div>
262
263<p>... which starts out an anonymous namespace.  Anonymous namespaces are to C++
264what the "<tt>static</tt>" keyword is to C (at global scope).  It makes the
265things declared inside of the anonymous namespace visible only to the current
266file.  If you're not familiar with them, consult a decent C++ book for more
267information.</p>
268
269<p>Next, we declare our pass itself:</p>
270
271<div class="doc_code">
272<pre>
273  <b>struct</b> Hello : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
274</pre>
275</div>
276
277<p>This declares a "<tt>Hello</tt>" class that is a subclass of <tt><a
278href="http://llvm.org/doxygen/classllvm_1_1FunctionPass.html">FunctionPass</a></tt>.
279The different builtin pass subclasses are described in detail <a
280href="#passtype">later</a>, but for now, know that <a
281href="#FunctionPass"><tt>FunctionPass</tt></a>'s operate on a function at a
282time.</p>
283
284<div class="doc_code">
285<pre>
286    static char ID;
287    Hello() : FunctionPass(ID) {}
288</pre>
289</div>
290
291<p>This declares pass identifier used by LLVM to identify pass. This allows LLVM
292to avoid using expensive C++ runtime information.</p>
293
294<div class="doc_code">
295<pre>
296    <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &amp;F) {
297      errs() &lt;&lt; "<i>Hello: </i>";
298      errs().write_escaped(F.getName()) &lt;&lt; "\n";
299      <b>return false</b>;
300    }
301  };  <i>// end of struct Hello</i>
302}  <i>// end of anonymous namespace</i>
303</pre>
304</div>
305
306<p>We declare a "<a href="#runOnFunction"><tt>runOnFunction</tt></a>" method,
307which overloads an abstract virtual method inherited from <a
308href="#FunctionPass"><tt>FunctionPass</tt></a>.  This is where we are supposed
309to do our thing, so we just print out our message with the name of each
310function.</p>
311
312<div class="doc_code">
313<pre>
314char Hello::ID = 0;
315</pre>
316</div>
317
318<p>We initialize pass ID here. LLVM uses ID's address to identify a pass, so
319initialization value is not important.</p>
320
321<div class="doc_code">
322<pre>
323static RegisterPass&lt;Hello&gt; X("<i>hello</i>", "<i>Hello World Pass</i>",
324                             false /* Only looks at CFG */,
325                             false /* Analysis Pass */);
326</pre>
327</div>
328
329<p>Lastly, we <a href="#registration">register our class</a> <tt>Hello</tt>,
330giving it a command line argument "<tt>hello</tt>", and a name "<tt>Hello World
331Pass</tt>". The last two arguments describe its behavior: if a pass walks CFG
332without modifying it then the third argument is set to <tt>true</tt>; if a pass
333is an analysis pass, for example dominator tree pass, then <tt>true</tt> is
334supplied as the fourth argument.</p>
335
336<p>As a whole, the <tt>.cpp</tt> file looks like:</p>
337
338<div class="doc_code">
339<pre>
340<b>#include</b> "<a href="http://llvm.org/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
341<b>#include</b> "<a href="http://llvm.org/doxygen/Function_8h-source.html">llvm/Function.h</a>"
342<b>#include</b> "<a href="http://llvm.org/doxygen/raw__ostream_8h.html">llvm/Support/raw_ostream.h</a>"
343
344<b>using namespace llvm;</b>
345
346<b>namespace</b> {
347  <b>struct Hello</b> : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
348
349    static char ID;
350    Hello() : FunctionPass(ID) {}
351
352    <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &amp;F) {
353      errs() &lt;&lt; "<i>Hello: </i>";
354      errs().write_escaped(F.getName()) &lt;&lt; '\n';
355      <b>return false</b>;
356    }
357
358  };
359}
360
361char Hello::ID = 0;
362static RegisterPass&lt;Hello&gt; X("hello", "Hello World Pass", false, false);
363</pre>
364</div>
365
366<p>Now that it's all together, compile the file with a simple "<tt>gmake</tt>"
367command in the local directory and you should get a new file
368"<tt>Debug+Asserts/lib/Hello.so</tt>" under the top level directory of the LLVM
369source tree (not in the local directory).  Note that everything in this file is
370contained in an anonymous namespace &mdash; this reflects the fact that passes
371are self contained units that do not need external interfaces (although they can
372have them) to be useful.</p>
373
374</div>
375
376<!-- ======================================================================= -->
377<h3>
378  <a name="running">Running a pass with <tt>opt</tt></a>
379</h3>
380
381<div>
382
383<p>Now that you have a brand new shiny shared object file, we can use the
384<tt>opt</tt> command to run an LLVM program through your pass.  Because you
385registered your pass with <tt>RegisterPass</tt>, you will be able to
386use the <tt>opt</tt> tool to access it, once loaded.</p>
387
388<p>To test it, follow the example at the end of the <a
389href="GettingStarted.html">Getting Started Guide</a> to compile "Hello World" to
390LLVM.  We can now run the bitcode file (<tt>hello.bc</tt>) for the program
391through our transformation like this (or course, any bitcode file will
392work):</p>
393
394<div class="doc_code"><pre>
395$ opt -load ../../../Debug+Asserts/lib/Hello.so -hello &lt; hello.bc &gt; /dev/null
396Hello: __main
397Hello: puts
398Hello: main
399</pre></div>
400
401<p>The '<tt>-load</tt>' option specifies that '<tt>opt</tt>' should load your
402pass as a shared object, which makes '<tt>-hello</tt>' a valid command line
403argument (which is one reason you need to <a href="#registration">register your
404pass</a>).  Because the hello pass does not modify the program in any
405interesting way, we just throw away the result of <tt>opt</tt> (sending it to
406<tt>/dev/null</tt>).</p>
407
408<p>To see what happened to the other string you registered, try running
409<tt>opt</tt> with the <tt>-help</tt> option:</p>
410
411<div class="doc_code"><pre>
412$ opt -load ../../../Debug+Asserts/lib/Hello.so -help
413OVERVIEW: llvm .bc -&gt; .bc modular optimizer
414
415USAGE: opt [options] &lt;input bitcode&gt;
416
417OPTIONS:
418  Optimizations available:
419...
420    -funcresolve    - Resolve Functions
421    -gcse           - Global Common Subexpression Elimination
422    -globaldce      - Dead Global Elimination
423    <b>-hello          - Hello World Pass</b>
424    -indvars        - Canonicalize Induction Variables
425    -inline         - Function Integration/Inlining
426    -instcombine    - Combine redundant instructions
427...
428</pre></div>
429
430<p>The pass name get added as the information string for your pass, giving some
431documentation to users of <tt>opt</tt>.  Now that you have a working pass, you
432would go ahead and make it do the cool transformations you want.  Once you get
433it all working and tested, it may become useful to find out how fast your pass
434is.  The <a href="#passManager"><tt>PassManager</tt></a> provides a nice command
435line option (<tt>--time-passes</tt>) that allows you to get information about
436the execution time of your pass along with the other passes you queue up.  For
437example:</p>
438
439<div class="doc_code"><pre>
440$ opt -load ../../../Debug+Asserts/lib/Hello.so -hello -time-passes &lt; hello.bc &gt; /dev/null
441Hello: __main
442Hello: puts
443Hello: main
444===============================================================================
445                      ... Pass execution timing report ...
446===============================================================================
447  Total Execution Time: 0.02 seconds (0.0479059 wall clock)
448
449   ---User Time---   --System Time--   --User+System--   ---Wall Time---  --- Pass Name ---
450   0.0100 (100.0%)   0.0000 (  0.0%)   0.0100 ( 50.0%)   0.0402 ( 84.0%)  Bitcode Writer
451   0.0000 (  0.0%)   0.0100 (100.0%)   0.0100 ( 50.0%)   0.0031 (  6.4%)  Dominator Set Construction
452   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0013 (  2.7%)  Module Verifier
453 <b>  0.0000 (  0.0%)   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0033 (  6.9%)  Hello World Pass</b>
454   0.0100 (100.0%)   0.0100 (100.0%)   0.0200 (100.0%)   0.0479 (100.0%)  TOTAL
455</pre></div>
456
457<p>As you can see, our implementation above is pretty fast :).  The additional
458passes listed are automatically inserted by the '<tt>opt</tt>' tool to verify
459that the LLVM emitted by your pass is still valid and well formed LLVM, which
460hasn't been broken somehow.</p>
461
462<p>Now that you have seen the basics of the mechanics behind passes, we can talk
463about some more details of how they work and how to use them.</p>
464
465</div>
466
467</div>
468
469<!-- *********************************************************************** -->
470<h2>
471  <a name="passtype">Pass classes and requirements</a>
472</h2>
473<!-- *********************************************************************** -->
474
475<div>
476
477<p>One of the first things that you should do when designing a new pass is to
478decide what class you should subclass for your pass.  The <a
479href="#basiccode">Hello World</a> example uses the <tt><a
480href="#FunctionPass">FunctionPass</a></tt> class for its implementation, but we
481did not discuss why or when this should occur.  Here we talk about the classes
482available, from the most general to the most specific.</p>
483
484<p>When choosing a superclass for your Pass, you should choose the <b>most
485specific</b> class possible, while still being able to meet the requirements
486listed.  This gives the LLVM Pass Infrastructure information necessary to
487optimize how passes are run, so that the resultant compiler isn't unnecessarily
488slow.</p>
489
490<!-- ======================================================================= -->
491<h3>
492  <a name="ImmutablePass">The <tt>ImmutablePass</tt> class</a>
493</h3>
494
495<div>
496
497<p>The most plain and boring type of pass is the "<tt><a
498href="http://llvm.org/doxygen/classllvm_1_1ImmutablePass.html">ImmutablePass</a></tt>"
499class.  This pass type is used for passes that do not have to be run, do not
500change state, and never need to be updated.  This is not a normal type of
501transformation or analysis, but can provide information about the current
502compiler configuration.</p>
503
504<p>Although this pass class is very infrequently used, it is important for
505providing information about the current target machine being compiled for, and
506other static information that can affect the various transformations.</p>
507
508<p><tt>ImmutablePass</tt>es never invalidate other transformations, are never
509invalidated, and are never "run".</p>
510
511</div>
512
513<!-- ======================================================================= -->
514<h3>
515  <a name="ModulePass">The <tt>ModulePass</tt> class</a>
516</h3>
517
518<div>
519
520<p>The "<tt><a
521href="http://llvm.org/doxygen/classllvm_1_1ModulePass.html">ModulePass</a></tt>"
522class is the most general of all superclasses that you can use.  Deriving from
523<tt>ModulePass</tt> indicates that your pass uses the entire program as a unit,
524referring to function bodies in no predictable order, or adding and removing
525functions.  Because nothing is known about the behavior of <tt>ModulePass</tt>
526subclasses, no optimization can be done for their execution.</p>
527
528<p>A module pass can use function level passes (e.g. dominators) using
529the getAnalysis interface
530<tt>getAnalysis&lt;DominatorTree&gt;(llvm::Function *)</tt> to provide the
531function to retrieve analysis result for, if the function pass does not require
532any module or immutable passes. Note that this can only be done for functions for which the
533analysis ran, e.g. in the case of dominators you should only ask for the
534DominatorTree for function definitions, not declarations.</p>
535
536<p>To write a correct <tt>ModulePass</tt> subclass, derive from
537<tt>ModulePass</tt> and overload the <tt>runOnModule</tt> method with the
538following signature:</p>
539
540<!-- _______________________________________________________________________ -->
541<h4>
542  <a name="runOnModule">The <tt>runOnModule</tt> method</a>
543</h4>
544
545<div>
546
547<div class="doc_code"><pre>
548  <b>virtual bool</b> runOnModule(Module &amp;M) = 0;
549</pre></div>
550
551<p>The <tt>runOnModule</tt> method performs the interesting work of the pass.
552It should return true if the module was modified by the transformation and
553false otherwise.</p>
554
555</div>
556
557</div>
558
559<!-- ======================================================================= -->
560<h3>
561  <a name="CallGraphSCCPass">The <tt>CallGraphSCCPass</tt> class</a>
562</h3>
563
564<div>
565
566<p>The "<tt><a
567href="http://llvm.org/doxygen/classllvm_1_1CallGraphSCCPass.html">CallGraphSCCPass</a></tt>"
568is used by passes that need to traverse the program bottom-up on the call graph
569(callees before callers).  Deriving from CallGraphSCCPass provides some
570mechanics for building and traversing the CallGraph, but also allows the system
571to optimize execution of CallGraphSCCPass's.  If your pass meets the
572requirements outlined below, and doesn't meet the requirements of a <tt><a
573href="#FunctionPass">FunctionPass</a></tt> or <tt><a
574href="#BasicBlockPass">BasicBlockPass</a></tt>, you should derive from
575<tt>CallGraphSCCPass</tt>.</p>
576
577<p><b>TODO</b>: explain briefly what SCC, Tarjan's algo, and B-U mean.</p>
578
579<p>To be explicit, <tt>CallGraphSCCPass</tt> subclasses are:</p>
580
581<ol>
582
583<li>... <em>not allowed</em> to inspect or modify any <tt>Function</tt>s other
584than those in the current SCC and the direct callers and direct callees of the
585SCC.</li>
586
587<li>... <em>required</em> to preserve the current CallGraph object, updating it
588to reflect any changes made to the program.</li>
589
590<li>... <em>not allowed</em> to add or remove SCC's from the current Module,
591though they may change the contents of an SCC.</li>
592
593<li>... <em>allowed</em> to add or remove global variables from the current
594Module.</li>
595
596<li>... <em>allowed</em> to maintain state across invocations of
597    <a href="#runOnSCC"><tt>runOnSCC</tt></a> (including global data).</li>
598</ol>
599
600<p>Implementing a <tt>CallGraphSCCPass</tt> is slightly tricky in some cases
601because it has to handle SCCs with more than one node in it.  All of the virtual
602methods described below should return true if they modified the program, or
603false if they didn't.</p>
604
605<!-- _______________________________________________________________________ -->
606<h4>
607  <a name="doInitialization_scc">
608    The <tt>doInitialization(CallGraph &amp;)</tt> method
609  </a>
610</h4>
611
612<div>
613
614<div class="doc_code"><pre>
615  <b>virtual bool</b> doInitialization(CallGraph &amp;CG);
616</pre></div>
617
618<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that
619<tt>CallGraphSCCPass</tt>'s are not allowed to do.  They can add and remove
620functions, get pointers to functions, etc.  The <tt>doInitialization</tt> method
621is designed to do simple initialization type of stuff that does not depend on
622the SCCs being processed.  The <tt>doInitialization</tt> method call is not
623scheduled to overlap with any other pass executions (thus it should be very
624fast).</p>
625
626</div>
627
628<!-- _______________________________________________________________________ -->
629<h4>
630  <a name="runOnSCC">The <tt>runOnSCC</tt> method</a>
631</h4>
632
633<div>
634
635<div class="doc_code"><pre>
636  <b>virtual bool</b> runOnSCC(CallGraphSCC &amp;SCC) = 0;
637</pre></div>
638
639<p>The <tt>runOnSCC</tt> method performs the interesting work of the pass, and
640should return true if the module was modified by the transformation, false
641otherwise.</p>
642
643</div>
644
645<!-- _______________________________________________________________________ -->
646<h4>
647  <a name="doFinalization_scc">
648    The <tt>doFinalization(CallGraph &amp;)</tt> method
649  </a>
650</h4>
651
652<div>
653
654<div class="doc_code"><pre>
655  <b>virtual bool</b> doFinalization(CallGraph &amp;CG);
656</pre></div>
657
658<p>The <tt>doFinalization</tt> method is an infrequently used method that is
659called when the pass framework has finished calling <a
660href="#runOnFunction"><tt>runOnFunction</tt></a> for every function in the
661program being compiled.</p>
662
663</div>
664
665</div>
666
667<!-- ======================================================================= -->
668<h3>
669  <a name="FunctionPass">The <tt>FunctionPass</tt> class</a>
670</h3>
671
672<div>
673
674<p>In contrast to <tt>ModulePass</tt> subclasses, <tt><a
675href="http://llvm.org/doxygen/classllvm_1_1Pass.html">FunctionPass</a></tt>
676subclasses do have a predictable, local behavior that can be expected by the
677system.  All <tt>FunctionPass</tt> execute on each function in the program
678independent of all of the other functions in the program.
679<tt>FunctionPass</tt>'s do not require that they are executed in a particular
680order, and <tt>FunctionPass</tt>'s do not modify external functions.</p>
681
682<p>To be explicit, <tt>FunctionPass</tt> subclasses are not allowed to:</p>
683
684<ol>
685<li>Modify a Function other than the one currently being processed.</li>
686<li>Add or remove Function's from the current Module.</li>
687<li>Add or remove global variables from the current Module.</li>
688<li>Maintain state across invocations of
689    <a href="#runOnFunction"><tt>runOnFunction</tt></a> (including global data)</li>
690</ol>
691
692<p>Implementing a <tt>FunctionPass</tt> is usually straightforward (See the <a
693href="#basiccode">Hello World</a> pass for example).  <tt>FunctionPass</tt>'s
694may overload three virtual methods to do their work.  All of these methods
695should return true if they modified the program, or false if they didn't.</p>
696
697<!-- _______________________________________________________________________ -->
698<h4>
699  <a name="doInitialization_mod">
700    The <tt>doInitialization(Module &amp;)</tt> method
701  </a>
702</h4>
703
704<div>
705
706<div class="doc_code"><pre>
707  <b>virtual bool</b> doInitialization(Module &amp;M);
708</pre></div>
709
710<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that
711<tt>FunctionPass</tt>'s are not allowed to do.  They can add and remove
712functions, get pointers to functions, etc.  The <tt>doInitialization</tt> method
713is designed to do simple initialization type of stuff that does not depend on
714the functions being processed.  The <tt>doInitialization</tt> method call is not
715scheduled to overlap with any other pass executions (thus it should be very
716fast).</p>
717
718<p>A good example of how this method should be used is the <a
719href="http://llvm.org/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations</a>
720pass.  This pass converts <tt>malloc</tt> and <tt>free</tt> instructions into
721platform dependent <tt>malloc()</tt> and <tt>free()</tt> function calls.  It
722uses the <tt>doInitialization</tt> method to get a reference to the malloc and
723free functions that it needs, adding prototypes to the module if necessary.</p>
724
725</div>
726
727<!-- _______________________________________________________________________ -->
728<h4>
729  <a name="runOnFunction">The <tt>runOnFunction</tt> method</a>
730</h4>
731
732<div>
733
734<div class="doc_code"><pre>
735  <b>virtual bool</b> runOnFunction(Function &amp;F) = 0;
736</pre></div><p>
737
738<p>The <tt>runOnFunction</tt> method must be implemented by your subclass to do
739the transformation or analysis work of your pass.  As usual, a true value should
740be returned if the function is modified.</p>
741
742</div>
743
744<!-- _______________________________________________________________________ -->
745<h4>
746  <a name="doFinalization_mod">
747    The <tt>doFinalization(Module &amp;)</tt> method
748  </a>
749</h4>
750
751<div>
752
753<div class="doc_code"><pre>
754  <b>virtual bool</b> doFinalization(Module &amp;M);
755</pre></div>
756
757<p>The <tt>doFinalization</tt> method is an infrequently used method that is
758called when the pass framework has finished calling <a
759href="#runOnFunction"><tt>runOnFunction</tt></a> for every function in the
760program being compiled.</p>
761
762</div>
763
764</div>
765
766<!-- ======================================================================= -->
767<h3>
768  <a name="LoopPass">The <tt>LoopPass</tt> class </a>
769</h3>
770
771<div>
772
773<p> All <tt>LoopPass</tt> execute on each loop in the function independent of
774all of the other loops in the function. <tt>LoopPass</tt> processes loops in
775loop nest order such that outer most loop is processed last. </p>
776
777<p> <tt>LoopPass</tt> subclasses are allowed to update loop nest using
778<tt>LPPassManager</tt> interface. Implementing a loop pass is usually
779straightforward. <tt>LoopPass</tt>'s may overload three virtual methods to
780do their work. All these methods should return true if they modified the
781program, or false if they didn't. </p>
782
783<!-- _______________________________________________________________________ -->
784<h4>
785  <a name="doInitialization_loop">
786    The <tt>doInitialization(Loop *,LPPassManager &amp;)</tt> method
787  </a>
788</h4>
789
790<div>
791
792<div class="doc_code"><pre>
793  <b>virtual bool</b> doInitialization(Loop *, LPPassManager &amp;LPM);
794</pre></div>
795
796<p>The <tt>doInitialization</tt> method is designed to do simple initialization
797type of stuff that does not depend on the functions being processed.  The
798<tt>doInitialization</tt> method call is not scheduled to overlap with any
799other pass executions (thus it should be very fast). LPPassManager
800interface should be used to access Function or Module level analysis
801information.</p>
802
803</div>
804
805
806<!-- _______________________________________________________________________ -->
807<h4>
808  <a name="runOnLoop">The <tt>runOnLoop</tt> method</a>
809</h4>
810
811<div>
812
813<div class="doc_code"><pre>
814  <b>virtual bool</b> runOnLoop(Loop *, LPPassManager &amp;LPM) = 0;
815</pre></div><p>
816
817<p>The <tt>runOnLoop</tt> method must be implemented by your subclass to do
818the transformation or analysis work of your pass.  As usual, a true value should
819be returned if the function is modified. <tt>LPPassManager</tt> interface
820should be used to update loop nest.</p>
821
822</div>
823
824<!-- _______________________________________________________________________ -->
825<h4>
826  <a name="doFinalization_loop">The <tt>doFinalization()</tt> method</a>
827</h4>
828
829<div>
830
831<div class="doc_code"><pre>
832  <b>virtual bool</b> doFinalization();
833</pre></div>
834
835<p>The <tt>doFinalization</tt> method is an infrequently used method that is
836called when the pass framework has finished calling <a
837href="#runOnLoop"><tt>runOnLoop</tt></a> for every loop in the
838program being compiled. </p>
839
840</div>
841
842</div>
843
844<!-- ======================================================================= -->
845<h3>
846  <a name="RegionPass">The <tt>RegionPass</tt> class </a>
847</h3>
848
849<div>
850
851<p> <tt>RegionPass</tt> is similar to <a href="#LoopPass"><tt>LoopPass</tt></a>,
852but executes on each single entry single exit region in the function.
853<tt>RegionPass</tt> processes regions in nested order such that the outer most
854region is processed last.  </p>
855
856<p> <tt>RegionPass</tt> subclasses are allowed to update the region tree by using
857the <tt>RGPassManager</tt> interface. You may overload three virtual methods of
858<tt>RegionPass</tt> to implement your own region pass. All these
859methods should return true if they modified the program, or false if they didn not.
860</p>
861
862<!-- _______________________________________________________________________ -->
863<h4>
864  <a name="doInitialization_region">
865    The <tt>doInitialization(Region *, RGPassManager &amp;)</tt> method
866  </a>
867</h4>
868
869<div>
870
871<div class="doc_code"><pre>
872  <b>virtual bool</b> doInitialization(Region *, RGPassManager &amp;RGM);
873</pre></div>
874
875<p>The <tt>doInitialization</tt> method is designed to do simple initialization
876type of stuff that does not depend on the functions being processed.  The
877<tt>doInitialization</tt> method call is not scheduled to overlap with any
878other pass executions (thus it should be very fast). RPPassManager
879interface should be used to access Function or Module level analysis
880information.</p>
881
882</div>
883
884
885<!-- _______________________________________________________________________ -->
886<h4>
887  <a name="runOnRegion">The <tt>runOnRegion</tt> method</a>
888</h4>
889
890<div>
891
892<div class="doc_code"><pre>
893  <b>virtual bool</b> runOnRegion(Region *, RGPassManager &amp;RGM) = 0;
894</pre></div><p>
895
896<p>The <tt>runOnRegion</tt> method must be implemented by your subclass to do
897the transformation or analysis work of your pass.  As usual, a true value should
898be returned if the region is modified. <tt>RGPassManager</tt> interface
899should be used to update region tree.</p>
900
901</div>
902
903<!-- _______________________________________________________________________ -->
904<h4>
905  <a name="doFinalization_region">The <tt>doFinalization()</tt> method</a>
906</h4>
907
908<div>
909
910<div class="doc_code"><pre>
911  <b>virtual bool</b> doFinalization();
912</pre></div>
913
914<p>The <tt>doFinalization</tt> method is an infrequently used method that is
915called when the pass framework has finished calling <a
916href="#runOnRegion"><tt>runOnRegion</tt></a> for every region in the
917program being compiled. </p>
918
919</div>
920
921</div>
922
923<!-- ======================================================================= -->
924<h3>
925  <a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
926</h3>
927
928<div>
929
930<p><tt>BasicBlockPass</tt>'s are just like <a
931href="#FunctionPass"><tt>FunctionPass</tt></a>'s, except that they must limit
932their scope of inspection and modification to a single basic block at a time.
933As such, they are <b>not</b> allowed to do any of the following:</p>
934
935<ol>
936<li>Modify or inspect any basic blocks outside of the current one</li>
937<li>Maintain state across invocations of
938    <a href="#runOnBasicBlock"><tt>runOnBasicBlock</tt></a></li>
939<li>Modify the control flow graph (by altering terminator instructions)</li>
940<li>Any of the things forbidden for
941    <a href="#FunctionPass"><tt>FunctionPass</tt></a>es.</li>
942</ol>
943
944<p><tt>BasicBlockPass</tt>es are useful for traditional local and "peephole"
945optimizations.  They may override the same <a
946href="#doInitialization_mod"><tt>doInitialization(Module &amp;)</tt></a> and <a
947href="#doFinalization_mod"><tt>doFinalization(Module &amp;)</tt></a> methods that <a
948href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have the following virtual methods that may also be implemented:</p>
949
950<!-- _______________________________________________________________________ -->
951<h4>
952  <a name="doInitialization_fn">
953    The <tt>doInitialization(Function &amp;)</tt> method
954  </a>
955</h4>
956
957<div>
958
959<div class="doc_code"><pre>
960  <b>virtual bool</b> doInitialization(Function &amp;F);
961</pre></div>
962
963<p>The <tt>doIninitialize</tt> method is allowed to do most of the things that
964<tt>BasicBlockPass</tt>'s are not allowed to do, but that
965<tt>FunctionPass</tt>'s can.  The <tt>doInitialization</tt> method is designed
966to do simple initialization that does not depend on the
967BasicBlocks being processed.  The <tt>doInitialization</tt> method call is not
968scheduled to overlap with any other pass executions (thus it should be very
969fast).</p>
970
971</div>
972
973<!-- _______________________________________________________________________ -->
974<h4>
975  <a name="runOnBasicBlock">The <tt>runOnBasicBlock</tt> method</a>
976</h4>
977
978<div>
979
980<div class="doc_code"><pre>
981  <b>virtual bool</b> runOnBasicBlock(BasicBlock &amp;BB) = 0;
982</pre></div>
983
984<p>Override this function to do the work of the <tt>BasicBlockPass</tt>.  This
985function is not allowed to inspect or modify basic blocks other than the
986parameter, and are not allowed to modify the CFG.  A true value must be returned
987if the basic block is modified.</p>
988
989</div>
990
991<!-- _______________________________________________________________________ -->
992<h4>
993  <a name="doFinalization_fn">
994    The <tt>doFinalization(Function &amp;)</tt> method
995  </a>
996</h4>
997
998<div>
999
1000<div class="doc_code"><pre>
1001  <b>virtual bool</b> doFinalization(Function &amp;F);
1002</pre></div>
1003
1004<p>The <tt>doFinalization</tt> method is an infrequently used method that is
1005called when the pass framework has finished calling <a
1006href="#runOnBasicBlock"><tt>runOnBasicBlock</tt></a> for every BasicBlock in the
1007program being compiled.  This can be used to perform per-function
1008finalization.</p>
1009
1010</div>
1011
1012</div>
1013
1014<!-- ======================================================================= -->
1015<h3>
1016  <a name="MachineFunctionPass">The <tt>MachineFunctionPass</tt> class</a>
1017</h3>
1018
1019<div>
1020
1021<p>A <tt>MachineFunctionPass</tt> is a part of the LLVM code generator that
1022executes on the machine-dependent representation of each LLVM function in the
1023program.</p>
1024
1025<p>Code generator passes are registered and initialized specially by
1026<tt>TargetMachine::addPassesToEmitFile</tt> and similar routines, so they
1027cannot generally be run from the <tt>opt</tt> or <tt>bugpoint</tt>
1028commands.</p>
1029
1030<p>A <tt>MachineFunctionPass</tt> is also a <tt>FunctionPass</tt>, so all
1031the restrictions that apply to a <tt>FunctionPass</tt> also apply to it.
1032<tt>MachineFunctionPass</tt>es also have additional restrictions. In particular,
1033<tt>MachineFunctionPass</tt>es are not allowed to do any of the following:</p>
1034
1035<ol>
1036<li>Modify or create any LLVM IR Instructions, BasicBlocks, Arguments,
1037    Functions, GlobalVariables, GlobalAliases, or Modules.</li>
1038<li>Modify a MachineFunction other than the one currently being processed.</li>
1039<li>Maintain state across invocations of <a
1040href="#runOnMachineFunction"><tt>runOnMachineFunction</tt></a> (including global
1041data)</li>
1042</ol>
1043
1044<!-- _______________________________________________________________________ -->
1045<h4>
1046  <a name="runOnMachineFunction">
1047    The <tt>runOnMachineFunction(MachineFunction &amp;MF)</tt> method
1048  </a>
1049</h4>
1050
1051<div>
1052
1053<div class="doc_code"><pre>
1054  <b>virtual bool</b> runOnMachineFunction(MachineFunction &amp;MF) = 0;
1055</pre></div>
1056
1057<p><tt>runOnMachineFunction</tt> can be considered the main entry point of a
1058<tt>MachineFunctionPass</tt>; that is, you should override this method to do the
1059work of your <tt>MachineFunctionPass</tt>.</p>
1060
1061<p>The <tt>runOnMachineFunction</tt> method is called on every
1062<tt>MachineFunction</tt> in a <tt>Module</tt>, so that the
1063<tt>MachineFunctionPass</tt> may perform optimizations on the machine-dependent
1064representation of the function. If you want to get at the LLVM <tt>Function</tt>
1065for the <tt>MachineFunction</tt> you're working on, use
1066<tt>MachineFunction</tt>'s <tt>getFunction()</tt> accessor method -- but
1067remember, you may not modify the LLVM <tt>Function</tt> or its contents from a
1068<tt>MachineFunctionPass</tt>.</p>
1069
1070</div>
1071
1072</div>
1073
1074</div>
1075
1076<!-- *********************************************************************** -->
1077<h2>
1078  <a name="registration">Pass registration</a>
1079</h2>
1080<!-- *********************************************************************** -->
1081
1082<div>
1083
1084<p>In the <a href="#basiccode">Hello World</a> example pass we illustrated how
1085pass registration works, and discussed some of the reasons that it is used and
1086what it does.  Here we discuss how and why passes are registered.</p>
1087
1088<p>As we saw above, passes are registered with the <b><tt>RegisterPass</tt></b>
1089template.  The template parameter is the name of the pass that is to be used on
1090the command line to specify that the pass should be added to a program (for
1091example, with <tt>opt</tt> or <tt>bugpoint</tt>).  The first argument is the
1092name of the pass, which is to be used for the <tt>-help</tt> output of
1093programs, as
1094well as for debug output generated by the <tt>--debug-pass</tt> option.</p>
1095
1096<p>If you want your pass to be easily dumpable, you should
1097implement the virtual <tt>print</tt> method:</p>
1098
1099<!-- _______________________________________________________________________ -->
1100<h4>
1101  <a name="print">The <tt>print</tt> method</a>
1102</h4>
1103
1104<div>
1105
1106<div class="doc_code"><pre>
1107  <b>virtual void</b> print(std::ostream &amp;O, <b>const</b> Module *M) <b>const</b>;
1108</pre></div>
1109
1110<p>The <tt>print</tt> method must be implemented by "analyses" in order to print
1111a human readable version of the analysis results.  This is useful for debugging
1112an analysis itself, as well as for other people to figure out how an analysis
1113works.  Use the <tt>opt -analyze</tt> argument to invoke this method.</p>
1114
1115<p>The <tt>llvm::OStream</tt> parameter specifies the stream to write the results on,
1116and the <tt>Module</tt> parameter gives a pointer to the top level module of the
1117program that has been analyzed.  Note however that this pointer may be null in
1118certain circumstances (such as calling the <tt>Pass::dump()</tt> from a
1119debugger), so it should only be used to enhance debug output, it should not be
1120depended on.</p>
1121
1122</div>
1123
1124</div>
1125
1126<!-- *********************************************************************** -->
1127<h2>
1128  <a name="interaction">Specifying interactions between passes</a>
1129</h2>
1130<!-- *********************************************************************** -->
1131
1132<div>
1133
1134<p>One of the main responsibilities of the <tt>PassManager</tt> is to make sure
1135that passes interact with each other correctly.  Because <tt>PassManager</tt>
1136tries to <a href="#passmanager">optimize the execution of passes</a> it must
1137know how the passes interact with each other and what dependencies exist between
1138the various passes.  To track this, each pass can declare the set of passes that
1139are required to be executed before the current pass, and the passes which are
1140invalidated by the current pass.</p>
1141
1142<p>Typically this functionality is used to require that analysis results are
1143computed before your pass is run.  Running arbitrary transformation passes can
1144invalidate the computed analysis results, which is what the invalidation set
1145specifies.  If a pass does not implement the <tt><a
1146href="#getAnalysisUsage">getAnalysisUsage</a></tt> method, it defaults to not
1147having any prerequisite passes, and invalidating <b>all</b> other passes.</p>
1148
1149<!-- _______________________________________________________________________ -->
1150<h4>
1151  <a name="getAnalysisUsage">The <tt>getAnalysisUsage</tt> method</a>
1152</h4>
1153
1154<div>
1155
1156<div class="doc_code"><pre>
1157  <b>virtual void</b> getAnalysisUsage(AnalysisUsage &amp;Info) <b>const</b>;
1158</pre></div>
1159
1160<p>By implementing the <tt>getAnalysisUsage</tt> method, the required and
1161invalidated sets may be specified for your transformation.  The implementation
1162should fill in the <tt><a
1163href="http://llvm.org/doxygen/classllvm_1_1AnalysisUsage.html">AnalysisUsage</a></tt>
1164object with information about which passes are required and not invalidated.  To
1165do this, a pass may call any of the following methods on the AnalysisUsage
1166object:</p>
1167</div>
1168
1169<!-- _______________________________________________________________________ -->
1170<h4>
1171  <a name="AU::addRequired">
1172    The <tt>AnalysisUsage::addRequired&lt;&gt;</tt>
1173    and <tt>AnalysisUsage::addRequiredTransitive&lt;&gt;</tt> methods
1174  </a>
1175</h4>
1176
1177<div>
1178<p>
1179If your pass requires a previous pass to be executed (an analysis for example),
1180it can use one of these methods to arrange for it to be run before your pass.
1181LLVM has many different types of analyses and passes that can be required,
1182spanning the range from <tt>DominatorSet</tt> to <tt>BreakCriticalEdges</tt>.
1183Requiring <tt>BreakCriticalEdges</tt>, for example, guarantees that there will
1184be no critical edges in the CFG when your pass has been run.
1185</p>
1186
1187<p>
1188Some analyses chain to other analyses to do their job.  For example, an <a
1189href="AliasAnalysis.html">AliasAnalysis</a> implementation is required to <a
1190href="AliasAnalysis.html#chaining">chain</a> to other alias analysis passes.  In
1191cases where analyses chain, the <tt>addRequiredTransitive</tt> method should be
1192used instead of the <tt>addRequired</tt> method.  This informs the PassManager
1193that the transitively required pass should be alive as long as the requiring
1194pass is.
1195</p>
1196</div>
1197
1198<!-- _______________________________________________________________________ -->
1199<h4>
1200  <a name="AU::addPreserved">
1201    The <tt>AnalysisUsage::addPreserved&lt;&gt;</tt> method
1202  </a>
1203</h4>
1204
1205<div>
1206<p>
1207One of the jobs of the PassManager is to optimize how and when analyses are run.
1208In particular, it attempts to avoid recomputing data unless it needs to.  For
1209this reason, passes are allowed to declare that they preserve (i.e., they don't
1210invalidate) an existing analysis if it's available.  For example, a simple
1211constant folding pass would not modify the CFG, so it can't possibly affect the
1212results of dominator analysis.  By default, all passes are assumed to invalidate
1213all others.
1214</p>
1215
1216<p>
1217The <tt>AnalysisUsage</tt> class provides several methods which are useful in
1218certain circumstances that are related to <tt>addPreserved</tt>.  In particular,
1219the <tt>setPreservesAll</tt> method can be called to indicate that the pass does
1220not modify the LLVM program at all (which is true for analyses), and the
1221<tt>setPreservesCFG</tt> method can be used by transformations that change
1222instructions in the program but do not modify the CFG or terminator instructions
1223(note that this property is implicitly set for <a
1224href="#BasicBlockPass">BasicBlockPass</a>'s).
1225</p>
1226
1227<p>
1228<tt>addPreserved</tt> is particularly useful for transformations like
1229<tt>BreakCriticalEdges</tt>.  This pass knows how to update a small set of loop
1230and dominator related analyses if they exist, so it can preserve them, despite
1231the fact that it hacks on the CFG.
1232</p>
1233</div>
1234
1235<!-- _______________________________________________________________________ -->
1236<h4>
1237  <a name="AU::examples">
1238    Example implementations of <tt>getAnalysisUsage</tt>
1239  </a>
1240</h4>
1241
1242<div>
1243
1244<div class="doc_code"><pre>
1245  <i>// This example modifies the program, but does not modify the CFG</i>
1246  <b>void</b> <a href="http://llvm.org/doxygen/structLICM.html">LICM</a>::getAnalysisUsage(AnalysisUsage &amp;AU) <b>const</b> {
1247    AU.setPreservesCFG();
1248    AU.addRequired&lt;<a href="http://llvm.org/doxygen/classllvm_1_1LoopInfo.html">LoopInfo</a>&gt;();
1249  }
1250</pre></div>
1251
1252</div>
1253
1254<!-- _______________________________________________________________________ -->
1255<h4>
1256  <a name="getAnalysis">
1257    The <tt>getAnalysis&lt;&gt;</tt> and
1258    <tt>getAnalysisIfAvailable&lt;&gt;</tt> methods
1259  </a>
1260</h4>
1261
1262<div>
1263
1264<p>The <tt>Pass::getAnalysis&lt;&gt;</tt> method is automatically inherited by
1265your class, providing you with access to the passes that you declared that you
1266required with the <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a>
1267method.  It takes a single template argument that specifies which pass class you
1268want, and returns a reference to that pass.  For example:</p>
1269
1270<div class="doc_code"><pre>
1271   bool LICM::runOnFunction(Function &amp;F) {
1272     LoopInfo &amp;LI = getAnalysis&lt;LoopInfo&gt;();
1273     ...
1274   }
1275</pre></div>
1276
1277<p>This method call returns a reference to the pass desired.  You may get a
1278runtime assertion failure if you attempt to get an analysis that you did not
1279declare as required in your <a
1280href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> implementation.  This
1281method can be called by your <tt>run*</tt> method implementation, or by any
1282other local method invoked by your <tt>run*</tt> method.
1283
1284A module level pass can use function level analysis info using this interface.
1285For example:</p>
1286
1287<div class="doc_code"><pre>
1288   bool ModuleLevelPass::runOnModule(Module &amp;M) {
1289     ...
1290     DominatorTree &amp;DT = getAnalysis&lt;DominatorTree&gt;(Func);
1291     ...
1292   }
1293</pre></div>
1294
1295<p>In above example, runOnFunction for DominatorTree is called by pass manager
1296before returning a reference to the desired pass.</p>
1297
1298<p>
1299If your pass is capable of updating analyses if they exist (e.g.,
1300<tt>BreakCriticalEdges</tt>, as described above), you can use the
1301<tt>getAnalysisIfAvailable</tt> method, which returns a pointer to the analysis
1302if it is active.  For example:</p>
1303
1304<div class="doc_code"><pre>
1305  ...
1306  if (DominatorSet *DS = getAnalysisIfAvailable&lt;DominatorSet&gt;()) {
1307    <i>// A DominatorSet is active.  This code will update it.</i>
1308  }
1309  ...
1310</pre></div>
1311
1312</div>
1313
1314</div>
1315
1316<!-- *********************************************************************** -->
1317<h2>
1318  <a name="analysisgroup">Implementing Analysis Groups</a>
1319</h2>
1320<!-- *********************************************************************** -->
1321
1322<div>
1323
1324<p>Now that we understand the basics of how passes are defined, how they are
1325used, and how they are required from other passes, it's time to get a little bit
1326fancier.  All of the pass relationships that we have seen so far are very
1327simple: one pass depends on one other specific pass to be run before it can run.
1328For many applications, this is great, for others, more flexibility is
1329required.</p>
1330
1331<p>In particular, some analyses are defined such that there is a single simple
1332interface to the analysis results, but multiple ways of calculating them.
1333Consider alias analysis for example.  The most trivial alias analysis returns
1334"may alias" for any alias query.  The most sophisticated analysis a
1335flow-sensitive, context-sensitive interprocedural analysis that can take a
1336significant amount of time to execute (and obviously, there is a lot of room
1337between these two extremes for other implementations).  To cleanly support
1338situations like this, the LLVM Pass Infrastructure supports the notion of
1339Analysis Groups.</p>
1340
1341<!-- _______________________________________________________________________ -->
1342<h4>
1343  <a name="agconcepts">Analysis Group Concepts</a>
1344</h4>
1345
1346<div>
1347
1348<p>An Analysis Group is a single simple interface that may be implemented by
1349multiple different passes.  Analysis Groups can be given human readable names
1350just like passes, but unlike passes, they need not derive from the <tt>Pass</tt>
1351class.  An analysis group may have one or more implementations, one of which is
1352the "default" implementation.</p>
1353
1354<p>Analysis groups are used by client passes just like other passes are: the
1355<tt>AnalysisUsage::addRequired()</tt> and <tt>Pass::getAnalysis()</tt> methods.
1356In order to resolve this requirement, the <a href="#passmanager">PassManager</a>
1357scans the available passes to see if any implementations of the analysis group
1358are available.  If none is available, the default implementation is created for
1359the pass to use.  All standard rules for <A href="#interaction">interaction
1360between passes</a> still apply.</p>
1361
1362<p>Although <a href="#registration">Pass Registration</a> is optional for normal
1363passes, all analysis group implementations must be registered, and must use the
1364<A href="#registerag"><tt>INITIALIZE_AG_PASS</tt></a> template to join the
1365implementation pool.  Also, a default implementation of the interface
1366<b>must</b> be registered with <A
1367href="#registerag"><tt>RegisterAnalysisGroup</tt></a>.</p>
1368
1369<p>As a concrete example of an Analysis Group in action, consider the <a
1370href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>
1371analysis group.  The default implementation of the alias analysis interface (the
1372<tt><a
1373href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">basicaa</a></tt>
1374pass) just does a few simple checks that don't require significant analysis to
1375compute (such as: two different globals can never alias each other, etc).
1376Passes that use the <tt><a
1377href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a></tt>
1378interface (for example the <tt><a
1379href="http://llvm.org/doxygen/structGCSE.html">gcse</a></tt> pass), do
1380not care which implementation of alias analysis is actually provided, they just
1381use the designated interface.</p>
1382
1383<p>From the user's perspective, commands work just like normal.  Issuing the
1384command '<tt>opt -gcse ...</tt>' will cause the <tt>basicaa</tt> class to be
1385instantiated and added to the pass sequence.  Issuing the command '<tt>opt
1386-somefancyaa -gcse ...</tt>' will cause the <tt>gcse</tt> pass to use the
1387<tt>somefancyaa</tt> alias analysis (which doesn't actually exist, it's just a
1388hypothetical example) instead.</p>
1389
1390</div>
1391
1392<!-- _______________________________________________________________________ -->
1393<h4>
1394  <a name="registerag">Using <tt>RegisterAnalysisGroup</tt></a>
1395</h4>
1396
1397<div>
1398
1399<p>The <tt>RegisterAnalysisGroup</tt> template is used to register the analysis
1400group itself, while the <tt>INITIALIZE_AG_PASS</tt> is used to add pass
1401implementations to the analysis group.  First,
1402an analysis group should be registered, with a human readable name
1403provided for it.
1404Unlike registration of passes, there is no command line argument to be specified
1405for the Analysis Group Interface itself, because it is "abstract":</p>
1406
1407<div class="doc_code"><pre>
1408  <b>static</b> RegisterAnalysisGroup&lt;<a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>&gt; A("<i>Alias Analysis</i>");
1409</pre></div>
1410
1411<p>Once the analysis is registered, passes can declare that they are valid
1412implementations of the interface by using the following code:</p>
1413
1414<div class="doc_code"><pre>
1415<b>namespace</b> {
1416  //<i> Declare that we implement the AliasAnalysis interface</i>
1417  INITIALIZE_AG_PASS(FancyAA, <a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>, "<i>somefancyaa</i>",
1418                     "<i>A more complex alias analysis implementation</i>",
1419                     false, // <i>Is CFG Only?</i>
1420                     true,  // <i>Is Analysis?</i>
1421                     false, // <i>Is default Analysis Group implementation?</i>
1422                    );
1423}
1424</pre></div>
1425
1426<p>This just shows a class <tt>FancyAA</tt> that
1427uses the <tt>INITIALIZE_AG_PASS</tt> macro both to register and
1428to "join" the <tt><a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a></tt>
1429analysis group.  Every implementation of an analysis group should join using
1430this macro.</p>
1431
1432<div class="doc_code"><pre>
1433<b>namespace</b> {
1434  //<i> Declare that we implement the AliasAnalysis interface</i>
1435  INITIALIZE_AG_PASS(BasicAA, <a href="http://llvm.org/doxygen/classllvm_1_1AliasAnalysis.html">AliasAnalysis</a>, "<i>basicaa</i>",
1436                     "<i>Basic Alias Analysis (default AA impl)</i>",
1437                     false, // <i>Is CFG Only?</i>
1438                     true,  // <i>Is Analysis?</i>
1439                     true, // <i>Is default Analysis Group implementation?</i>
1440                    );
1441}
1442</pre></div>
1443
1444<p>Here we show how the default implementation is specified (using the final
1445argument to the <tt>INITIALIZE_AG_PASS</tt> template).  There must be exactly
1446one default implementation available at all times for an Analysis Group to be
1447used.  Only default implementation can derive from <tt>ImmutablePass</tt>.
1448Here we declare that the
1449 <tt><a href="http://llvm.org/doxygen/structBasicAliasAnalysis.html">BasicAliasAnalysis</a></tt>
1450pass is the default implementation for the interface.</p>
1451
1452</div>
1453
1454</div>
1455
1456<!-- *********************************************************************** -->
1457<h2>
1458  <a name="passStatistics">Pass Statistics</a>
1459</h2>
1460<!-- *********************************************************************** -->
1461
1462<div>
1463<p>The <a
1464href="http://llvm.org/doxygen/Statistic_8h-source.html"><tt>Statistic</tt></a>
1465class is designed to be an easy way to expose various success
1466metrics from passes.  These statistics are printed at the end of a
1467run, when the -stats command line option is enabled on the command
1468line. See the <a href="http://llvm.org/docs/ProgrammersManual.html#Statistic">Statistics section</a> in the Programmer's Manual for details.
1469
1470</div>
1471
1472
1473<!-- *********************************************************************** -->
1474<h2>
1475  <a name="passmanager">What PassManager does</a>
1476</h2>
1477<!-- *********************************************************************** -->
1478
1479<div>
1480
1481<p>The <a
1482href="http://llvm.org/doxygen/PassManager_8h-source.html"><tt>PassManager</tt></a>
1483<a
1484href="http://llvm.org/doxygen/classllvm_1_1PassManager.html">class</a>
1485takes a list of passes, ensures their <a href="#interaction">prerequisites</a>
1486are set up correctly, and then schedules passes to run efficiently.  All of the
1487LLVM tools that run passes use the <tt>PassManager</tt> for execution of these
1488passes.</p>
1489
1490<p>The <tt>PassManager</tt> does two main things to try to reduce the execution
1491time of a series of passes:</p>
1492
1493<ol>
1494<li><b>Share analysis results</b> - The PassManager attempts to avoid
1495recomputing analysis results as much as possible.  This means keeping track of
1496which analyses are available already, which analyses get invalidated, and which
1497analyses are needed to be run for a pass.  An important part of work is that the
1498<tt>PassManager</tt> tracks the exact lifetime of all analysis results, allowing
1499it to <a href="#releaseMemory">free memory</a> allocated to holding analysis
1500results as soon as they are no longer needed.</li>
1501
1502<li><b>Pipeline the execution of passes on the program</b> - The
1503<tt>PassManager</tt> attempts to get better cache and memory usage behavior out
1504of a series of passes by pipelining the passes together.  This means that, given
1505a series of consecutive <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s, it
1506will execute all of the <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s on
1507the first function, then all of the <a
1508href="#FunctionPass"><tt>FunctionPass</tt></a>es on the second function,
1509etc... until the entire program has been run through the passes.
1510
1511<p>This improves the cache behavior of the compiler, because it is only touching
1512the LLVM program representation for a single function at a time, instead of
1513traversing the entire program.  It reduces the memory consumption of compiler,
1514because, for example, only one <a
1515href="http://llvm.org/doxygen/classllvm_1_1DominatorSet.html"><tt>DominatorSet</tt></a>
1516needs to be calculated at a time.  This also makes it possible to implement
1517some <a
1518href="#SMP">interesting enhancements</a> in the future.</p></li>
1519
1520</ol>
1521
1522<p>The effectiveness of the <tt>PassManager</tt> is influenced directly by how
1523much information it has about the behaviors of the passes it is scheduling.  For
1524example, the "preserved" set is intentionally conservative in the face of an
1525unimplemented <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method.
1526Not implementing when it should be implemented will have the effect of not
1527allowing any analysis results to live across the execution of your pass.</p>
1528
1529<p>The <tt>PassManager</tt> class exposes a <tt>--debug-pass</tt> command line
1530options that is useful for debugging pass execution, seeing how things work, and
1531diagnosing when you should be preserving more analyses than you currently are
1532(To get information about all of the variants of the <tt>--debug-pass</tt>
1533option, just type '<tt>opt -help-hidden</tt>').</p>
1534
1535<p>By using the <tt>--debug-pass=Structure</tt> option, for example, we can see
1536how our <a href="#basiccode">Hello World</a> pass interacts with other passes.
1537Lets try it out with the <tt>gcse</tt> and <tt>licm</tt> passes:</p>
1538
1539<div class="doc_code"><pre>
1540$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -licm --debug-pass=Structure &lt; hello.bc &gt; /dev/null
1541Module Pass Manager
1542  Function Pass Manager
1543    Dominator Set Construction
1544    Immediate Dominators Construction
1545    Global Common Subexpression Elimination
1546--  Immediate Dominators Construction
1547--  Global Common Subexpression Elimination
1548    Natural Loop Construction
1549    Loop Invariant Code Motion
1550--  Natural Loop Construction
1551--  Loop Invariant Code Motion
1552    Module Verifier
1553--  Dominator Set Construction
1554--  Module Verifier
1555  Bitcode Writer
1556--Bitcode Writer
1557</pre></div>
1558
1559<p>This output shows us when passes are constructed and when the analysis
1560results are known to be dead (prefixed with '<tt>--</tt>').  Here we see that
1561GCSE uses dominator and immediate dominator information to do its job.  The LICM
1562pass uses natural loop information, which uses dominator sets, but not immediate
1563dominators.  Because immediate dominators are no longer useful after the GCSE
1564pass, it is immediately destroyed.  The dominator sets are then reused to
1565compute natural loop information, which is then used by the LICM pass.</p>
1566
1567<p>After the LICM pass, the module verifier runs (which is automatically added
1568by the '<tt>opt</tt>' tool), which uses the dominator set to check that the
1569resultant LLVM code is well formed.  After it finishes, the dominator set
1570information is destroyed, after being computed once, and shared by three
1571passes.</p>
1572
1573<p>Lets see how this changes when we run the <a href="#basiccode">Hello
1574World</a> pass in between the two passes:</p>
1575
1576<div class="doc_code"><pre>
1577$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure &lt; hello.bc &gt; /dev/null
1578Module Pass Manager
1579  Function Pass Manager
1580    Dominator Set Construction
1581    Immediate Dominators Construction
1582    Global Common Subexpression Elimination
1583<b>--  Dominator Set Construction</b>
1584--  Immediate Dominators Construction
1585--  Global Common Subexpression Elimination
1586<b>    Hello World Pass
1587--  Hello World Pass
1588    Dominator Set Construction</b>
1589    Natural Loop Construction
1590    Loop Invariant Code Motion
1591--  Natural Loop Construction
1592--  Loop Invariant Code Motion
1593    Module Verifier
1594--  Dominator Set Construction
1595--  Module Verifier
1596  Bitcode Writer
1597--Bitcode Writer
1598Hello: __main
1599Hello: puts
1600Hello: main
1601</pre></div>
1602
1603<p>Here we see that the <a href="#basiccode">Hello World</a> pass has killed the
1604Dominator Set pass, even though it doesn't modify the code at all!  To fix this,
1605we need to add the following <a
1606href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method to our pass:</p>
1607
1608<div class="doc_code"><pre>
1609    <i>// We don't modify the program, so we preserve all analyses</i>
1610    <b>virtual void</b> getAnalysisUsage(AnalysisUsage &amp;AU) <b>const</b> {
1611      AU.setPreservesAll();
1612    }
1613</pre></div>
1614
1615<p>Now when we run our pass, we get this output:</p>
1616
1617<div class="doc_code"><pre>
1618$ opt -load ../../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure &lt; hello.bc &gt; /dev/null
1619Pass Arguments:  -gcse -hello -licm
1620Module Pass Manager
1621  Function Pass Manager
1622    Dominator Set Construction
1623    Immediate Dominators Construction
1624    Global Common Subexpression Elimination
1625--  Immediate Dominators Construction
1626--  Global Common Subexpression Elimination
1627    Hello World Pass
1628--  Hello World Pass
1629    Natural Loop Construction
1630    Loop Invariant Code Motion
1631--  Loop Invariant Code Motion
1632--  Natural Loop Construction
1633    Module Verifier
1634--  Dominator Set Construction
1635--  Module Verifier
1636  Bitcode Writer
1637--Bitcode Writer
1638Hello: __main
1639Hello: puts
1640Hello: main
1641</pre></div>
1642
1643<p>Which shows that we don't accidentally invalidate dominator information
1644anymore, and therefore do not have to compute it twice.</p>
1645
1646<!-- _______________________________________________________________________ -->
1647<h4>
1648  <a name="releaseMemory">The <tt>releaseMemory</tt> method</a>
1649</h4>
1650
1651<div>
1652
1653<div class="doc_code"><pre>
1654  <b>virtual void</b> releaseMemory();
1655</pre></div>
1656
1657<p>The <tt>PassManager</tt> automatically determines when to compute analysis
1658results, and how long to keep them around for.  Because the lifetime of the pass
1659object itself is effectively the entire duration of the compilation process, we
1660need some way to free analysis results when they are no longer useful.  The
1661<tt>releaseMemory</tt> virtual method is the way to do this.</p>
1662
1663<p>If you are writing an analysis or any other pass that retains a significant
1664amount of state (for use by another pass which "requires" your pass and uses the
1665<a href="#getAnalysis">getAnalysis</a> method) you should implement
1666<tt>releaseMemory</tt> to, well, release the memory allocated to maintain this
1667internal state.  This method is called after the <tt>run*</tt> method for the
1668class, before the next call of <tt>run*</tt> in your pass.</p>
1669
1670</div>
1671
1672</div>
1673
1674<!-- *********************************************************************** -->
1675<h2>
1676  <a name="registering">Registering dynamically loaded passes</a>
1677</h2>
1678<!-- *********************************************************************** -->
1679
1680<div>
1681
1682<p><i>Size matters</i> when constructing production quality tools using llvm,
1683both for the purposes of distribution, and for regulating the resident code size
1684when running on the target system. Therefore, it becomes desirable to
1685selectively use some passes, while omitting others and maintain the flexibility
1686to change configurations later on. You want to be able to do all this, and,
1687provide feedback to the user. This is where pass registration comes into
1688play.</p>
1689
1690<p>The fundamental mechanisms for pass registration are the
1691<tt>MachinePassRegistry</tt> class and subclasses of
1692<tt>MachinePassRegistryNode</tt>.</p>
1693
1694<p>An instance of <tt>MachinePassRegistry</tt> is used to maintain a list of
1695<tt>MachinePassRegistryNode</tt> objects.  This instance maintains the list and
1696communicates additions and deletions to the command line interface.</p>
1697
1698<p>An instance of <tt>MachinePassRegistryNode</tt> subclass is used to maintain
1699information provided about a particular pass.  This information includes the
1700command line name, the command help string and the address of the function used
1701to create an instance of the pass.  A global static constructor of one of these
1702instances <i>registers</i> with a corresponding <tt>MachinePassRegistry</tt>,
1703the static destructor <i>unregisters</i>. Thus a pass that is statically linked
1704in the tool will be registered at start up. A dynamically loaded pass will
1705register on load and unregister at unload.</p>
1706
1707<!-- _______________________________________________________________________ -->
1708<h3>
1709  <a name="registering_existing">Using existing registries</a>
1710</h3>
1711
1712<div>
1713
1714<p>There are predefined registries to track instruction scheduling
1715(<tt>RegisterScheduler</tt>) and register allocation (<tt>RegisterRegAlloc</tt>)
1716machine passes.  Here we will describe how to <i>register</i> a register
1717allocator machine pass.</p>
1718
1719<p>Implement your register allocator machine pass.  In your register allocator
1720.cpp file add the following include;</p>
1721
1722<div class="doc_code"><pre>
1723  #include "llvm/CodeGen/RegAllocRegistry.h"
1724</pre></div>
1725
1726<p>Also in your register allocator .cpp file, define a creator function in the
1727form; </p>
1728
1729<div class="doc_code"><pre>
1730  FunctionPass *createMyRegisterAllocator() {
1731    return new MyRegisterAllocator();
1732  }
1733</pre></div>
1734
1735<p>Note that the signature of this function should match the type of
1736<tt>RegisterRegAlloc::FunctionPassCtor</tt>.  In the same file add the
1737"installing" declaration, in the form;</p>
1738
1739<div class="doc_code"><pre>
1740  static RegisterRegAlloc myRegAlloc("myregalloc",
1741    "  my register allocator help string",
1742    createMyRegisterAllocator);
1743</pre></div>
1744
1745<p>Note the two spaces prior to the help string produces a tidy result on the
1746-help query.</p>
1747
1748<div class="doc_code"><pre>
1749$ llc -help
1750  ...
1751  -regalloc                    - Register allocator to use (default=linearscan)
1752    =linearscan                -   linear scan register allocator
1753    =local                     -   local register allocator
1754    =simple                    -   simple register allocator
1755    =myregalloc                -   my register allocator help string
1756  ...
1757</pre></div>
1758
1759<p>And that's it.  The user is now free to use <tt>-regalloc=myregalloc</tt> as
1760an option.  Registering instruction schedulers is similar except use the
1761<tt>RegisterScheduler</tt> class.  Note that the
1762<tt>RegisterScheduler::FunctionPassCtor</tt> is significantly different from
1763<tt>RegisterRegAlloc::FunctionPassCtor</tt>.</p>
1764
1765<p>To force the load/linking of your register allocator into the llc/lli tools,
1766add your creator function's global declaration to "Passes.h" and add a "pseudo"
1767call line to <tt>llvm/Codegen/LinkAllCodegenComponents.h</tt>.</p>
1768
1769</div>
1770
1771
1772<!-- _______________________________________________________________________ -->
1773<h3>
1774  <a name="registering_new">Creating new registries</a>
1775</h3>
1776
1777<div>
1778
1779<p>The easiest way to get started is to clone one of the existing registries; we
1780recommend <tt>llvm/CodeGen/RegAllocRegistry.h</tt>.  The key things to modify
1781are the class name and the <tt>FunctionPassCtor</tt> type.</p>
1782
1783<p>Then you need to declare the registry.  Example: if your pass registry is
1784<tt>RegisterMyPasses</tt> then define;</p>
1785
1786<div class="doc_code"><pre>
1787MachinePassRegistry RegisterMyPasses::Registry;
1788</pre></div>
1789
1790<p>And finally, declare the command line option for your passes.  Example:</p>
1791
1792<div class="doc_code"><pre>
1793  cl::opt&lt;RegisterMyPasses::FunctionPassCtor, false,
1794          RegisterPassParser&lt;RegisterMyPasses&gt; &gt;
1795  MyPassOpt("mypass",
1796            cl::init(&amp;createDefaultMyPass),
1797            cl::desc("my pass option help"));
1798</pre></div>
1799
1800<p>Here the command option is "mypass", with createDefaultMyPass as the default
1801creator.</p>
1802
1803</div>
1804
1805</div>
1806
1807<!-- *********************************************************************** -->
1808<h2>
1809  <a name="debughints">Using GDB with dynamically loaded passes</a>
1810</h2>
1811<!-- *********************************************************************** -->
1812
1813<div>
1814
1815<p>Unfortunately, using GDB with dynamically loaded passes is not as easy as it
1816should be.  First of all, you can't set a breakpoint in a shared object that has
1817not been loaded yet, and second of all there are problems with inlined functions
1818in shared objects.  Here are some suggestions to debugging your pass with
1819GDB.</p>
1820
1821<p>For sake of discussion, I'm going to assume that you are debugging a
1822transformation invoked by <tt>opt</tt>, although nothing described here depends
1823on that.</p>
1824
1825<!-- _______________________________________________________________________ -->
1826<h4>
1827  <a name="breakpoint">Setting a breakpoint in your pass</a>
1828</h4>
1829
1830<div>
1831
1832<p>First thing you do is start <tt>gdb</tt> on the <tt>opt</tt> process:</p>
1833
1834<div class="doc_code"><pre>
1835$ <b>gdb opt</b>
1836GNU gdb 5.0
1837Copyright 2000 Free Software Foundation, Inc.
1838GDB is free software, covered by the GNU General Public License, and you are
1839welcome to change it and/or distribute copies of it under certain conditions.
1840Type "show copying" to see the conditions.
1841There is absolutely no warranty for GDB.  Type "show warranty" for details.
1842This GDB was configured as "sparc-sun-solaris2.6"...
1843(gdb)
1844</pre></div>
1845
1846<p>Note that <tt>opt</tt> has a lot of debugging information in it, so it takes
1847time to load.  Be patient.  Since we cannot set a breakpoint in our pass yet
1848(the shared object isn't loaded until runtime), we must execute the process, and
1849have it stop before it invokes our pass, but after it has loaded the shared
1850object.  The most foolproof way of doing this is to set a breakpoint in
1851<tt>PassManager::run</tt> and then run the process with the arguments you
1852want:</p>
1853
1854<div class="doc_code"><pre>
1855(gdb) <b>break llvm::PassManager::run</b>
1856Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.
1857(gdb) <b>run test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]</b>
1858Starting program: opt test.bc -load $(LLVMTOP)/llvm/Debug+Asserts/lib/[libname].so -[passoption]
1859Breakpoint 1, PassManager::run (this=0xffbef174, M=@0x70b298) at Pass.cpp:70
186070      bool PassManager::run(Module &amp;M) { return PM-&gt;run(M); }
1861(gdb)
1862</pre></div>
1863
1864<p>Once the <tt>opt</tt> stops in the <tt>PassManager::run</tt> method you are
1865now free to set breakpoints in your pass so that you can trace through execution
1866or do other standard debugging stuff.</p>
1867
1868</div>
1869
1870<!-- _______________________________________________________________________ -->
1871<h4>
1872  <a name="debugmisc">Miscellaneous Problems</a>
1873</h4>
1874
1875<div>
1876
1877<p>Once you have the basics down, there are a couple of problems that GDB has,
1878some with solutions, some without.</p>
1879
1880<ul>
1881<li>Inline functions have bogus stack information.  In general, GDB does a
1882pretty good job getting stack traces and stepping through inline functions.
1883When a pass is dynamically loaded however, it somehow completely loses this
1884capability.  The only solution I know of is to de-inline a function (move it
1885from the body of a class to a .cpp file).</li>
1886
1887<li>Restarting the program breaks breakpoints.  After following the information
1888above, you have succeeded in getting some breakpoints planted in your pass.  Nex
1889thing you know, you restart the program (i.e., you type '<tt>run</tt>' again),
1890and you start getting errors about breakpoints being unsettable.  The only way I
1891have found to "fix" this problem is to <tt>delete</tt> the breakpoints that are
1892already set in your pass, run the program, and re-set the breakpoints once
1893execution stops in <tt>PassManager::run</tt>.</li>
1894
1895</ul>
1896
1897<p>Hopefully these tips will help with common case debugging situations.  If
1898you'd like to contribute some tips of your own, just contact <a
1899href="mailto:sabre@nondot.org">Chris</a>.</p>
1900
1901</div>
1902
1903</div>
1904
1905<!-- *********************************************************************** -->
1906<h2>
1907  <a name="future">Future extensions planned</a>
1908</h2>
1909<!-- *********************************************************************** -->
1910
1911<div>
1912
1913<p>Although the LLVM Pass Infrastructure is very capable as it stands, and does
1914some nifty stuff, there are things we'd like to add in the future.  Here is
1915where we are going:</p>
1916
1917<!-- _______________________________________________________________________ -->
1918<h4>
1919  <a name="SMP">Multithreaded LLVM</a>
1920</h4>
1921
1922<div>
1923
1924<p>Multiple CPU machines are becoming more common and compilation can never be
1925fast enough: obviously we should allow for a multithreaded compiler.  Because of
1926the semantics defined for passes above (specifically they cannot maintain state
1927across invocations of their <tt>run*</tt> methods), a nice clean way to
1928implement a multithreaded compiler would be for the <tt>PassManager</tt> class
1929to create multiple instances of each pass object, and allow the separate
1930instances to be hacking on different parts of the program at the same time.</p>
1931
1932<p>This implementation would prevent each of the passes from having to implement
1933multithreaded constructs, requiring only the LLVM core to have locking in a few
1934places (for global resources).  Although this is a simple extension, we simply
1935haven't had time (or multiprocessor machines, thus a reason) to implement this.
1936Despite that, we have kept the LLVM passes SMP ready, and you should too.</p>
1937
1938</div>
1939
1940</div>
1941
1942<!-- *********************************************************************** -->
1943<hr>
1944<address>
1945  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1946  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
1947  <a href="http://validator.w3.org/check/referer"><img
1948  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
1949
1950  <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1951  <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
1952  Last modified: $Date: 2011-10-11 03:03:52 -0400 (Tue, 11 Oct 2011) $
1953</address>
1954
1955</body>
1956</html>
1957