Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 | <html><head><title>LLVM Programmer's Manual</title></head> |
| 3 | |
| 4 | <body bgcolor=white> |
| 5 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 6 | <table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> |
| 7 | <tr><td> <font size=+3 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>LLVM Programmer's Manual</b></font></td> |
| 8 | </tr></table> |
| 9 | |
| 10 | <ol> |
| 11 | <li><a href="#introduction">Introduction</a> |
| 12 | <li><a href="#general">General Information</a> |
| 13 | <ul> |
| 14 | <li><a href="#stl">The C++ Standard Template Library</a> |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 15 | <!-- |
| 16 | <li>The <tt>-time-passes</tt> option |
| 17 | <li>How to use the LLVM Makefile system |
| 18 | <li>How to write a regression test |
| 19 | --> |
| 20 | </ul> |
| 21 | <li><a href="#apis">Important and useful LLVM APIs</a> |
| 22 | <ul> |
Chris Lattner | 1d43fd4 | 2002-09-09 05:53:21 +0000 | [diff] [blame] | 23 | <li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt> and |
| 24 | <tt>dyn_cast<></tt> templates</a> |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 25 | <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro & |
| 26 | <tt>-debug</tt> option</a> |
| 27 | <li><a href="#Statistic">The <tt>Statistic</tt> template & |
| 28 | <tt>-stats</tt> option</a> |
| 29 | <!-- |
| 30 | <li>The <tt>InstVisitor</tt> template |
| 31 | <li>The general graph API |
| 32 | --> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 33 | </ul> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 34 | <li><a href="#common">Helpful Hints for Common Operations</a> |
| 35 | <ul> |
| 36 | <li><a href="#inspection">Basic Inspection and Traversal Routines</a> |
| 37 | <ul> |
| 38 | <li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s |
| 39 | in a <tt>Function</tt></a> |
| 40 | <li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s |
| 41 | in a <tt>BasicBlock</tt></a> |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 42 | <li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s |
| 43 | in a <tt>Function</tt></a> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 44 | <li><a href="#iterate_convert">Turning an iterator into a class |
| 45 | pointer</a> |
Chris Lattner | f1ebdc3 | 2002-09-06 22:09:21 +0000 | [diff] [blame] | 46 | <li><a href="#iterate_complex">Finding call sites: a more complex |
| 47 | example</a> |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 48 | <li><a href="#iterate_chains">Iterating over def-use & use-def |
| 49 | chains</a> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 50 | </ul> |
| 51 | <li><a href="#simplechanges">Making simple changes</a> |
| 52 | <ul> |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 53 | <li><a href="#schanges_creating">Creating and inserting new |
| 54 | <tt>Instruction</tt>s</a> |
| 55 | <li><a href="#schanges_deleting">Deleting |
| 56 | <tt>Instruction</tt>s</a> |
| 57 | <li><a href="#schanges_replacing">Replacing an |
| 58 | <tt>Instruction</tt> with another <tt>Value</tt></a> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 59 | </ul> |
| 60 | <!-- |
| 61 | <li>Working with the Control Flow Graph |
| 62 | <ul> |
| 63 | <li>Accessing predecessors and successors of a <tt>BasicBlock</tt> |
| 64 | <li> |
| 65 | <li> |
| 66 | </ul> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 67 | --> |
| 68 | </ul> |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 69 | <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 70 | <ul> |
| 71 | <li><a href="#Value">The <tt>Value</tt> class</a> |
| 72 | <ul> |
| 73 | <li><a href="#User">The <tt>User</tt> class</a> |
| 74 | <ul> |
| 75 | <li><a href="#Instruction">The <tt>Instruction</tt> class</a> |
| 76 | <ul> |
| 77 | <li> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 78 | </ul> |
| 79 | <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a> |
| 80 | <ul> |
| 81 | <li><a href="#BasicBlock">The <tt>BasicBlock</tt> class</a> |
| 82 | <li><a href="#Function">The <tt>Function</tt> class</a> |
| 83 | <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a> |
| 84 | </ul> |
| 85 | <li><a href="#Module">The <tt>Module</tt> class</a> |
| 86 | <li><a href="#Constant">The <tt>Constant</tt> class</a> |
| 87 | <ul> |
| 88 | <li> |
| 89 | <li> |
| 90 | </ul> |
| 91 | </ul> |
| 92 | <li><a href="#Type">The <tt>Type</tt> class</a> |
| 93 | <li><a href="#Argument">The <tt>Argument</tt> class</a> |
| 94 | </ul> |
| 95 | <li>The <tt>SymbolTable</tt> class |
| 96 | <li>The <tt>ilist</tt> and <tt>iplist</tt> classes |
| 97 | <ul> |
| 98 | <li>Creating, inserting, moving and deleting from LLVM lists |
| 99 | </ul> |
| 100 | <li>Important iterator invalidation semantics to be aware of |
| 101 | </ul> |
| 102 | |
Chris Lattner | 6b121f1 | 2002-09-10 15:20:46 +0000 | [diff] [blame] | 103 | <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>, |
| 104 | <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>, and |
Chris Lattner | f1ebdc3 | 2002-09-06 22:09:21 +0000 | [diff] [blame] | 105 | <a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a></b><p> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 106 | </ol> |
| 107 | |
| 108 | |
| 109 | <!-- *********************************************************************** --> |
| 110 | <table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> |
| 111 | <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b> |
| 112 | <a name="introduction">Introduction |
| 113 | </b></font></td></tr></table><ul> |
| 114 | <!-- *********************************************************************** --> |
| 115 | |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 116 | This document is meant to highlight some of the important classes and interfaces |
| 117 | available in the LLVM source-base. This manual is not intended to explain what |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 118 | LLVM is, how it works, and what LLVM code looks like. It assumes that you know |
| 119 | the basics of LLVM and are interested in writing transformations or otherwise |
| 120 | analyzing or manipulating the code.<p> |
| 121 | |
| 122 | This document should get you oriented so that you can find your way in the |
| 123 | continuously growing source code that makes up the LLVM infrastructure. Note |
| 124 | that this manual is not intended to serve as a replacement for reading the |
| 125 | source code, so if you think there should be a method in one of these classes to |
| 126 | do something, but it's not listed, check the source. Links to the <a |
| 127 | href="/doxygen/">doxygen</a> sources are provided to make this as easy as |
| 128 | possible.<p> |
| 129 | |
| 130 | The first section of this document describes general information that is useful |
| 131 | to know when working in the LLVM infrastructure, and the second describes the |
| 132 | Core LLVM classes. In the future this manual will be extended with information |
| 133 | describing how to use extension libraries, such as dominator information, CFG |
| 134 | traversal routines, and useful utilities like the <tt><a |
| 135 | href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> template.<p> |
| 136 | |
| 137 | |
| 138 | <!-- *********************************************************************** --> |
| 139 | </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> |
| 140 | <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b> |
| 141 | <a name="general">General Information |
| 142 | </b></font></td></tr></table><ul> |
| 143 | <!-- *********************************************************************** --> |
| 144 | |
| 145 | This section contains general information that is useful if you are working in |
| 146 | the LLVM source-base, but that isn't specific to any particular API.<p> |
| 147 | |
| 148 | |
| 149 | <!-- ======================================================================= --> |
| 150 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 151 | <tr><td> </td><td width="100%"> |
| 152 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 153 | <a name="stl">The C++ Standard Template Library</a> |
| 154 | </b></font></td></tr></table><ul> |
| 155 | |
| 156 | LLVM makes heavy use of the C++ Standard Template Library (STL), perhaps much |
| 157 | more than you are used to, or have seen before. Because of this, you might want |
| 158 | to do a little background reading in the techniques used and capabilities of the |
| 159 | library. There are many good pages that discuss the STL, and several books on |
| 160 | the subject that you can get, so it will not be discussed in this document.<p> |
| 161 | |
| 162 | Here are some useful links:<p> |
| 163 | <ol> |
Chris Lattner | ab0577b | 2002-09-22 21:25:12 +0000 | [diff] [blame] | 164 | <li><a href="http://www.dinkumware.com/refxcpp.html">Dinkumware C++ |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 165 | Library reference</a> - an excellent reference for the STL and other parts of |
Chris Lattner | e9ddc7f | 2002-10-21 02:38:02 +0000 | [diff] [blame] | 166 | the standard C++ library. |
| 167 | |
| 168 | <li><a href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> - This is an |
| 169 | O'Reilly book in the making. It has a decent <a |
| 170 | href="http://www.tempest-sw.com/cpp/ch13-libref.html">Standard Library |
| 171 | Reference</a> that rivals Dinkumware's, and is actually free until the book is |
| 172 | published. |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 173 | |
| 174 | <li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently Asked |
| 175 | Questions</a> |
| 176 | |
| 177 | <li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's Guide</a> - |
| 178 | Contains a useful <a |
| 179 | href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction to the |
| 180 | STL</a>. |
| 181 | |
| 182 | <li><a href="http://www.research.att.com/~bs/C++.html">Bjarne Stroustrup's C++ |
| 183 | Page</a> |
| 184 | |
| 185 | </ol><p> |
| 186 | |
| 187 | You are also encouraged to take a look at the <a |
| 188 | href="CodingStandards.html">LLVM Coding Standards</a> guide which focuses on how |
| 189 | to write maintainable code more than where to put your curly braces.<p> |
| 190 | |
| 191 | |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 192 | <!-- *********************************************************************** --> |
| 193 | </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> |
| 194 | <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b> |
| 195 | <a name="apis">Important and useful LLVM APIs |
| 196 | </b></font></td></tr></table><ul> |
| 197 | <!-- *********************************************************************** --> |
| 198 | |
| 199 | Here we highlight some LLVM APIs that are generally useful and good to know |
| 200 | about when writing transformations.<p> |
| 201 | |
Chris Lattner | 1d43fd4 | 2002-09-09 05:53:21 +0000 | [diff] [blame] | 202 | <!-- ======================================================================= --> |
| 203 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 204 | <tr><td> </td><td width="100%"> |
| 205 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 206 | <a name="isa">The isa<>, cast<> and dyn_cast<> templates</a> |
| 207 | </b></font></td></tr></table><ul> |
| 208 | |
Chris Lattner | 979d9b7 | 2002-09-10 00:39:05 +0000 | [diff] [blame] | 209 | The LLVM source-base makes extensive use of a custom form of RTTI. These |
| 210 | templates have many similarities to the C++ <tt>dynamic_cast<></tt> |
| 211 | operator, but they don't have some drawbacks (primarily stemming from the fact |
| 212 | that <tt>dynamic_cast<></tt> only works on classes that have a v-table). |
| 213 | Because they are used so often, you must know what they do and how they work. |
| 214 | All of these templates are defined in the <a |
| 215 | href="/doxygen/Casting_8h-source.html"><tt>Support/Casting.h</tt></a> file (note |
| 216 | that you very rarely have to include this file directly).<p> |
Chris Lattner | 1d43fd4 | 2002-09-09 05:53:21 +0000 | [diff] [blame] | 217 | |
Chris Lattner | 979d9b7 | 2002-09-10 00:39:05 +0000 | [diff] [blame] | 218 | <dl> |
| 219 | |
| 220 | <dt><tt>isa<></tt>: |
| 221 | |
| 222 | <dd>The <tt>isa<></tt> operator works exactly like the Java |
| 223 | "<tt>instanceof</tt>" operator. It returns true or false depending on whether a |
| 224 | reference or pointer points to an instance of the specified class. This can be |
| 225 | very useful for constraint checking of various sorts (example below).<p> |
| 226 | |
| 227 | |
| 228 | <dt><tt>cast<></tt>: |
| 229 | |
| 230 | <dd>The <tt>cast<></tt> operator is a "checked cast" operation. It |
| 231 | converts a pointer or reference from a base class to a derived cast, causing an |
| 232 | assertion failure if it is not really an instance of the right type. This |
| 233 | should be used in cases where you have some information that makes you believe |
| 234 | that something is of the right type. An example of the <tt>isa<></tt> and |
| 235 | <tt>cast<></tt> template is:<p> |
| 236 | |
| 237 | <pre> |
| 238 | static bool isLoopInvariant(const <a href="#Value">Value</a> *V, const Loop *L) { |
| 239 | if (isa<<a href="#Constant">Constant</a>>(V) || isa<<a href="#Argument">Argument</a>>(V) || isa<<a href="#GlobalValue">GlobalValue</a>>(V)) |
| 240 | return true; |
| 241 | |
| 242 | <i>// Otherwise, it must be an instruction...</i> |
| 243 | return !L->contains(cast<<a href="#Instruction">Instruction</a>>(V)->getParent()); |
| 244 | </pre><p> |
| 245 | |
| 246 | Note that you should <b>not</b> use an <tt>isa<></tt> test followed by a |
| 247 | <tt>cast<></tt>, for that use the <tt>dyn_cast<></tt> operator.<p> |
| 248 | |
| 249 | |
| 250 | <dt><tt>dyn_cast<></tt>: |
| 251 | |
| 252 | <dd>The <tt>dyn_cast<></tt> operator is a "checking cast" operation. It |
| 253 | checks to see if the operand is of the specified type, and if so, returns a |
| 254 | pointer to it (this operator does not work with references). If the operand is |
| 255 | not of the correct type, a null pointer is returned. Thus, this works very much |
| 256 | like the <tt>dynamic_cast</tt> operator in C++, and should be used in the same |
Chris Lattner | 6b121f1 | 2002-09-10 15:20:46 +0000 | [diff] [blame] | 257 | circumstances. Typically, the <tt>dyn_cast<></tt> operator is used in an |
| 258 | <tt>if</tt> statement or some other flow control statement like this:<p> |
| 259 | |
| 260 | <pre> |
| 261 | if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) { |
| 262 | ... |
| 263 | } |
| 264 | </pre><p> |
| 265 | |
| 266 | This form of the <tt>if</tt> statement effectively combines together a call to |
| 267 | <tt>isa<></tt> and a call to <tt>cast<></tt> into one statement, |
| 268 | which is very convenient.<p> |
| 269 | |
| 270 | Another common example is:<p> |
Chris Lattner | 979d9b7 | 2002-09-10 00:39:05 +0000 | [diff] [blame] | 271 | |
| 272 | <pre> |
| 273 | <i>// Loop over all of the phi nodes in a basic block</i> |
| 274 | BasicBlock::iterator BBI = BB->begin(); |
Chris Lattner | 6a54710 | 2003-04-23 16:26:15 +0000 | [diff] [blame] | 275 | for (; <a href="#PhiNode">PHINode</a> *PN = dyn_cast<<a href="#PHINode">PHINode</a>>(BBI); ++BBI) |
Chris Lattner | 979d9b7 | 2002-09-10 00:39:05 +0000 | [diff] [blame] | 276 | cerr << *PN; |
| 277 | </pre><p> |
| 278 | |
Chris Lattner | 6b121f1 | 2002-09-10 15:20:46 +0000 | [diff] [blame] | 279 | Note that the <tt>dyn_cast<></tt> operator, like C++'s |
| 280 | <tt>dynamic_cast</tt> or Java's <tt>instanceof</tt> operator, can be abused. In |
| 281 | particular you should not use big chained <tt>if/then/else</tt> blocks to check |
| 282 | for lots of different variants of classes. If you find yourself wanting to do |
| 283 | this, it is much cleaner and more efficient to use the InstVisitor class to |
| 284 | dispatch over the instruction type directly.<p> |
Chris Lattner | 979d9b7 | 2002-09-10 00:39:05 +0000 | [diff] [blame] | 285 | |
| 286 | |
Chris Lattner | 6b121f1 | 2002-09-10 15:20:46 +0000 | [diff] [blame] | 287 | <dt><tt>cast_or_null<></tt>: |
| 288 | |
| 289 | <dd>The <tt>cast_or_null<></tt> operator works just like the |
| 290 | <tt>cast<></tt> operator, except that it allows for a null pointer as an |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 291 | argument (which it then propagates). This can sometimes be useful, allowing you |
Chris Lattner | 6b121f1 | 2002-09-10 15:20:46 +0000 | [diff] [blame] | 292 | to combine several null checks into one.<p> |
| 293 | |
| 294 | |
| 295 | <dt><tt>dyn_cast_or_null<></tt>: |
| 296 | |
| 297 | <dd>The <tt>dyn_cast_or_null<></tt> operator works just like the |
| 298 | <tt>dyn_cast<></tt> operator, except that it allows for a null pointer as |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 299 | an argument (which it then propagates). This can sometimes be useful, allowing |
Chris Lattner | 6b121f1 | 2002-09-10 15:20:46 +0000 | [diff] [blame] | 300 | you to combine several null checks into one.<p> |
| 301 | |
Chris Lattner | 979d9b7 | 2002-09-10 00:39:05 +0000 | [diff] [blame] | 302 | </dl> |
Chris Lattner | 1d43fd4 | 2002-09-09 05:53:21 +0000 | [diff] [blame] | 303 | |
Chris Lattner | 6b121f1 | 2002-09-10 15:20:46 +0000 | [diff] [blame] | 304 | These five templates can be used with any classes, whether they have a v-table |
| 305 | or not. To add support for these templates, you simply need to add |
| 306 | <tt>classof</tt> static methods to the class you are interested casting to. |
| 307 | Describing this is currently outside the scope of this document, but there are |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 308 | lots of examples in the LLVM source base.<p> |
Chris Lattner | 1d43fd4 | 2002-09-09 05:53:21 +0000 | [diff] [blame] | 309 | |
| 310 | |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 311 | <!-- ======================================================================= --> |
| 312 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 313 | <tr><td> </td><td width="100%"> |
| 314 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 315 | <a name="DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt> option</a> |
| 316 | </b></font></td></tr></table><ul> |
| 317 | |
| 318 | Often when working on your pass you will put a bunch of debugging printouts and |
| 319 | other code into your pass. After you get it working, you want to remove |
| 320 | it... but you may need it again in the future (to work out new bugs that you run |
| 321 | across).<p> |
| 322 | |
| 323 | Naturally, because of this, you don't want to delete the debug printouts, but |
| 324 | you don't want them to always be noisy. A standard compromise is to comment |
| 325 | them out, allowing you to enable them if you need them in the future.<p> |
| 326 | |
| 327 | The "<tt><a |
Chris Lattner | 8328f1d | 2002-10-01 22:39:41 +0000 | [diff] [blame] | 328 | href="/doxygen/Statistic_8h-source.html">Support/Statistic.h</a></tt>" |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 329 | file provides a macro named <tt>DEBUG()</tt> that is a much nicer solution to |
| 330 | this problem. Basically, you can put arbitrary code into the argument of the |
| 331 | <tt>DEBUG</tt> macro, and it is only executed if '<tt>opt</tt>' is run with the |
| 332 | '<tt>-debug</tt>' command line argument: |
| 333 | |
| 334 | <pre> |
| 335 | ... |
| 336 | DEBUG(std::cerr << "I am here!\n"); |
| 337 | ... |
| 338 | </pre><p> |
| 339 | |
| 340 | Then you can run your pass like this:<p> |
| 341 | |
| 342 | <pre> |
| 343 | $ opt < a.bc > /dev/null -mypass |
| 344 | <no output> |
| 345 | $ opt < a.bc > /dev/null -mypass -debug |
| 346 | I am here! |
| 347 | $ |
| 348 | </pre><p> |
| 349 | |
| 350 | Using the <tt>DEBUG()</tt> macro instead of a home brewed solution allows you to |
| 351 | now have to create "yet another" command line option for the debug output for |
Chris Lattner | a4e7c4e | 2002-11-08 06:50:02 +0000 | [diff] [blame] | 352 | your pass. Note that <tt>DEBUG()</tt> macros are disabled for optimized builds, |
| 353 | so they do not cause a performance impact at all (for the same reason, they |
| 354 | should also not contain side-effects!).<p> |
| 355 | |
| 356 | One additional nice thing about the <tt>DEBUG()</tt> macro is that you can |
| 357 | enable or disable it directly in gdb. Just use "<tt>set DebugFlag=0</tt>" or |
| 358 | "<tt>set DebugFlag=1</tt>" from the gdb if the program is running. If the |
| 359 | program hasn't been started yet, you can always just run it with |
| 360 | <tt>-debug</tt>.<p> |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 361 | |
| 362 | |
| 363 | <!-- ======================================================================= --> |
| 364 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 365 | <tr><td> </td><td width="100%"> |
| 366 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 367 | <a name="Statistic">The <tt>Statistic</tt> template & <tt>-stats</tt> |
| 368 | option</a> |
| 369 | </b></font></td></tr></table><ul> |
| 370 | |
| 371 | The "<tt><a |
Chris Lattner | 8328f1d | 2002-10-01 22:39:41 +0000 | [diff] [blame] | 372 | href="/doxygen/Statistic_8h-source.html">Support/Statistic.h</a></tt>" |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 373 | file provides a template named <tt>Statistic</tt> that is used as a unified way |
| 374 | to keeping track of what the LLVM compiler is doing and how effective various |
| 375 | optimizations are. It is useful to see what optimizations are contributing to |
| 376 | making a particular program run faster.<p> |
| 377 | |
| 378 | Often you may run your pass on some big program, and you're interested to see |
| 379 | how many times it makes a certain transformation. Although you can do this with |
| 380 | hand inspection, or some ad-hoc method, this is a real pain and not very useful |
| 381 | for big programs. Using the <tt>Statistic</tt> template makes it very easy to |
| 382 | keep track of this information, and the calculated information is presented in a |
| 383 | uniform manner with the rest of the passes being executed.<p> |
| 384 | |
| 385 | There are many examples of <tt>Statistic</tt> users, but this basics of using it |
| 386 | are as follows:<p> |
| 387 | |
| 388 | <ol> |
| 389 | <li>Define your statistic like this:<p> |
| 390 | |
| 391 | <pre> |
Chris Lattner | 8328f1d | 2002-10-01 22:39:41 +0000 | [diff] [blame] | 392 | static Statistic<> NumXForms("mypassname", "The # of times I did stuff"); |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 393 | </pre><p> |
| 394 | |
| 395 | The <tt>Statistic</tt> template can emulate just about any data-type, but if you |
| 396 | do not specify a template argument, it defaults to acting like an unsigned int |
| 397 | counter (this is usually what you want).<p> |
| 398 | |
| 399 | <li>Whenever you make a transformation, bump the counter:<p> |
| 400 | |
| 401 | <pre> |
| 402 | ++NumXForms; // I did stuff |
| 403 | </pre><p> |
| 404 | |
| 405 | </ol><p> |
| 406 | |
| 407 | That's all you have to do. To get '<tt>opt</tt>' to print out the statistics |
| 408 | gathered, use the '<tt>-stats</tt>' option:<p> |
| 409 | |
| 410 | <pre> |
| 411 | $ opt -stats -mypassname < program.bc > /dev/null |
| 412 | ... statistic output ... |
| 413 | </pre><p> |
| 414 | |
| 415 | When running <tt>gccas</tt> on a C file from the SPEC benchmark suite, it gives |
| 416 | a report that looks like this:<p> |
| 417 | |
| 418 | <pre> |
| 419 | 7646 bytecodewriter - Number of normal instructions |
| 420 | 725 bytecodewriter - Number of oversized instructions |
| 421 | 129996 bytecodewriter - Number of bytecode bytes written |
| 422 | 2817 raise - Number of insts DCEd or constprop'd |
| 423 | 3213 raise - Number of cast-of-self removed |
| 424 | 5046 raise - Number of expression trees converted |
| 425 | 75 raise - Number of other getelementptr's formed |
| 426 | 138 raise - Number of load/store peepholes |
| 427 | 42 deadtypeelim - Number of unused typenames removed from symtab |
| 428 | 392 funcresolve - Number of varargs functions resolved |
| 429 | 27 globaldce - Number of global variables removed |
| 430 | 2 adce - Number of basic blocks removed |
| 431 | 134 cee - Number of branches revectored |
| 432 | 49 cee - Number of setcc instruction eliminated |
| 433 | 532 gcse - Number of loads removed |
| 434 | 2919 gcse - Number of instructions removed |
| 435 | 86 indvars - Number of cannonical indvars added |
| 436 | 87 indvars - Number of aux indvars removed |
| 437 | 25 instcombine - Number of dead inst eliminate |
| 438 | 434 instcombine - Number of insts combined |
| 439 | 248 licm - Number of load insts hoisted |
| 440 | 1298 licm - Number of insts hoisted to a loop pre-header |
| 441 | 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header) |
| 442 | 75 mem2reg - Number of alloca's promoted |
| 443 | 1444 cfgsimplify - Number of blocks simplified |
| 444 | </pre><p> |
| 445 | |
| 446 | Obviously, with so many optimizations, having a unified framework for this stuff |
| 447 | is very nice. Making your pass fit well into the framework makes it more |
| 448 | maintainable and useful.<p> |
| 449 | |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 450 | |
Chris Lattner | b99344f | 2002-09-06 16:40:10 +0000 | [diff] [blame] | 451 | <!-- *********************************************************************** --> |
| 452 | </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> |
| 453 | <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b> |
| 454 | <a name="common">Helpful Hints for Common Operations |
Chris Lattner | 986e0c9 | 2002-09-22 19:38:40 +0000 | [diff] [blame] | 455 | </b></font></td></tr></table><ul> <!-- |
| 456 | *********************************************************************** --> |
Chris Lattner | b99344f | 2002-09-06 16:40:10 +0000 | [diff] [blame] | 457 | |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 458 | This section describes how to perform some very simple transformations of LLVM |
| 459 | code. This is meant to give examples of common idioms used, showing the |
| 460 | practical side of LLVM transformations.<p> |
| 461 | |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 462 | Because this is a "how-to" section, you should also read about the main classes |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 463 | that you will be working with. The <a href="#coreclasses">Core LLVM Class |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 464 | Hierarchy Reference</a> contains details and descriptions of the main classes |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 465 | that you should know about.<p> |
| 466 | |
| 467 | <!-- NOTE: this section should be heavy on example code --> |
| 468 | |
| 469 | |
| 470 | <!-- ======================================================================= --> |
| 471 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 472 | <tr><td> </td><td width="100%"> |
| 473 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 474 | <a name="inspection">Basic Inspection and Traversal Routines</a> |
| 475 | </b></font></td></tr></table><ul> |
| 476 | |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 477 | The LLVM compiler infrastructure have many different data structures that may be |
| 478 | traversed. Following the example of the C++ standard template library, the |
| 479 | techniques used to traverse these various data structures are all basically the |
| 480 | same. For a enumerable sequence of values, the <tt>XXXbegin()</tt> function (or |
| 481 | method) returns an iterator to the start of the sequence, the <tt>XXXend()</tt> |
| 482 | function returns an iterator pointing to one past the last valid element of the |
| 483 | sequence, and there is some <tt>XXXiterator</tt> data type that is common |
| 484 | between the two operations.<p> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 485 | |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 486 | Because the pattern for iteration is common across many different aspects of the |
| 487 | program representation, the standard template library algorithms may be used on |
| 488 | them, and it is easier to remember how to iterate. First we show a few common |
| 489 | examples of the data structures that need to be traversed. Other data |
| 490 | structures are traversed in very similar ways.<p> |
| 491 | |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 492 | |
| 493 | <!-- _______________________________________________________________________ --> |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 494 | </ul><h4><a name="iterate_function"><hr size=0>Iterating over the <a |
| 495 | href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a |
| 496 | href="#Function"><tt>Function</tt></a> </h4><ul> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 497 | |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 498 | It's quite common to have a <tt>Function</tt> instance that you'd like |
| 499 | to transform in some way; in particular, you'd like to manipulate its |
| 500 | <tt>BasicBlock</tt>s. To facilitate this, you'll need to iterate over |
| 501 | all of the <tt>BasicBlock</tt>s that constitute the <tt>Function</tt>. |
| 502 | The following is an example that prints the name of a |
| 503 | <tt>BasicBlock</tt> and the number of <tt>Instruction</tt>s it |
| 504 | contains: |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 505 | |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 506 | <pre> |
| 507 | // func is a pointer to a Function instance |
| 508 | for(Function::iterator i = func->begin(), e = func->end(); i != e; ++i) { |
| 509 | |
| 510 | // print out the name of the basic block if it has one, and then the |
| 511 | // number of instructions that it contains |
| 512 | |
Joel Stanley | 72ef35e | 2002-09-06 23:05:12 +0000 | [diff] [blame] | 513 | cerr << "Basic block (name=" << i->getName() << ") has " |
| 514 | << i->size() << " instructions.\n"; |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 515 | } |
| 516 | </pre> |
| 517 | |
| 518 | Note that i can be used as if it were a pointer for the purposes of |
| 519 | invoking member functions of the <tt>Instruction</tt> class. This is |
| 520 | because the indirection operator is overloaded for the iterator |
| 521 | classes. In the above code, the expression <tt>i->size()</tt> is |
| 522 | exactly equivalent to <tt>(*i).size()</tt> just like you'd expect. |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 523 | |
| 524 | <!-- _______________________________________________________________________ --> |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 525 | </ul><h4><a name="iterate_basicblock"><hr size=0>Iterating over the <a |
| 526 | href="#Instruction"><tt>Instruction</tt></a>s in a <a |
| 527 | href="#BasicBlock"><tt>BasicBlock</tt></a> </h4><ul> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 528 | |
Joel Stanley | aaeb1c1 | 2002-09-06 23:42:40 +0000 | [diff] [blame] | 529 | Just like when dealing with <tt>BasicBlock</tt>s in |
| 530 | <tt>Function</tt>s, it's easy to iterate over the individual |
| 531 | instructions that make up <tt>BasicBlock</tt>s. Here's a code snippet |
| 532 | that prints out each instruction in a <tt>BasicBlock</tt>: |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 533 | |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 534 | <pre> |
| 535 | // blk is a pointer to a BasicBlock instance |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 536 | for(BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i) |
Chris Lattner | 2b76306 | 2002-09-06 22:51:10 +0000 | [diff] [blame] | 537 | // the next statement works since operator<<(ostream&,...) |
| 538 | // is overloaded for Instruction& |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 539 | cerr << *i << "\n"; |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 540 | </pre> |
| 541 | |
| 542 | However, this isn't really the best way to print out the contents of a |
| 543 | <tt>BasicBlock</tt>! Since the ostream operators are overloaded for |
| 544 | virtually anything you'll care about, you could have just invoked the |
Chris Lattner | 2b76306 | 2002-09-06 22:51:10 +0000 | [diff] [blame] | 545 | print routine on the basic block itself: <tt>cerr << *blk << |
| 546 | "\n";</tt>.<p> |
| 547 | |
| 548 | Note that currently operator<< is implemented for <tt>Value*</tt>, so it |
| 549 | will print out the contents of the pointer, instead of |
| 550 | the pointer value you might expect. This is a deprecated interface that will |
| 551 | be removed in the future, so it's best not to depend on it. To print out the |
| 552 | pointer value for now, you must cast to <tt>void*</tt>.<p> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 553 | |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 554 | |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 555 | <!-- _______________________________________________________________________ --> |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 556 | </ul><h4><a name="iterate_institer"><hr size=0>Iterating over the <a |
| 557 | href="#Instruction"><tt>Instruction</tt></a>s in a <a |
| 558 | href="#Function"><tt>Function</tt></a></h4><ul> |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 559 | |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 560 | If you're finding that you commonly iterate over a <tt>Function</tt>'s |
| 561 | <tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s |
| 562 | <tt>Instruction</tt>s, <tt>InstIterator</tt> should be used instead. |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 563 | You'll need to include <a href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>, and then |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 564 | instantiate <tt>InstIterator</tt>s explicitly in your code. Here's a |
| 565 | small example that shows how to dump all instructions in a function to |
| 566 | stderr (<b>Note:</b> Dereferencing an <tt>InstIterator</tt> yields an |
| 567 | <tt>Instruction*</tt>, <i>not</i> an <tt>Instruction&</tt>!): |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 568 | |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 569 | <pre> |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 570 | #include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>" |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 571 | ... |
| 572 | // Suppose F is a ptr to a function |
| 573 | for(inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i) |
| 574 | cerr << **i << "\n"; |
| 575 | </pre> |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 576 | |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 577 | Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a |
| 578 | worklist with its initial contents. For example, if you wanted to |
| 579 | initialize a worklist to contain all instructions in a |
| 580 | <tt>Function</tt> F, all you would need to do is something like: |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 581 | |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 582 | <pre> |
| 583 | std::set<Instruction*> worklist; |
| 584 | worklist.insert(inst_begin(F), inst_end(F)); |
| 585 | </pre> |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 586 | |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 587 | The STL set <tt>worklist</tt> would now contain all instructions in |
| 588 | the <tt>Function</tt> pointed to by F. |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 589 | |
| 590 | <!-- _______________________________________________________________________ --> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 591 | </ul><h4><a name="iterate_convert"><hr size=0>Turning an iterator into a class |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 592 | pointer (and vice-versa) </h4><ul> |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 593 | |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 594 | Sometimes, it'll be useful to grab a reference (or pointer) to a class |
| 595 | instance when all you've got at hand is an iterator. Well, extracting |
| 596 | a reference or a pointer from an iterator is very straightforward. |
| 597 | Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and |
| 598 | <tt>j</tt> is a <tt>BasicBlock::const_iterator</tt>: |
| 599 | |
| 600 | <pre> |
Chris Lattner | 83b5ee0 | 2002-09-06 22:12:58 +0000 | [diff] [blame] | 601 | Instruction& inst = *i; // grab reference to instruction reference |
| 602 | Instruction* pinst = &*i; // grab pointer to instruction reference |
| 603 | const Instruction& inst = *j; |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 604 | </pre> |
| 605 | However, the iterators you'll be working with in the LLVM framework |
| 606 | are special: they will automatically convert to a ptr-to-instance type |
| 607 | whenever they need to. Instead of dereferencing the iterator and then |
| 608 | taking the address of the result, you can simply assign the iterator |
| 609 | to the proper pointer type and you get the dereference and address-of |
| 610 | operation as a result of the assignment (behind the scenes, this is a |
| 611 | result of overloading casting mechanisms). Thus the last line of the |
| 612 | last example, |
| 613 | |
Chris Lattner | 83b5ee0 | 2002-09-06 22:12:58 +0000 | [diff] [blame] | 614 | <pre>Instruction* pinst = &*i;</pre> |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 615 | |
| 616 | is semantically equivalent to |
| 617 | |
| 618 | <pre>Instruction* pinst = i;</pre> |
| 619 | |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 620 | It's also possible to turn a class pointer into the corresponding |
| 621 | iterator. Usually, this conversion is quite inexpensive. The |
| 622 | following code snippet illustrates use of the conversion constructors |
| 623 | provided by LLVM iterators. By using these, you can explicitly grab |
| 624 | the iterator of something without actually obtaining it via iteration |
| 625 | over some structure: |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 626 | |
| 627 | <pre> |
| 628 | void printNextInstruction(Instruction* inst) { |
| 629 | BasicBlock::iterator it(inst); |
| 630 | ++it; // after this line, it refers to the instruction after *inst. |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 631 | if(it != inst->getParent()->end()) cerr << *it << "\n"; |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 632 | } |
| 633 | </pre> |
Joel Stanley | aaeb1c1 | 2002-09-06 23:42:40 +0000 | [diff] [blame] | 634 | Of course, this example is strictly pedagogical, because it'd be much |
| 635 | better to explicitly grab the next instruction directly from inst. |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 636 | |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 637 | |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 638 | <!--_______________________________________________________________________--> |
| 639 | </ul><h4><a name="iterate_complex"><hr size=0>Finding call sites: a slightly |
| 640 | more complex example </h4><ul> |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 641 | |
| 642 | Say that you're writing a FunctionPass and would like to count all the |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 643 | locations in the entire module (that is, across every |
Misha Brukman | 79223ed | 2003-07-28 19:21:20 +0000 | [diff] [blame] | 644 | <tt>Function</tt>) where a certain function (i.e., some |
| 645 | <tt>Function</tt>*) is already in scope. As you'll learn later, you may |
Joel Stanley | d8aabb2 | 2002-09-09 16:29:58 +0000 | [diff] [blame] | 646 | want to use an <tt>InstVisitor</tt> to accomplish this in a much more |
| 647 | straightforward manner, but this example will allow us to explore how |
| 648 | you'd do it if you didn't have <tt>InstVisitor</tt> around. In |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 649 | pseudocode, this is what we want to do: |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 650 | |
| 651 | <pre> |
| 652 | initialize callCounter to zero |
| 653 | for each Function f in the Module |
| 654 | for each BasicBlock b in f |
| 655 | for each Instruction i in b |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 656 | if(i is a CallInst and calls the given function) |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 657 | increment callCounter |
| 658 | </pre> |
| 659 | |
| 660 | And the actual code is (remember, since we're writing a |
Joel Stanley | d8aabb2 | 2002-09-09 16:29:58 +0000 | [diff] [blame] | 661 | <tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 662 | has to override the <tt>runOnFunction</tt> method...): |
| 663 | |
| 664 | <pre> |
Joel Stanley | d8aabb2 | 2002-09-09 16:29:58 +0000 | [diff] [blame] | 665 | Function* targetFunc = ...; |
| 666 | |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 667 | class OurFunctionPass : public FunctionPass { |
| 668 | public: |
Joel Stanley | d8aabb2 | 2002-09-09 16:29:58 +0000 | [diff] [blame] | 669 | OurFunctionPass(): callCounter(0) { } |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 670 | |
Chris Lattner | caa5d13 | 2002-09-09 19:58:18 +0000 | [diff] [blame] | 671 | virtual runOnFunction(Function& F) { |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 672 | for(Function::iterator b = F.begin(), be = F.end(); b != be; ++b) { |
| 673 | for(BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) { |
Chris Lattner | a9030cb | 2002-09-16 22:08:07 +0000 | [diff] [blame] | 674 | if (<a href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a href="#CallInst">CallInst</a>>(&*i)) { |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 675 | // we know we've encountered a call instruction, so we |
| 676 | // need to determine if it's a call to the |
| 677 | // function pointed to by m_func or not. |
| 678 | |
Joel Stanley | d8aabb2 | 2002-09-09 16:29:58 +0000 | [diff] [blame] | 679 | if(callInst->getCalledFunction() == targetFunc) |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 680 | ++callCounter; |
| 681 | } |
| 682 | } |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 683 | } |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 684 | |
| 685 | private: |
Joel Stanley | d8aabb2 | 2002-09-09 16:29:58 +0000 | [diff] [blame] | 686 | unsigned callCounter; |
Joel Stanley | e7be650 | 2002-09-09 15:50:33 +0000 | [diff] [blame] | 687 | }; |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 688 | </pre> |
| 689 | |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 690 | <!--_______________________________________________________________________--> |
| 691 | </ul><h4><a name="iterate_chains"><hr size=0>Iterating over def-use & |
| 692 | use-def chains</h4><ul> |
| 693 | |
Joel Stanley | 01040b2 | 2002-09-11 20:50:04 +0000 | [diff] [blame] | 694 | Frequently, we might have an instance of the <a |
| 695 | href="/doxygen/classValue.html">Value Class</a> and we want to |
| 696 | determine which <tt>User</tt>s use the <tt>Value</tt>. The list of |
| 697 | all <tt>User</tt>s of a particular <tt>Value</tt> is called a |
| 698 | <i>def-use</i> chain. For example, let's say we have a |
| 699 | <tt>Function*</tt> named <tt>F</tt> to a particular function |
| 700 | <tt>foo</tt>. Finding all of the instructions that <i>use</i> |
| 701 | <tt>foo</tt> is as simple as iterating over the <i>def-use</i> chain of |
| 702 | <tt>F</tt>: |
| 703 | |
| 704 | <pre> |
| 705 | Function* F = ...; |
| 706 | |
| 707 | for(Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) { |
Chris Lattner | 24b7092 | 2002-09-17 22:43:00 +0000 | [diff] [blame] | 708 | if(Instruction* Inst = dyn_cast<Instruction>(*i)) { |
| 709 | cerr << "F is used in instruction:\n"; |
| 710 | cerr << *Inst << "\n"; |
Joel Stanley | 01040b2 | 2002-09-11 20:50:04 +0000 | [diff] [blame] | 711 | } |
| 712 | } |
| 713 | </pre> |
| 714 | |
| 715 | Alternately, it's common to have an instance of the <a |
| 716 | href="/doxygen/classUser.html">User Class</a> and need to know what |
| 717 | <tt>Value</tt>s are used by it. The list of all <tt>Value</tt>s used |
| 718 | by a <tt>User</tt> is known as a <i>use-def</i> chain. Instances of |
| 719 | class <tt>Instruction</tt> are common <tt>User</tt>s, so we might want |
| 720 | to iterate over all of the values that a particular instruction uses |
| 721 | (that is, the operands of the particular <tt>Instruction</tt>): |
| 722 | |
| 723 | <pre> |
| 724 | Instruction* pi = ...; |
| 725 | |
| 726 | for(User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) { |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 727 | Value* v = *i; |
Joel Stanley | 01040b2 | 2002-09-11 20:50:04 +0000 | [diff] [blame] | 728 | ... |
| 729 | } |
| 730 | </pre> |
| 731 | |
| 732 | |
Chris Lattner | 1a3105b | 2002-09-09 05:49:39 +0000 | [diff] [blame] | 733 | <!-- |
| 734 | def-use chains ("finding all users of"): Value::use_begin/use_end |
| 735 | use-def chains ("finding all values used"): User::op_begin/op_end [op=operand] |
| 736 | --> |
| 737 | |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 738 | <!-- ======================================================================= --> |
| 739 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 740 | <tr><td> </td><td width="100%"> |
| 741 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 742 | <a name="simplechanges">Making simple changes</a> |
| 743 | </b></font></td></tr></table><ul> |
| 744 | |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 745 | There are some primitive transformation operations present in the LLVM |
| 746 | infrastructure that are worth knowing about. When performing |
| 747 | transformations, it's fairly common to manipulate the contents of |
| 748 | basic blocks. This section describes some of the common methods for |
| 749 | doing so and gives example code. |
| 750 | |
| 751 | <!--_______________________________________________________________________--> |
| 752 | </ul><h4><a name="schanges_creating"><hr size=0>Creating and inserting |
| 753 | new <tt>Instruction</tt>s</h4><ul> |
| 754 | |
| 755 | <i>Instantiating Instructions</i> |
| 756 | |
| 757 | <p>Creation of <tt>Instruction</tt>s is straightforward: simply call the |
| 758 | constructor for the kind of instruction to instantiate and provide the |
| 759 | necessary parameters. For example, an <tt>AllocaInst</tt> only |
| 760 | <i>requires</i> a (const-ptr-to) <tt>Type</tt>. Thus: |
| 761 | |
| 762 | <pre>AllocaInst* ai = new AllocaInst(Type::IntTy);</pre> |
| 763 | |
| 764 | will create an <tt>AllocaInst</tt> instance that represents the |
| 765 | allocation of one integer in the current stack frame, at runtime. |
| 766 | Each <tt>Instruction</tt> subclass is likely to have varying default |
| 767 | parameters which change the semantics of the instruction, so refer to |
Chris Lattner | 4e1f96b | 2002-09-12 19:06:51 +0000 | [diff] [blame] | 768 | the <a href="/doxygen/classInstruction.html">doxygen documentation for |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 769 | the subclass of Instruction</a> that you're interested in |
| 770 | instantiating.</p> |
| 771 | |
| 772 | <p><i>Naming values</i></p> |
| 773 | |
| 774 | <p> |
| 775 | It is very useful to name the values of instructions when you're able |
| 776 | to, as this facilitates the debugging of your transformations. If you |
| 777 | end up looking at generated LLVM machine code, you definitely want to |
| 778 | have logical names associated with the results of instructions! By |
| 779 | supplying a value for the <tt>Name</tt> (default) parameter of the |
| 780 | <tt>Instruction</tt> constructor, you associate a logical name with |
| 781 | the result of the instruction's execution at runtime. For example, |
| 782 | say that I'm writing a transformation that dynamically allocates space |
| 783 | for an integer on the stack, and that integer is going to be used as |
| 784 | some kind of index by some other code. To accomplish this, I place an |
| 785 | <tt>AllocaInst</tt> at the first point in the first |
| 786 | <tt>BasicBlock</tt> of some <tt>Function</tt>, and I'm intending to |
| 787 | use it within the same <tt>Function</tt>. I might do: |
| 788 | |
| 789 | <pre>AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");</pre> |
| 790 | |
| 791 | where <tt>indexLoc</tt> is now the logical name of the instruction's |
| 792 | execution value, which is a pointer to an integer on the runtime |
| 793 | stack. |
| 794 | </p> |
| 795 | |
| 796 | <p><i>Inserting instructions</i></p> |
| 797 | |
| 798 | <p> |
| 799 | There are essentially two ways to insert an <tt>Instruction</tt> into |
| 800 | an existing sequence of instructions that form a <tt>BasicBlock</tt>: |
| 801 | <ul> |
| 802 | <li>Insertion into an explicit instruction list |
| 803 | |
| 804 | <p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within |
| 805 | that <tt>BasicBlock</tt>, and a newly-created instruction |
| 806 | we wish to insert before <tt>*pi</tt>, we do the following: |
| 807 | |
| 808 | <pre> |
| 809 | BasicBlock* pb = ...; |
| 810 | Instruction* pi = ...; |
| 811 | Instruction* newInst = new Instruction(...); |
| 812 | pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb |
| 813 | </pre> |
| 814 | </p> |
| 815 | |
| 816 | <li>Insertion into an implicit instruction list |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 817 | <p><tt>Instruction</tt> instances that are already in |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 818 | <tt>BasicBlock</tt>s are implicitly associated with an existing |
| 819 | instruction list: the instruction list of the enclosing basic block. |
| 820 | Thus, we could have accomplished the same thing as the above code |
| 821 | without being given a <tt>BasicBlock</tt> by doing: |
| 822 | <pre> |
| 823 | Instruction* pi = ...; |
| 824 | Instruction* newInst = new Instruction(...); |
| 825 | pi->getParent()->getInstList().insert(pi, newInst); |
| 826 | </pre> |
| 827 | In fact, this sequence of steps occurs so frequently that the |
| 828 | <tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes |
| 829 | provide constructors which take (as a default parameter) a pointer to |
| 830 | an <tt>Instruction</tt> which the newly-created <tt>Instruction</tt> |
| 831 | should precede. That is, <tt>Instruction</tt> constructors are |
| 832 | capable of inserting the newly-created instance into the |
| 833 | <tt>BasicBlock</tt> of a provided instruction, immediately before that |
| 834 | instruction. Using an <tt>Instruction</tt> constructor with a |
| 835 | <tt>insertBefore</tt> (default) parameter, the above code becomes: |
| 836 | <pre> |
| 837 | Instruction* pi = ...; |
| 838 | Instruction* newInst = new Instruction(..., pi); |
| 839 | </pre> |
| 840 | which is much cleaner, especially if you're creating a lot of |
| 841 | instructions and adding them to <tt>BasicBlock</tt>s. |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 842 | </p> |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 843 | </p> |
Chris Lattner | 9ebf516 | 2002-09-12 19:08:16 +0000 | [diff] [blame] | 844 | </ul> |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 845 | |
| 846 | <!--_______________________________________________________________________--> |
| 847 | </ul><h4><a name="schanges_deleting"><hr size=0>Deleting |
Chris Lattner | 4e1f96b | 2002-09-12 19:06:51 +0000 | [diff] [blame] | 848 | <tt>Instruction</tt>s</h4><ul> |
| 849 | |
| 850 | Deleting an instruction from an existing sequence of instructions that form a <a |
| 851 | href="#BasicBlock"><tt>BasicBlock</tt></a> is very straightforward. First, you |
| 852 | must have a pointer to the instruction that you wish to delete. Second, you |
| 853 | need to obtain the pointer to that instruction's basic block. You use the |
| 854 | pointer to the basic block to get its list of instructions and then use the |
| 855 | erase function to remove your instruction.<p> |
| 856 | |
| 857 | For example:<p> |
| 858 | |
| 859 | <pre> |
| 860 | <a href="#Instruction">Instruction</a> *I = .. ; |
Chris Lattner | 7dbf683 | 2002-09-18 05:14:25 +0000 | [diff] [blame] | 861 | <a href="#BasicBlock">BasicBlock</a> *BB = I->getParent(); |
| 862 | BB->getInstList().erase(I); |
Chris Lattner | 4e1f96b | 2002-09-12 19:06:51 +0000 | [diff] [blame] | 863 | </pre><p> |
| 864 | |
Joel Stanley | 753eb71 | 2002-09-11 22:32:24 +0000 | [diff] [blame] | 865 | <!--_______________________________________________________________________--> |
| 866 | </ul><h4><a name="schanges_replacing"><hr size=0>Replacing an |
| 867 | <tt>Instruction</tt> with another <tt>Value</tt></h4><ul> |
| 868 | |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 869 | <p><i>Replacing individual instructions</i></p> |
| 870 | <p> |
| 871 | Including "<a |
Misha Brukman | 79223ed | 2003-07-28 19:21:20 +0000 | [diff] [blame] | 872 | href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>" permits use of two very useful replace functions: |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 873 | <tt>ReplaceInstWithValue</tt> and <tt>ReplaceInstWithInst</tt>. |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 874 | |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 875 | <ul> |
| 876 | |
Chris Lattner | 7dbf683 | 2002-09-18 05:14:25 +0000 | [diff] [blame] | 877 | <li><tt>ReplaceInstWithValue</tt> |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 878 | |
| 879 | <p>This function replaces all uses (within a basic block) of a given |
| 880 | instruction with a value, and then removes the original instruction. |
| 881 | The following example illustrates the replacement of the result of a |
| 882 | particular <tt>AllocaInst</tt> that allocates memory for a single |
| 883 | integer with an null pointer to an integer.</p> |
| 884 | |
| 885 | <pre> |
| 886 | AllocaInst* instToReplace = ...; |
Joel Stanley | 4b28793 | 2002-09-29 17:31:54 +0000 | [diff] [blame] | 887 | BasicBlock::iterator ii(instToReplace); |
| 888 | ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii, |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 889 | Constant::getNullValue(PointerType::get(Type::IntTy))); |
| 890 | </pre> |
| 891 | |
Chris Lattner | 7dbf683 | 2002-09-18 05:14:25 +0000 | [diff] [blame] | 892 | <li><tt>ReplaceInstWithInst</tt> |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 893 | |
| 894 | <p>This function replaces a particular instruction with another |
| 895 | instruction. The following example illustrates the replacement of one |
| 896 | <tt>AllocaInst</tt> with another.<p> |
| 897 | |
| 898 | <pre> |
| 899 | AllocaInst* instToReplace = ...; |
Joel Stanley | 4b28793 | 2002-09-29 17:31:54 +0000 | [diff] [blame] | 900 | BasicBlock::iterator ii(instToReplace); |
| 901 | ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii, |
Misha Brukman | e7a7ab4 | 2003-05-07 21:47:39 +0000 | [diff] [blame] | 902 | new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt")); |
Joel Stanley | 9dd1ad6 | 2002-09-18 03:17:23 +0000 | [diff] [blame] | 903 | </pre> |
| 904 | |
| 905 | </ul> |
| 906 | <p><i>Replacing multiple uses of <tt>User</tt>s and |
| 907 | <tt>Value</tt>s</i></p> |
| 908 | |
| 909 | You can use <tt>Value::replaceAllUsesWith</tt> and |
| 910 | <tt>User::replaceUsesOfWith</tt> to change more than one use at a |
| 911 | time. See the doxygen documentation for the <a |
| 912 | href="/doxygen/classValue.html">Value Class</a> and <a |
| 913 | href="/doxygen/classUser.html">User Class</a>, respectively, for more |
| 914 | information. |
| 915 | |
| 916 | <!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out: |
| 917 | include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with: |
| 918 | ReplaceInstWithValue, ReplaceInstWithInst |
Chris Lattner | ae7f759 | 2002-09-06 18:31:18 +0000 | [diff] [blame] | 919 | --> |
Chris Lattner | b99344f | 2002-09-06 16:40:10 +0000 | [diff] [blame] | 920 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 921 | <!-- *********************************************************************** --> |
| 922 | </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0> |
| 923 | <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b> |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 924 | <a name="coreclasses">The Core LLVM Class Hierarchy Reference |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 925 | </b></font></td></tr></table><ul> |
| 926 | <!-- *********************************************************************** --> |
| 927 | |
| 928 | The Core LLVM classes are the primary means of representing the program being |
| 929 | inspected or transformed. The core LLVM classes are defined in header files in |
| 930 | the <tt>include/llvm/</tt> directory, and implemented in the <tt>lib/VMCore</tt> |
| 931 | directory.<p> |
| 932 | |
| 933 | |
| 934 | <!-- ======================================================================= --> |
| 935 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 936 | <tr><td> </td><td width="100%"> |
| 937 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 938 | <a name="Value">The <tt>Value</tt> class</a> |
| 939 | </b></font></td></tr></table><ul> |
| 940 | |
| 941 | <tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt></b><br> |
| 942 | doxygen info: <a href="/doxygen/classValue.html">Value Class</a><p> |
| 943 | |
| 944 | |
| 945 | The <tt>Value</tt> class is the most important class in LLVM Source base. It |
| 946 | represents a typed value that may be used (among other things) as an operand to |
| 947 | an instruction. There are many different types of <tt>Value</tt>s, such as <a |
| 948 | href="#Constant"><tt>Constant</tt></a>s, <a |
| 949 | href="#Argument"><tt>Argument</tt></a>s, and even <a |
| 950 | href="#Instruction"><tt>Instruction</tt></a>s and <a |
| 951 | href="#Function"><tt>Function</tt></a>s are <tt>Value</tt>s.<p> |
| 952 | |
| 953 | A particular <tt>Value</tt> may be used many times in the LLVM representation |
| 954 | for a program. For example, an incoming argument to a function (represented |
| 955 | with an instance of the <a href="#Argument">Argument</a> class) is "used" by |
| 956 | every instruction in the function that references the argument. To keep track |
| 957 | of this relationship, the <tt>Value</tt> class keeps a list of all of the <a |
| 958 | href="#User"><tt>User</tt></a>s that is using it (the <a |
| 959 | href="#User"><tt>User</tt></a> class is a base class for all nodes in the LLVM |
| 960 | graph that can refer to <tt>Value</tt>s). This use list is how LLVM represents |
Joel Stanley | 9b96c44 | 2002-09-06 21:55:13 +0000 | [diff] [blame] | 961 | def-use information in the program, and is accessible through the <tt>use_</tt>* |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 962 | methods, shown below.<p> |
| 963 | |
| 964 | Because LLVM is a typed representation, every LLVM <tt>Value</tt> is typed, and |
| 965 | this <a href="#Type">Type</a> is available through the <tt>getType()</tt> |
| 966 | method. <a name="#nameWarning">In addition, all LLVM values can be named. The |
| 967 | "name" of the <tt>Value</tt> is symbolic string printed in the LLVM code:<p> |
| 968 | |
| 969 | <pre> |
| 970 | %<b>foo</b> = add int 1, 2 |
| 971 | </pre> |
| 972 | |
| 973 | The name of this instruction is "foo". <b>NOTE</b> that the name of any value |
| 974 | may be missing (an empty string), so names should <b>ONLY</b> be used for |
| 975 | debugging (making the source code easier to read, debugging printouts), they |
| 976 | should not be used to keep track of values or map between them. For this |
| 977 | purpose, use a <tt>std::map</tt> of pointers to the <tt>Value</tt> itself |
| 978 | instead.<p> |
| 979 | |
| 980 | One important aspect of LLVM is that there is no distinction between an SSA |
| 981 | variable and the operation that produces it. Because of this, any reference to |
| 982 | the value produced by an instruction (or the value available as an incoming |
| 983 | argument, for example) is represented as a direct pointer to the class that |
| 984 | represents this value. Although this may take some getting used to, it |
| 985 | simplifies the representation and makes it easier to manipulate.<p> |
| 986 | |
| 987 | |
| 988 | <!-- _______________________________________________________________________ --> |
| 989 | </ul><h4><a name="m_Value"><hr size=0>Important Public Members of |
| 990 | the <tt>Value</tt> class</h4><ul> |
| 991 | |
| 992 | <li><tt>Value::use_iterator</tt> - Typedef for iterator over the use-list<br> |
| 993 | <tt>Value::use_const_iterator</tt> |
| 994 | - Typedef for const_iterator over the use-list<br> |
| 995 | <tt>unsigned use_size()</tt> - Returns the number of users of the value.<br> |
| 996 | <tt>bool use_empty()</tt> - Returns true if there are no users.<br> |
| 997 | <tt>use_iterator use_begin()</tt> |
| 998 | - Get an iterator to the start of the use-list.<br> |
| 999 | <tt>use_iterator use_end()</tt> |
| 1000 | - Get an iterator to the end of the use-list.<br> |
| 1001 | <tt><a href="#User">User</a> *use_back()</tt> |
| 1002 | - Returns the last element in the list.<p> |
| 1003 | |
| 1004 | These methods are the interface to access the def-use information in LLVM. As with all other iterators in LLVM, the naming conventions follow the conventions defined by the <a href="#stl">STL</a>.<p> |
| 1005 | |
| 1006 | <li><tt><a href="#Type">Type</a> *getType() const</tt><p> |
| 1007 | This method returns the Type of the Value. |
| 1008 | |
| 1009 | <li><tt>bool hasName() const</tt><br> |
| 1010 | <tt>std::string getName() const</tt><br> |
| 1011 | <tt>void setName(const std::string &Name)</tt><p> |
| 1012 | |
| 1013 | This family of methods is used to access and assign a name to a <tt>Value</tt>, |
| 1014 | be aware of the <a href="#nameWarning">precaution above</a>.<p> |
| 1015 | |
| 1016 | |
| 1017 | <li><tt>void replaceAllUsesWith(Value *V)</tt><p> |
| 1018 | |
| 1019 | This method traverses the use list of a <tt>Value</tt> changing all <a |
Misha Brukman | c4f5bb0 | 2002-09-18 02:21:57 +0000 | [diff] [blame] | 1020 | href="#User"><tt>User</tt>s</a> of the current value to refer to "<tt>V</tt>" |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1021 | instead. For example, if you detect that an instruction always produces a |
| 1022 | constant value (for example through constant folding), you can replace all uses |
| 1023 | of the instruction with the constant like this:<p> |
| 1024 | |
| 1025 | <pre> |
| 1026 | Inst->replaceAllUsesWith(ConstVal); |
| 1027 | </pre><p> |
| 1028 | |
| 1029 | |
| 1030 | |
| 1031 | <!-- ======================================================================= --> |
| 1032 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1033 | <tr><td> </td><td width="100%"> |
| 1034 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1035 | <a name="User">The <tt>User</tt> class</a> |
| 1036 | </b></font></td></tr></table><ul> |
| 1037 | |
| 1038 | <tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt></b><br> |
| 1039 | doxygen info: <a href="/doxygen/classUser.html">User Class</a><br> |
| 1040 | Superclass: <a href="#Value"><tt>Value</tt></a><p> |
| 1041 | |
| 1042 | |
| 1043 | The <tt>User</tt> class is the common base class of all LLVM nodes that may |
| 1044 | refer to <a href="#Value"><tt>Value</tt></a>s. It exposes a list of "Operands" |
| 1045 | that are all of the <a href="#Value"><tt>Value</tt></a>s that the User is |
| 1046 | referring to. The <tt>User</tt> class itself is a subclass of |
| 1047 | <tt>Value</tt>.<p> |
| 1048 | |
| 1049 | The operands of a <tt>User</tt> point directly to the LLVM <a |
| 1050 | href="#Value"><tt>Value</tt></a> that it refers to. Because LLVM uses Static |
| 1051 | Single Assignment (SSA) form, there can only be one definition referred to, |
| 1052 | allowing this direct connection. This connection provides the use-def |
| 1053 | information in LLVM.<p> |
| 1054 | |
| 1055 | <!-- _______________________________________________________________________ --> |
| 1056 | </ul><h4><a name="m_User"><hr size=0>Important Public Members of |
| 1057 | the <tt>User</tt> class</h4><ul> |
| 1058 | |
| 1059 | The <tt>User</tt> class exposes the operand list in two ways: through an index |
| 1060 | access interface and through an iterator based interface.<p> |
| 1061 | |
| 1062 | <li><tt>Value *getOperand(unsigned i)</tt><br> |
| 1063 | <tt>unsigned getNumOperands()</tt><p> |
| 1064 | |
| 1065 | These two methods expose the operands of the <tt>User</tt> in a convenient form |
| 1066 | for direct access.<p> |
| 1067 | |
| 1068 | <li><tt>User::op_iterator</tt> - Typedef for iterator over the operand list<br> |
| 1069 | <tt>User::op_const_iterator</tt> |
| 1070 | <tt>use_iterator op_begin()</tt> |
| 1071 | - Get an iterator to the start of the operand list.<br> |
| 1072 | <tt>use_iterator op_end()</tt> |
| 1073 | - Get an iterator to the end of the operand list.<p> |
| 1074 | |
| 1075 | Together, these methods make up the iterator based interface to the operands of |
| 1076 | a <tt>User</tt>.<p> |
| 1077 | |
| 1078 | |
| 1079 | |
| 1080 | <!-- ======================================================================= --> |
| 1081 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1082 | <tr><td> </td><td width="100%"> |
| 1083 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1084 | <a name="Instruction">The <tt>Instruction</tt> class</a> |
| 1085 | </b></font></td></tr></table><ul> |
| 1086 | |
| 1087 | <tt>#include "<a |
| 1088 | href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt></b><br> |
| 1089 | doxygen info: <a href="/doxygen/classInstruction.html">Instruction Class</a><br> |
| 1090 | Superclasses: <a href="#User"><tt>User</tt></a>, <a |
| 1091 | href="#Value"><tt>Value</tt></a><p> |
| 1092 | |
| 1093 | The <tt>Instruction</tt> class is the common base class for all LLVM |
| 1094 | instructions. It provides only a few methods, but is a very commonly used |
| 1095 | class. The primary data tracked by the <tt>Instruction</tt> class itself is the |
| 1096 | opcode (instruction type) and the parent <a |
| 1097 | href="#BasicBlock"><tt>BasicBlock</tt></a> the <tt>Instruction</tt> is embedded |
| 1098 | into. To represent a specific type of instruction, one of many subclasses of |
| 1099 | <tt>Instruction</tt> are used.<p> |
| 1100 | |
| 1101 | Because the <tt>Instruction</tt> class subclasses the <a |
| 1102 | href="#User"><tt>User</tt></a> class, its operands can be accessed in the same |
| 1103 | way as for other <a href="#User"><tt>User</tt></a>s (with the |
| 1104 | <tt>getOperand()</tt>/<tt>getNumOperands()</tt> and |
| 1105 | <tt>op_begin()</tt>/<tt>op_end()</tt> methods).<p> |
| 1106 | |
Chris Lattner | 1763525 | 2002-09-12 17:18:46 +0000 | [diff] [blame] | 1107 | An important file for the <tt>Instruction</tt> class is the |
| 1108 | <tt>llvm/Instruction.def</tt> file. This file contains some meta-data about the |
| 1109 | various different types of instructions in LLVM. It describes the enum values |
| 1110 | that are used as opcodes (for example <tt>Instruction::Add</tt> and |
| 1111 | <tt>Instruction::SetLE</tt>), as well as the concrete sub-classes of |
| 1112 | <tt>Instruction</tt> that implement the instruction (for example <tt><a |
| 1113 | href="#BinaryOperator">BinaryOperator</a></tt> and <tt><a |
| 1114 | href="#SetCondInst">SetCondInst</a></tt>). Unfortunately, the use of macros in |
| 1115 | this file confused doxygen, so these enum values don't show up correctly in the |
| 1116 | <a href="/doxygen/classInstruction.html">doxygen output</a>.<p> |
| 1117 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1118 | |
| 1119 | <!-- _______________________________________________________________________ --> |
| 1120 | </ul><h4><a name="m_Instruction"><hr size=0>Important Public Members of |
| 1121 | the <tt>Instruction</tt> class</h4><ul> |
| 1122 | |
| 1123 | <li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt><p> |
| 1124 | |
| 1125 | Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that this |
| 1126 | <tt>Instruction</tt> is embedded into.<p> |
| 1127 | |
Chris Lattner | c3dc212 | 2003-02-26 16:38:15 +0000 | [diff] [blame] | 1128 | <li><tt>bool mayWriteToMemory()</tt><p> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1129 | |
Chris Lattner | c3dc212 | 2003-02-26 16:38:15 +0000 | [diff] [blame] | 1130 | Returns true if the instruction writes to memory, i.e. it is a <tt>call</tt>, |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1131 | <tt>free</tt>, <tt>invoke</tt>, or <tt>store</tt>.<p> |
| 1132 | |
| 1133 | <li><tt>unsigned getOpcode()</tt><p> |
| 1134 | |
| 1135 | Returns the opcode for the <tt>Instruction</tt>.<p> |
| 1136 | |
Chris Lattner | 1763525 | 2002-09-12 17:18:46 +0000 | [diff] [blame] | 1137 | <li><tt><a href="#Instruction">Instruction</a> *clone() const</tt><p> |
| 1138 | |
| 1139 | Returns another instance of the specified instruction, identical in all ways to |
| 1140 | the original except that the instruction has no parent (ie it's not embedded |
| 1141 | into a <a href="#BasicBlock"><tt>BasicBlock</tt></a>), and it has no name.<p> |
| 1142 | |
| 1143 | |
| 1144 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1145 | <!-- |
| 1146 | |
| 1147 | \subsection{Subclasses of Instruction :} |
| 1148 | \begin{itemize} |
| 1149 | <li>BinaryOperator : This subclass of Instruction defines a general interface to the all the instructions involvong binary operators in LLVM. |
| 1150 | \begin{itemize} |
| 1151 | <li><tt>bool swapOperands()</tt>: Exchange the two operands to this instruction. If the instruction cannot be reversed (i.e. if it's a Div), it returns true. |
| 1152 | \end{itemize} |
| 1153 | <li>TerminatorInst : This subclass of Instructions defines an interface for all instructions that can terminate a BasicBlock. |
| 1154 | \begin{itemize} |
| 1155 | <li> <tt>unsigned getNumSuccessors()</tt>: Returns the number of successors for this terminator instruction. |
| 1156 | <li><tt>BasicBlock *getSuccessor(unsigned i)</tt>: As the name suggests returns the ith successor BasicBlock. |
| 1157 | <li><tt>void setSuccessor(unsigned i, BasicBlock *B)</tt>: sets BasicBlock B as the ith succesor to this terminator instruction. |
| 1158 | \end{itemize} |
| 1159 | |
| 1160 | <li>PHINode : This represents the PHI instructions in the SSA form. |
| 1161 | \begin{itemize} |
| 1162 | <li><tt> unsigned getNumIncomingValues()</tt>: Returns the number of incoming edges to this PHI node. |
| 1163 | <li><tt> Value *getIncomingValue(unsigned i)</tt>: Returns the ith incoming Value. |
| 1164 | <li><tt>void setIncomingValue(unsigned i, Value *V)</tt>: Sets the ith incoming Value as V |
| 1165 | <li><tt>BasicBlock *getIncomingBlock(unsigned i)</tt>: Returns the Basic Block corresponding to the ith incoming Value. |
| 1166 | <li><tt> void addIncoming(Value *D, BasicBlock *BB)</tt>: |
| 1167 | Add an incoming value to the end of the PHI list |
| 1168 | <li><tt> int getBasicBlockIndex(const BasicBlock *BB) const</tt>: |
| 1169 | Returns the first index of the specified basic block in the value list for this PHI. Returns -1 if no instance. |
| 1170 | \end{itemize} |
| 1171 | <li>CastInst : In LLVM all casts have to be done through explicit cast instructions. CastInst defines the interface to the cast instructions. |
| 1172 | <li>CallInst : This defines an interface to the call instruction in LLVM. ARguments to the function are nothing but operands of the instruction. |
| 1173 | \begin{itemize} |
| 1174 | <li>: <tt>Function *getCalledFunction()</tt>: Returns a handle to the function that is being called by this Function. |
| 1175 | \end{itemize} |
| 1176 | <li>LoadInst, StoreInst, GetElemPtrInst : These subclasses represent load, store and getelementptr instructions in LLVM. |
| 1177 | \begin{itemize} |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1178 | <li><tt>Value * getPointerOperand()</tt>: Returns the Pointer Operand which is typically the 0th operand. |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1179 | \end{itemize} |
| 1180 | <li>BranchInst : This is a subclass of TerminatorInst and defines the interface for conditional and unconditional branches in LLVM. |
| 1181 | \begin{itemize} |
| 1182 | <li><tt>bool isConditional()</tt>: Returns true if the branch is a conditional branch else returns false |
| 1183 | <li> <tt>Value *getCondition()</tt>: Returns the condition if it is a conditional branch else returns null. |
| 1184 | <li> <tt>void setUnconditionalDest(BasicBlock *Dest)</tt>: Changes the current branch to an unconditional one targetting the specified block. |
| 1185 | \end{itemize} |
| 1186 | |
| 1187 | \end{itemize} |
| 1188 | |
| 1189 | --> |
| 1190 | |
| 1191 | |
| 1192 | <!-- ======================================================================= --> |
| 1193 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1194 | <tr><td> </td><td width="100%"> |
| 1195 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1196 | <a name="BasicBlock">The <tt>BasicBlock</tt> class</a> |
| 1197 | </b></font></td></tr></table><ul> |
| 1198 | |
| 1199 | <tt>#include "<a |
| 1200 | href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt></b><br> |
| 1201 | doxygen info: <a href="/doxygen/classBasicBlock.html">BasicBlock Class</a><br> |
| 1202 | Superclass: <a href="#Value"><tt>Value</tt></a><p> |
| 1203 | |
| 1204 | |
| 1205 | This class represents a single entry multiple exit section of the code, commonly |
| 1206 | known as a basic block by the compiler community. The <tt>BasicBlock</tt> class |
| 1207 | maintains a list of <a href="#Instruction"><tt>Instruction</tt></a>s, which form |
| 1208 | the body of the block. Matching the language definition, the last element of |
| 1209 | this list of instructions is always a terminator instruction (a subclass of the |
| 1210 | <a href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).<p> |
| 1211 | |
| 1212 | In addition to tracking the list of instructions that make up the block, the |
| 1213 | <tt>BasicBlock</tt> class also keeps track of the <a |
| 1214 | href="#Function"><tt>Function</tt></a> that it is embedded into.<p> |
| 1215 | |
| 1216 | Note that <tt>BasicBlock</tt>s themselves are <a |
| 1217 | href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions |
| 1218 | like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type |
| 1219 | <tt>label</tt>.<p> |
| 1220 | |
| 1221 | |
| 1222 | <!-- _______________________________________________________________________ --> |
| 1223 | </ul><h4><a name="m_BasicBlock"><hr size=0>Important Public Members of |
| 1224 | the <tt>BasicBlock</tt> class</h4><ul> |
| 1225 | |
| 1226 | <li><tt>BasicBlock(const std::string &Name = "", <a |
| 1227 | href="#Function">Function</a> *Parent = 0)</tt><p> |
| 1228 | |
| 1229 | The <tt>BasicBlock</tt> constructor is used to create new basic blocks for |
| 1230 | insertion into a function. The constructor simply takes a name for the new |
| 1231 | block, and optionally a <a href="#Function"><tt>Function</tt></a> to insert it |
| 1232 | into. If the <tt>Parent</tt> parameter is specified, the new |
| 1233 | <tt>BasicBlock</tt> is automatically inserted at the end of the specified <a |
| 1234 | href="#Function"><tt>Function</tt></a>, if not specified, the BasicBlock must be |
| 1235 | manually inserted into the <a href="#Function"><tt>Function</tt></a>.<p> |
| 1236 | |
| 1237 | <li><tt>BasicBlock::iterator</tt> - Typedef for instruction list iterator<br> |
| 1238 | <tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br> |
| 1239 | <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>, |
| 1240 | <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p> |
| 1241 | |
| 1242 | These methods and typedefs are forwarding functions that have the same semantics |
| 1243 | as the standard library methods of the same names. These methods expose the |
| 1244 | underlying instruction list of a basic block in a way that is easy to |
| 1245 | manipulate. To get the full complement of container operations (including |
| 1246 | operations to update the list), you must use the <tt>getInstList()</tt> |
| 1247 | method.<p> |
| 1248 | |
| 1249 | <li><tt>BasicBlock::InstListType &getInstList()</tt><p> |
| 1250 | |
| 1251 | This method is used to get access to the underlying container that actually |
| 1252 | holds the Instructions. This method must be used when there isn't a forwarding |
| 1253 | function in the <tt>BasicBlock</tt> class for the operation that you would like |
| 1254 | to perform. Because there are no forwarding functions for "updating" |
| 1255 | operations, you need to use this if you want to update the contents of a |
| 1256 | <tt>BasicBlock</tt>.<p> |
| 1257 | |
| 1258 | <li><tt><A href="#Function">Function</a> *getParent()</tt><p> |
| 1259 | |
| 1260 | Returns a pointer to <a href="#Function"><tt>Function</tt></a> the block is |
| 1261 | embedded into, or a null pointer if it is homeless.<p> |
| 1262 | |
| 1263 | <li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt><p> |
| 1264 | |
| 1265 | Returns a pointer to the terminator instruction that appears at the end of the |
| 1266 | <tt>BasicBlock</tt>. If there is no terminator instruction, or if the last |
| 1267 | instruction in the block is not a terminator, then a null pointer is |
| 1268 | returned.<p> |
| 1269 | |
| 1270 | |
| 1271 | <!-- ======================================================================= --> |
| 1272 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1273 | <tr><td> </td><td width="100%"> |
| 1274 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1275 | <a name="GlobalValue">The <tt>GlobalValue</tt> class</a> |
| 1276 | </b></font></td></tr></table><ul> |
| 1277 | |
| 1278 | <tt>#include "<a |
| 1279 | href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt></b><br> |
| 1280 | doxygen info: <a href="/doxygen/classGlobalValue.html">GlobalValue Class</a><br> |
| 1281 | Superclasses: <a href="#User"><tt>User</tt></a>, <a |
| 1282 | href="#Value"><tt>Value</tt></a><p> |
| 1283 | |
| 1284 | Global values (<A href="#GlobalVariable"><tt>GlobalVariable</tt></a>s or <a |
| 1285 | href="#Function"><tt>Function</tt></a>s) are the only LLVM values that are |
| 1286 | visible in the bodies of all <a href="#Function"><tt>Function</tt></a>s. |
| 1287 | Because they are visible at global scope, they are also subject to linking with |
| 1288 | other globals defined in different translation units. To control the linking |
| 1289 | process, <tt>GlobalValue</tt>s know their linkage rules. Specifically, |
| 1290 | <tt>GlobalValue</tt>s know whether they have internal or external linkage.<p> |
| 1291 | |
| 1292 | If a <tt>GlobalValue</tt> has internal linkage (equivalent to being |
| 1293 | <tt>static</tt> in C), it is not visible to code outside the current translation |
| 1294 | unit, and does not participate in linking. If it has external linkage, it is |
| 1295 | visible to external code, and does participate in linking. In addition to |
| 1296 | linkage information, <tt>GlobalValue</tt>s keep track of which <a |
| 1297 | href="#Module"><tt>Module</tt></a> they are currently part of.<p> |
| 1298 | |
| 1299 | Because <tt>GlobalValue</tt>s are memory objects, they are always referred to by |
| 1300 | their address. As such, the <a href="#Type"><tt>Type</tt></a> of a global is |
| 1301 | always a pointer to its contents. This is explained in the LLVM Language |
| 1302 | Reference Manual.<p> |
| 1303 | |
| 1304 | |
| 1305 | <!-- _______________________________________________________________________ --> |
| 1306 | </ul><h4><a name="m_GlobalValue"><hr size=0>Important Public Members of |
| 1307 | the <tt>GlobalValue</tt> class</h4><ul> |
| 1308 | |
| 1309 | <li><tt>bool hasInternalLinkage() const</tt><br> |
| 1310 | <tt>bool hasExternalLinkage() const</tt><br> |
| 1311 | <tt>void setInternalLinkage(bool HasInternalLinkage)</tt><p> |
| 1312 | |
| 1313 | These methods manipulate the linkage characteristics of the |
| 1314 | <tt>GlobalValue</tt>.<p> |
| 1315 | |
| 1316 | <li><tt><a href="#Module">Module</a> *getParent()</tt><p> |
| 1317 | |
| 1318 | This returns the <a href="#Module"><tt>Module</tt></a> that the GlobalValue is |
| 1319 | currently embedded into.<p> |
| 1320 | |
| 1321 | |
| 1322 | |
| 1323 | <!-- ======================================================================= --> |
| 1324 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1325 | <tr><td> </td><td width="100%"> |
| 1326 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1327 | <a name="Function">The <tt>Function</tt> class</a> |
| 1328 | </b></font></td></tr></table><ul> |
| 1329 | |
| 1330 | <tt>#include "<a |
| 1331 | href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt></b><br> |
| 1332 | doxygen info: <a href="/doxygen/classFunction.html">Function Class</a><br> |
| 1333 | Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a |
| 1334 | href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a><p> |
| 1335 | |
| 1336 | The <tt>Function</tt> class represents a single procedure in LLVM. It is |
| 1337 | actually one of the more complex classes in the LLVM heirarchy because it must |
| 1338 | keep track of a large amount of data. The <tt>Function</tt> class keeps track |
| 1339 | of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <a |
| 1340 | href="#Argument"><tt>Argument</tt></a>s, and a <a |
| 1341 | href="#SymbolTable"><tt>SymbolTable</tt></a>.<p> |
| 1342 | |
| 1343 | The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most commonly |
| 1344 | used part of <tt>Function</tt> objects. The list imposes an implicit ordering |
| 1345 | of the blocks in the function, which indicate how the code will be layed out by |
| 1346 | the backend. Additionally, the first <a |
| 1347 | href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node for the |
| 1348 | <tt>Function</tt>. It is not legal in LLVM explicitly branch to this initial |
| 1349 | block. There are no implicit exit nodes, and in fact there may be multiple exit |
| 1350 | nodes from a single <tt>Function</tt>. If the <a |
| 1351 | href="#BasicBlock"><tt>BasicBlock</tt></a> list is empty, this indicates that |
| 1352 | the <tt>Function</tt> is actually a function declaration: the actual body of the |
| 1353 | function hasn't been linked in yet.<p> |
| 1354 | |
| 1355 | In addition to a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, the |
| 1356 | <tt>Function</tt> class also keeps track of the list of formal <a |
| 1357 | href="#Argument"><tt>Argument</tt></a>s that the function receives. This |
| 1358 | container manages the lifetime of the <a href="#Argument"><tt>Argument</tt></a> |
| 1359 | nodes, just like the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list does for |
| 1360 | the <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.<p> |
| 1361 | |
| 1362 | The <a href="#SymbolTable"><tt>SymbolTable</tt></a> is a very rarely used LLVM |
| 1363 | feature that is only used when you have to look up a value by name. Aside from |
| 1364 | that, the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is used internally to |
| 1365 | make sure that there are not conflicts between the names of <a |
| 1366 | href="#Instruction"><tt>Instruction</tt></a>s, <a |
| 1367 | href="#BasicBlock"><tt>BasicBlock</tt></a>s, or <a |
| 1368 | href="#Argument"><tt>Argument</tt></a>s in the function body.<p> |
| 1369 | |
| 1370 | |
| 1371 | <!-- _______________________________________________________________________ --> |
| 1372 | </ul><h4><a name="m_Function"><hr size=0>Important Public Members of |
| 1373 | the <tt>Function</tt> class</h4><ul> |
| 1374 | |
| 1375 | <li><tt>Function(const <a href="#FunctionType">FunctionType</a> *Ty, bool isInternal, const std::string &N = "")</tt><p> |
| 1376 | |
| 1377 | Constructor used when you need to create new <tt>Function</tt>s to add the the |
| 1378 | program. The constructor must specify the type of the function to create and |
| 1379 | whether or not it should start out with internal or external linkage.<p> |
| 1380 | |
| 1381 | <li><tt>bool isExternal()</tt><p> |
| 1382 | |
| 1383 | Return whether or not the <tt>Function</tt> has a body defined. If the function |
| 1384 | is "external", it does not have a body, and thus must be resolved by linking |
| 1385 | with a function defined in a different translation unit.<p> |
| 1386 | |
| 1387 | |
| 1388 | <li><tt>Function::iterator</tt> - Typedef for basic block list iterator<br> |
| 1389 | <tt>Function::const_iterator</tt> - Typedef for const_iterator.<br> |
| 1390 | <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>, |
| 1391 | <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p> |
| 1392 | |
| 1393 | These are forwarding methods that make it easy to access the contents of a |
| 1394 | <tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a> |
| 1395 | list.<p> |
| 1396 | |
| 1397 | <li><tt>Function::BasicBlockListType &getBasicBlockList()</tt><p> |
| 1398 | |
| 1399 | Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s. This is |
| 1400 | neccesary to use when you need to update the list or perform a complex action |
| 1401 | that doesn't have a forwarding method.<p> |
| 1402 | |
| 1403 | |
| 1404 | <li><tt>Function::aiterator</tt> - Typedef for the argument list iterator<br> |
| 1405 | <tt>Function::const_aiterator</tt> - Typedef for const_iterator.<br> |
| 1406 | <tt>abegin()</tt>, <tt>aend()</tt>, <tt>afront()</tt>, <tt>aback()</tt>, |
| 1407 | <tt>asize()</tt>, <tt>aempty()</tt>, <tt>arbegin()</tt>, <tt>arend()</tt><p> |
| 1408 | |
| 1409 | These are forwarding methods that make it easy to access the contents of a |
| 1410 | <tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a> list.<p> |
| 1411 | |
| 1412 | <li><tt>Function::ArgumentListType &getArgumentList()</tt><p> |
| 1413 | |
| 1414 | Returns the list of <a href="#Argument"><tt>Argument</tt></a>s. This is |
| 1415 | neccesary to use when you need to update the list or perform a complex action |
| 1416 | that doesn't have a forwarding method.<p> |
| 1417 | |
| 1418 | |
| 1419 | |
| 1420 | <li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryNode()</tt><p> |
| 1421 | |
| 1422 | Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the |
| 1423 | function. Because the entry block for the function is always the first block, |
| 1424 | this returns the first block of the <tt>Function</tt>.<p> |
| 1425 | |
| 1426 | <li><tt><a href="#Type">Type</a> *getReturnType()</tt><br> |
| 1427 | <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt><p> |
| 1428 | |
| 1429 | This traverses the <a href="#Type"><tt>Type</tt></a> of the <tt>Function</tt> |
| 1430 | and returns the return type of the function, or the <a |
| 1431 | href="#FunctionType"><tt>FunctionType</tt></a> of the actual function.<p> |
| 1432 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1433 | <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p> |
| 1434 | |
| 1435 | Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this |
Chris Lattner | 6e6026b | 2002-11-20 18:36:02 +0000 | [diff] [blame] | 1436 | <tt>Function</tt>.<p> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1437 | |
| 1438 | |
| 1439 | |
| 1440 | <!-- ======================================================================= --> |
| 1441 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1442 | <tr><td> </td><td width="100%"> |
| 1443 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1444 | <a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a> |
| 1445 | </b></font></td></tr></table><ul> |
| 1446 | |
| 1447 | <tt>#include "<a |
| 1448 | href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt></b><br> |
| 1449 | doxygen info: <a href="/doxygen/classGlobalVariable.html">GlobalVariable Class</a><br> |
| 1450 | Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a |
| 1451 | href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a><p> |
| 1452 | |
Chris Lattner | 0377de4 | 2002-09-06 14:50:55 +0000 | [diff] [blame] | 1453 | Global variables are represented with the (suprise suprise) |
| 1454 | <tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are |
| 1455 | also subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such |
| 1456 | are always referenced by their address (global values must live in memory, so |
| 1457 | their "name" refers to their address). Global variables may have an initial |
| 1458 | value (which must be a <a href="#Constant"><tt>Constant</tt></a>), and if they |
| 1459 | have an initializer, they may be marked as "constant" themselves (indicating |
| 1460 | that their contents never change at runtime).<p> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1461 | |
| 1462 | |
| 1463 | <!-- _______________________________________________________________________ --> |
Chris Lattner | 0377de4 | 2002-09-06 14:50:55 +0000 | [diff] [blame] | 1464 | </ul><h4><a name="m_GlobalVariable"><hr size=0>Important Public Members of the |
| 1465 | <tt>GlobalVariable</tt> class</h4><ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1466 | |
| 1467 | <li><tt>GlobalVariable(const <a href="#Type">Type</a> *Ty, bool isConstant, bool |
| 1468 | isInternal, <a href="#Constant">Constant</a> *Initializer = 0, const std::string |
| 1469 | &Name = "")</tt><p> |
| 1470 | |
Chris Lattner | 0377de4 | 2002-09-06 14:50:55 +0000 | [diff] [blame] | 1471 | Create a new global variable of the specified type. If <tt>isConstant</tt> is |
| 1472 | true then the global variable will be marked as unchanging for the program, and |
| 1473 | if <tt>isInternal</tt> is true the resultant global variable will have internal |
| 1474 | linkage. Optionally an initializer and name may be specified for the global variable as well.<p> |
| 1475 | |
| 1476 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1477 | <li><tt>bool isConstant() const</tt><p> |
| 1478 | |
| 1479 | Returns true if this is a global variable is known not to be modified at |
| 1480 | runtime.<p> |
| 1481 | |
Chris Lattner | 0377de4 | 2002-09-06 14:50:55 +0000 | [diff] [blame] | 1482 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1483 | <li><tt>bool hasInitializer()</tt><p> |
| 1484 | |
| 1485 | Returns true if this <tt>GlobalVariable</tt> has an intializer.<p> |
| 1486 | |
Chris Lattner | 0377de4 | 2002-09-06 14:50:55 +0000 | [diff] [blame] | 1487 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1488 | <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt><p> |
| 1489 | |
Chris Lattner | 0377de4 | 2002-09-06 14:50:55 +0000 | [diff] [blame] | 1490 | Returns the intial value for a <tt>GlobalVariable</tt>. It is not legal to call |
| 1491 | this method if there is no initializer.<p> |
| 1492 | |
| 1493 | |
| 1494 | <!-- ======================================================================= --> |
| 1495 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1496 | <tr><td> </td><td width="100%"> |
| 1497 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1498 | <a name="Module">The <tt>Module</tt> class</a> |
| 1499 | </b></font></td></tr></table><ul> |
| 1500 | |
| 1501 | <tt>#include "<a |
| 1502 | href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt></b><br> |
| 1503 | doxygen info: <a href="/doxygen/classModule.html">Module Class</a><p> |
| 1504 | |
| 1505 | The <tt>Module</tt> class represents the top level structure present in LLVM |
| 1506 | programs. An LLVM module is effectively either a translation unit of the |
| 1507 | original program or a combination of several translation units merged by the |
| 1508 | linker. The <tt>Module</tt> class keeps track of a list of <a |
| 1509 | href="#Function"><tt>Function</tt></a>s, a list of <a |
| 1510 | href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a |
| 1511 | href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it contains a few |
| 1512 | helpful member functions that try to make common operations easy.<p> |
| 1513 | |
| 1514 | |
| 1515 | <!-- _______________________________________________________________________ --> |
| 1516 | </ul><h4><a name="m_Module"><hr size=0>Important Public Members of the |
| 1517 | <tt>Module</tt> class</h4><ul> |
| 1518 | |
| 1519 | <li><tt>Module::iterator</tt> - Typedef for function list iterator<br> |
| 1520 | <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br> |
| 1521 | <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>, |
| 1522 | <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p> |
| 1523 | |
| 1524 | These are forwarding methods that make it easy to access the contents of a |
| 1525 | <tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a> |
| 1526 | list.<p> |
| 1527 | |
| 1528 | <li><tt>Module::FunctionListType &getFunctionList()</tt><p> |
| 1529 | |
| 1530 | Returns the list of <a href="#Function"><tt>Function</tt></a>s. This is |
| 1531 | neccesary to use when you need to update the list or perform a complex action |
| 1532 | that doesn't have a forwarding method.<p> |
| 1533 | |
| 1534 | <!-- Global Variable --> |
| 1535 | <hr size=0> |
| 1536 | |
| 1537 | <li><tt>Module::giterator</tt> - Typedef for global variable list iterator<br> |
| 1538 | <tt>Module::const_giterator</tt> - Typedef for const_iterator.<br> |
| 1539 | <tt>gbegin()</tt>, <tt>gend()</tt>, <tt>gfront()</tt>, <tt>gback()</tt>, |
| 1540 | <tt>gsize()</tt>, <tt>gempty()</tt>, <tt>grbegin()</tt>, <tt>grend()</tt><p> |
| 1541 | |
| 1542 | These are forwarding methods that make it easy to access the contents of a |
| 1543 | <tt>Module</tt> object's <a href="#GlobalVariable"><tt>GlobalVariable</tt></a> |
| 1544 | list.<p> |
| 1545 | |
| 1546 | <li><tt>Module::GlobalListType &getGlobalList()</tt><p> |
| 1547 | |
| 1548 | Returns the list of <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s. |
| 1549 | This is neccesary to use when you need to update the list or perform a complex |
| 1550 | action that doesn't have a forwarding method.<p> |
| 1551 | |
| 1552 | |
| 1553 | <!-- Symbol table stuff --> |
| 1554 | <hr size=0> |
| 1555 | |
Chris Lattner | 0377de4 | 2002-09-06 14:50:55 +0000 | [diff] [blame] | 1556 | <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p> |
| 1557 | |
Chris Lattner | 6e6026b | 2002-11-20 18:36:02 +0000 | [diff] [blame] | 1558 | Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for |
| 1559 | this <tt>Module</tt>.<p> |
Chris Lattner | 0377de4 | 2002-09-06 14:50:55 +0000 | [diff] [blame] | 1560 | |
| 1561 | |
| 1562 | <!-- Convenience methods --> |
| 1563 | <hr size=0> |
| 1564 | |
| 1565 | <li><tt><a href="#Function">Function</a> *getFunction(const std::string &Name, const <a href="#FunctionType">FunctionType</a> *Ty)</tt><p> |
| 1566 | |
| 1567 | Look up the specified function in the <tt>Module</tt> <a |
| 1568 | href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return |
| 1569 | <tt>null</tt>.<p> |
| 1570 | |
| 1571 | |
| 1572 | <li><tt><a href="#Function">Function</a> *getOrInsertFunction(const std::string |
| 1573 | &Name, const <a href="#FunctionType">FunctionType</a> *T)</tt><p> |
| 1574 | |
| 1575 | Look up the specified function in the <tt>Module</tt> <a |
| 1576 | href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an |
| 1577 | external declaration for the function and return it.<p> |
| 1578 | |
| 1579 | |
| 1580 | <li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt><p> |
| 1581 | |
| 1582 | If there is at least one entry in the <a |
| 1583 | href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a |
| 1584 | href="#Type"><tt>Type</tt></a>, return it. Otherwise return the empty |
| 1585 | string.<p> |
| 1586 | |
| 1587 | |
| 1588 | <li><tt>bool addTypeName(const std::string &Name, const <a href="#Type">Type</a> |
| 1589 | *Ty)</tt><p> |
| 1590 | |
| 1591 | Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a> mapping |
| 1592 | <tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this name, true |
| 1593 | is returned and the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is not |
| 1594 | modified.<p> |
| 1595 | |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1596 | |
| 1597 | <!-- ======================================================================= --> |
| 1598 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1599 | <tr><td> </td><td width="100%"> |
| 1600 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1601 | <a name="Constant">The <tt>Constant</tt> class and subclasses</a> |
| 1602 | </b></font></td></tr></table><ul> |
| 1603 | |
| 1604 | Constant represents a base class for different types of constants. It is |
| 1605 | subclassed by ConstantBool, ConstantInt, ConstantSInt, ConstantUInt, |
| 1606 | ConstantArray etc for representing the various types of Constants.<p> |
| 1607 | |
| 1608 | |
| 1609 | <!-- _______________________________________________________________________ --> |
| 1610 | </ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul> |
| 1611 | |
| 1612 | <li><tt>bool isConstantExpr()</tt>: Returns true if it is a ConstantExpr |
| 1613 | |
| 1614 | |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1615 | <hr> |
| 1616 | Important Subclasses of Constant<p> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1617 | |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1618 | <ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1619 | <li>ConstantSInt : This subclass of Constant represents a signed integer constant. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1620 | <ul> |
| 1621 | <li><tt>int64_t getValue() const</tt>: Returns the underlying value of this constant. |
| 1622 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1623 | <li>ConstantUInt : This class represents an unsigned integer. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1624 | <ul> |
| 1625 | <li><tt>uint64_t getValue() const</tt>: Returns the underlying value of this constant. |
| 1626 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1627 | <li>ConstantFP : This class represents a floating point constant. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1628 | <ul> |
| 1629 | <li><tt>double getValue() const</tt>: Returns the underlying value of this constant. |
| 1630 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1631 | <li>ConstantBool : This represents a boolean constant. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1632 | <ul> |
| 1633 | <li><tt>bool getValue() const</tt>: Returns the underlying value of this constant. |
| 1634 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1635 | <li>ConstantArray : This represents a constant array. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1636 | <ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1637 | <li><tt>const std::vector<Use> &getValues() const</tt>: Returns a Vecotr of component constants that makeup this array. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1638 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1639 | <li>ConstantStruct : This represents a constant struct. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1640 | <ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1641 | <li><tt>const std::vector<Use> &getValues() const</tt>: Returns a Vecotr of component constants that makeup this array. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1642 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1643 | <li>ConstantPointerRef : This represents a constant pointer value that is initialized to point to a global value, which lies at a constant fixed address. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1644 | <ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1645 | <li><tt>GlobalValue *getValue()</tt>: Returns the global value to which this pointer is pointing to. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1646 | </ul> |
| 1647 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1648 | |
| 1649 | |
| 1650 | <!-- ======================================================================= --> |
| 1651 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1652 | <tr><td> </td><td width="100%"> |
| 1653 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1654 | <a name="Type">The <tt>Type</tt> class and Derived Types</a> |
| 1655 | </b></font></td></tr></table><ul> |
| 1656 | |
| 1657 | Type as noted earlier is also a subclass of a Value class. Any primitive |
| 1658 | type (like int, short etc) in LLVM is an instance of Type Class. All |
| 1659 | other types are instances of subclasses of type like FunctionType, |
| 1660 | ArrayType etc. DerivedType is the interface for all such dervied types |
| 1661 | including FunctionType, ArrayType, PointerType, StructType. Types can have |
| 1662 | names. They can be recursive (StructType). There exists exactly one instance |
| 1663 | of any type structure at a time. This allows using pointer equality of Type *s for comparing types. |
| 1664 | |
| 1665 | <!-- _______________________________________________________________________ --> |
| 1666 | </ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul> |
| 1667 | |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1668 | <li><tt>PrimitiveID getPrimitiveID() const</tt>: Returns the base type of the type. |
| 1669 | <li><tt> bool isSigned() const</tt>: Returns whether an integral numeric type is signed. This is true for SByteTy, ShortTy, IntTy, LongTy. Note that this is not true for Float and Double. |
| 1670 | <li><tt>bool isUnsigned() const</tt>: Returns whether a numeric type is unsigned. This is not quite the complement of isSigned... nonnumeric types return false as they do with isSigned. This returns true for UByteTy, UShortTy, UIntTy, and ULongTy. |
| 1671 | <li><tt> bool isInteger() const</tt>: Equilivent to isSigned() || isUnsigned(), but with only a single virtual function invocation. |
| 1672 | <li><tt>bool isIntegral() const</tt>: Returns true if this is an integral type, which is either Bool type or one of the Integer types. |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1673 | |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1674 | <li><tt>bool isFloatingPoint()</tt>: Return true if this is one of the two floating point types. |
| 1675 | <li><tt>bool isRecursive() const</tt>: Returns rue if the type graph contains a cycle. |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1676 | <li><tt>isLosslesslyConvertableTo (const Type *Ty) const</tt>: Return true if this type can be converted to 'Ty' without any reinterpretation of bits. For example, uint to int. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1677 | <li><tt>bool isPrimitiveType() const</tt>: Returns true if it is a primitive type. |
| 1678 | <li><tt>bool isDerivedType() const</tt>: Returns true if it is a derived type. |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1679 | <li><tt>const Type * getContainedType (unsigned i) const</tt>: |
| 1680 | This method is used to implement the type iterator. For derived types, this returns the types 'contained' in the derived type, returning 0 when 'i' becomes invalid. This allows the user to iterate over the types in a struct, for example, really easily. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1681 | <li><tt>unsigned getNumContainedTypes() const</tt>: Return the number of types in the derived type. |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1682 | |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1683 | <p> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1684 | |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1685 | <hr> |
| 1686 | Derived Types<p> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1687 | |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1688 | <ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1689 | <li>SequentialType : This is subclassed by ArrayType and PointerType |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1690 | <ul> |
| 1691 | <li><tt>const Type * getElementType() const</tt>: Returns the type of each of the elements in the sequential type. |
| 1692 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1693 | <li>ArrayType : This is a subclass of SequentialType and defines interface for array types. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1694 | <ul> |
| 1695 | <li><tt>unsigned getNumElements() const</tt>: Returns the number of elements in the array. |
| 1696 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1697 | <li>PointerType : Subclass of SequentialType for pointer types. |
| 1698 | <li>StructType : subclass of DerivedTypes for struct types |
| 1699 | <li>FunctionType : subclass of DerivedTypes for function types. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1700 | |
| 1701 | <ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1702 | |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1703 | <li><tt>bool isVarArg() const</tt>: Returns true if its a vararg function |
| 1704 | <li><tt> const Type * getReturnType() const</tt>: Returns the return type of the function. |
| 1705 | <li><tt> const ParamTypes &getParamTypes() const</tt>: Returns a vector of parameter types. |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1706 | <li><tt>const Type * getParamType (unsigned i)</tt>: Returns the type of the ith parameter. |
Chris Lattner | c75ff9a | 2002-10-01 23:17:09 +0000 | [diff] [blame] | 1707 | <li><tt> const unsigned getNumParams() const</tt>: Returns the number of formal parameters. |
| 1708 | </ul> |
| 1709 | </ul> |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1710 | |
| 1711 | |
| 1712 | |
| 1713 | |
| 1714 | <!-- ======================================================================= --> |
| 1715 | </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0> |
| 1716 | <tr><td> </td><td width="100%"> |
| 1717 | <font color="#EEEEFF" face="Georgia,Palatino"><b> |
| 1718 | <a name="Argument">The <tt>Argument</tt> class</a> |
| 1719 | </b></font></td></tr></table><ul> |
| 1720 | |
| 1721 | This subclass of Value defines the interface for incoming formal arguments to a |
| 1722 | function. A Function maitanis a list of its formal arguments. An argument has a |
| 1723 | pointer to the parent Function. |
| 1724 | |
| 1725 | |
| 1726 | |
| 1727 | |
| 1728 | <!-- *********************************************************************** --> |
| 1729 | </ul> |
| 1730 | <!-- *********************************************************************** --> |
| 1731 | |
| 1732 | <hr><font size-1> |
| 1733 | <address>By: <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and |
| 1734 | <a href="mailto:sabre@nondot.org">Chris Lattner</a></address> |
| 1735 | <!-- Created: Tue Aug 6 15:00:33 CDT 2002 --> |
| 1736 | <!-- hhmts start --> |
Chris Lattner | 6a54710 | 2003-04-23 16:26:15 +0000 | [diff] [blame] | 1737 | Last modified: Wed Apr 23 11:21:57 CDT 2003 |
Chris Lattner | 9355b47 | 2002-09-06 02:50:58 +0000 | [diff] [blame] | 1738 | <!-- hhmts end --> |
| 1739 | </font></body></html> |