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