docs/ProgrammersManual.html

   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
   6 <table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
   7 <tr><td>&nbsp; <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>
  15     <li><a href="#isa">The <tt>isa&lt;&gt;</tt>, <tt>cast&lt;&gt;</tt> and
  16                        <tt>dyn_cast&lt;&gt;</tt> templates</a>
  17   </ul>
  18   <li><a href="#common">Helpful Hints for Common Operations</a>
  19   <ul>
  20     <li><a href="#inspection">Basic Inspection and Traversal Routines</a>
  21     <ul>
  22       <li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s
  23                                        in a <tt>Function</tt></a>
  24       <li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s
  25                                        in a <tt>BasicBlock</tt></a>
  26       <li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s
  27                                        in a <tt>Function</tt></a>
  28       <li><a href="#iterate_convert">Turning an iterator into a class
  29                                         pointer</a>
  30       <li><a href="#iterate_complex">Finding call sites: a more complex
  31                                         example</a>
  32       <li><a href="#iterate_chains">Iterating over def-use &amp; use-def
  33                                     chains</a>
  34     </ul>
  35     <li><a href="#simplechanges">Making simple changes</a>
  36     <ul>
  37       <li>Creating and inserting new <tt>Instruction</tt>s
  38       <li>Deleting <tt>Instruction</tt>s
  39       <li>Replacing an <tt>Instruction</tt> with another <tt>Value</tt>
  40     </ul>
  41 <!--
  42     <li>Working with the Control Flow Graph
  43     <ul>
  44       <li>Accessing predecessors and successors of a <tt>BasicBlock</tt>
  45       <li>
  46       <li>
  47     </ul>
  48     <li>Useful LLVM APIs
  49     <ul>
  50       <li>The general graph API
  51       <li>The <tt>InstVisitor</tt> template
  52       <li>The DEBUG() macro
  53       <li>The <tt>Statistic</tt> template
  54 -->
  55     </ul>
  56 <!--
  57     <li>Useful related topics
  58     <ul>
  59       <li>The <tt>-time-passes</tt> option
  60       <li>How to use the LLVM Makefile system
  61       <li>How to write a regression test
  62       <li>
  63     </ul>
  64 -->
  65   </ul>
  66   <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
  67   <ul>
  68     <li><a href="#Value">The <tt>Value</tt> class</a>
  69     <ul>
  70       <li><a href="#User">The <tt>User</tt> class</a>
  71       <ul>
  72         <li><a href="#Instruction">The <tt>Instruction</tt> class</a>
  73         <ul>
  74         <li>
  75         </ul>
  76         <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a>
  77         <ul>
  78           <li><a href="#BasicBlock">The <tt>BasicBlock</tt> class</a>
  79           <li><a href="#Function">The <tt>Function</tt> class</a>
  80           <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a>
  81         </ul>
  82         <li><a href="#Module">The <tt>Module</tt> class</a>
  83         <li><a href="#Constant">The <tt>Constant</tt> class</a>
  84         <ul>
  85         <li>
  86         <li>
  87         </ul>
  88       </ul>
  89       <li><a href="#Type">The <tt>Type</tt> class</a>
  90       <li><a href="#Argument">The <tt>Argument</tt> class</a>
  91     </ul>
  92     <li>The <tt>SymbolTable</tt> class
  93     <li>The <tt>ilist</tt> and <tt>iplist</tt> classes
  94     <ul>
  95       <li>Creating, inserting, moving and deleting from LLVM lists
  96     </ul>
  97     <li>Important iterator invalidation semantics to be aware of
  98   </ul>
  99
 100   <p><b>Written by <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>
 101       <a href="mailto:sabre@nondot.org">Chris Lattner</a>, and
 102       <a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a></b><p>
 103 </ol>
 104
 105
 106 <!-- *********************************************************************** -->
 107 <table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 108 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 109 <a name="introduction">Introduction
 110 </b></font></td></tr></table><ul>
 111 <!-- *********************************************************************** -->
 112
 113 This document is meant to highlight some of the important classes and interfaces
 114 available in the LLVM source-base.  This manual is not intended to explain what
 115 LLVM is, how it works, and what LLVM code looks like.  It assumes that you know
 116 the basics of LLVM and are interested in writing transformations or otherwise
 117 analyzing or manipulating the code.<p>
 118
 119 This document should get you oriented so that you can find your way in the
 120 continuously growing source code that makes up the LLVM infrastructure.  Note
 121 that this manual is not intended to serve as a replacement for reading the
 122 source code, so if you think there should be a method in one of these classes to
 123 do something, but it's not listed, check the source.  Links to the <a
 124 href="/doxygen/">doxygen</a> sources are provided to make this as easy as
 125 possible.<p>
 126
 127 The first section of this document describes general information that is useful
 128 to know when working in the LLVM infrastructure, and the second describes the
 129 Core LLVM classes.  In the future this manual will be extended with information
 130 describing how to use extension libraries, such as dominator information, CFG
 131 traversal routines, and useful utilities like the <tt><a
 132 href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> template.<p>
 133
 134
 135 <!-- *********************************************************************** -->
 136 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 137 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 138 <a name="general">General Information
 139 </b></font></td></tr></table><ul>
 140 <!-- *********************************************************************** -->
 141
 142 This section contains general information that is useful if you are working in
 143 the LLVM source-base, but that isn't specific to any particular API.<p>
 144
 145
 146 <!-- ======================================================================= -->
 147 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 148 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 149 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 150 <a name="stl">The C++ Standard Template Library</a>
 151 </b></font></td></tr></table><ul>
 152
 153 LLVM makes heavy use of the C++ Standard Template Library (STL), perhaps much
 154 more than you are used to, or have seen before.  Because of this, you might want
 155 to do a little background reading in the techniques used and capabilities of the
 156 library.  There are many good pages that discuss the STL, and several books on
 157 the subject that you can get, so it will not be discussed in this document.<p>
 158
 159 Here are some useful links:<p>
 160 <ol>
 161 <li><a href="http://www.dinkumware.com/htm_cpl/index.html">Dinkumware C++
 162 Library reference</a> - an excellent reference for the STL and other parts of
 163 the standard C++ library.<br>
 164
 165 <li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently Asked
 166 Questions</a>
 167
 168 <li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's Guide</a> -
 169 Contains a useful <a
 170 href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction to the
 171 STL</a>.
 172
 173 <li><a href="http://www.research.att.com/~bs/C++.html">Bjarne Stroustrup's C++
 174 Page</a>
 175
 176 </ol><p>
 177
 178 You are also encouraged to take a look at the <a
 179 href="CodingStandards.html">LLVM Coding Standards</a> guide which focuses on how
 180 to write maintainable code more than where to put your curly braces.<p>
 181
 182
 183 <!-- ======================================================================= -->
 184 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 185 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 186 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 187 <a name="isa">The isa&lt;&gt;, cast&lt;&gt; and dyn_cast&lt;&gt; templates</a>
 188 </b></font></td></tr></table><ul>
 189
 190
 191
 192
 193
 194
 195 <!-- *********************************************************************** -->
 196 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 197 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 198 <a name="common">Helpful Hints for Common Operations
 199 </b></font></td></tr></table><ul>
 200 <!-- *********************************************************************** -->
 201
 202 This section describes how to perform some very simple transformations of LLVM
 203 code.  This is meant to give examples of common idioms used, showing the
 204 practical side of LLVM transformations.<p>
 205
 206 Because this is a "how-to" section, you should also read about the main classes
 207 that you will be working with.  The <a href="#coreclasses">Core LLVM Class
 208 Hierarchy Reference</a> contains details and descriptions of the main classes
 209 that you should know about.<p>
 210
 211 <!-- NOTE: this section should be heavy on example code -->
 212
 213
 214 <!-- ======================================================================= -->
 215 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 216 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 217 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 218 <a name="inspection">Basic Inspection and Traversal Routines</a>
 219 </b></font></td></tr></table><ul>
 220
 221 The LLVM compiler infrastructure have many different data structures that may be
 222 traversed.  Following the example of the C++ standard template library, the
 223 techniques used to traverse these various data structures are all basically the
 224 same.  For a enumerable sequence of values, the <tt>XXXbegin()</tt> function (or
 225 method) returns an iterator to the start of the sequence, the <tt>XXXend()</tt>
 226 function returns an iterator pointing to one past the last valid element of the
 227 sequence, and there is some <tt>XXXiterator</tt> data type that is common
 228 between the two operations.<p>
 229
 230 Because the pattern for iteration is common across many different aspects of the
 231 program representation, the standard template library algorithms may be used on
 232 them, and it is easier to remember how to iterate.  First we show a few common
 233 examples of the data structures that need to be traversed.  Other data
 234 structures are traversed in very similar ways.<p>
 235
 236
 237 <!-- _______________________________________________________________________ -->
 238 </ul><h4><a name="iterate_function"><hr size=0>Iterating over the <a
 239 href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a
 240 href="#Function"><tt>Function</tt></a> </h4><ul>
 241
 242 It's quite common to have a <tt>Function</tt> instance that you'd like
 243 to transform in some way; in particular, you'd like to manipulate its
 244 <tt>BasicBlock</tt>s.  To facilitate this, you'll need to iterate over
 245 all of the <tt>BasicBlock</tt>s that constitute the <tt>Function</tt>.
 246 The following is an example that prints the name of a
 247 <tt>BasicBlock</tt> and the number of <tt>Instruction</tt>s it
 248 contains:
 249
 250 <pre>
 251   // func is a pointer to a Function instance
 252   for(Function::iterator i = func->begin(), e = func->end(); i != e; ++i) {
 253
 254       // print out the name of the basic block if it has one, and then the
 255       // number of instructions that it contains
 256
 257       cerr &lt;&lt "Basic block (name=" &lt;&lt i-&gt;getName() &lt;&lt; ") has "
 258            &lt;&lt i-&gt;size() &lt;&lt " instructions.\n";
 259   }
 260 </pre>
 261
 262 Note that i can be used as if it were a pointer for the purposes of
 263 invoking member functions of the <tt>Instruction</tt> class.  This is
 264 because the indirection operator is overloaded for the iterator
 265 classes.  In the above code, the expression <tt>i->size()</tt> is
 266 exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.
 267
 268 <!-- _______________________________________________________________________ -->
 269 </ul><h4><a name="iterate_basicblock"><hr size=0>Iterating over the <a
 270 href="#Instruction"><tt>Instruction</tt></a>s in a <a
 271 href="#BasicBlock"><tt>BasicBlock</tt></a> </h4><ul>
 272
 273 Just like when dealing with <tt>BasicBlock</tt>s in
 274 <tt>Function</tt>s, it's easy to iterate over the individual
 275 instructions that make up <tt>BasicBlock</tt>s.  Here's a code snippet
 276 that prints out each instruction in a <tt>BasicBlock</tt>:
 277
 278 <pre>
 279   // blk is a pointer to a BasicBlock instance
 280   for(BasicBlock::iterator i = blk-&gt;begin(), e = blk-&gt;end(); i != e; ++i)
 281      // the next statement works since operator&lt;&lt;(ostream&amp;,...)
 282      // is overloaded for Instruction&amp;
 283      cerr &lt;&lt; *i &lt;&lt; "\n";
 284 </pre>
 285
 286 However, this isn't really the best way to print out the contents of a
 287 <tt>BasicBlock</tt>!  Since the ostream operators are overloaded for
 288 virtually anything you'll care about, you could have just invoked the
 289 print routine on the basic block itself: <tt>cerr &lt;&lt; *blk &lt;&lt;
 290 "\n";</tt>.<p>
 291
 292 Note that currently operator&lt;&lt; is implemented for <tt>Value*</tt>, so it
 293 will print out the contents of the pointer, instead of
 294 the pointer value you might expect.  This is a deprecated interface that will
 295 be removed in the future, so it's best not to depend on it.  To print out the
 296 pointer value for now, you must cast to <tt>void*</tt>.<p>
 297
 298
 299 <!-- _______________________________________________________________________ -->
 300 </ul><h4><a name="iterate_institer"><hr size=0>Iterating over the <a
 301 href="#Instruction"><tt>Instruction</tt></a>s in a <a
 302 href="#Function"><tt>Function</tt></a></h4><ul>
 303
 304 If you're finding that you commonly iterate over a <tt>Function</tt>'s
 305 <tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s
 306 <tt>Instruction</tt>s, <tt>InstIterator</tt> should be used instead.
 307 You'll need to include <a href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>, and then
 308 instantiate <tt>InstIterator</tt>s explicitly in your code.  Here's a
 309 small example that shows how to dump all instructions in a function to
 310 stderr (<b>Note:</b> Dereferencing an <tt>InstIterator</tt> yields an
 311 <tt>Instruction*</tt>, <i>not</i> an <tt>Instruction&amp</tt>!):
 312
 313 <pre>
 314 #include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"
 315 ...
 316 // Suppose F is a ptr to a function
 317 for(inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
 318   cerr &lt;&lt **i &lt;&lt "\n";
 319 </pre>
 320
 321 Easy, isn't it?  You can also use <tt>InstIterator</tt>s to fill a
 322 worklist with its initial contents.  For example, if you wanted to
 323 initialize a worklist to contain all instructions in a
 324 <tt>Function</tt> F, all you would need to do is something like:
 325
 326 <pre>
 327 std::set&lt;Instruction*&gt worklist;
 328 worklist.insert(inst_begin(F), inst_end(F));
 329 </pre>
 330
 331 The STL set <tt>worklist</tt> would now contain all instructions in
 332 the <tt>Function</tt> pointed to by F.
 333
 334 <!-- _______________________________________________________________________ -->
 335 </ul><h4><a name="iterate_convert"><hr size=0>Turning an iterator into a class
 336 pointer (and vice-versa) </h4><ul>
 337
 338 Sometimes, it'll be useful to grab a reference (or pointer) to a class
 339 instance when all you've got at hand is an iterator.  Well, extracting
 340 a reference or a pointer from an iterator is very straightforward.
 341 Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and
 342 <tt>j</tt> is a <tt>BasicBlock::const_iterator</tt>:
 343
 344 <pre>
 345     Instruction&amp; inst = *i;   // grab reference to instruction reference
 346     Instruction* pinst = &amp;*i; // grab pointer to instruction reference
 347     const Instruction&amp; inst = *j;
 348 </pre>
 349 However, the iterators you'll be working with in the LLVM framework
 350 are special: they will automatically convert to a ptr-to-instance type
 351 whenever they need to.  Instead of dereferencing the iterator and then
 352 taking the address of the result, you can simply assign the iterator
 353 to the proper pointer type and you get the dereference and address-of
 354 operation as a result of the assignment (behind the scenes, this is a
 355 result of overloading casting mechanisms).  Thus the last line of the
 356 last example,
 357
 358 <pre>Instruction* pinst = &amp;*i;</pre>
 359
 360 is semantically equivalent to
 361
 362 <pre>Instruction* pinst = i;</pre>
 363
 364 <b>Caveat emptor</b>: The above syntax works <i>only</i> when you're
 365 <i>not</i> working with <tt>dyn_cast</tt>.  The template definition of
 366 <tt>dyn_cast</tt> isn't implemented to handle this yet, so you'll
 367 still need the following in order for things to work properly:
 368
 369 <pre>
 370 BasicBlock::iterator bbi = ...;
 371 <a href="#BranchInst">BranchInst</a>* b = <a href="#isa">dyn_cast</a>&lt;<a href="#BranchInst">BranchInst</a>&gt;(&amp;*bbi);
 372 </pre>
 373
 374 It's also possible to turn a class pointer into the corresponding
 375 iterator.  Usually, this conversion is quite inexpensive.  The
 376 following code snippet illustrates use of the conversion constructors
 377 provided by LLVM iterators.  By using these, you can explicitly grab
 378 the iterator of something without actually obtaining it via iteration
 379 over some structure:
 380
 381 <pre>
 382 void printNextInstruction(Instruction* inst) {
 383     BasicBlock::iterator it(inst);
 384     ++it; // after this line, it refers to the instruction after *inst.
 385     if(it != inst-&gt;getParent()->end()) cerr &lt;&lt; *it &lt;&lt; "\n";
 386 }
 387 </pre>
 388 Of course, this example is strictly pedagogical, because it'd be much
 389 better to explicitly grab the next instruction directly from inst.
 390
 391 <!--   dereferenced iterator = Class &
 392        iterators have converting constructor for 'Class *'
 393        iterators automatically convert to 'Class *' except in dyn_cast<> case
 394  -->
 395
 396 <!--_______________________________________________________________________-->
 397 </ul><h4><a name="iterate_complex"><hr size=0>Finding call sites: a slightly
 398 more complex example </h4><ul>
 399
 400 Say that you're writing a FunctionPass and would like to count all the
 401 locations in the entire module (that is, across every
 402 <tt>Function</tt>) where a certain function (i.e. some
 403 <tt>Function</tt>*) already in scope.  As you'll learn later, you may
 404 want to use an <tt>InstVisitor</tt> to accomplish this in a much more
 405 straightforward manner, but this example will allow us to explore how
 406 you'd do it if you didn't have <tt>InstVisitor</tt> around.  In
 407 pseudocode, this is what we want to do:
 408
 409 <pre>
 410 initialize callCounter to zero
 411 for each Function f in the Module
 412     for each BasicBlock b in f
 413       for each Instruction i in b
 414         if(i is a CallInst and calls the given function)
 415           increment callCounter
 416 </pre>
 417
 418 And the actual code is (remember, since we're writing a
 419 <tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply
 420 has to override the <tt>runOnFunction</tt> method...):
 421
 422 <pre>
 423
 424 Function* targetFunc = ...;
 425
 426 class OurFunctionPass : public FunctionPass {
 427   public:
 428     OurFunctionPass(): callCounter(0) { }
 429
 430     virtual runOnFunction(Function&amp; F) {
 431         for(Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
 432             for(BasicBlock::iterator i = b-&gt;begin(); ie = b-&gt;end(); i != ie; ++i) {
 433                 if (<a href="#CallInst">CallInst</a>* callInst = dyn_cast&lt;<a href="#CallInst">CallInst</a>&gt;(&amp;*inst)) {
 434                     // we know we've encountered a call instruction, so we
 435                     // need to determine if it's a call to the
 436                     // function pointed to by m_func or not.
 437
 438                     if(callInst-&gt;getCalledFunction() == targetFunc)
 439                         ++callCounter;
 440             }
 441         }
 442     }
 443
 444   private:
 445     unsigned  callCounter;
 446 };
 447 </pre>
 448
 449 <!--_______________________________________________________________________-->
 450 </ul><h4><a name="iterate_chains"><hr size=0>Iterating over def-use &amp;
 451 use-def chains</h4><ul>
 452
 453 <!--
 454   def-use chains ("finding all users of"): Value::use_begin/use_end
 455   use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
 456 -->
 457
 458 <!-- ======================================================================= -->
 459 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 460 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 461 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 462 <a name="simplechanges">Making simple changes</a>
 463 </b></font></td></tr></table><ul>
 464
 465 <!-- Value::replaceAllUsesWith
 466      User::replaceUsesOfWith
 467   Point out: include/llvm/Transforms/Utils/
 468     especially BasicBlockUtils.h with:
 469          ReplaceInstWithValue, ReplaceInstWithInst
 470
 471 -->
 472
 473
 474 <!-- *********************************************************************** -->
 475 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 476 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 477 <a name="coreclasses">The Core LLVM Class Hierarchy Reference
 478 </b></font></td></tr></table><ul>
 479 <!-- *********************************************************************** -->
 480
 481 The Core LLVM classes are the primary means of representing the program being
 482 inspected or transformed.  The core LLVM classes are defined in header files in
 483 the <tt>include/llvm/</tt> directory, and implemented in the <tt>lib/VMCore</tt>
 484 directory.<p>
 485
 486
 487 <!-- ======================================================================= -->
 488 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 489 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 490 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 491 <a name="Value">The <tt>Value</tt> class</a>
 492 </b></font></td></tr></table><ul>
 493
 494 <tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt></b><br>
 495 doxygen info: <a href="/doxygen/classValue.html">Value Class</a><p>
 496
 497
 498 The <tt>Value</tt> class is the most important class in LLVM Source base.  It
 499 represents a typed value that may be used (among other things) as an operand to
 500 an instruction.  There are many different types of <tt>Value</tt>s, such as <a
 501 href="#Constant"><tt>Constant</tt></a>s, <a
 502 href="#Argument"><tt>Argument</tt></a>s, and even <a
 503 href="#Instruction"><tt>Instruction</tt></a>s and <a
 504 href="#Function"><tt>Function</tt></a>s are <tt>Value</tt>s.<p>
 505
 506 A particular <tt>Value</tt> may be used many times in the LLVM representation
 507 for a program.  For example, an incoming argument to a function (represented
 508 with an instance of the <a href="#Argument">Argument</a> class) is "used" by
 509 every instruction in the function that references the argument.  To keep track
 510 of this relationship, the <tt>Value</tt> class keeps a list of all of the <a
 511 href="#User"><tt>User</tt></a>s that is using it (the <a
 512 href="#User"><tt>User</tt></a> class is a base class for all nodes in the LLVM
 513 graph that can refer to <tt>Value</tt>s).  This use list is how LLVM represents
 514 def-use information in the program, and is accessible through the <tt>use_</tt>*
 515 methods, shown below.<p>
 516
 517 Because LLVM is a typed representation, every LLVM <tt>Value</tt> is typed, and
 518 this <a href="#Type">Type</a> is available through the <tt>getType()</tt>
 519 method.  <a name="#nameWarning">In addition, all LLVM values can be named.  The
 520 "name" of the <tt>Value</tt> is symbolic string printed in the LLVM code:<p>
 521
 522 <pre>
 523    %<b>foo</b> = add int 1, 2
 524 </pre>
 525
 526 The name of this instruction is "foo".  <b>NOTE</b> that the name of any value
 527 may be missing (an empty string), so names should <b>ONLY</b> be used for
 528 debugging (making the source code easier to read, debugging printouts), they
 529 should not be used to keep track of values or map between them.  For this
 530 purpose, use a <tt>std::map</tt> of pointers to the <tt>Value</tt> itself
 531 instead.<p>
 532
 533 One important aspect of LLVM is that there is no distinction between an SSA
 534 variable and the operation that produces it.  Because of this, any reference to
 535 the value produced by an instruction (or the value available as an incoming
 536 argument, for example) is represented as a direct pointer to the class that
 537 represents this value.  Although this may take some getting used to, it
 538 simplifies the representation and makes it easier to manipulate.<p>
 539
 540
 541 <!-- _______________________________________________________________________ -->
 542 </ul><h4><a name="m_Value"><hr size=0>Important Public Members of
 543 the <tt>Value</tt> class</h4><ul>
 544
 545 <li><tt>Value::use_iterator</tt> - Typedef for iterator over the use-list<br>
 546     <tt>Value::use_const_iterator</tt>
 547                  - Typedef for const_iterator over the use-list<br>
 548     <tt>unsigned use_size()</tt> - Returns the number of users of the value.<br>
 549     <tt>bool use_empty()</tt> - Returns true if there are no users.<br>
 550     <tt>use_iterator use_begin()</tt>
 551                  - Get an iterator to the start of the use-list.<br>
 552     <tt>use_iterator use_end()</tt>
 553                  - Get an iterator to the end of the use-list.<br>
 554     <tt><a href="#User">User</a> *use_back()</tt>
 555                  - Returns the last element in the list.<p>
 556
 557 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>
 558
 559 <li><tt><a href="#Type">Type</a> *getType() const</tt><p>
 560 This method returns the Type of the Value.
 561
 562 <li><tt>bool hasName() const</tt><br>
 563     <tt>std::string getName() const</tt><br>
 564     <tt>void setName(const std::string &amp;Name)</tt><p>
 565
 566 This family of methods is used to access and assign a name to a <tt>Value</tt>,
 567 be aware of the <a href="#nameWarning">precaution above</a>.<p>
 568
 569
 570 <li><tt>void replaceAllUsesWith(Value *V)</tt><p>
 571
 572 This method traverses the use list of a <tt>Value</tt> changing all <a
 573 href="#User"><tt>User</tt>'s</a> of the current value to refer to "<tt>V</tt>"
 574 instead.  For example, if you detect that an instruction always produces a
 575 constant value (for example through constant folding), you can replace all uses
 576 of the instruction with the constant like this:<p>
 577
 578 <pre>
 579   Inst-&gt;replaceAllUsesWith(ConstVal);
 580 </pre><p>
 581
 582
 583
 584 <!-- ======================================================================= -->
 585 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 586 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 587 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 588 <a name="User">The <tt>User</tt> class</a>
 589 </b></font></td></tr></table><ul>
 590
 591 <tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt></b><br>
 592 doxygen info: <a href="/doxygen/classUser.html">User Class</a><br>
 593 Superclass: <a href="#Value"><tt>Value</tt></a><p>
 594
 595
 596 The <tt>User</tt> class is the common base class of all LLVM nodes that may
 597 refer to <a href="#Value"><tt>Value</tt></a>s.  It exposes a list of "Operands"
 598 that are all of the <a href="#Value"><tt>Value</tt></a>s that the User is
 599 referring to.  The <tt>User</tt> class itself is a subclass of
 600 <tt>Value</tt>.<p>
 601
 602 The operands of a <tt>User</tt> point directly to the LLVM <a
 603 href="#Value"><tt>Value</tt></a> that it refers to.  Because LLVM uses Static
 604 Single Assignment (SSA) form, there can only be one definition referred to,
 605 allowing this direct connection.  This connection provides the use-def
 606 information in LLVM.<p>
 607
 608 <!-- _______________________________________________________________________ -->
 609 </ul><h4><a name="m_User"><hr size=0>Important Public Members of
 610 the <tt>User</tt> class</h4><ul>
 611
 612 The <tt>User</tt> class exposes the operand list in two ways: through an index
 613 access interface and through an iterator based interface.<p>
 614
 615 <li><tt>Value *getOperand(unsigned i)</tt><br>
 616     <tt>unsigned getNumOperands()</tt><p>
 617
 618 These two methods expose the operands of the <tt>User</tt> in a convenient form
 619 for direct access.<p>
 620
 621 <li><tt>User::op_iterator</tt> - Typedef for iterator over the operand list<br>
 622     <tt>User::op_const_iterator</tt>
 623     <tt>use_iterator op_begin()</tt>
 624                  - Get an iterator to the start of the operand list.<br>
 625     <tt>use_iterator op_end()</tt>
 626                  - Get an iterator to the end of the operand list.<p>
 627
 628 Together, these methods make up the iterator based interface to the operands of
 629 a <tt>User</tt>.<p>
 630
 631
 632
 633 <!-- ======================================================================= -->
 634 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 635 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 636 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 637 <a name="Instruction">The <tt>Instruction</tt> class</a>
 638 </b></font></td></tr></table><ul>
 639
 640 <tt>#include "<a
 641 href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt></b><br>
 642 doxygen info: <a href="/doxygen/classInstruction.html">Instruction Class</a><br>
 643 Superclasses: <a href="#User"><tt>User</tt></a>, <a
 644 href="#Value"><tt>Value</tt></a><p>
 645
 646 The <tt>Instruction</tt> class is the common base class for all LLVM
 647 instructions.  It provides only a few methods, but is a very commonly used
 648 class.  The primary data tracked by the <tt>Instruction</tt> class itself is the
 649 opcode (instruction type) and the parent <a
 650 href="#BasicBlock"><tt>BasicBlock</tt></a> the <tt>Instruction</tt> is embedded
 651 into.  To represent a specific type of instruction, one of many subclasses of
 652 <tt>Instruction</tt> are used.<p>
 653
 654 Because the <tt>Instruction</tt> class subclasses the <a
 655 href="#User"><tt>User</tt></a> class, its operands can be accessed in the same
 656 way as for other <a href="#User"><tt>User</tt></a>s (with the
 657 <tt>getOperand()</tt>/<tt>getNumOperands()</tt> and
 658 <tt>op_begin()</tt>/<tt>op_end()</tt> methods).<p>
 659
 660
 661 <!-- _______________________________________________________________________ -->
 662 </ul><h4><a name="m_Instruction"><hr size=0>Important Public Members of
 663 the <tt>Instruction</tt> class</h4><ul>
 664
 665 <li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt><p>
 666
 667 Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that this
 668 <tt>Instruction</tt> is embedded into.<p>
 669
 670 <li><tt>bool hasSideEffects()</tt><p>
 671
 672 Returns true if the instruction has side effects, i.e. it is a <tt>call</tt>,
 673 <tt>free</tt>, <tt>invoke</tt>, or <tt>store</tt>.<p>
 674
 675 <li><tt>unsigned getOpcode()</tt><p>
 676
 677 Returns the opcode for the <tt>Instruction</tt>.<p>
 678
 679 <!--
 680
 681 \subsection{Subclasses of Instruction :}
 682 \begin{itemize}
 683 <li>BinaryOperator : This subclass of Instruction defines a general interface to the all the instructions involvong  binary operators in LLVM.
 684         \begin{itemize}
 685         <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.
 686         \end{itemize}
 687 <li>TerminatorInst : This subclass of Instructions defines an interface for all instructions that can terminate a BasicBlock.
 688         \begin{itemize}
 689          <li> <tt>unsigned getNumSuccessors()</tt>: Returns the number of successors for this terminator instruction.
 690         <li><tt>BasicBlock *getSuccessor(unsigned i)</tt>: As the name suggests returns the ith successor BasicBlock.
 691         <li><tt>void setSuccessor(unsigned i, BasicBlock *B)</tt>: sets BasicBlock B as the ith succesor to this terminator instruction.
 692         \end{itemize}
 693
 694 <li>PHINode : This represents the PHI instructions in the SSA form.
 695         \begin{itemize}
 696         <li><tt> unsigned getNumIncomingValues()</tt>: Returns the number of incoming edges to this PHI node.
 697         <li><tt> Value *getIncomingValue(unsigned i)</tt>: Returns the ith incoming Value.
 698         <li><tt>void setIncomingValue(unsigned i, Value *V)</tt>: Sets the ith incoming Value as V
 699         <li><tt>BasicBlock *getIncomingBlock(unsigned i)</tt>: Returns the Basic Block corresponding to the ith incoming Value.
 700         <li><tt> void addIncoming(Value *D, BasicBlock *BB)</tt>:
 701         Add an incoming value to the end of the PHI list
 702         <li><tt> int getBasicBlockIndex(const BasicBlock *BB) const</tt>:
 703         Returns the first index of the specified basic block in the value list for this PHI.  Returns -1 if no instance.
 704         \end{itemize}
 705 <li>CastInst : In LLVM all casts have to be done through explicit cast instructions. CastInst defines the interface to the cast instructions.
 706 <li>CallInst : This defines an interface to the call instruction in LLVM. ARguments to the function are nothing but operands of the instruction.
 707         \begin{itemize}
 708         <li>: <tt>Function *getCalledFunction()</tt>: Returns a handle to the function that is being called by this Function.
 709         \end{itemize}
 710 <li>LoadInst, StoreInst, GetElemPtrInst : These subclasses represent load, store and getelementptr instructions in LLVM.
 711         \begin{itemize}
 712         <li><tt>Value * getPointerOperand ()</tt>: Returns the Pointer Operand which is typically the 0th operand.
 713         \end{itemize}
 714 <li>BranchInst : This is a subclass of TerminatorInst and defines the interface for conditional and unconditional branches in LLVM.
 715         \begin{itemize}
 716         <li><tt>bool isConditional()</tt>: Returns true if the branch is a conditional branch else returns false
 717         <li> <tt>Value *getCondition()</tt>: Returns the condition if it is a conditional branch else returns null.
 718         <li> <tt>void setUnconditionalDest(BasicBlock *Dest)</tt>: Changes the current branch to an unconditional one targetting the specified block.
 719         \end{itemize}
 720
 721 \end{itemize}
 722
 723 -->
 724
 725
 726 <!-- ======================================================================= -->
 727 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 728 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 729 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 730 <a name="BasicBlock">The <tt>BasicBlock</tt> class</a>
 731 </b></font></td></tr></table><ul>
 732
 733 <tt>#include "<a
 734 href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt></b><br>
 735 doxygen info: <a href="/doxygen/classBasicBlock.html">BasicBlock Class</a><br>
 736 Superclass: <a href="#Value"><tt>Value</tt></a><p>
 737
 738
 739 This class represents a single entry multiple exit section of the code, commonly
 740 known as a basic block by the compiler community.  The <tt>BasicBlock</tt> class
 741 maintains a list of <a href="#Instruction"><tt>Instruction</tt></a>s, which form
 742 the body of the block.  Matching the language definition, the last element of
 743 this list of instructions is always a terminator instruction (a subclass of the
 744 <a href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).<p>
 745
 746 In addition to tracking the list of instructions that make up the block, the
 747 <tt>BasicBlock</tt> class also keeps track of the <a
 748 href="#Function"><tt>Function</tt></a> that it is embedded into.<p>
 749
 750 Note that <tt>BasicBlock</tt>s themselves are <a
 751 href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions
 752 like branches and can go in the switch tables.  <tt>BasicBlock</tt>s have type
 753 <tt>label</tt>.<p>
 754
 755
 756 <!-- _______________________________________________________________________ -->
 757 </ul><h4><a name="m_BasicBlock"><hr size=0>Important Public Members of
 758 the <tt>BasicBlock</tt> class</h4><ul>
 759
 760 <li><tt>BasicBlock(const std::string &amp;Name = "", <a
 761 href="#Function">Function</a> *Parent = 0)</tt><p>
 762
 763 The <tt>BasicBlock</tt> constructor is used to create new basic blocks for
 764 insertion into a function.  The constructor simply takes a name for the new
 765 block, and optionally a <a href="#Function"><tt>Function</tt></a> to insert it
 766 into.  If the <tt>Parent</tt> parameter is specified, the new
 767 <tt>BasicBlock</tt> is automatically inserted at the end of the specified <a
 768 href="#Function"><tt>Function</tt></a>, if not specified, the BasicBlock must be
 769 manually inserted into the <a href="#Function"><tt>Function</tt></a>.<p>
 770
 771 <li><tt>BasicBlock::iterator</tt> - Typedef for instruction list iterator<br>
 772     <tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
 773     <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
 774     <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
 775
 776 These methods and typedefs are forwarding functions that have the same semantics
 777 as the standard library methods of the same names.  These methods expose the
 778 underlying instruction list of a basic block in a way that is easy to
 779 manipulate.  To get the full complement of container operations (including
 780 operations to update the list), you must use the <tt>getInstList()</tt>
 781 method.<p>
 782
 783 <li><tt>BasicBlock::InstListType &amp;getInstList()</tt><p>
 784
 785 This method is used to get access to the underlying container that actually
 786 holds the Instructions.  This method must be used when there isn't a forwarding
 787 function in the <tt>BasicBlock</tt> class for the operation that you would like
 788 to perform.  Because there are no forwarding functions for "updating"
 789 operations, you need to use this if you want to update the contents of a
 790 <tt>BasicBlock</tt>.<p>
 791
 792 <li><tt><A href="#Function">Function</a> *getParent()</tt><p>
 793
 794 Returns a pointer to <a href="#Function"><tt>Function</tt></a> the block is
 795 embedded into, or a null pointer if it is homeless.<p>
 796
 797 <li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt><p>
 798
 799 Returns a pointer to the terminator instruction that appears at the end of the
 800 <tt>BasicBlock</tt>.  If there is no terminator instruction, or if the last
 801 instruction in the block is not a terminator, then a null pointer is
 802 returned.<p>
 803
 804
 805 <!-- ======================================================================= -->
 806 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 807 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 808 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 809 <a name="GlobalValue">The <tt>GlobalValue</tt> class</a>
 810 </b></font></td></tr></table><ul>
 811
 812 <tt>#include "<a
 813 href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt></b><br>
 814 doxygen info: <a href="/doxygen/classGlobalValue.html">GlobalValue Class</a><br>
 815 Superclasses: <a href="#User"><tt>User</tt></a>, <a
 816 href="#Value"><tt>Value</tt></a><p>
 817
 818 Global values (<A href="#GlobalVariable"><tt>GlobalVariable</tt></a>s or <a
 819 href="#Function"><tt>Function</tt></a>s) are the only LLVM values that are
 820 visible in the bodies of all <a href="#Function"><tt>Function</tt></a>s.
 821 Because they are visible at global scope, they are also subject to linking with
 822 other globals defined in different translation units.  To control the linking
 823 process, <tt>GlobalValue</tt>s know their linkage rules.  Specifically,
 824 <tt>GlobalValue</tt>s know whether they have internal or external linkage.<p>
 825
 826 If a <tt>GlobalValue</tt> has internal linkage (equivalent to being
 827 <tt>static</tt> in C), it is not visible to code outside the current translation
 828 unit, and does not participate in linking.  If it has external linkage, it is
 829 visible to external code, and does participate in linking.  In addition to
 830 linkage information, <tt>GlobalValue</tt>s keep track of which <a
 831 href="#Module"><tt>Module</tt></a> they are currently part of.<p>
 832
 833 Because <tt>GlobalValue</tt>s are memory objects, they are always referred to by
 834 their address.  As such, the <a href="#Type"><tt>Type</tt></a> of a global is
 835 always a pointer to its contents.  This is explained in the LLVM Language
 836 Reference Manual.<p>
 837
 838
 839 <!-- _______________________________________________________________________ -->
 840 </ul><h4><a name="m_GlobalValue"><hr size=0>Important Public Members of
 841 the <tt>GlobalValue</tt> class</h4><ul>
 842
 843 <li><tt>bool hasInternalLinkage() const</tt><br>
 844     <tt>bool hasExternalLinkage() const</tt><br>
 845     <tt>void setInternalLinkage(bool HasInternalLinkage)</tt><p>
 846
 847 These methods manipulate the linkage characteristics of the
 848 <tt>GlobalValue</tt>.<p>
 849
 850 <li><tt><a href="#Module">Module</a> *getParent()</tt><p>
 851
 852 This returns the <a href="#Module"><tt>Module</tt></a> that the GlobalValue is
 853 currently embedded into.<p>
 854
 855
 856
 857 <!-- ======================================================================= -->
 858 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 859 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 860 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 861 <a name="Function">The <tt>Function</tt> class</a>
 862 </b></font></td></tr></table><ul>
 863
 864 <tt>#include "<a
 865 href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt></b><br>
 866 doxygen info: <a href="/doxygen/classFunction.html">Function Class</a><br>
 867 Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
 868 href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a><p>
 869
 870 The <tt>Function</tt> class represents a single procedure in LLVM.  It is
 871 actually one of the more complex classes in the LLVM heirarchy because it must
 872 keep track of a large amount of data.  The <tt>Function</tt> class keeps track
 873 of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <a
 874 href="#Argument"><tt>Argument</tt></a>s, and a <a
 875 href="#SymbolTable"><tt>SymbolTable</tt></a>.<p>
 876
 877 The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most commonly
 878 used part of <tt>Function</tt> objects.  The list imposes an implicit ordering
 879 of the blocks in the function, which indicate how the code will be layed out by
 880 the backend.  Additionally, the first <a
 881 href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node for the
 882 <tt>Function</tt>.  It is not legal in LLVM explicitly branch to this initial
 883 block.  There are no implicit exit nodes, and in fact there may be multiple exit
 884 nodes from a single <tt>Function</tt>.  If the <a
 885 href="#BasicBlock"><tt>BasicBlock</tt></a> list is empty, this indicates that
 886 the <tt>Function</tt> is actually a function declaration: the actual body of the
 887 function hasn't been linked in yet.<p>
 888
 889 In addition to a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, the
 890 <tt>Function</tt> class also keeps track of the list of formal <a
 891 href="#Argument"><tt>Argument</tt></a>s that the function receives.  This
 892 container manages the lifetime of the <a href="#Argument"><tt>Argument</tt></a>
 893 nodes, just like the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list does for
 894 the <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.<p>
 895
 896 The <a href="#SymbolTable"><tt>SymbolTable</tt></a> is a very rarely used LLVM
 897 feature that is only used when you have to look up a value by name.  Aside from
 898 that, the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is used internally to
 899 make sure that there are not conflicts between the names of <a
 900 href="#Instruction"><tt>Instruction</tt></a>s, <a
 901 href="#BasicBlock"><tt>BasicBlock</tt></a>s, or <a
 902 href="#Argument"><tt>Argument</tt></a>s in the function body.<p>
 903
 904
 905 <!-- _______________________________________________________________________ -->
 906 </ul><h4><a name="m_Function"><hr size=0>Important Public Members of
 907 the <tt>Function</tt> class</h4><ul>
 908
 909 <li><tt>Function(const <a href="#FunctionType">FunctionType</a> *Ty, bool isInternal, const std::string &amp;N = "")</tt><p>
 910
 911 Constructor used when you need to create new <tt>Function</tt>s to add the the
 912 program.  The constructor must specify the type of the function to create and
 913 whether or not it should start out with internal or external linkage.<p>
 914
 915 <li><tt>bool isExternal()</tt><p>
 916
 917 Return whether or not the <tt>Function</tt> has a body defined.  If the function
 918 is "external", it does not have a body, and thus must be resolved by linking
 919 with a function defined in a different translation unit.<p>
 920
 921
 922 <li><tt>Function::iterator</tt> - Typedef for basic block list iterator<br>
 923     <tt>Function::const_iterator</tt> - Typedef for const_iterator.<br>
 924     <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
 925     <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
 926
 927 These are forwarding methods that make it easy to access the contents of a
 928 <tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
 929 list.<p>
 930
 931 <li><tt>Function::BasicBlockListType &amp;getBasicBlockList()</tt><p>
 932
 933 Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.  This is
 934 neccesary to use when you need to update the list or perform a complex action
 935 that doesn't have a forwarding method.<p>
 936
 937
 938 <li><tt>Function::aiterator</tt> - Typedef for the argument list iterator<br>
 939     <tt>Function::const_aiterator</tt> - Typedef for const_iterator.<br>
 940     <tt>abegin()</tt>, <tt>aend()</tt>, <tt>afront()</tt>, <tt>aback()</tt>,
 941     <tt>asize()</tt>, <tt>aempty()</tt>, <tt>arbegin()</tt>, <tt>arend()</tt><p>
 942
 943 These are forwarding methods that make it easy to access the contents of a
 944 <tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a> list.<p>
 945
 946 <li><tt>Function::ArgumentListType &amp;getArgumentList()</tt><p>
 947
 948 Returns the list of <a href="#Argument"><tt>Argument</tt></a>s.  This is
 949 neccesary to use when you need to update the list or perform a complex action
 950 that doesn't have a forwarding method.<p>
 951
 952
 953
 954 <li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryNode()</tt><p>
 955
 956 Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
 957 function.  Because the entry block for the function is always the first block,
 958 this returns the first block of the <tt>Function</tt>.<p>
 959
 960 <li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
 961     <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt><p>
 962
 963 This traverses the <a href="#Type"><tt>Type</tt></a> of the <tt>Function</tt>
 964 and returns the return type of the function, or the <a
 965 href="#FunctionType"><tt>FunctionType</tt></a> of the actual function.<p>
 966
 967
 968 <li><tt>bool hasSymbolTable() const</tt><p>
 969
 970 Return true if the <tt>Function</tt> has a symbol table allocated to it and if
 971 there is at least one entry in it.<p>
 972
 973 <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p>
 974
 975 Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
 976 <tt>Function</tt> or a null pointer if one has not been allocated (because there
 977 are no named values in the function).<p>
 978
 979 <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTableSure()</tt><p>
 980
 981 Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
 982 <tt>Function</tt> or allocate a new <a
 983 href="#SymbolTable"><tt>SymbolTable</tt></a> if one is not already around.  This
 984 should only be used when adding elements to the <a
 985 href="#SymbolTable"><tt>SymbolTable</tt></a>, so that empty symbol tables are
 986 not left laying around.<p>
 987
 988
 989
 990 <!-- ======================================================================= -->
 991 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 992 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 993 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 994 <a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a>
 995 </b></font></td></tr></table><ul>
 996
 997 <tt>#include "<a
 998 href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt></b><br>
 999 doxygen info: <a href="/doxygen/classGlobalVariable.html">GlobalVariable Class</a><br>
1000 Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
1001 href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a><p>
1002
1003 Global variables are represented with the (suprise suprise)
1004 <tt>GlobalVariable</tt> class.  Like functions, <tt>GlobalVariable</tt>s are
1005 also subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such
1006 are always referenced by their address (global values must live in memory, so
1007 their "name" refers to their address).  Global variables may have an initial
1008 value (which must be a <a href="#Constant"><tt>Constant</tt></a>), and if they
1009 have an initializer, they may be marked as "constant" themselves (indicating
1010 that their contents never change at runtime).<p>
1011
1012
1013 <!-- _______________________________________________________________________ -->
1014 </ul><h4><a name="m_GlobalVariable"><hr size=0>Important Public Members of the
1015 <tt>GlobalVariable</tt> class</h4><ul>
1016
1017 <li><tt>GlobalVariable(const <a href="#Type">Type</a> *Ty, bool isConstant, bool
1018 isInternal, <a href="#Constant">Constant</a> *Initializer = 0, const std::string
1019 &amp;Name = "")</tt><p>
1020
1021 Create a new global variable of the specified type.  If <tt>isConstant</tt> is
1022 true then the global variable will be marked as unchanging for the program, and
1023 if <tt>isInternal</tt> is true the resultant global variable will have internal
1024 linkage.  Optionally an initializer and name may be specified for the global variable as well.<p>
1025
1026
1027 <li><tt>bool isConstant() const</tt><p>
1028
1029 Returns true if this is a global variable is known not to be modified at
1030 runtime.<p>
1031
1032
1033 <li><tt>bool hasInitializer()</tt><p>
1034
1035 Returns true if this <tt>GlobalVariable</tt> has an intializer.<p>
1036
1037
1038 <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt><p>
1039
1040 Returns the intial value for a <tt>GlobalVariable</tt>.  It is not legal to call
1041 this method if there is no initializer.<p>
1042
1043
1044 <!-- ======================================================================= -->
1045 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1046 <tr><td>&nbsp;</td><td width="100%">&nbsp;
1047 <font color="#EEEEFF" face="Georgia,Palatino"><b>
1048 <a name="Module">The <tt>Module</tt> class</a>
1049 </b></font></td></tr></table><ul>
1050
1051 <tt>#include "<a
1052 href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt></b><br>
1053 doxygen info: <a href="/doxygen/classModule.html">Module Class</a><p>
1054
1055 The <tt>Module</tt> class represents the top level structure present in LLVM
1056 programs.  An LLVM module is effectively either a translation unit of the
1057 original program or a combination of several translation units merged by the
1058 linker.  The <tt>Module</tt> class keeps track of a list of <a
1059 href="#Function"><tt>Function</tt></a>s, a list of <a
1060 href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
1061 href="#SymbolTable"><tt>SymbolTable</tt></a>.  Additionally, it contains a few
1062 helpful member functions that try to make common operations easy.<p>
1063
1064
1065 <!-- _______________________________________________________________________ -->
1066 </ul><h4><a name="m_Module"><hr size=0>Important Public Members of the
1067 <tt>Module</tt> class</h4><ul>
1068
1069 <li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
1070     <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
1071     <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
1072     <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
1073
1074 These are forwarding methods that make it easy to access the contents of a
1075 <tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
1076 list.<p>
1077
1078 <li><tt>Module::FunctionListType &amp;getFunctionList()</tt><p>
1079
1080 Returns the list of <a href="#Function"><tt>Function</tt></a>s.  This is
1081 neccesary to use when you need to update the list or perform a complex action
1082 that doesn't have a forwarding method.<p>
1083
1084 <!--  Global Variable -->
1085 <hr size=0>
1086
1087 <li><tt>Module::giterator</tt> - Typedef for global variable list iterator<br>
1088     <tt>Module::const_giterator</tt> - Typedef for const_iterator.<br>
1089     <tt>gbegin()</tt>, <tt>gend()</tt>, <tt>gfront()</tt>, <tt>gback()</tt>,
1090     <tt>gsize()</tt>, <tt>gempty()</tt>, <tt>grbegin()</tt>, <tt>grend()</tt><p>
1091
1092 These are forwarding methods that make it easy to access the contents of a
1093 <tt>Module</tt> object's <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>
1094 list.<p>
1095
1096 <li><tt>Module::GlobalListType &amp;getGlobalList()</tt><p>
1097
1098 Returns the list of <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s.
1099 This is neccesary to use when you need to update the list or perform a complex
1100 action that doesn't have a forwarding method.<p>
1101
1102
1103 <!--  Symbol table stuff -->
1104 <hr size=0>
1105
1106 <li><tt>bool hasSymbolTable() const</tt><p>
1107
1108 Return true if the <tt>Module</tt> has a symbol table allocated to it and if
1109 there is at least one entry in it.<p>
1110
1111 <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p>
1112
1113 Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
1114 <tt>Module</tt> or a null pointer if one has not been allocated (because there
1115 are no named values in the function).<p>
1116
1117 <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTableSure()</tt><p>
1118
1119 Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
1120 <tt>Module</tt> or allocate a new <a
1121 href="#SymbolTable"><tt>SymbolTable</tt></a> if one is not already around.  This
1122 should only be used when adding elements to the <a
1123 href="#SymbolTable"><tt>SymbolTable</tt></a>, so that empty symbol tables are
1124 not left laying around.<p>
1125
1126
1127 <!--  Convenience methods -->
1128 <hr size=0>
1129
1130 <li><tt><a href="#Function">Function</a> *getFunction(const std::string &amp;Name, const <a href="#FunctionType">FunctionType</a> *Ty)</tt><p>
1131
1132 Look up the specified function in the <tt>Module</tt> <a
1133 href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return
1134 <tt>null</tt>.<p>
1135
1136
1137 <li><tt><a href="#Function">Function</a> *getOrInsertFunction(const std::string
1138          &amp;Name, const <a href="#FunctionType">FunctionType</a> *T)</tt><p>
1139
1140 Look up the specified function in the <tt>Module</tt> <a
1141 href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an
1142 external declaration for the function and return it.<p>
1143
1144
1145 <li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt><p>
1146
1147 If there is at least one entry in the <a
1148 href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a
1149 href="#Type"><tt>Type</tt></a>, return it.  Otherwise return the empty
1150 string.<p>
1151
1152
1153 <li><tt>bool addTypeName(const std::string &Name, const <a href="#Type">Type</a>
1154 *Ty)</tt><p>
1155
1156 Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a> mapping
1157 <tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this name, true
1158 is returned and the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is not
1159 modified.<p>
1160
1161
1162 <!-- ======================================================================= -->
1163 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1164 <tr><td>&nbsp;</td><td width="100%">&nbsp;
1165 <font color="#EEEEFF" face="Georgia,Palatino"><b>
1166 <a name="Constant">The <tt>Constant</tt> class and subclasses</a>
1167 </b></font></td></tr></table><ul>
1168
1169 Constant represents a base class for different types of constants. It is
1170 subclassed by ConstantBool, ConstantInt, ConstantSInt, ConstantUInt,
1171 ConstantArray etc for representing the various types of Constants.<p>
1172
1173
1174 <!-- _______________________________________________________________________ -->
1175 </ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul>
1176
1177 <li><tt>bool isConstantExpr()</tt>: Returns true if it is a ConstantExpr
1178
1179
1180
1181
1182 \subsection{Important Subclasses of Constant}
1183 \begin{itemize}
1184 <li>ConstantSInt : This subclass of Constant represents a signed integer constant.
1185         \begin{itemize}
1186         <li><tt>int64_t getValue () const</tt>: Returns the underlying value of this constant.
1187         \end{itemize}
1188 <li>ConstantUInt : This class represents an unsigned integer.
1189         \begin{itemize}
1190         <li><tt>uint64_t getValue () const</tt>: Returns the underlying value of this constant.
1191         \end{itemize}
1192 <li>ConstantFP : This class represents a floating point constant.
1193         \begin{itemize}
1194         <li><tt>double getValue () const</tt>: Returns the underlying value of this constant.
1195         \end{itemize}
1196 <li>ConstantBool : This represents a boolean constant.
1197         \begin{itemize}
1198         <li><tt>bool getValue () const</tt>: Returns the underlying value of this constant.
1199         \end{itemize}
1200 <li>ConstantArray : This represents a constant array.
1201         \begin{itemize}
1202         <li><tt>const std::vector<Use> &amp;getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
1203         \end{itemize}
1204 <li>ConstantStruct : This represents a constant struct.
1205         \begin{itemize}
1206         <li><tt>const std::vector<Use> &amp;getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
1207         \end{itemize}
1208 <li>ConstantPointerRef : This represents a constant pointer value that is initialized to point to a global value, which lies at a constant fixed address.
1209         \begin{itemize}
1210 <li><tt>GlobalValue *getValue()</tt>: Returns the global value to which this pointer is pointing to.
1211         \end{itemize}
1212 \end{itemize}
1213
1214
1215 <!-- ======================================================================= -->
1216 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1217 <tr><td>&nbsp;</td><td width="100%">&nbsp;
1218 <font color="#EEEEFF" face="Georgia,Palatino"><b>
1219 <a name="Type">The <tt>Type</tt> class and Derived Types</a>
1220 </b></font></td></tr></table><ul>
1221
1222 Type as noted earlier is also a subclass of a Value class.  Any primitive
1223 type (like int, short etc) in LLVM is an instance of Type Class.  All
1224 other types are instances of subclasses of type like FunctionType,
1225 ArrayType etc. DerivedType is the interface for all such dervied types
1226 including FunctionType, ArrayType, PointerType, StructType. Types can have
1227 names. They can be recursive (StructType). There exists exactly one instance
1228 of any type structure at a time. This allows using pointer equality of Type *s for comparing types.
1229
1230 <!-- _______________________________________________________________________ -->
1231 </ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul>
1232
1233 <li><tt>PrimitiveID getPrimitiveID () const</tt>: Returns the base type of the type.
1234 <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.
1235 <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.
1236 <li><tt> bool isInteger () const</tt>: Equilivent to isSigned() || isUnsigned(), but with only a single virtual function invocation.
1237 <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.
1238
1239 <li><tt>bool isFloatingPoint ()</tt>: Return true if this is one of the two floating point types.
1240 <li><tt>bool isRecursive () const</tt>: Returns rue if the type graph contains a cycle.
1241 <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.
1242 <li><tt>bool isPrimitiveType () const</tt>: Returns true if it is a primitive type.
1243 <li><tt>bool isDerivedType () const</tt>: Returns true if it is a derived type.
1244 <li><tt>const Type * getContainedType (unsigned i) const</tt>:
1245 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.
1246 <li><tt>unsigned getNumContainedTypes () const</tt>: Return the number of types in the derived type.
1247
1248
1249
1250 \subsection{Derived Types}
1251 \begin{itemize}
1252 <li>SequentialType : This is subclassed by ArrayType and PointerType
1253         \begin{itemize}
1254         <li><tt>const Type * getElementType () const</tt>: Returns the type of each of the elements in the sequential type.
1255         \end{itemize}
1256 <li>ArrayType : This is a subclass of SequentialType and defines interface for array types.
1257         \begin{itemize}
1258         <li><tt>unsigned getNumElements () const</tt>: Returns the number of elements in the array.
1259         \end{itemize}
1260 <li>PointerType : Subclass of SequentialType for  pointer types.
1261 <li>StructType : subclass of DerivedTypes for struct types
1262 <li>FunctionType : subclass of DerivedTypes for function types.
1263         \begin{itemize}
1264
1265         <li><tt>bool isVarArg () const</tt>: Returns true if its a vararg function
1266         <li><tt> const Type * getReturnType () const</tt>: Returns the return type of the function.
1267         <li><tt> const ParamTypes &amp;getParamTypes () const</tt>: Returns a vector of parameter types.
1268         <li><tt>const Type * getParamType (unsigned i)</tt>: Returns the type of the ith parameter.
1269         <li><tt> const unsigned getNumParams () const</tt>: Returns the number of formal parameters.
1270         \end{itemize}
1271 \end{itemize}
1272
1273
1274
1275
1276 <!-- ======================================================================= -->
1277 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1278 <tr><td>&nbsp;</td><td width="100%">&nbsp;
1279 <font color="#EEEEFF" face="Georgia,Palatino"><b>
1280 <a name="Argument">The <tt>Argument</tt> class</a>
1281 </b></font></td></tr></table><ul>
1282
1283 This subclass of Value defines the interface for incoming formal arguments to a
1284 function. A Function maitanis a list of its formal arguments. An argument has a
1285 pointer to the parent Function.
1286
1287
1288
1289
1290 <!-- *********************************************************************** -->
1291 </ul>
1292 <!-- *********************************************************************** -->
1293
1294 <hr><font size-1>
1295 <address>By: <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and
1296 <a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
1297 <!-- Created: Tue Aug  6 15:00:33 CDT 2002 -->
1298 <!-- hhmts start -->
1299 Last modified: Mon Sep  9 14:56:55 CDT 2002
1300 <!-- hhmts end -->
1301 </font></body></html>