1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html><head><title>Writing an LLVM Pass</title></head>
5 I. General Structure of an LLVM Program
7 I.1 "What is a 'Value'?": Value & User class
8 I.2 Type & Derived Types
9 I.3 GlobalVariable, Function
11 I.5 Instruction & Subclasses
15 III. Useful things to know about the LLVM source base:
17 III.1 Useful links that introduce the STL
18 III.2 isa<>, cast<>, dyn_cast<>
19 III.3 Makefiles, useful options
20 III.4 How to use opt & analyze to debug stuff
21 III.5 How to write a regression test
22 III.6 DEBUG() and Statistics (-debug & -stats)
23 III.7 The -time-passes option
24 III.8 ... more as needed ...
26 I think that writing Section #1 would be very helpful and that's the most
27 stable portion of the sourcebase. #3 can be started on, but will probably
28 just grow as time goes on. I'd like to do Section #2 once I finish some
29 changes up that effect it.
35 <table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
36 <tr><td> <font size=+3 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>Writing an LLVM Pass</b></font></td>
41 <li><a href="#introduction">Introduction - What is a pass?</a>
42 <li><a href="#quickstart">Quick Start - Writing hello world</a>
44 <li><a href="#makefile">Setting up the build environment</a>
45 <li><a href="#basiccode">Basic code required</a>
46 <li><a href="#running">Running a pass with <tt>opt</tt>
47 or <tt>analyze</tt></a>
49 <li><a href="#passtype">Pass classes and requirements</a>
51 <li><a href="#Pass">The <tt>Pass</tt> class</a>
53 <li><a href="#run">The <tt>run</tt> method</a>
55 <li><a href="#FunctionPass">The <tt>FunctionPass</tt> class</a>
57 <li><a href="#doInitialization">The <tt>doInitialization</tt> method</a>
58 <li><a href="#runOnFunction">The <tt>runOnFunction</tt> method</a>
59 <li><a href="#doFinalization">The <tt>doFinalization</tt> method</a>
61 <li><a href="#BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
63 <li><a href="#runOnBasicBlock">The <tt>runOnBasicBlock</tt> method</a>
66 <li><a href="#registration">Pass Registration</a>
68 <li><a href="#print">The <tt>print</tt> method</a>
70 <li><a href="#interaction">Specifying interactions between passes</a>
72 <li><a href="#getAnalysisUsage">The <tt>getAnalysisUsage</tt> method</a>
73 <li><a href="#getAnalysis">The <tt>getAnalysis</tt> method</a>
75 <li><a href="#passmanager">What PassManager does</a>
77 <li><a href="#releaseMemory">The <tt>releaseMemory</tt> method</a>
79 <li><a href="#future">Future extensions planned</a>
81 <li><a href="#SMP">Multithreaded LLVM</a>
82 <li><a href="#ModuleSource">A new <tt>ModuleSource</tt> interface</a>
83 <li><a href="#PassFunctionPass"><tt>Pass</tt>'s requiring <tt>FunctionPass</tt>'s</a>
86 <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></b><p>
91 <!-- *********************************************************************** -->
92 <table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
93 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
94 <a name="introduction">Introduction - What is a pass?
95 </b></font></td></tr></table><ul>
96 <!-- *********************************************************************** -->
98 The LLVM Pass Framework is an important part of the LLVM system, because LLVM
99 passes are where the interesting parts of the compiler exist. Passes perform
100 the transformations and optimizations that make up the compiler, they build
101 the analysis results that are used by these transformations, and they are, above
102 all, a structuring technique for compiler code.<p>
104 All LLVM passes are subclasses of the <tt><a
105 href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt> class, which
106 implement functionality by overriding virtual methods inherited from
107 <tt>Pass</tt>. Depending on how your pass works, you may be able to inherit
109 href="http://llvm.cs.uiuc.edu/doxygen/structFunctionPass.html">FunctionPass</a></tt>
111 href="http://llvm.cs.uiuc.edu/doxygen/structBasicBlockPass.html">BasicBlockPass</a></tt>,
112 which gives the system more information about what your pass does, and how it
113 can be combined with other passes. One of the main features of the LLVM Pass
114 Framework is that it schedules passes to run in an efficient way based on the
115 constraints that your pass has.<p>
117 We start by showing you how to construct a pass, everything from setting up the
118 code, to compiling, loading, and executing it. After the basics are down, more
119 advanced features are discussed.<p>
122 <!-- *********************************************************************** -->
123 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
124 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
125 <a name="quickstart">Quick Start - Writing hello world
126 </b></font></td></tr></table><ul>
127 <!-- *********************************************************************** -->
129 Here we describe how to write the "hello world" of passes. The "Hello" pass is
130 designed to simply print out the name of non-external functions that exist in
131 the program being compiled. It does not modify the program at all, just
132 inspects it. The source code and files for this pass are available in the LLVM
133 source tree in the <tt>lib/Transforms/Hello</tt> directory.<p>
136 <!-- ======================================================================= -->
137 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
138 <tr><td> </td><td width="100%">
139 <font color="#EEEEFF" face="Georgia,Palatino"><b>
140 <a name="makefile">Setting up the build environment
141 </b></font></td></tr></table><ul>
143 First thing you need to do is create a new directory somewhere in the LLVM
144 source base. For this example, we'll assume that you made
145 "<tt>lib/Transforms/Hello</tt>". The first thing you must do is set up a build
146 script (Makefile) that will compile the source code for the new pass. To do
147 this, copy this into "<tt>Makefile</tt>" (be very careful that there are no
148 extra space characters at the end of the lines though... that seems to confuse
152 # Makefile for hello pass
154 # Path to top level of LLVM heirarchy
157 # Name of the library to build
160 # Build a dynamically loadable shared object
163 # Include the makefile implementation stuff
164 include $(LEVEL)/Makefile.common
165 </pre></ul><hr><ul><p>
167 This makefile specifies that all of the <tt>.cpp</tt> files in the current
168 directory are to be compiled and linked together into a
169 <tt>lib/Debug/libhello.so</tt> shared object that can be dynamically loaded by
170 the <tt>opt</tt> or <tt>analyze</tt> tools.<p>
172 Now that we have the build scripts set up, we just need to write the code for
176 <!-- ======================================================================= -->
177 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
178 <tr><td> </td><td width="100%">
179 <font color="#EEEEFF" face="Georgia,Palatino"><b>
180 <a name="basiccode">Basic code required
181 </b></font></td></tr></table><ul>
183 Now that we have a way to compile our new pass, we just have to write it. Start
187 <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
188 <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Function_8h-source.html">llvm/Function.h</a>"
191 Which are needed because we are writing a <tt><a
192 href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt>, and we are
194 href="http://llvm.cs.uiuc.edu/doxygen/classFunction.html">Function</a></tt>'s.<p>
202 ... which starts out an anonymous namespace. Anonymous namespaces are to C++
203 what the "<tt>static</tt>" keyword is to C (at global scope). It makes the
204 things declared inside of the anonymous namespace only visible to the current
205 file. If you're not familiar with them, consult a decent C++ book for more
208 Next, we declare our pass itself:<p>
211 <b>struct</b> Hello : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
214 This declares a "<tt>Hello</tt>" class that is a subclass of <tt><a
215 href="http://llvm.cs.uiuc.edu/doxygen/structFunctionPass.html">FunctionPass</a></tt>.
216 The different builting pass subclasses are described in detail <a
217 href="#passtype">later</a>, but for now, know that <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s
218 operate a function at a time.<p>
221 <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
222 std::cerr << "<i>Hello: </i>" << F.getName() << "\n";
225 }; <i>// end of struct Hello</i>
228 We declare a "<a href="#runOnFunction"><tt>runOnFunction</tt></a>" method, which
229 overloads an abstract virtual method inherited from <a
230 href="#FunctionPass"><tt>FunctionPass</tt></a>. This is where we are supposed
231 to do our thing, so we just print out our message with the name of each
235 RegisterOpt<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>");
236 } <i>// end of anonymous namespace</i>
239 Lastly, we register our class <tt>Hello</tt>, giving it a command line argument
240 "<tt>hello</tt>", and a name "<tt>Hello World Pass</tt>". There are several
241 different ways of <a href="#registration">registering your pass</a>, depending
242 on what it is to be used for. For "optimizations" we use the
243 <tt>RegisterOpt</tt> template.<p>
245 As a whole, the <tt>.cpp</tt> file looks like:<p>
248 <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
249 <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Function_8h-source.html">llvm/Function.h</a>"
252 <b>struct Hello</b> : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
253 <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
254 std::cerr << "<i>Hello: </i>" << F.getName() << "\n";
259 RegisterOpt<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>");
263 Now that it's all together, compile the file with a simple "<tt>gmake</tt>"
264 command in the local directory and you should get a new
265 "<tt>lib/Debug/libhello.so</tt> file. Note that everything in this file is
266 contained in an anonymous namespace: this reflects the fact that passes are self
267 contained units that do not need external interfaces (although they can have
268 them) to be useful.<p>
271 <!-- ======================================================================= -->
272 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
273 <tr><td> </td><td width="100%">
274 <font color="#EEEEFF" face="Georgia,Palatino"><b>
275 <a name="running">Running a pass with <tt>opt</tt> or <tt>analyze</tt>
276 </b></font></td></tr></table><ul>
278 Now that you have a brand new shiny <tt>.so</tt> file, we can use the
279 <tt>opt</tt> command to run an LLVM program through your pass. Because you
280 registered your pass with the <tt>RegisterOpt</tt> template, you will be able to
281 use the <tt>opt</tt> tool to access it, once loaded.<p>
283 To test it, follow the example at the end of the <a
284 href="GettingStarted.html">Getting Started Guide</a> to compile "Hello World" to
285 LLVM. We can now run the bytecode file (<tt>hello.bc</tt>) for the program
286 through our transformation like this (or course, any bytecode file will
290 $ opt -load ../../../lib/Debug/libhello.so -hello < hello.bc > /dev/null
296 The '<tt>-load</tt>' option specifies that '<tt>opt</tt>' should load your pass
297 as a shared object, which makes '<tt>-hello</tt>' a valid command line argument
298 (which is one reason you need to <a href="#registration">register your
299 pass</a>). Because the hello pass does not modify the program in any
300 interesting way, we just throw away the result of <tt>opt</tt> (sending it to
301 <tt>/dev/null</tt>).<p>
303 To see what happened to the other string you registered, try running
304 <tt>opt</tt> with the <tt>--help</tt> option:<p>
307 $ opt -load ../../../lib/Debug/libhello.so --help
308 OVERVIEW: llvm .bc -> .bc modular optimizer
310 USAGE: opt [options] <input bytecode>
313 Optimizations available:
315 -funcresolve - Resolve Functions
316 -gcse - Global Common Subexpression Elimination
317 -globaldce - Dead Global Elimination
318 <b>-hello - Hello World Pass</b>
319 -indvars - Cannonicalize Induction Variables
320 -inline - Function Integration/Inlining
321 -instcombine - Combine redundant instructions
325 The pass name get added as the information string for your pass, giving some
326 documentation to users of <tt>opt</tt>. Now that you have a working pass, you
327 would go ahead and make it do the cool transformations you want. Once you get
328 it all working and tested, it may become useful to find out how fast your pass
329 is. The <a href="#passManager"><tt>PassManager</tt></a> provides a nice command
330 line option (<tt>--time-passes</tt>) that allows you to get information about
331 the execution time of your pass along with the other passes you queue up. For
335 $ opt -load ../../../lib/Debug/libhello.so -hello -time-passes < hello.bc > /dev/null
339 ===============================================================================
340 ... Pass execution timing report ...
341 ===============================================================================
342 Total Execution Time: 0.02 seconds (0.0479059 wall clock)
344 ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Pass Name ---
345 0.0100 (100.0%) 0.0000 ( 0.0%) 0.0100 ( 50.0%) 0.0402 ( 84.0%) Bytecode Writer
346 0.0000 ( 0.0%) 0.0100 (100.0%) 0.0100 ( 50.0%) 0.0031 ( 6.4%) Dominator Set Construction
347 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0013 ( 2.7%) Module Verifier
348 <b> 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0033 ( 6.9%) Hello World Pass</b>
349 0.0100 (100.0%) 0.0100 (100.0%) 0.0200 (100.0%) 0.0479 (100.0%) TOTAL
352 As you can see, our implementation above is pretty fast :). The additional
353 passes listed are automatically inserted by the '<tt>opt</tt>' tool to verify
354 that the LLVM emitted by your pass is still valid and well formed LLVM, which
355 hasn't been broken somehow.
357 Now that you have seen the basics of the mechanics behind passes, we can talk
358 about some more details of how they work and how to use them.<p>
362 <!-- *********************************************************************** -->
363 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
364 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
365 <a name="passtype">Pass classes and requirements
366 </b></font></td></tr></table><ul>
367 <!-- *********************************************************************** -->
369 One of the first things that you should do when designing a new pass is to
370 decide what class you should subclass for your pass. The <a
371 href="#basiccode">Hello World</a> example uses the <tt><a
372 href="#FunctionPass">FunctionPass</a></tt> class for its implementation, but we
373 did not discuss why or when this should occur. Here we talk about the classes
374 available, from the most general to the most specific.<p>
376 When choosing a superclass for your Pass, you should choose the most specific
377 class possible, while still being able to meet the requirements listed. This
378 gives the LLVM Pass Infrastructure information neccesary to optimize how passes
379 are run, so that the resultant compiler isn't unneccesarily slow.<p>
383 <!-- ======================================================================= -->
384 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
385 <tr><td> </td><td width="100%">
386 <font color="#EEEEFF" face="Georgia,Palatino"><b>
387 <a name="Pass">The <tt>Pass</tt> class
388 </b></font></td></tr></table><ul>
390 The "<tt><a href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt>"
391 class is the most general of all superclasses that you can use. Deriving from
392 <tt>Pass</tt> indicates that your pass uses the entire program as a unit,
393 refering to function bodies in no predictable order, or adding and removing
394 functions. Because nothing is known about the behavior of direct <tt>Pass</tt>
395 subclasses, no optimization can be done for their execution.<p>
397 To write a correct <tt>Pass</tt> subclass, derive from <tt>Pass</tt> and
398 overload the <tt>run</tt> method with the following signature:<p>
400 <!-- _______________________________________________________________________ -->
401 </ul><h4><a name="run"><hr size=0>The <tt>run</tt> method</h4><ul>
405 <b>virtual bool</b> run(Module &M) = 0;
408 The <tt>run</tt> method performs the interesting work of the pass, and should
409 return true if the module was modified by the transformation, false
414 <!-- ======================================================================= -->
415 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
416 <tr><td> </td><td width="100%">
417 <font color="#EEEEFF" face="Georgia,Palatino"><b>
418 <a name="FunctionPass">The <tt>FunctionPass</tt> class
419 </b></font></td></tr></table><ul>
421 In contrast to direct <tt>Pass</tt> subclasses, direct <tt><a
422 href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">FunctionPass</a></tt>
423 subclasses do have a predictable, local behavior that can be expected by the
424 system. All <tt>FunctionPass</tt> execute on each function in the program
425 independant of all of the other functions in the program.
426 <tt>FunctionPass</tt>'s do not require that they are executed in a particular
427 order, and <tt>FunctionPass</tt>'s do not modify external functions.<p>
429 To be explicit, <tt>FunctionPass</tt> subclasses are not allowed to:<p>
432 <li>Modify a Function other than the one currently being processed.
433 <li>Add or remove Function's from the current Module.
434 <li>Add or remove global variables from the current Module.
435 <li>Maintain state across invocations of
436 <a href="#runOnFunction"><tt>runOnFunction</tt></a> (including global data)
439 Implementing a <tt>FunctionPass</tt> is usually straightforward (See the <a
440 href="#basiccode">Hello World</a> pass for example). <tt>FunctionPass</tt>'s
441 may overload three virtual methods to do their work. All of these methods
442 should return true if they modified the program, or false if they didn't.<p>
444 <!-- _______________________________________________________________________ -->
445 </ul><h4><a name="doInitialization"><hr size=0>The <tt>doInitialization</tt>
449 <b>virtual bool</b> doInitialization(Module &M);
452 The <tt>doIninitialize</tt> method is allowed to do most of the things that
453 <tt>FunctionPass</tt>'s are not allowed to do. They can add and remove
454 functions, get pointers to functions, etc. The <tt>doInitialize</tt> method is
455 designed to do simple initialization type of stuff that does not depend on the
456 functions being processed. The <tt>doInitialization</tt> function call is not
457 scheduled to overlap with any other pass executions.<p>
459 A good example of how this method should be used is the <a
460 href="http://llvm.cs.uiuc.edu/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations</a>
461 pass. This pass converts <tt>malloc</tt> and <tt>free</tt> instructions into
462 platform dependant <tt>malloc()</tt> and <tt>free()</tt> function calls. It
463 uses the <tt>doInitialization</tt> method to get a reference to the malloc and
464 free functions that it needs, adding prototypes to the module if neccesary.<p>
466 <!-- _______________________________________________________________________ -->
467 </ul><h4><a name="runOnFunction"><hr size=0>The <tt>runOnFunction</tt> method</h4><ul>
470 <b>virtual bool</b> runOnFunction(Function &F) = 0;
473 The <tt>runOnFunction</tt> method must be implemented by your subclass to do the
474 transformation or analysis work of your pass. As usual, a true value should be
475 returned if the function is modified.<p>
477 <!-- _______________________________________________________________________ -->
478 </ul><h4><a name="doFinalization"><hr size=0>The <tt>doFinalization</tt> method</h4><ul>
481 <b>virtual bool</b> doFinalization(Module &M);
484 The <tt>doFinalization</tt> method is an infrequently used method that is called
485 when the pass framework has finished calling <a
486 href="#runOnFunction"><tt>runOnFunction</tt></a> for every function in the
487 program being compiled.<p>
491 <!-- ======================================================================= -->
492 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
493 <tr><td> </td><td width="100%">
494 <font color="#EEEEFF" face="Georgia,Palatino"><b>
495 <a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
496 </b></font></td></tr></table><ul>
498 <tt>BasicBlockPass</tt>'s are just like <a
499 href="#FunctionPass"><tt>FunctionPass</tt></a>'s, except that they must limit
500 their scope of inspection and modification to a single basic block at a time.
501 As such, they are <b>not</b> allowed to do any of the following:<p>
504 <li>Modify or inspect any basic blocks outside of the current one
505 <li>Maintain state across invocations of
506 <a href="#runOnBasicBlock"><tt>runOnBasicBlock</tt></a>
507 <li>Modify the constrol flow graph (by altering terminator instructions)
508 <li>Any of the things verboten for
509 <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s.
512 <tt>BasicBlockPass</tt>'s are useful for traditional local and "peephole"
513 optimizations. They may override the same <a
514 href="#doInitialization"><tt>doInitialization</tt></a> and <a
515 href="#doFinalization"><tt>doFinalization</tt></a> methods that <a
516 href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have a
517 <tt>runOnBasicBlock</tt> method:<p>
519 <!-- _______________________________________________________________________ -->
520 </ul><h4><a name="runOnBasicBlock"><hr size=0>The <tt>runOnBasicBlock</tt> method</h4><ul>
523 <b>virtual bool</b> runOnBasicBlock(BasicBlock &BB) = 0;
526 Override this function to do the work of the <tt>BasicBlockPass</tt>. This
527 function is not allowed to inspect or modify basic blocks other than the
528 parameter, and are not allowed to modify the CFG. A true value must be returned
529 if the basic block is modified.<p>
532 <!-- *********************************************************************** -->
533 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
534 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
535 <a name="registration">Pass registration
536 </b></font></td></tr></table><ul>
537 <!-- *********************************************************************** -->
539 In the <a href="#basiccode">Hello World</a> example pass we illustrated how pass
540 registration works, and discussed some of the reasons that it is used and what
541 it does. Here we discuss how and why passes are registered.<p>
543 Passes can be registered in several different ways. Depending on the general
544 classification of the pass, you should use one of the following templates to
545 register the pass:<p>
548 <li><b><tt>RegisterOpt</tt></b> - This template should be used when you are
549 registering a pass that logically should be available for use in the
550 '<tt>opt</tt>' utility.<p>
552 <li><b><tt>RegisterAnalysis</tt></b> - This template should be used when you are
553 registering a pass that logically should be available for use in the
554 '<tt>analysis</tt>' utility.<p>
556 <li><b><tt>RegisterLLC</tt></b> - This template should be used when you are
557 registering a pass that logically should be available for use in the
558 '<tt>llc</tt>' utility.<p>
560 <li><b><tt>RegisterPass</tt></b> - This is the generic form of the
561 <tt>Register*</tt> templates that should be used if you want your pass listed by
562 multiple or no utilities. This template takes an extra third argument that
563 specifies which tools it should be listed in. See the <a
564 href="http://llvm.cs.uiuc.edu/doxygen/PassSupport_8h-source.html">PassSupport.h</a>
565 file for more information.<p>
568 Regardless of how you register your pass, you must specify at least two
569 parameters. The first parameter is the name of the pass that is to be used on
570 the command line to specify that the pass should be added to a program (for
571 example <tt>opt</tt> or <tt>analyze</tt>). The second argument is the name of
572 the pass, which is to be used for the <tt>--help</tt> output of programs, as
573 well as for debug output generated by the <tt>--debug-pass</tt> option.<p>
575 If you pass is constructed by its default constructor, you only ever have to
576 pass these two arguments. If, on the other hand, you require other information
577 (like target specific information), you must pass an additional argument. This
578 argument is a pointer to a function used to create the pass. For an example of
579 how this works, look at the <a
580 href="http://llvm.cs.uiuc.edu/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations.cpp</a>
583 If a pass is registered to be used by the <tt>analyze</tt> utility, you should
584 implement the virtual <tt>print</tt> method:<p>
586 <!-- _______________________________________________________________________ -->
587 </ul><h4><a name="print"><hr size=0>The <tt>print</tt> method</h4><ul>
590 <b>virtual void</b> print(std::ostream &O, <b>const</b> Module *M) <b>const</b>;
593 The <tt>print</tt> method must be implemented by "analyses" in order to print a
594 human readable version of the analysis results. This is useful for debugging an
595 analysis itself, as well as for other people to figure out how an analysis
596 works. The <tt>analyze</tt> tool uses this method to generate its output.<p>
598 The <tt>ostream</tt> parameter specifies the stream to write the results on, and
599 the <tt>Module</tt> parameter gives a pointer to the top level module of the
600 program that has been analyzed. Note however that this pointer may be null in
601 certain circumstances (such as calling the <tt>Pass::dump()</tt> from a
602 debugger), so it should only be used to enhance debug output, it should not be
606 <!-- *********************************************************************** -->
607 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
608 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
609 <a name="interaction">Specifying interactions between passes
610 </b></font></td></tr></table><ul>
611 <!-- *********************************************************************** -->
613 One of the main responsibilities of the <tt>PassManager</tt> is the make sure
614 that passes interact with each other correctly. Because <tt>PassManager</tt>
615 tries to <a href="#passmanager">optimize the execution of passes</a> it must
616 know how the passes interact with each other and what dependencies exist between
617 the various passes. To track this, each pass can declare the set of passes that
618 are required to be executed before the current pass, and the passes which are
619 invalidated by the current pass.<p>
621 Typically this functionality is used to require that analysis results are
622 computed before your pass is run. Running arbitrary transformation passes can
623 invalidate the computed analysis results, which is what the invalidation set
624 specifies. If a pass does not implement the <tt><a
625 href="#getAnalysisUsage">getAnalysisUsage</a></tt> method, it defaults to not
626 having any prerequisite passes, and invalidating <b>all</b> other passes.<p>
629 <!-- _______________________________________________________________________ -->
630 </ul><h4><a name="getAnalysisUsage"><hr size=0>The <tt>getAnalysisUsage</tt> method</h4><ul>
633 <b>virtual void</b> getAnalysisUsage(AnalysisUsage &Info) <b>const</b>;
636 By implementing the <tt>getAnalysisUsage</tt> method, the required and
637 invalidated sets may be specified for your transformation. The implementation
638 should fill in the <tt><a
639 href="http://llvm.cs.uiuc.edu/doxygen/classAnalysisUsage.html">AnalysisUsage</a></tt>
640 object with information about which passes are required and not invalidated. To do this, the following set methods are provided by the <tt><a
641 href="http://llvm.cs.uiuc.edu/doxygen/classAnalysisUsage.html">AnalysisUsage</a></tt> class:<p>
644 <i>// addRequires - Add the specified pass to the required set for your pass.</i>
645 <b>template</b><<b>class</b> PassClass>
646 AnalysisUsage &AnalysisUsage::addRequired();
648 <i>// addPreserved - Add the specified pass to the set of analyses preserved by
650 <b>template</b><<b>class</b> PassClass>
651 AnalysisUsage &AnalysisUsage::addPreserved();
653 <i>// setPreservesAll - Call this if the pass does not modify its input at all</i>
654 <b>void</b> AnalysisUsage::setPreservesAll();
656 <i>// preservesCFG - This function should be called by the pass, iff they do not:
658 // 1. Add or remove basic blocks from the function
659 // 2. Modify terminator instructions in any way.
661 // This is automatically implied for <a href="#BasicBlockPass">BasicBlockPass</a>'s
663 <b>void</b> AnalysisUsage::preservesCFG();
666 Some examples of how to use these methods are:<p>
669 <i>// This is an example implementation from an analysis, which does not modify
670 // the program at all, yet has a prerequisite.</i>
671 <b>void</b> <a href="http://llvm.cs.uiuc.edu/doxygen/structPostDominanceFrontier.html">PostDominanceFrontier</a>::getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
672 AU.setPreservesAll();
673 AU.addRequired<<a href="http://llvm.cs.uiuc.edu/doxygen/structPostDominatorTree.html">PostDominatorTree</a>>();
680 <i>// This example modifies the program, but does not modify the CFG</i>
681 <b>void</b> <a href="http://llvm.cs.uiuc.edu/doxygen/structLICM.html">LICM</a>::getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
683 AU.addRequired<<a href="http://llvm.cs.uiuc.edu/doxygen/classLoopInfo.html">LoopInfo</a>>();
687 <!-- _______________________________________________________________________ -->
688 </ul><h4><a name="getAnalysis"><hr size=0>The <tt>getAnalysis<></tt> method</h4><ul>
690 The <tt>Pass::getAnalysis<></tt> method is inherited by your class,
691 providing you with access to the passes that you declared that you required with
692 the <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method. It takes
693 a single template argument that specifies which pass class you want, and returns
694 a reference to that pass.<p>
697 <b>template</b><<b>typename</b> PassClass>
698 AnalysisType &getAnalysis();
701 This method call returns a reference to the pass desired. You may get a runtime
702 assertion failure if you attempt to get an analysis that you did not declare as
703 required in your <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a>
704 implementation. This method can be called by your <tt>run*</tt> method
705 implementation, or by any other local method invoked by your <tt>run*</tt>
710 <!-- *********************************************************************** -->
711 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
712 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
713 <a name="passmanager">What PassManager does
714 </b></font></td></tr></table><ul>
715 <!-- *********************************************************************** -->
718 href="http://llvm.cs.uiuc.edu/doxygen/PassManager_8h-source.html"><tt>PassManager</tt></a>
719 <a href="http://llvm.cs.uiuc.edu/doxygen/classPassManager.html">class</a> takes
720 a list of passes, ensures their <a href="#interaction">prerequisites</a> are set
721 up correctly, and then schedules passes to run efficiently. All of the LLVM
722 tools that run passes use the <tt>PassManager</tt> for execution of these
725 The <tt>PassManager</tt> does two main things to try to reduce the execution
726 time of a series of passes:<p>
729 <li><b>Share analysis results</b> - The PassManager attempts to avoid
730 recomputing analysis results as much as possible. This means keeping track of
731 which analyses are available already, which analyses get invalidated, and which
732 analyses are needed to be run for a pass. An important part of work is that the
733 <tt>PassManager</tt> tracks the exact lifetime of all analysis results, allowing
734 it to <a href="#releaseMemory">free memory</a> allocated to holding analysis
735 results as soon as they are no longer needed.<p>
737 <li><b>Pipeline the execution of passes on the program</b> - The
738 <tt>PassManager</tt> attempts to get better cache and memory usage behavior out
739 of a series of passes by pipelining the passes together. This means that, given
740 a series of consequtive <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s, it
741 will execute all of the <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s on
742 the first function, then all of the <a
743 href="#FunctionPass"><tt>FunctionPass</tt></a>'s on the second function,
744 etc... until the entire program has been run through the passes.<p>
746 This improves the cache behavior of the compiler, because it is only touching
747 the LLVM program representation for a single function at a time, instead of
748 traversing the entire program. It reduces the memory consumption of compiler,
749 because, for example, only one <a
750 href="http://llvm.cs.uiuc.edu/doxygen/structDominatorSet.html"><tt>DominatorSet</tt></a>
751 needs to be calculated at a time. This also makes it possible some <a
752 href="#SMP">interesting enhancements</a> in the future.<p>
756 The effectiveness of the <tt>PassManager</tt> is influenced directly by how much
757 information it has about the behaviors of the passes it is scheduling. For
758 example, the "preserved" set is intentionally conservative in the face of an
759 unimplemented <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method.
760 Not implementing when it should be implemented will have the effect of not
761 allowing any analysis results to live across the execution of your pass.<p>
763 The <tt>PassManager</tt> class exposes a <tt>--debug-pass</tt> command line
764 options that is useful for debugging pass execution, seeing how things work, and
765 diagnosing when you should be preserving more analyses than you currently are
766 (To get information about all of the variants of the <tt>--debug-pass</tt>
767 option, just type '<tt>opt --help-hidden</tt>').<p>
769 By using the <tt>--debug-pass=Structure</tt> option, for example, we can see how
770 our <a href="#basiccode">Hello World</a> pass interacts with other passes. Lets
771 try it out with the <tt>gcse</tt> and <tt>licm</tt> passes:<p>
774 $ opt -load ../../../lib/Debug/libhello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
776 Function Pass Manager
777 Dominator Set Construction
778 Immediate Dominators Construction
779 Global Common Subexpression Elimination
780 -- Immediate Dominators Construction
781 -- Global Common Subexpression Elimination
782 Natural Loop Construction
783 Loop Invariant Code Motion
784 -- Natural Loop Construction
785 -- Loop Invariant Code Motion
787 -- Dominator Set Construction
793 This output shows us when passes are constructed and when the analysis results
794 are known to be dead (prefixed with '<tt>--</tt>'). Here we see that GCSE uses
795 dominator and immediate dominator information to do its job. The LICM pass uses
796 natural loop information, which uses dominator sets, but not immediate
797 dominators. Because immediate dominators are no longer useful after the GCSE
798 pass, it is immediately destroyed. The dominator sets are then reused to
799 compute natural loop information, which is then used by the LICM pass.<p>
801 After the LICM pass, the module verifier runs (which is automatically added by
802 the '<tt>opt</tt>' tool), which uses the dominator set to check that the
803 resultant LLVM code is well formed. After it finishes, the dominator set
804 information is destroyed, after being computed once, and shared by three
807 Lets see how this changes when we run the <a href="#basiccode">Hello World</a>
808 pass in between the two passes:<p>
811 $ opt -load ../../../lib/Debug/libhello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
813 Function Pass Manager
814 Dominator Set Construction
815 Immediate Dominators Construction
816 Global Common Subexpression Elimination
817 <b>-- Dominator Set Construction</b>
818 -- Immediate Dominators Construction
819 -- Global Common Subexpression Elimination
822 Dominator Set Construction</b>
823 Natural Loop Construction
824 Loop Invariant Code Motion
825 -- Natural Loop Construction
826 -- Loop Invariant Code Motion
828 -- Dominator Set Construction
837 Here we see that the <a href="#basiccode">Hello World</a> pass has killed the
838 Dominator Set pass, even though it doesn't modify the code at all! To fix this,
839 we need to add the following <a
840 href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method to our pass:<p>
843 <i>// We don't modify the program, so we preserve all analyses</i>
844 <b>virtual void</b> getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
845 AU.setPreservesAll();
849 Now when we run our pass, we get this output:<p>
852 $ opt -load ../../../lib/Debug/libhello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
853 Pass Arguments: -gcse -hello -licm
855 Function Pass Manager
856 Dominator Set Construction
857 Immediate Dominators Construction
858 Global Common Subexpression Elimination
859 -- Immediate Dominators Construction
860 -- Global Common Subexpression Elimination
863 Natural Loop Construction
864 Loop Invariant Code Motion
865 -- Loop Invariant Code Motion
866 -- Natural Loop Construction
868 -- Dominator Set Construction
877 Which shows that we don't accidentally invalidate dominator information
878 anymore, and therefore do not have to compute it twice.<p>
881 <!-- _______________________________________________________________________ -->
882 </ul><h4><a name="releaseMemory"><hr size=0>The <tt>releaseMemory</tt> method</h4><ul>
885 <b>virtual void</b> releaseMemory();
888 The <tt>PassManager</tt> automatically determines when to compute analysis
889 results, and how long to keep them around for. Because the lifetime of the pass
890 object itself is effectively the entire duration of the compilation process, we
891 need some way to free analysis results when they are no longer useful. The
892 <tt>releaseMemory</tt> virtual method is the way to do this.<p>
894 If you are writing an analysis or any other pass that retains a significant
895 amount of state (for use by another pass which "requires" your pass and uses the
896 <a href="#getAnalysis">getAnalysis</a> method) you should implement
897 <tt>releaseMEmory</tt> to, well, release the memory allocated to maintain this
898 internal state. This method is called after the <tt>run*</tt> method for the
899 class, before the next call of <tt>run*</tt> in your pass.<p>
902 <!-- *********************************************************************** -->
903 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
904 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
905 <a name="future">Future extensions planned
906 </b></font></td></tr></table><ul>
907 <!-- *********************************************************************** -->
909 Although the LLVM Pass Infrastructure is very capable as it stands, and does
910 some nifty stuff, there are things we'd like to add in the future. Here is
911 where we are going:<p>
913 <!-- _______________________________________________________________________ -->
914 </ul><h4><a name="SMP"><hr size=0>Multithreaded LLVM</h4><ul>
916 Multiple CPU machines are becoming more command and compilation can never be
917 fast enough: obviously we should allow for a multithreaded compiler. Because of
918 the semantics defined for passes above (specifically they cannot maintain state
919 across invocations of their <tt>run*</tt> methods), a nice clean way to
920 implement a multithreaded compiler would be for the <tt>PassManager</tt> class
921 to create multiple instances of each pass object, and allow the seperate
922 instances to be hacking on different parts of the program at the same time.<p>
924 This implementation would prevent each of the passes from having to implement
925 multithreaded constructs, requiring only the LLVM core to have locking in a few
926 places (for global resources). Although this is a simple extension, we simply
927 haven't had time (or multiprocessor machines, thus a reason) to implement this.
928 Despite that, we have kept the LLVM passes SMP ready, and you should too.<p>
931 <!-- _______________________________________________________________________ -->
932 </ul><h4><a name="ModuleSource"><hr size=0>A new <tt>ModuleSource</tt> interface</h4><ul>
934 Currently, the <tt>PassManager</tt>'s <tt>run</tt> method takes a <tt><a
935 href="http://llvm.cs.uiuc.edu/doxygen/classModule.html">Module</a></tt> as
936 input, and runs all of the passes on this module. The problem with this
937 approach is that none of the <tt>PassManager</tt> features can be used for
938 timing and debugging the actual <b>loading</b> of the module from disk or
941 To solve this problem, eventually the <tt>PassManger</tt> class will accept a
942 <tt>ModuleSource</tt> object instead of a Module itself. When complete, this
943 will also allow for streaming of functions out of the bytecode representation,
944 allowing us to avoid holding the entire program in memory at once if we only are
945 dealing with <a href="#FunctionPass">FunctionPass</a>'s.<p>
947 As part of a different issue, eventually the bytecode loader will be extended to
948 allow on-demand loading of functions from the bytecode representation, in order
949 to better support the runtime reoptimizer. The bytecode format is already
950 capable of this, the loader just needs to be reworked a bit.<p>
953 <!-- _______________________________________________________________________ -->
954 </ul><h4><a name="PassFunctionPass"><hr size=0><tt>Pass</tt>'s requiring <tt>FunctionPass</tt>'s</h4><ul>
956 Currently it is illegal for a <a href="#Pass"><tt>Pass</tt></a> to require a <a
957 href="#FunctionPass"><tt>FunctionPass</tt></a>. This is because there is only
958 one instance of the <a href="#FunctionPass"><tt>FunctionPass</tt></a> object
959 ever created, thus nowhere to store information for all of the functions in the
960 program at the same time. Although this has come up a couple of times before,
961 this has always been worked around by factoring one big complicated pass into a
962 global and an interprocedural part, both of which are distinct. In the future,
963 it would be nice to have this though.<p>
965 Note that it is no problem for a <a
966 href="#FunctionPass"><tt>FunctionPass</tt></a> to require the results of a <a
967 href="#Pass"><tt>Pass</tt></a>, only the other way around.<p>
970 <!-- *********************************************************************** -->
972 <!-- *********************************************************************** -->
975 <address><a href="mailto:sabre@nondot.org">Christopher Lattner</a></address>
976 <!-- Created: Tue Aug 6 15:00:33 CDT 2002 -->
978 Last modified: Wed Aug 14 15:06:49 CDT 2002
980 </font></body></html>