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