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