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