1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
4 <title>LLVM Programmer's Manual</title>
6 <body style="background-color: white;">
7 <table width="100%" bgcolor="#330077" border="0" cellpadding="4"
11 <td> <font size="+3" color="#eeeeff"
12 face="Georgia,Palatino,Times,Roman"><b>LLVM Programmer's Manual</b></font></td>
17 <li><a href="#introduction">Introduction</a> </li>
18 <li><a href="#general">General Information</a>
20 <li><a href="#stl">The C++ Standard Template Library</a><!--
21 <li>The <tt>-time-passes</tt> option
22 <li>How to use the LLVM Makefile system
23 <li>How to write a regression test
27 <li><a href="#apis">Important and useful LLVM APIs</a>
29 <li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt>
30 and <tt>dyn_cast<></tt> templates</a> </li>
31 <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt>
34 <li><a href="#DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt>
35 and the <tt>-debug-only</tt> option</a> </li>
38 <li><a href="#Statistic">The <tt>Statistic</tt> template & <tt>-stats</tt>
40 <li>The <tt>InstVisitor</tt> template
41 <li>The general graph API
45 <li><a href="#common">Helpful Hints for Common Operations</a>
47 <li><a href="#inspection">Basic Inspection and Traversal Routines</a>
49 <li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s
50 in a <tt>Function</tt></a> </li>
51 <li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s
52 in a <tt>BasicBlock</tt></a> </li>
53 <li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s
54 in a <tt>Function</tt></a> </li>
55 <li><a href="#iterate_convert">Turning an iterator into a
56 class pointer</a> </li>
57 <li><a href="#iterate_complex">Finding call sites: a more
58 complex example</a> </li>
59 <li><a href="#calls_and_invokes">Treating calls and invokes
60 the same way</a> </li>
61 <li><a href="#iterate_chains">Iterating over def-use &
62 use-def chains</a> </li>
65 <li><a href="#simplechanges">Making simple changes</a>
67 <li><a href="#schanges_creating">Creating and inserting new
68 <tt>Instruction</tt>s</a> </li>
69 <li><a href="#schanges_deleting">Deleting <tt>Instruction</tt>s</a> </li>
70 <li><a href="#schanges_replacing">Replacing an <tt>Instruction</tt>
71 with another <tt>Value</tt></a> </li>
74 <li>Working with the Control Flow Graph
76 <li>Accessing predecessors and successors of a <tt>BasicBlock</tt>
83 <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
85 <li><a href="#Value">The <tt>Value</tt> class</a>
87 <li><a href="#User">The <tt>User</tt> class</a>
89 <li><a href="#Instruction">The <tt>Instruction</tt> class</a>
91 <li> <a href="#GetElementPtrInst">The <span
92 style="font-family: monospace;">GetElementPtrInst</span> class</a><br>
96 <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a>
98 <li><a href="#BasicBlock">The <tt>BasicBlock</tt>
100 <li><a href="#Function">The <tt>Function</tt> class</a> </li>
101 <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt>
105 <li><a href="#Module">The <tt>Module</tt> class</a> </li>
106 <li><a href="#Constant">The <tt>Constant</tt> class</a>
116 <li><a href="#Type">The <tt>Type</tt> class</a> </li>
117 <li><a href="#Argument">The <tt>Argument</tt> class</a> </li>
120 <li>The <tt>SymbolTable</tt> class </li>
121 <li>The <tt>ilist</tt> and <tt>iplist</tt> classes
123 <li>Creating, inserting, moving and deleting from LLVM lists </li>
126 <li>Important iterator invalidation semantics to be aware of </li>
128 <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>,<a
129 href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>, and <a
130 href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a></b></p>
134 <!-- *********************************************************************** -->
135 <table width="100%" bgcolor="#330077" border="0" cellpadding="4"
139 <td align="center"><font color="#eeeeff" size="+2"
140 face="Georgia,Palatino"><b> <a name="introduction">Introduction </a></b></font></td>
145 <!-- *********************************************************************** -->
146 This document is meant to highlight some of the important classes and
147 interfaces available in the LLVM source-base. This manual is not
148 intended to explain what LLVM is, how it works, and what LLVM code looks
149 like. It assumes that you know the basics of LLVM and are interested
150 in writing transformations or otherwise analyzing or manipulating the
152 <p> This document should get you oriented so that you can find your
153 way in the continuously growing source code that makes up the LLVM
154 infrastructure. Note that this manual is not intended to serve as a
155 replacement for reading the source code, so if you think there should be
156 a method in one of these classes to do something, but it's not listed,
157 check the source. Links to the <a href="/doxygen/">doxygen</a> sources
158 are provided to make this as easy as possible.</p>
159 <p> The first section of this document describes general information
160 that is useful to know when working in the LLVM infrastructure, and the
161 second describes the Core LLVM classes. In the future this manual will
162 be extended with information describing how to use extension libraries,
163 such as dominator information, CFG traversal routines, and useful
164 utilities like the <tt><a href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt>
166 <p><!-- *********************************************************************** --> </p>
168 <table width="100%" bgcolor="#330077" border="0" cellpadding="4"
172 <td align="center"><font color="#eeeeff" size="+2"
173 face="Georgia,Palatino"><b> <a name="general">General Information </a></b></font></td>
178 <!-- *********************************************************************** -->
179 This section contains general information that is useful if you are
180 working in the LLVM source-base, but that isn't specific to any
182 <p><!-- ======================================================================= --> </p>
184 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
189 <td width="100%"> <font color="#eeeeff"
190 face="Georgia,Palatino"><b> <a name="stl">The C++ Standard Template
191 Library</a> </b></font></td>
196 LLVM makes heavy use of the C++ Standard Template Library (STL),
197 perhaps much more than you are used to, or have seen before. Because of
198 this, you might want to do a little background reading in the
199 techniques used and capabilities of the library. There are many good
200 pages that discuss the STL, and several books on the subject that you
201 can get, so it will not be discussed in this document.
202 <p> Here are some useful links:</p>
205 <li><a href="http://www.dinkumware.com/refxcpp.html">Dinkumware C++
206 Library reference</a> - an excellent reference for the STL and other
207 parts of the standard C++ library. </li>
208 <li><a href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> -
209 This is an O'Reilly book in the making. It has a decent <a
210 href="http://www.tempest-sw.com/cpp/ch13-libref.html">Standard Library
211 Reference</a> that rivals Dinkumware's, and is actually free until the
212 book is published. </li>
213 <li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently
214 Asked Questions</a> </li>
215 <li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's
216 Guide</a> - Contains a useful <a
217 href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction
218 to the STL</a>. </li>
219 <li><a href="http://www.research.att.com/%7Ebs/C++.html">Bjarne
220 Stroustrup's C++ Page</a> </li>
222 <p> You are also encouraged to take a look at the <a
223 href="CodingStandards.html">LLVM Coding Standards</a> guide which
224 focuses on how to write maintainable code more than where to put your
226 <p><!-- ======================================================================= --> </p>
228 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
233 <td width="100%"> <font color="#eeeeff"
234 face="Georgia,Palatino"><b> <a name="stl">Other useful references</a> </b></font></td>
239 LLVM is currently using CVS as its source versioning system. You may
240 find this reference handy:
243 <li><a href="http://www.psc.edu/%7Esemke/cvs_branches.html">CVS
244 Branch and Tag Primer</a></li>
246 <p><!-- *********************************************************************** --> </p>
248 <table width="100%" bgcolor="#330077" border="0" cellpadding="4"
252 <td align="center"><font color="#eeeeff" size="+2"
253 face="Georgia,Palatino"><b> <a name="apis">Important and useful LLVM
254 APIs </a></b></font></td>
259 <!-- *********************************************************************** -->
260 Here we highlight some LLVM APIs that are generally useful and good to
261 know about when writing transformations.
262 <p><!-- ======================================================================= --> </p>
264 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
269 <td width="100%"> <font color="#eeeeff"
270 face="Georgia,Palatino"><b> <a name="isa">The isa<>,
271 cast<> and dyn_cast<> templates</a> </b></font></td>
276 The LLVM source-base makes extensive use of a custom form of RTTI.
277 These templates have many similarities to the C++ <tt>dynamic_cast<></tt>
278 operator, but they don't have some drawbacks (primarily stemming from
279 the fact that <tt>dynamic_cast<></tt> only works on classes that
280 have a v-table). Because they are used so often, you must know what they
281 do and how they work. All of these templates are defined in the <a
282 href="/doxygen/Casting_8h-source.html"><tt>Support/Casting.h</tt></a>
283 file (note that you very rarely have to include this file directly).
286 <dt><tt>isa<></tt>: </dt>
287 <dd>The <tt>isa<></tt> operator works exactly like the Java "<tt>instanceof</tt>"
288 operator. It returns true or false depending on whether a reference or
289 pointer points to an instance of the specified class. This can be very
290 useful for constraint checking of various sorts (example below).
293 <dt><tt>cast<></tt>: </dt>
294 <dd>The <tt>cast<></tt> operator is a "checked cast"
295 operation. It converts a pointer or reference from a base class to a
296 derived cast, causing an assertion failure if it is not really an
297 instance of the right type. This should be used in cases where you have
298 some information that makes you believe that something is of the right
299 type. An example of the <tt>isa<></tt> and <tt>cast<></tt>
302 <pre>static bool isLoopInvariant(const <a href="#Value">Value</a> *V, const Loop *L) {<br> if (isa<<a
303 href="#Constant">Constant</a>>(V) || isa<<a href="#Argument">Argument</a>>(V) || isa<<a
304 href="#GlobalValue">GlobalValue</a>>(V))<br> return true;<br><br> <i>// Otherwise, it must be an instruction...</i><br> return !L->contains(cast<<a
305 href="#Instruction">Instruction</a>>(V)->getParent());<br></pre>
306 <p> Note that you should <b>not</b> use an <tt>isa<></tt>
307 test followed by a <tt>cast<></tt>, for that use the <tt>dyn_cast<></tt>
311 <dt><tt>dyn_cast<></tt>: </dt>
312 <dd>The <tt>dyn_cast<></tt> operator is a "checking cast"
313 operation. It checks to see if the operand is of the specified type, and
314 if so, returns a pointer to it (this operator does not work with
315 references). If the operand is not of the correct type, a null pointer
316 is returned. Thus, this works very much like the <tt>dynamic_cast</tt>
317 operator in C++, and should be used in the same circumstances.
318 Typically, the <tt>dyn_cast<></tt> operator is used in an <tt>if</tt>
319 statement or some other flow control statement like this:
321 <pre> if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a
322 href="#AllocationInst">AllocationInst</a>>(Val)) {<br> ...<br> }<br></pre>
323 <p> This form of the <tt>if</tt> statement effectively combines
324 together a call to <tt>isa<></tt> and a call to <tt>cast<></tt>
325 into one statement, which is very convenient.</p>
326 <p> Another common example is:</p>
328 <pre> <i>// Loop over all of the phi nodes in a basic block</i><br> BasicBlock::iterator BBI = BB->begin();<br> for (; <a
329 href="#PhiNode">PHINode</a> *PN = dyn_cast<<a href="#PHINode">PHINode</a>>(BBI); ++BBI)<br> cerr << *PN;<br></pre>
330 <p> Note that the <tt>dyn_cast<></tt> operator, like C++'s <tt>dynamic_cast</tt>
331 or Java's <tt>instanceof</tt> operator, can be abused. In particular
332 you should not use big chained <tt>if/then/else</tt> blocks to check for
333 lots of different variants of classes. If you find yourself wanting to
334 do this, it is much cleaner and more efficient to use the InstVisitor
335 class to dispatch over the instruction type directly.</p>
338 <dt><tt>cast_or_null<></tt>: </dt>
339 <dd>The <tt>cast_or_null<></tt> operator works just like the <tt>cast<></tt>
340 operator, except that it allows for a null pointer as an argument (which
341 it then propagates). This can sometimes be useful, allowing you to
342 combine several null checks into one.
345 <dt><tt>dyn_cast_or_null<></tt>: </dt>
346 <dd>The <tt>dyn_cast_or_null<></tt> operator works just like
347 the <tt>dyn_cast<></tt> operator, except that it allows for a null
348 pointer as an argument (which it then propagates). This can sometimes
349 be useful, allowing you to combine several null checks into one.
353 These five templates can be used with any classes, whether they have a
354 v-table or not. To add support for these templates, you simply need to
355 add <tt>classof</tt> static methods to the class you are interested
356 casting to. Describing this is currently outside the scope of this
357 document, but there are lots of examples in the LLVM source base.
358 <p><!-- ======================================================================= --> </p>
360 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
365 <td width="100%"> <font color="#eeeeff"
366 face="Georgia,Palatino"><b> <a name="DEBUG">The <tt>DEBUG()</tt> macro
367 & <tt>-debug</tt> option</a> </b></font></td>
372 Often when working on your pass you will put a bunch of debugging
373 printouts and other code into your pass. After you get it working, you
374 want to remove it... but you may need it again in the future (to work
375 out new bugs that you run across).
376 <p> Naturally, because of this, you don't want to delete the debug
377 printouts, but you don't want them to always be noisy. A standard
378 compromise is to comment them out, allowing you to enable them if you
379 need them in the future.</p>
380 <p> The "<tt><a href="/doxygen/Debug_8h-source.html">Support/Debug.h</a></tt>"
381 file provides a macro named <tt>DEBUG()</tt> that is a much nicer
382 solution to this problem. Basically, you can put arbitrary code into
383 the argument of the <tt>DEBUG</tt> macro, and it is only executed if '<tt>opt</tt>'
384 (or any other tool) is run with the '<tt>-debug</tt>' command line
386 <pre> ... <br> DEBUG(std::cerr << "I am here!\n");<br> ...<br></pre>
387 <p> Then you can run your pass like this:</p>
389 <pre> $ opt < a.bc > /dev/null -mypass<br> <no output><br> $ opt < a.bc > /dev/null -mypass -debug<br> I am here!<br> $<br></pre>
390 <p> Using the <tt>DEBUG()</tt> macro instead of a home-brewed solution
391 allows you to not have to create "yet another" command line option for
392 the debug output for your pass. Note that <tt>DEBUG()</tt> macros are
393 disabled for optimized builds, so they do not cause a performance impact
394 at all (for the same reason, they should also not contain
396 <p> One additional nice thing about the <tt>DEBUG()</tt> macro is that
397 you can enable or disable it directly in gdb. Just use "<tt>set
398 DebugFlag=0</tt>" or "<tt>set DebugFlag=1</tt>" from the gdb if the
399 program is running. If the program hasn't been started yet, you can
400 always just run it with <tt>-debug</tt>.</p>
401 <p><!-- _______________________________________________________________________ --> </p>
403 <h4><a name="DEBUG_TYPE">
404 <hr size="1">Fine grained debug info with <tt>DEBUG_TYPE()</tt> and the <tt>-debug-only</tt>
407 Sometimes you may find yourself in a situation where enabling <tt>-debug</tt>
408 just turns on <b>too much</b> information (such as when working on the
409 code generator). If you want to enable debug information with more
410 fine-grained control, you define the <tt>DEBUG_TYPE</tt> macro and the <tt>-debug</tt>
411 only option as follows:
413 <pre> ...<br> DEBUG(std::cerr << "No debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE "foo"<br> DEBUG(std::cerr << "'foo' debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE "bar"<br> DEBUG(std::cerr << "'bar' debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE ""<br> DEBUG(std::cerr << "No debug type (2)\n");<br> ...<br></pre>
414 <p> Then you can run your pass like this:</p>
416 <pre> $ opt < a.bc > /dev/null -mypass<br> <no output><br> $ opt < a.bc > /dev/null -mypass -debug<br> No debug type<br> 'foo' debug type<br> 'bar' debug type<br> No debug type (2)<br> $ opt < a.bc > /dev/null -mypass -debug-only=foo<br> 'foo' debug type<br> $ opt < a.bc > /dev/null -mypass -debug-only=bar<br> 'bar' debug type<br> $<br></pre>
417 <p> Of course, in practice, you should only set <tt>DEBUG_TYPE</tt> at
418 the top of a file, to specify the debug type for the entire module (if
419 you do this before you <tt>#include "Support/Debug.h"</tt>, you don't
420 have to insert the ugly <tt>#undef</tt>'s). Also, you should use names
421 more meaningful than "foo" and "bar", because there is no system in
422 place to ensure that names do not conflict. If two different modules
423 use the same string, they will all be turned on when the name is
424 specified. This allows, for example, all debug information for
425 instruction scheduling to be enabled with <tt>-debug-type=InstrSched</tt>,
426 even if the source lives in multiple files.</p>
427 <p><!-- ======================================================================= --> </p>
429 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
434 <td width="100%"> <font color="#eeeeff"
435 face="Georgia,Palatino"><b> <a name="Statistic">The <tt>Statistic</tt>
436 template & <tt>-stats</tt> option</a> </b></font></td>
441 The "<tt><a href="/doxygen/Statistic_8h-source.html">Support/Statistic.h</a></tt>"
442 file provides a template named <tt>Statistic</tt> that is used as a
443 unified way to keep track of what the LLVM compiler is doing and how
444 effective various optimizations are. It is useful to see what
445 optimizations are contributing to making a particular program run
447 <p> Often you may run your pass on some big program, and you're
448 interested to see how many times it makes a certain transformation.
449 Although you can do this with hand inspection, or some ad-hoc method,
450 this is a real pain and not very useful for big programs. Using the <tt>Statistic</tt>
451 template makes it very easy to keep track of this information, and the
452 calculated information is presented in a uniform manner with the rest of
453 the passes being executed.</p>
454 <p> There are many examples of <tt>Statistic</tt> uses, but the basics
455 of using it are as follows:</p>
458 <li>Define your statistic like this:
460 <pre>static Statistic<> NumXForms("mypassname", "The # of times I did stuff");<br></pre>
461 <p> The <tt>Statistic</tt> template can emulate just about any
462 data-type, but if you do not specify a template argument, it defaults to
463 acting like an unsigned int counter (this is usually what you want).</p>
466 <li>Whenever you make a transformation, bump the counter:
468 <pre> ++NumXForms; // I did stuff<br></pre>
472 <p> That's all you have to do. To get '<tt>opt</tt>' to print out the
473 statistics gathered, use the '<tt>-stats</tt>' option:</p>
475 <pre> $ opt -stats -mypassname < program.bc > /dev/null<br> ... statistic output ...<br></pre>
476 <p> When running <tt>gccas</tt> on a C file from the SPEC benchmark
477 suite, it gives a report that looks like this:</p>
479 <pre> 7646 bytecodewriter - Number of normal instructions<br> 725 bytecodewriter - Number of oversized instructions<br> 129996 bytecodewriter - Number of bytecode bytes written<br> 2817 raise - Number of insts DCEd or constprop'd<br> 3213 raise - Number of cast-of-self removed<br> 5046 raise - Number of expression trees converted<br> 75 raise - Number of other getelementptr's formed<br> 138 raise - Number of load/store peepholes<br> 42 deadtypeelim - Number of unused typenames removed from symtab<br> 392 funcresolve - Number of varargs functions resolved<br> 27 globaldce - Number of global variables removed<br> 2 adce - Number of basic blocks removed<br> 134 cee - Number of branches revectored<br> 49 cee - Number of setcc instruction eliminated<br> 532 gcse - Number of loads removed<br> 2919 gcse - Number of instructions removed<br> 86 indvars - Number of canonical indvars added<br> 87 indvars - Number of aux indvars removed<br> 25 instcombine - Number of dead inst eliminate<br> 434 instcombine - Number of insts combined<br> 248 licm - Number of load insts hoisted<br> 1298 licm - Number of insts hoisted to a loop pre-header<br> 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)<br> 75 mem2reg - Number of alloca's promoted<br> 1444 cfgsimplify - Number of blocks simplified<br></pre>
480 <p> Obviously, with so many optimizations, having a unified framework
481 for this stuff is very nice. Making your pass fit well into the
482 framework makes it more maintainable and useful.</p>
483 <p><!-- *********************************************************************** --> </p>
485 <table width="100%" bgcolor="#330077" border="0" cellpadding="4"
489 <td align="center"><font color="#eeeeff" size="+2"
490 face="Georgia,Palatino"><b> <a name="common">Helpful Hints for Common
491 Operations </a></b></font></td>
497 *********************************************************************** -->
498 This section describes how to perform some very simple transformations
499 of LLVM code. This is meant to give examples of common idioms used,
500 showing the practical side of LLVM transformations.
501 <p> Because this is a "how-to" section, you should also read about the
502 main classes that you will be working with. The <a href="#coreclasses">Core
503 LLVM Class Hierarchy Reference</a> contains details and descriptions of
504 the main classes that you should know about.</p>
505 <p><!-- NOTE: this section should be heavy on example code --><!-- ======================================================================= --> </p>
507 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
512 <td width="100%"> <font color="#eeeeff"
513 face="Georgia,Palatino"><b> <a name="inspection">Basic Inspection and
514 Traversal Routines</a> </b></font></td>
519 The LLVM compiler infrastructure have many different data structures
520 that may be traversed. Following the example of the C++ standard
521 template library, the techniques used to traverse these various data
522 structures are all basically the same. For a enumerable sequence of
523 values, the <tt>XXXbegin()</tt> function (or method) returns an iterator
524 to the start of the sequence, the <tt>XXXend()</tt> function returns an
525 iterator pointing to one past the last valid element of the sequence,
526 and there is some <tt>XXXiterator</tt> data type that is common between
528 <p> Because the pattern for iteration is common across many different
529 aspects of the program representation, the standard template library
530 algorithms may be used on them, and it is easier to remember how to
531 iterate. First we show a few common examples of the data structures that
532 need to be traversed. Other data structures are traversed in very
534 <p><!-- _______________________________________________________________________ --> </p>
537 <hr size="1"><a name="iterate_function">Iterating over the </a><a
538 href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a href="#Function"><tt>Function</tt></a> </h4>
540 It's quite common to have a <tt>Function</tt> instance that you'd like
541 to transform in some way; in particular, you'd like to manipulate its <tt>BasicBlock</tt>s.
542 To facilitate this, you'll need to iterate over all of the <tt>BasicBlock</tt>s
543 that constitute the <tt>Function</tt>. The following is an example
544 that prints the name of a <tt>BasicBlock</tt> and the number of <tt>Instruction</tt>s
546 <pre> // func is a pointer to a Function instance<br> for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i) {<br><br> // print out the name of the basic block if it has one, and then the<br> // number of instructions that it contains<br><br> cerr << "Basic block (name=" << i->getName() << ") has " <br> << i->size() << " instructions.\n";<br> }<br></pre>
547 Note that i can be used as if it were a pointer for the purposes of
548 invoking member functions of the <tt>Instruction</tt> class. This is
549 because the indirection operator is overloaded for the iterator
550 classes. In the above code, the expression <tt>i->size()</tt> is
551 exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.<!-- _______________________________________________________________________ -->
554 <hr size="1"><a name="iterate_basicblock">Iterating over the </a><a
555 href="#Instruction"><tt>Instruction</tt></a>s in a <a
556 href="#BasicBlock"><tt>BasicBlock</tt></a> </h4>
558 Just like when dealing with <tt>BasicBlock</tt>s in <tt>Function</tt>s,
559 it's easy to iterate over the individual instructions that make up <tt>BasicBlock</tt>s.
560 Here's a code snippet that prints out each instruction in a <tt>BasicBlock</tt>:
561 <pre> // blk is a pointer to a BasicBlock instance<br> for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)<br> // the next statement works since operator<<(ostream&,...) <br> // is overloaded for Instruction&<br> cerr << *i << "\n";<br></pre>
562 However, this isn't really the best way to print out the contents of a <tt>BasicBlock</tt>!
563 Since the ostream operators are overloaded for virtually anything
564 you'll care about, you could have just invoked the print routine on the
565 basic block itself: <tt>cerr << *blk << "\n";</tt>.
566 <p> Note that currently operator<< is implemented for <tt>Value*</tt>,
567 so it will print out the contents of the pointer, instead of the
568 pointer value you might expect. This is a deprecated interface that
569 will be removed in the future, so it's best not to depend on it. To
570 print out the pointer value for now, you must cast to <tt>void*</tt>.</p>
571 <p><!-- _______________________________________________________________________ --> </p>
574 <hr size="1"><a name="iterate_institer">Iterating over the </a><a
575 href="#Instruction"><tt>Instruction</tt></a>s in a <a href="#Function"><tt>Function</tt></a></h4>
577 If you're finding that you commonly iterate over a <tt>Function</tt>'s <tt>BasicBlock</tt>s
578 and then that <tt>BasicBlock</tt>'s <tt>Instruction</tt>s, <tt>InstIterator</tt>
579 should be used instead. You'll need to include <a
580 href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>,
581 and then instantiate <tt>InstIterator</tt>s explicitly in your code.
582 Here's a small example that shows how to dump all instructions in a
583 function to stderr (<b>Note:</b> Dereferencing an <tt>InstIterator</tt>
584 yields an <tt>Instruction*</tt>, <i>not</i> an <tt>Instruction&</tt>!):
585 <pre>#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"<br>...<br>// Suppose F is a ptr to a function<br>for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)<br> cerr << **i << "\n";<br></pre>
586 Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a
587 worklist with its initial contents. For example, if you wanted to
588 initialize a worklist to contain all instructions in a <tt>Function</tt>
589 F, all you would need to do is something like:
590 <pre>std::set<Instruction*> worklist;<br>worklist.insert(inst_begin(F), inst_end(F));<br></pre>
591 The STL set <tt>worklist</tt> would now contain all instructions in the <tt>Function</tt>
592 pointed to by F.<!-- _______________________________________________________________________ -->
595 <hr size="1"><a name="iterate_convert">Turning an iterator into a class
596 pointer (and vice-versa) </a></h4>
598 Sometimes, it'll be useful to grab a reference (or pointer) to a class
599 instance when all you've got at hand is an iterator. Well, extracting
600 a reference or a pointer from an iterator is very straightforward.
601 Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and <tt>j</tt>
602 is a <tt>BasicBlock::const_iterator</tt>:
603 <pre> Instruction& inst = *i; // grab reference to instruction reference<br> Instruction* pinst = &*i; // grab pointer to instruction reference<br> const Instruction& inst = *j;<br></pre>
604 However, the iterators you'll be working with in the LLVM framework are
605 special: they will automatically convert to a ptr-to-instance type
606 whenever they need to. Instead of dereferencing the iterator and then
607 taking the address of the result, you can simply assign the iterator to
608 the proper pointer type and you get the dereference and address-of
609 operation as a result of the assignment (behind the scenes, this is a
610 result of overloading casting mechanisms). Thus the last line of the
612 <pre>Instruction* pinst = &*i;</pre>
613 is semantically equivalent to
614 <pre>Instruction* pinst = i;</pre>
615 It's also possible to turn a class pointer into the corresponding
616 iterator. Usually, this conversion is quite inexpensive. The
617 following code snippet illustrates use of the conversion constructors
618 provided by LLVM iterators. By using these, you can explicitly grab
619 the iterator of something without actually obtaining it via iteration
621 <pre>void printNextInstruction(Instruction* inst) {<br> BasicBlock::iterator it(inst);<br> ++it; // after this line, it refers to the instruction after *inst.<br> if (it != inst->getParent()->end()) cerr << *it << "\n";<br>}<br></pre>
622 Of course, this example is strictly pedagogical, because it'd be much
623 better to explicitly grab the next instruction directly from inst.<!--_______________________________________________________________________-->
626 <hr size="1"><a name="iterate_complex">Finding call sites: a slightly
627 more complex example </a></h4>
629 Say that you're writing a FunctionPass and would like to count all the
630 locations in the entire module (that is, across every <tt>Function</tt>)
631 where a certain function (i.e., some <tt>Function</tt>*) is already in
632 scope. As you'll learn later, you may want to use an <tt>InstVisitor</tt>
633 to accomplish this in a much more straightforward manner, but this
634 example will allow us to explore how you'd do it if you didn't have <tt>InstVisitor</tt>
635 around. In pseudocode, this is what we want to do:
636 <pre>initialize callCounter to zero<br>for each Function f in the Module<br> for each BasicBlock b in f<br> for each Instruction i in b<br> if (i is a CallInst and calls the given function)<br> increment callCounter<br></pre>
637 And the actual code is (remember, since we're writing a <tt>FunctionPass</tt>,
638 our <tt>FunctionPass</tt>-derived class simply has to override the <tt>runOnFunction</tt>
640 <pre>Function* targetFunc = ...;<br><br>class OurFunctionPass : public FunctionPass {<br> public:<br> OurFunctionPass(): callCounter(0) { }<br><br> virtual runOnFunction(Function& F) {<br> for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {<br> for (BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {<br> if (<a
641 href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a
642 href="#CallInst">CallInst</a>>(&*i)) {<br> // we know we've encountered a call instruction, so we<br> // need to determine if it's a call to the<br> // function pointed to by m_func or not.<br> <br> if (callInst->getCalledFunction() == targetFunc)<br> ++callCounter;<br> }<br> }<br> }<br> <br> private:<br> unsigned callCounter;<br>};<br></pre>
643 <!--_______________________________________________________________________-->
646 <hr size="1"><a name="calls_and_invokes">Treating calls and invokes the
649 <p>You may have noticed that the previous example was a bit
650 oversimplified in that it did not deal with call sites generated by
651 'invoke' instructions. In this, and in other situations, you may find
652 that you want to treat <tt>CallInst</tt>s and <tt>InvokeInst</tt>s
653 the same way, even though their most-specific common base class is <tt>Instruction</tt>,
654 which includes lots of less closely-related things. For these cases,
655 LLVM provides a handy wrapper class called <a
656 href="http://llvm.cs.uiuc.edu/doxygen/classCallSite.html"><tt>CallSite </tt></a>.
657 It is essentially a wrapper around an <tt>Instruction</tt> pointer,
658 with some methods that provide functionality common to <tt>CallInst</tt>s
659 and <tt>InvokeInst</tt>s.</p>
660 <p>This class is supposed to have "value semantics". So it should be
661 passed by value, not by reference; it should not be dynamically
662 allocated or deallocated using <tt>operator new</tt> or <tt>operator
663 delete</tt>. It is efficiently copyable, assignable and constructable,
664 with costs equivalents to that of a bare pointer. (You will notice, if
665 you look at its definition, that it has only a single data member.)</p>
666 <!--_______________________________________________________________________-->
669 <hr size="1"><a name="iterate_chains">Iterating over def-use &
670 use-def chains</a></h4>
672 Frequently, we might have an instance of the <a
673 href="/doxygen/classValue.html">Value Class</a> and we want to
674 determine which <tt>User</tt>s use the <tt>Value</tt>. The list of
675 all <tt>User</tt>s of a particular <tt>Value</tt> is called a <i>def-use</i>
676 chain. For example, let's say we have a <tt>Function*</tt> named <tt>F</tt>
677 to a particular function <tt>foo</tt>. Finding all of the instructions
678 that <i>use</i> <tt>foo</tt> is as simple as iterating over the <i>def-use</i>
680 <pre>Function* F = ...;<br><br>for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) {<br> if (Instruction *Inst = dyn_cast<Instruction>(*i)) {<br> cerr << "F is used in instruction:\n";<br> cerr << *Inst << "\n";<br> }<br>}<br></pre>
681 Alternately, it's common to have an instance of the <a
682 href="/doxygen/classUser.html">User Class</a> and need to know what <tt>Value</tt>s
683 are used by it. The list of all <tt>Value</tt>s used by a <tt>User</tt>
684 is known as a <i>use-def</i> chain. Instances of class <tt>Instruction</tt>
685 are common <tt>User</tt>s, so we might want to iterate over all of the
686 values that a particular instruction uses (that is, the operands of the
687 particular <tt>Instruction</tt>):
688 <pre>Instruction* pi = ...;<br><br>for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {<br> Value* v = *i;<br> ...<br>}<br></pre>
690 def-use chains ("finding all users of"): Value::use_begin/use_end
691 use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
692 --><!-- ======================================================================= -->
694 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
699 <td width="100%"> <font color="#eeeeff"
700 face="Georgia,Palatino"><b> <a name="simplechanges">Making simple
701 changes</a> </b></font></td>
706 There are some primitive transformation operations present in the LLVM
707 infrastructure that are worth knowing about. When performing
708 transformations, it's fairly common to manipulate the contents of basic
709 blocks. This section describes some of the common methods for doing so
710 and gives example code.<!--_______________________________________________________________________-->
713 <hr size="1"><a name="schanges_creating">Creating and inserting new <tt>Instruction</tt>s</a></h4>
715 <i>Instantiating Instructions</i>
716 <p>Creation of <tt>Instruction</tt>s is straightforward: simply call
717 the constructor for the kind of instruction to instantiate and provide
718 the necessary parameters. For example, an <tt>AllocaInst</tt> only <i>requires</i>
719 a (const-ptr-to) <tt>Type</tt>. Thus: </p>
720 <pre>AllocaInst* ai = new AllocaInst(Type::IntTy);</pre>
721 will create an <tt>AllocaInst</tt> instance that represents the
722 allocation of one integer in the current stack frame, at runtime. Each <tt>Instruction</tt>
723 subclass is likely to have varying default parameters which change the
724 semantics of the instruction, so refer to the <a
725 href="/doxygen/classInstruction.html">doxygen documentation for the
726 subclass of Instruction</a> that you're interested in instantiating.
727 <p><i>Naming values</i></p>
728 <p> It is very useful to name the values of instructions when you're
729 able to, as this facilitates the debugging of your transformations. If
730 you end up looking at generated LLVM machine code, you definitely want
731 to have logical names associated with the results of instructions! By
732 supplying a value for the <tt>Name</tt> (default) parameter of the <tt>Instruction</tt>
733 constructor, you associate a logical name with the result of the
734 instruction's execution at runtime. For example, say that I'm writing a
735 transformation that dynamically allocates space for an integer on the
736 stack, and that integer is going to be used as some kind of index by
737 some other code. To accomplish this, I place an <tt>AllocaInst</tt> at
738 the first point in the first <tt>BasicBlock</tt> of some <tt>Function</tt>,
739 and I'm intending to use it within the same <tt>Function</tt>. I
741 <pre>AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");</pre>
742 where <tt>indexLoc</tt> is now the logical name of the instruction's
743 execution value, which is a pointer to an integer on the runtime stack.
744 <p><i>Inserting instructions</i></p>
745 <p> There are essentially two ways to insert an <tt>Instruction</tt>
746 into an existing sequence of instructions that form a <tt>BasicBlock</tt>:</p>
748 <li>Insertion into an explicit instruction list
749 <p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt>
750 within that <tt>BasicBlock</tt>, and a newly-created instruction we
751 wish to insert before <tt>*pi</tt>, we do the following: </p>
752 <pre> BasicBlock *pb = ...;<br> Instruction *pi = ...;<br> Instruction *newInst = new Instruction(...);<br> pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb<br></pre>
754 <li>Insertion into an implicit instruction list
755 <p><tt>Instruction</tt> instances that are already in <tt>BasicBlock</tt>s
756 are implicitly associated with an existing instruction list: the
757 instruction list of the enclosing basic block. Thus, we could have
758 accomplished the same thing as the above code without being given a <tt>BasicBlock</tt>
760 <pre> Instruction *pi = ...;<br> Instruction *newInst = new Instruction(...);<br> pi->getParent()->getInstList().insert(pi, newInst);<br></pre>
761 In fact, this sequence of steps occurs so frequently that the <tt>Instruction</tt>
762 class and <tt>Instruction</tt>-derived classes provide constructors
763 which take (as a default parameter) a pointer to an <tt>Instruction</tt>
764 which the newly-created <tt>Instruction</tt> should precede. That is, <tt>Instruction</tt>
765 constructors are capable of inserting the newly-created instance into
766 the <tt>BasicBlock</tt> of a provided instruction, immediately before
767 that instruction. Using an <tt>Instruction</tt> constructor with a <tt>insertBefore</tt>
768 (default) parameter, the above code becomes:
769 <pre>Instruction* pi = ...;<br>Instruction* newInst = new Instruction(..., pi);<br></pre>
770 which is much cleaner, especially if you're creating a lot of
771 instructions and adding them to <tt>BasicBlock</tt>s. </li>
773 <!--_______________________________________________________________________-->
776 <hr size="1"><a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a></h4>
778 Deleting an instruction from an existing sequence of instructions that
779 form a <a href="#BasicBlock"><tt>BasicBlock</tt></a> is very
780 straightforward. First, you must have a pointer to the instruction that
781 you wish to delete. Second, you need to obtain the pointer to that
782 instruction's basic block. You use the pointer to the basic block to
783 get its list of instructions and then use the erase function to remove
787 <pre> <a href="#Instruction">Instruction</a> *I = .. ;<br> <a
788 href="#BasicBlock">BasicBlock</a> *BB = I->getParent();<br> BB->getInstList().erase(I);<br></pre>
789 <p><!--_______________________________________________________________________--> </p>
792 <hr size="1"><a name="schanges_replacing">Replacing an <tt>Instruction</tt>
793 with another <tt>Value</tt></a></h4>
795 <p><i>Replacing individual instructions</i></p>
796 <p> Including "<a href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>"
797 permits use of two very useful replace functions: <tt>ReplaceInstWithValue</tt>
798 and <tt>ReplaceInstWithInst</tt>. </p>
800 <h4><a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a></h4>
803 <li><tt>ReplaceInstWithValue</tt>
804 <p>This function replaces all uses (within a basic block) of a
805 given instruction with a value, and then removes the original
806 instruction. The following example illustrates the replacement of the
807 result of a particular <tt>AllocaInst</tt> that allocates memory for a
808 single integer with an null pointer to an integer.</p>
809 <pre>AllocaInst* instToReplace = ...;<br>BasicBlock::iterator ii(instToReplace);<br>ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,<br> Constant::getNullValue(PointerType::get(Type::IntTy)));<br></pre>
811 <li><tt>ReplaceInstWithInst</tt>
812 <p>This function replaces a particular instruction with another
813 instruction. The following example illustrates the replacement of one <tt>AllocaInst</tt>
816 <pre>AllocaInst* instToReplace = ...;<br>BasicBlock::iterator ii(instToReplace);<br>ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,<br> new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));<br></pre>
819 <p><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></p>
820 You can use <tt>Value::replaceAllUsesWith</tt> and <tt>User::replaceUsesOfWith</tt>
821 to change more than one use at a time. See the doxygen documentation
822 for the <a href="/doxygen/classValue.html">Value Class</a> and <a
823 href="/doxygen/classUser.html">User Class</a>, respectively, for more
824 information.<!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
825 include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
826 ReplaceInstWithValue, ReplaceInstWithInst
827 --><!-- *********************************************************************** -->
829 <table width="100%" bgcolor="#330077" border="0" cellpadding="4"
833 <td align="center"><font color="#eeeeff" size="+2"
834 face="Georgia,Palatino"><b> <a name="coreclasses">The Core LLVM Class
835 Hierarchy Reference </a></b></font></td>
840 <!-- *********************************************************************** -->
841 The Core LLVM classes are the primary means of representing the program
842 being inspected or transformed. The core LLVM classes are defined in
843 header files in the <tt>include/llvm/</tt> directory, and implemented in
844 the <tt>lib/VMCore</tt> directory.
845 <p><!-- ======================================================================= --> </p>
847 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
852 <td width="100%"> <font color="#eeeeff"
853 face="Georgia,Palatino"><b> <a name="Value">The <tt>Value</tt> class</a> </b></font></td>
858 <tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt><br>
859 doxygen info: <a href="/doxygen/classValue.html">Value Class</a>
860 <p> The <tt>Value</tt> class is the most important class in the LLVM
861 Source base. It represents a typed value that may be used (among other
862 things) as an operand to an instruction. There are many different types
863 of <tt>Value</tt>s, such as <a href="#Constant"><tt>Constant</tt></a>s,<a
864 href="#Argument"><tt>Argument</tt></a>s. Even <a href="#Instruction"><tt>Instruction</tt></a>s
865 and <a href="#Function"><tt>Function</tt></a>s are <tt>Value</tt>s.</p>
866 <p> A particular <tt>Value</tt> may be used many times in the LLVM
867 representation for a program. For example, an incoming argument to a
868 function (represented with an instance of the <a href="#Argument">Argument</a>
869 class) is "used" by every instruction in the function that references
870 the argument. To keep track of this relationship, the <tt>Value</tt>
871 class keeps a list of all of the <a href="#User"><tt>User</tt></a>s
872 that is using it (the <a href="#User"><tt>User</tt></a> class is a base
873 class for all nodes in the LLVM graph that can refer to <tt>Value</tt>s).
874 This use list is how LLVM represents def-use information in the
875 program, and is accessible through the <tt>use_</tt>* methods, shown
877 <p> Because LLVM is a typed representation, every LLVM <tt>Value</tt>
878 is typed, and this <a href="#Type">Type</a> is available through the <tt>getType()</tt>
879 method. In addition, all LLVM values can be named. The "name" of the <tt>Value</tt>
880 is a symbolic string printed in the LLVM code:</p>
882 <pre> %<b>foo</b> = add int 1, 2<br></pre>
883 <a name="#nameWarning">The name of this instruction is "foo". <b>NOTE</b>
884 that the name of any value may be missing (an empty string), so names
885 should <b>ONLY</b> be used for debugging (making the source code easier
886 to read, debugging printouts), they should not be used to keep track of
887 values or map between them. For this purpose, use a <tt>std::map</tt>
888 of pointers to the <tt>Value</tt> itself instead.</a>
889 <p> One important aspect of LLVM is that there is no distinction
890 between an SSA variable and the operation that produces it. Because of
891 this, any reference to the value produced by an instruction (or the
892 value available as an incoming argument, for example) is represented as
893 a direct pointer to the class that represents this value. Although
894 this may take some getting used to, it simplifies the representation
895 and makes it easier to manipulate.</p>
896 <p><!-- _______________________________________________________________________ --> </p>
899 <hr size="1"><a name="m_Value">Important Public Members of the <tt>Value</tt>
902 <li><tt>Value::use_iterator</tt> - Typedef for iterator over the
904 <tt>Value::use_const_iterator</tt> - Typedef for const_iterator over
906 <tt>unsigned use_size()</tt> - Returns the number of users of the
908 <tt>bool use_empty()</tt> - Returns true if there are no users.<br>
909 <tt>use_iterator use_begin()</tt> - Get an iterator to the start of
911 <tt>use_iterator use_end()</tt> - Get an iterator to the end of the
913 <tt><a href="#User">User</a> *use_back()</tt> - Returns the last
915 <p> These methods are the interface to access the def-use
916 information in LLVM. As with all other iterators in LLVM, the naming
917 conventions follow the conventions defined by the <a href="#stl">STL</a>.</p>
920 <li><tt><a href="#Type">Type</a> *getType() const</tt>
921 <p> This method returns the Type of the Value. </p>
923 <li><tt>bool hasName() const</tt><br>
924 <tt>std::string getName() const</tt><br>
925 <tt>void setName(const std::string &Name)</tt>
926 <p> This family of methods is used to access and assign a name to a <tt>Value</tt>,
927 be aware of the <a href="#nameWarning">precaution above</a>.</p>
930 <li><tt>void replaceAllUsesWith(Value *V)</tt>
931 <p> This method traverses the use list of a <tt>Value</tt> changing
932 all <a href="#User"><tt>User</tt>s</a> of the current value to refer to "<tt>V</tt>"
933 instead. For example, if you detect that an instruction always
934 produces a constant value (for example through constant folding), you
935 can replace all uses of the instruction with the constant like this:</p>
937 <pre> Inst->replaceAllUsesWith(ConstVal);<br></pre>
938 <p><!-- ======================================================================= --> </p>
941 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
946 <td width="100%"> <font color="#eeeeff"
947 face="Georgia,Palatino"><b> <a name="User">The <tt>User</tt> class</a> </b></font></td>
952 <tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt><br>
953 doxygen info: <a href="/doxygen/classUser.html">User Class</a><br>
954 Superclass: <a href="#Value"><tt>Value</tt></a>
955 <p> The <tt>User</tt> class is the common base class of all LLVM nodes
956 that may refer to <a href="#Value"><tt>Value</tt></a>s. It exposes a
957 list of "Operands" that are all of the <a href="#Value"><tt>Value</tt></a>s
958 that the User is referring to. The <tt>User</tt> class itself is a
959 subclass of <tt>Value</tt>.</p>
960 <p> The operands of a <tt>User</tt> point directly to the LLVM <a
961 href="#Value"><tt>Value</tt></a> that it refers to. Because LLVM uses
962 Static Single Assignment (SSA) form, there can only be one definition
963 referred to, allowing this direct connection. This connection provides
964 the use-def information in LLVM.</p>
965 <p><!-- _______________________________________________________________________ --> </p>
968 <hr size="1"><a name="m_User">Important Public Members of the <tt>User</tt>
971 The <tt>User</tt> class exposes the operand list in two ways: through
972 an index access interface and through an iterator based interface.
974 <li><tt>Value *getOperand(unsigned i)</tt><br>
975 <tt>unsigned getNumOperands()</tt>
976 <p> These two methods expose the operands of the <tt>User</tt> in a
977 convenient form for direct access.</p>
980 <li><tt>User::op_iterator</tt> - Typedef for iterator over the operand
982 <tt>User::op_const_iterator</tt> <tt>use_iterator op_begin()</tt> -
983 Get an iterator to the start of the operand list.<br>
984 <tt>use_iterator op_end()</tt> - Get an iterator to the end of the
986 <p> Together, these methods make up the iterator based interface to
987 the operands of a <tt>User</tt>.</p>
988 <p><!-- ======================================================================= --> </p>
991 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
996 <td width="100%"> <font color="#eeeeff"
997 face="Georgia,Palatino"><b> <a name="Instruction">The <tt>Instruction</tt>
998 class</a> </b></font></td>
1003 <tt>#include "</tt><tt><a href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt><br>
1004 doxygen info: <a href="/doxygen/classInstruction.html">Instruction
1006 Superclasses: <a href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a>
1007 <p> The <tt>Instruction</tt> class is the common base class for all
1008 LLVM instructions. It provides only a few methods, but is a very
1009 commonly used class. The primary data tracked by the <tt>Instruction</tt>
1010 class itself is the opcode (instruction type) and the parent <a
1011 href="#BasicBlock"><tt>BasicBlock</tt></a> the <tt>Instruction</tt> is
1012 embedded into. To represent a specific type of instruction, one of many
1013 subclasses of <tt>Instruction</tt> are used.</p>
1014 <p> Because the <tt>Instruction</tt> class subclasses the <a
1015 href="#User"><tt>User</tt></a> class, its operands can be accessed in
1016 the same way as for other <a href="#User"><tt>User</tt></a>s (with the <tt>getOperand()</tt>/<tt>getNumOperands()</tt>
1017 and <tt>op_begin()</tt>/<tt>op_end()</tt> methods).</p>
1018 <p> An important file for the <tt>Instruction</tt> class is the <tt>llvm/Instruction.def</tt>
1019 file. This file contains some meta-data about the various different
1020 types of instructions in LLVM. It describes the enum values that are
1021 used as opcodes (for example <tt>Instruction::Add</tt> and <tt>Instruction::SetLE</tt>),
1022 as well as the concrete sub-classes of <tt>Instruction</tt> that
1023 implement the instruction (for example <tt><a href="#BinaryOperator">BinaryOperator</a></tt>
1024 and <tt><a href="#SetCondInst">SetCondInst</a></tt>). Unfortunately,
1025 the use of macros in this file confuses doxygen, so these enum values
1026 don't show up correctly in the <a href="/doxygen/classInstruction.html">doxygen
1028 <p><!-- _______________________________________________________________________ --> </p>
1031 <hr size="1"><a name="m_Instruction">Important Public Members of the <tt>Instruction</tt>
1034 <li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt>
1035 <p> Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that
1036 this <tt>Instruction</tt> is embedded into.</p>
1039 <li><tt>bool mayWriteToMemory()</tt>
1040 <p> Returns true if the instruction writes to memory, i.e. it is a <tt>call</tt>,<tt>free</tt>,<tt>invoke</tt>,
1041 or <tt>store</tt>.</p>
1044 <li><tt>unsigned getOpcode()</tt>
1045 <p> Returns the opcode for the <tt>Instruction</tt>.</p>
1048 <li><tt><a href="#Instruction">Instruction</a> *clone() const</tt>
1049 <p> Returns another instance of the specified instruction, identical
1050 in all ways to the original except that the instruction has no parent
1051 (ie it's not embedded into a <a href="#BasicBlock"><tt>BasicBlock</tt></a>),
1052 and it has no name</p>
1055 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
1060 <td width="100%"> <font color="#eeeeff"
1061 face="Georgia,Palatino"><b> <a name="BasicBlock">The <tt>BasicBlock</tt>
1062 class</a> </b></font></td>
1067 <tt>#include "<a href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt><br>
1068 doxygen info: <a href="/doxygen/classBasicBlock.html">BasicBlock Class</a><br>
1069 Superclass: <a href="#Value"><tt>Value</tt></a>
1070 <p> This class represents a single entry multiple exit section of the
1071 code, commonly known as a basic block by the compiler community. The <tt>BasicBlock</tt>
1072 class maintains a list of <a href="#Instruction"><tt>Instruction</tt></a>s,
1073 which form the body of the block. Matching the language definition,
1074 the last element of this list of instructions is always a terminator
1075 instruction (a subclass of the <a href="#TerminatorInst"><tt>TerminatorInst</tt></a>
1077 <p> In addition to tracking the list of instructions that make up the
1078 block, the <tt>BasicBlock</tt> class also keeps track of the <a
1079 href="#Function"><tt>Function</tt></a> that it is embedded into.</p>
1080 <p> Note that <tt>BasicBlock</tt>s themselves are <a href="#Value"><tt>Value</tt></a>s,
1081 because they are referenced by instructions like branches and can go in
1082 the switch tables. <tt>BasicBlock</tt>s have type <tt>label</tt>.</p>
1083 <p><!-- _______________________________________________________________________ --> </p>
1086 <hr size="1"><a name="m_BasicBlock">Important Public Members of the <tt>BasicBlock</tt>
1089 <li><tt>BasicBlock(const std::string &Name = "", </tt><tt><a
1090 href="#Function">Function</a> *Parent = 0)</tt>
1091 <p> The <tt>BasicBlock</tt> constructor is used to create new basic
1092 blocks for insertion into a function. The constructor optionally takes
1093 a name for the new block, and a <a href="#Function"><tt>Function</tt></a>
1094 to insert it into. If the <tt>Parent</tt> parameter is specified, the
1095 new <tt>BasicBlock</tt> is automatically inserted at the end of the
1096 specified <a href="#Function"><tt>Function</tt></a>, if not specified,
1097 the BasicBlock must be manually inserted into the <a href="#Function"><tt>Function</tt></a>.</p>
1100 <li><tt>BasicBlock::iterator</tt> - Typedef for instruction list
1102 <tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
1103 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,<tt>size()</tt>,<tt>empty()</tt>,<tt>rbegin()</tt>,<tt>rend()
1104 - </tt>STL style functions for accessing the instruction list.
1105 <p> These methods and typedefs are forwarding functions that have
1106 the same semantics as the standard library methods of the same names.
1107 These methods expose the underlying instruction list of a basic block in
1108 a way that is easy to manipulate. To get the full complement of
1109 container operations (including operations to update the list), you must
1110 use the <tt>getInstList()</tt> method.</p>
1113 <li><tt>BasicBlock::InstListType &getInstList()</tt>
1114 <p> This method is used to get access to the underlying container
1115 that actually holds the Instructions. This method must be used when
1116 there isn't a forwarding function in the <tt>BasicBlock</tt> class for
1117 the operation that you would like to perform. Because there are no
1118 forwarding functions for "updating" operations, you need to use this if
1119 you want to update the contents of a <tt>BasicBlock</tt>.</p>
1122 <li><tt><a href="#Function">Function</a> *getParent()</tt>
1123 <p> Returns a pointer to <a href="#Function"><tt>Function</tt></a>
1124 the block is embedded into, or a null pointer if it is homeless.</p>
1127 <li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt>
1128 <p> Returns a pointer to the terminator instruction that appears at
1129 the end of the <tt>BasicBlock</tt>. If there is no terminator
1130 instruction, or if the last instruction in the block is not a
1131 terminator, then a null pointer is returned.</p>
1132 <p><!-- ======================================================================= --> </p>
1135 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
1140 <td width="100%"> <font color="#eeeeff"
1141 face="Georgia,Palatino"><b> <a name="GlobalValue">The <tt>GlobalValue</tt>
1142 class</a> </b></font></td>
1147 <tt>#include "<a href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt><br>
1148 doxygen info: <a href="/doxygen/classGlobalValue.html">GlobalValue
1150 Superclasses: <a href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a>
1151 <p> Global values (<a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s
1152 or <a href="#Function"><tt>Function</tt></a>s) are the only LLVM
1153 values that are visible in the bodies of all <a href="#Function"><tt>Function</tt></a>s.
1154 Because they are visible at global scope, they are also subject to
1155 linking with other globals defined in different translation units. To
1156 control the linking process, <tt>GlobalValue</tt>s know their linkage
1157 rules. Specifically, <tt>GlobalValue</tt>s know whether they have
1158 internal or external linkage, as defined by the <span
1159 style="font-family: monospace;">LinkageTypes</span> enumerator.</p>
1160 <p> If a <tt>GlobalValue</tt> has internal linkage (equivalent to
1161 being <tt>static</tt> in C), it is not visible to code outside the
1162 current translation unit, and does not participate in linking. If it
1163 has external linkage, it is visible to external code, and does
1164 participate in linking. In addition to linkage information, <tt>GlobalValue</tt>s
1165 keep track of which <a href="#Module"><tt>Module</tt></a> they are
1166 currently part of.</p>
1167 <p> Because <tt>GlobalValue</tt>s are memory objects, they are always
1168 referred to by their <span style="font-weight: bold;">address</span><span
1169 style="font-weight: bold;">.</span> As such, the <a href="#Type"><tt>Type</tt></a>
1170 of a global is always a pointer to its contents. It is important to
1171 remember this when using the <span style="font-family: monospace;">GetElementPtrInst</span>
1172 instruction because this pointer must be dereferenced first. For
1173 example, if you have a <span style="font-family: monospace;">GlobalVariable</span>
1174 (a subclass of <span style="font-family: monospace;">GlobalValue)</span>
1175 that is an array of 24 ints, type <span style="font-family: monospace;">[24
1176 x int]</span>, then the <span style="font-family: monospace;">GlobalVariable</span>
1177 is a pointer to that array. Although the address of the first element of
1178 this array and the value of the <span style="font-family: monospace;">GlobalVariable</span>
1179 are the same, they have different types. The <span
1180 style="font-family: monospace;">GlobalVariable</span>'s type is <span
1181 style="font-family: monospace;">[24 x int]</span>. The first element's
1182 type is <span style="font-family: monospace;">int.</span> Because of
1183 this, accessing a global value requires you to dereference the pointer
1184 with <span style="font-family: monospace;">GetElementPtrInst</span>
1185 first, then its elements can be accessed. This is explained in
1186 the <a href="LangRef.html#globalvars">LLVM Language Reference Manual</a>.</p>
1187 <p><!-- _______________________________________________________________________ --> </p>
1190 <hr size="1"><a name="m_GlobalValue">Important Public Members of the <tt>GlobalValue</tt>
1193 <li><tt>bool hasInternalLinkage() const</tt><br>
1194 <tt>bool hasExternalLinkage() const</tt><br>
1195 <tt>void setInternalLinkage(bool HasInternalLinkage)</tt>
1196 <p> These methods manipulate the linkage characteristics of the <tt>GlobalValue</tt>.</p>
1199 <li><tt><a href="#Module">Module</a> *getParent()</tt>
1200 <p> This returns the <a href="#Module"><tt>Module</tt></a> that the
1201 GlobalValue is currently embedded into.</p>
1202 <p><!-- ======================================================================= --> </p>
1205 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
1210 <td width="100%"> <font color="#eeeeff"
1211 face="Georgia,Palatino"><b> <a name="Function">The <tt>Function</tt>
1212 class</a> </b></font></td>
1217 <tt>#include "<a href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt><br>
1218 doxygen info: <a href="/doxygen/classFunction.html">Function Class</a><br>
1219 Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
1220 href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a>
1221 <p> The <tt>Function</tt> class represents a single procedure in LLVM.
1222 It is actually one of the more complex classes in the LLVM heirarchy
1223 because it must keep track of a large amount of data. The <tt>Function</tt>
1224 class keeps track of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s,
1225 a list of formal <a href="#Argument"><tt>Argument</tt></a>s, and a <a
1226 href="#SymbolTable"><tt>SymbolTable</tt></a>.</p>
1227 <p> The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the
1228 most commonly used part of <tt>Function</tt> objects. The list imposes
1229 an implicit ordering of the blocks in the function, which indicate how
1230 the code will be layed out by the backend. Additionally, the first <a
1231 href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node
1232 for the <tt>Function</tt>. It is not legal in LLVM to explicitly
1233 branch to this initial block. There are no implicit exit nodes, and in
1234 fact there may be multiple exit nodes from a single <tt>Function</tt>.
1235 If the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list is empty,
1236 this indicates that the <tt>Function</tt> is actually a function
1237 declaration: the actual body of the function hasn't been linked in yet.</p>
1238 <p> In addition to a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s,
1239 the <tt>Function</tt> class also keeps track of the list of formal <a
1240 href="#Argument"><tt>Argument</tt></a>s that the function receives.
1241 This container manages the lifetime of the <a href="#Argument"><tt>Argument</tt></a>
1242 nodes, just like the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list
1243 does for the <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.</p>
1244 <p> The <a href="#SymbolTable"><tt>SymbolTable</tt></a> is a very
1245 rarely used LLVM feature that is only used when you have to look up a
1246 value by name. Aside from that, the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
1247 is used internally to make sure that there are not conflicts between the
1248 names of <a href="#Instruction"><tt>Instruction</tt></a>s, <a
1249 href="#BasicBlock"><tt>BasicBlock</tt></a>s, or <a href="#Argument"><tt>Argument</tt></a>s
1250 in the function body.</p>
1251 <p><!-- _______________________________________________________________________ --> </p>
1254 <hr size="1"><a name="m_Function">Important Public Members of the <tt>Function</tt>
1257 <li><tt>Function(const </tt><tt><a href="#FunctionType">FunctionType</a>
1258 *Ty, bool isInternal, const std::string &N = "", Module* Parent = 0)</tt>
1259 <p> Constructor used when you need to create new <tt>Function</tt>s
1260 to add the the program. The constructor must specify the type of the
1261 function to create and whether or not it should start out with internal
1262 or external linkage. The <a href="#FunctionType"
1263 style="font-family: monospace;">FunctionType</a> argument specifies the
1264 formal arguments and return value for the function. The same <a
1265 href="#FunctionTypel" style="font-family: monospace;">FunctionType</a>
1266 value can be used to create multiple functions. The <span
1267 style="font-family: monospace;">Parent</span> argument specifies the
1268 Module in which the function is defined. If this argument is provided,
1269 the function will automatically be inserted into that module's list of
1273 <li><tt>bool isExternal()</tt>
1274 <p> Return whether or not the <tt>Function</tt> has a body defined.
1275 If the function is "external", it does not have a body, and thus must be
1276 resolved by linking with a function defined in a different translation
1280 <li><tt>Function::iterator</tt> - Typedef for basic block list iterator<br>
1281 <tt>Function::const_iterator</tt> - Typedef for const_iterator.<br>
1282 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,<tt>size()</tt>,<tt>empty()</tt>,<tt>rbegin()</tt>,<tt>rend()</tt>
1283 <p> These are forwarding methods that make it easy to access the
1284 contents of a <tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
1288 <li><tt>Function::BasicBlockListType &getBasicBlockList()</tt>
1289 <p> Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.
1290 This is necessary to use when you need to update the list or perform a
1291 complex action that doesn't have a forwarding method.</p>
1294 <li><tt>Function::aiterator</tt> - Typedef for the argument list
1296 <tt>Function::const_aiterator</tt> - Typedef for const_iterator.<br>
1297 <tt>abegin()</tt>, <tt>aend()</tt>, <tt>afront()</tt>, <tt>aback()</tt>,<tt>asize()</tt>,<tt>aempty()</tt>,<tt>arbegin()</tt>,<tt>arend()</tt>
1298 <p> These are forwarding methods that make it easy to access the
1299 contents of a <tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a>
1303 <li><tt>Function::ArgumentListType &getArgumentList()</tt>
1304 <p> Returns the list of <a href="#Argument"><tt>Argument</tt></a>s.
1305 This is necessary to use when you need to update the list or perform a
1306 complex action that doesn't have a forwarding method.</p>
1309 <li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryBlock()</tt>
1310 <p> Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a>
1311 for the function. Because the entry block for the function is always
1312 the first block, this returns the first block of the <tt>Function</tt>.</p>
1315 <li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
1316 <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt>
1317 <p> This traverses the <a href="#Type"><tt>Type</tt></a> of the <tt>Function</tt>
1318 and returns the return type of the function, or the <a
1319 href="#FunctionType"><tt>FunctionType</tt></a> of the actual function.</p>
1322 <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
1323 <p> Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
1324 for this <tt>Function</tt>.</p>
1325 <p><!-- ======================================================================= --> </p>
1328 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
1333 <td width="100%"> <font color="#eeeeff"
1334 face="Georgia,Palatino"><b> <a name="GlobalVariable">The <tt>GlobalVariable</tt>
1335 class</a> </b></font></td>
1340 <tt>#include "<a href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt><br>
1341 doxygen info: <a href="/doxygen/classGlobalVariable.html">GlobalVariable
1343 Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
1344 href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a>
1345 <p> Global variables are represented with the (suprise suprise) <tt>GlobalVariable</tt>
1346 class. Like functions, <tt>GlobalVariable</tt>s are also subclasses of <a
1347 href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such are always
1348 referenced by their address (global values must live in memory, so their
1349 "name" refers to their address). See <a href="#GlobalValue"><span
1350 style="font-family: monospace;">GlobalValue</span></a> for more on
1351 this. Global variables may have an initial value (which must be a <a
1352 href="#Constant"><tt>Constant</tt></a>), and if they have an
1353 initializer, they may be marked as "constant" themselves (indicating
1354 that their contents never change at runtime). </p>
1355 <p><!-- _______________________________________________________________________ --> </p>
1358 <hr size="1"><a name="m_GlobalVariable">Important Public Members of the <tt>GlobalVariable</tt>
1361 <li><tt>GlobalVariable(const </tt><tt><a href="#Type">Type</a> *Ty,
1362 bool isConstant, LinkageTypes& Linkage, <a href="#Constant">Constant</a>
1363 *Initializer = 0, const std::string &Name = "", Module* Parent = 0)</tt>
1364 <p> Create a new global variable of the specified type. If <tt>isConstant</tt>
1365 is true then the global variable will be marked as unchanging for the
1366 program. The Linkage parameter specifies the type of linkage (internal,
1367 external, weak, linkonce, appending) for the variable. If the linkage
1368 is InternalLinkage, WeakLinkage, or LinkOnceLinkage, then the
1369 resultant global variable will have internal linkage. AppendingLinkage
1370 concatenates together all instances (in different translation units) of
1371 the variable into a single variable but is only applicable to arrays.
1372 See the <a href="LangRef.html#modulestructure">LLVM Language
1373 Reference</a> for further details on linkage types. Optionally an
1374 initializer, a name, and the module to put the variable into may be
1375 specified for the global variable as well.</p>
1378 <li><tt>bool isConstant() const</tt>
1379 <p> Returns true if this is a global variable that is known not to
1380 be modified at runtime.</p>
1383 <li><tt>bool hasInitializer()</tt>
1384 <p> Returns true if this <tt>GlobalVariable</tt> has an intializer.</p>
1387 <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt>
1388 <p> Returns the intial value for a <tt>GlobalVariable</tt>. It is
1389 not legal to call this method if there is no initializer.</p>
1390 <p><!-- ======================================================================= --> </p>
1393 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
1398 <td width="100%"> <font color="#eeeeff"
1399 face="Georgia,Palatino"><b> <a name="Module">The <tt>Module</tt> class</a> </b></font></td>
1404 <tt>#include "<a href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt><br>
1405 doxygen info: <a href="/doxygen/classModule.html">Module Class</a>
1406 <p> The <tt>Module</tt> class represents the top level structure
1407 present in LLVM programs. An LLVM module is effectively either a
1408 translation unit of the original program or a combination of several
1409 translation units merged by the linker. The <tt>Module</tt> class keeps
1410 track of a list of <a href="#Function"><tt>Function</tt></a>s, a list
1411 of <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
1412 href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it
1413 contains a few helpful member functions that try to make common
1414 operations easy.</p>
1415 <p><!-- _______________________________________________________________________ --> </p>
1418 <hr size="1"><a name="m_Module">Important Public Members of the <tt>Module</tt>
1419 class<span style="font-family: monospace;"></span></a></h4>
1421 <li><span style="font-family: monospace;">Module::Module( std::string
1422 name = "" ) </span></li>
1424 <p style="margin-left: 40px;">Constructing a <a href="#Module">Module</a>
1425 is easy. You can optionally provide a name for it (probably based on the
1426 name of the translation unit).</p>
1428 <li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
1429 <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
1430 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,<tt>size()</tt>,<tt>empty()</tt>,<tt>rbegin()</tt>,<tt>rend()</tt>
1431 <p> These are forwarding methods that make it easy to access the
1432 contents of a <tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
1436 <li><tt>Module::FunctionListType &getFunctionList()</tt>
1437 <p> Returns the list of <a href="#Function"><tt>Function</tt></a>s.
1438 This is necessary to use when you need to update the list or perform a
1439 complex action that doesn't have a forwarding method.</p>
1440 <p><!-- Global Variable --> </p>
1442 <li><tt>Module::giterator</tt> - Typedef for global variable list
1444 <tt>Module::const_giterator</tt> - Typedef for const_iterator.<br>
1445 <tt>gbegin()</tt>, <tt>gend()</tt>, <tt>gfront()</tt>, <tt>gback()</tt>,<tt>gsize()</tt>,<tt>gempty()</tt>,<tt>grbegin()</tt>,<tt>grend()</tt>
1446 <p> These are forwarding methods that make it easy to access the
1447 contents of a <tt>Module</tt> object's <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>
1451 <li><tt>Module::GlobalListType &getGlobalList()</tt>
1452 <p> Returns the list of <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s.
1453 This is necessary to use when you need to update the list or perform a
1454 complex action that doesn't have a forwarding method.</p>
1455 <p><!-- Symbol table stuff --> </p>
1457 <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
1458 <p> Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
1459 for this <tt>Module</tt>.</p>
1460 <p><!-- Convenience methods --> </p>
1462 <li><tt><a href="#Function">Function</a> *getFunction(const
1463 std::string &Name, const <a href="#FunctionType">FunctionType</a>
1465 <p> Look up the specified function in the <tt>Module</tt> <a
1466 href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist,
1467 return <tt>null</tt>.</p>
1470 <li><tt><a href="#Function">Function</a> *getOrInsertFunction(const
1471 std::string &Name, const <a href="#FunctionType">FunctionType</a> *T)</tt>
1472 <p> Look up the specified function in the <tt>Module</tt> <a
1473 href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist,
1474 add an external declaration for the function and return it.</p>
1477 <li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt>
1478 <p> If there is at least one entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
1479 for the specified <a href="#Type"><tt>Type</tt></a>, return it.
1480 Otherwise return the empty string.</p>
1483 <li><tt>bool addTypeName(const std::string &Name, const <a
1484 href="#Type">Type</a> *Ty)</tt>
1485 <p> Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
1486 mapping <tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for
1487 this name, true is returned and the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
1488 is not modified.</p>
1489 <p><!-- ======================================================================= --> </p>
1492 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
1497 <td width="100%"> <font color="#eeeeff"
1498 face="Georgia,Palatino"><b> <a name="Constant">The <tt>Constant</tt>
1499 class and subclasses</a> </b></font></td>
1504 Constant represents a base class for different types of constants. It
1505 is subclassed by ConstantBool, ConstantInt, ConstantSInt, ConstantUInt,
1506 ConstantArray etc for representing the various types of Constants.
1507 <p><!-- _______________________________________________________________________ --> </p>
1510 <hr size="1"><a name="m_Value">Important Public Methods</a></h4>
1512 <li><tt>bool isConstantExpr()</tt>: Returns true if it is a
1514 <hr> Important Subclasses of Constant
1517 <li>ConstantSInt : This subclass of Constant represents a signed
1520 <li><tt>int64_t getValue() const</tt>: Returns the underlying value of
1521 this constant. </li>
1524 <li>ConstantUInt : This class represents an unsigned integer.
1526 <li><tt>uint64_t getValue() const</tt>: Returns the underlying value
1527 of this constant. </li>
1530 <li>ConstantFP : This class represents a floating point constant.
1532 <li><tt>double getValue() const</tt>: Returns the underlying value of
1533 this constant. </li>
1536 <li>ConstantBool : This represents a boolean constant.
1538 <li><tt>bool getValue() const</tt>: Returns the underlying value of
1539 this constant. </li>
1542 <li>ConstantArray : This represents a constant array.
1544 <li><tt>const std::vector<Use> &getValues() const</tt>:
1545 Returns a Vecotr of component constants that makeup this array. </li>
1548 <li>ConstantStruct : This represents a constant struct.
1550 <li><tt>const std::vector<Use> &getValues() const</tt>:
1551 Returns a Vecotr of component constants that makeup this array. </li>
1554 <li>ConstantPointerRef : This represents a constant pointer value
1555 that is initialized to point to a global value, which lies at a
1556 constant fixed address.
1558 <li><tt>GlobalValue *getValue()</tt>: Returns the global
1559 value to which this pointer is pointing to. </li>
1563 <!-- ======================================================================= --> </li>
1565 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
1570 <td width="100%"> <font color="#eeeeff"
1571 face="Georgia,Palatino"><b> <a name="Type">The <tt>Type</tt> class and
1572 Derived Types</a> </b></font></td>
1577 Type as noted earlier is also a subclass of a Value class. Any
1578 primitive type (like int, short etc) in LLVM is an instance of Type
1579 Class. All other types are instances of subclasses of type like
1580 FunctionType, ArrayType etc. DerivedType is the interface for all such
1581 dervied types including FunctionType, ArrayType, PointerType,
1582 StructType. Types can have names. They can be recursive (StructType).
1583 There exists exactly one instance of any type structure at a time. This
1584 allows using pointer equality of Type *s for comparing types.<!-- _______________________________________________________________________ -->
1587 <hr size="1"><a name="m_Value">Important Public Methods</a></h4>
1589 <li><tt>PrimitiveID getPrimitiveID() const</tt>: Returns the base
1590 type of the type. </li>
1591 <li><tt> bool isSigned() const</tt>: Returns whether an integral
1592 numeric type is signed. This is true for SByteTy, ShortTy, IntTy,
1593 LongTy. Note that this is not true for Float and Double. </li>
1594 <li><tt>bool isUnsigned() const</tt>: Returns whether a numeric type
1595 is unsigned. This is not quite the complement of isSigned... nonnumeric
1596 types return false as they do with isSigned. This returns true for
1597 UByteTy, UShortTy, UIntTy, and ULongTy. </li>
1598 <li><tt> bool isInteger() const</tt>: Equilivent to isSigned() ||
1599 isUnsigned(), but with only a single virtual function invocation. </li>
1600 <li><tt>bool isIntegral() const</tt>: Returns true if this is an
1601 integral type, which is either Bool type or one of the Integer types. </li>
1602 <li><tt>bool isFloatingPoint()</tt>: Return true if this is one of
1603 the two floating point types. </li>
1604 <li><tt>bool isRecursive() const</tt>: Returns rue if the type graph
1605 contains a cycle. </li>
1606 <li><tt>isLosslesslyConvertableTo (const Type *Ty) const</tt>: Return
1607 true if this type can be converted to 'Ty' without any reinterpretation
1608 of bits. For example, uint to int. </li>
1609 <li><tt>bool isPrimitiveType() const</tt>: Returns true if it is a
1610 primitive type. </li>
1611 <li><tt>bool isDerivedType() const</tt>: Returns true if it is a
1613 <li><tt>const Type * getContainedType (unsigned i) const</tt>: This
1614 method is used to implement the type iterator. For derived types, this
1615 returns the types 'contained' in the derived type, returning 0 when 'i'
1616 becomes invalid. This allows the user to iterate over the types in a
1617 struct, for example, really easily. </li>
1618 <li><tt>unsigned getNumContainedTypes() const</tt>: Return the number
1619 of types in the derived type.
1624 <li>SequentialType : This is subclassed by ArrayType and
1627 <li><tt>const Type * getElementType() const</tt>: Returns the type of
1628 each of the elements in the sequential type. </li>
1631 <li>ArrayType : This is a subclass of SequentialType and defines
1632 interface for array types.
1634 <li><tt>unsigned getNumElements() const</tt>: Returns the number of
1635 elements in the array. </li>
1638 <li>PointerType : Subclass of SequentialType for pointer types. </li>
1639 <li>StructType : subclass of DerivedTypes for struct types </li>
1640 <li>FunctionType : subclass of DerivedTypes for function types.
1642 <li><tt>bool isVarArg() const</tt>: Returns true if its a vararg
1644 <li><tt> const Type * getReturnType() const</tt>: Returns the
1645 return type of the function. </li>
1646 <li><tt> const ParamTypes &getParamTypes() const</tt>:
1647 Returns a vector of parameter types. </li>
1648 <li><tt>const Type * getParamType (unsigned i)</tt>: Returns
1649 the type of the ith parameter. </li>
1650 <li><tt> const unsigned getNumParams() const</tt>: Returns the
1651 number of formal parameters. </li>
1655 <!-- ======================================================================= --> </li>
1657 <table width="100%" bgcolor="#441188" border="0" cellpadding="4"
1662 <td width="100%"> <font color="#eeeeff"
1663 face="Georgia,Palatino"><b> <a name="Argument">The <tt>Argument</tt>
1664 class</a> </b></font></td>
1669 This subclass of Value defines the interface for incoming formal
1670 arguments to a function. A Function maitanis a list of its formal
1671 arguments. An argument has a pointer to the parent Function.<!-- *********************************************************************** -->
1673 <!-- *********************************************************************** -->
1674 <hr><font size-1="">
1675 <address>By: <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>
1676 and <a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
1677 </font><font size-1=""><a href="http://llvm.cs.uiuc.edu">The LLVM
1678 Compiler Infrastructure</a> <br>
1679 <!-- Created: Tue Aug 6 15:00:33 CDT 2002 --><!-- hhmts start --> Last
1680 modified: Fri Nov 7 13:24:22 CST 2003<!-- hhmts end --> </font>
projects / oota-llvm.git / blob