Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 4b28793c85d264f5f6285e4e7367df34a1c7057f / . / docs / ProgrammersManual.html
blob: b5d587be31fe3c21ea5f92cbf489a5e346c4e0e2 [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 = ...;
Joel Stanley4b287932002-09-29 17:31:54 +0000[diff] [blame^]885BasicBlock::iterator ii(instToReplace);
886ReplaceInstWithValue(instToReplace-&gt;getParent()-&gt;getInstList(), ii,
Joel Stanley9dd1ad62002-09-18 03:17:23 +0000[diff] [blame]887 Constant::getNullValue(PointerType::get(Type::IntTy)));
888</pre>
889
Chris Lattner7dbf6832002-09-18 05:14:25 +0000[diff] [blame]890<li><tt>ReplaceInstWithInst</tt>
Joel Stanley9dd1ad62002-09-18 03:17:23 +0000[diff] [blame]891
892<p>This function replaces a particular instruction with another
893instruction. The following example illustrates the replacement of one
894<tt>AllocaInst</tt> with another.<p>
895
896<pre>
897AllocaInst* instToReplace = ...;
Joel Stanley4b287932002-09-29 17:31:54 +0000[diff] [blame^]898BasicBlock::iterator ii(instToReplace);
899ReplaceInstWithInst(instToReplace-&gt;getParent()-&gt;getInstList(), ii,
Joel Stanley9dd1ad62002-09-18 03:17:23 +0000[diff] [blame]900 new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt");
901</pre>
902
903</ul>
904<p><i>Replacing multiple uses of <tt>User</tt>s and
905 <tt>Value</tt>s</i></p>
906
907You can use <tt>Value::replaceAllUsesWith</tt> and
908<tt>User::replaceUsesOfWith</tt> to change more than one use at a
909time. See the doxygen documentation for the <a
910href="/doxygen/classValue.html">Value Class</a> and <a
911href="/doxygen/classUser.html">User Class</a>, respectively, for more
912information.
913
914<!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
915include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
916ReplaceInstWithValue, ReplaceInstWithInst
Chris Lattnerae7f7592002-09-06 18:31:18 +0000[diff] [blame]917-->
Chris Lattnerb99344f2002-09-06 16:40:10 +0000[diff] [blame]918
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]919<!-- *********************************************************************** -->
920</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
921<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Joel Stanley9b96c442002-09-06 21:55:13 +0000[diff] [blame]922<a name="coreclasses">The Core LLVM Class Hierarchy Reference
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]923</b></font></td></tr></table><ul>
924<!-- *********************************************************************** -->
925
926The Core LLVM classes are the primary means of representing the program being
927inspected or transformed. The core LLVM classes are defined in header files in
928the <tt>include/llvm/</tt> directory, and implemented in the <tt>lib/VMCore</tt>
929directory.<p>
930
931
932<!-- ======================================================================= -->
933</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
934<tr><td>&nbsp;</td><td width="100%">&nbsp;
935<font color="#EEEEFF" face="Georgia,Palatino"><b>
936<a name="Value">The <tt>Value</tt> class</a>
937</b></font></td></tr></table><ul>
938
939<tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt></b><br>
940doxygen info: <a href="/doxygen/classValue.html">Value Class</a><p>
941
942
943The <tt>Value</tt> class is the most important class in LLVM Source base. It
944represents a typed value that may be used (among other things) as an operand to
945an instruction. There are many different types of <tt>Value</tt>s, such as <a
946href="#Constant"><tt>Constant</tt></a>s, <a
947href="#Argument"><tt>Argument</tt></a>s, and even <a
948href="#Instruction"><tt>Instruction</tt></a>s and <a
949href="#Function"><tt>Function</tt></a>s are <tt>Value</tt>s.<p>
950
951A particular <tt>Value</tt> may be used many times in the LLVM representation
952for a program. For example, an incoming argument to a function (represented
953with an instance of the <a href="#Argument">Argument</a> class) is "used" by
954every instruction in the function that references the argument. To keep track
955of this relationship, the <tt>Value</tt> class keeps a list of all of the <a
956href="#User"><tt>User</tt></a>s that is using it (the <a
957href="#User"><tt>User</tt></a> class is a base class for all nodes in the LLVM
958graph 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]959def-use information in the program, and is accessible through the <tt>use_</tt>*
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]960methods, shown below.<p>
961
962Because LLVM is a typed representation, every LLVM <tt>Value</tt> is typed, and
963this <a href="#Type">Type</a> is available through the <tt>getType()</tt>
964method. <a name="#nameWarning">In addition, all LLVM values can be named. The
965"name" of the <tt>Value</tt> is symbolic string printed in the LLVM code:<p>
966
967<pre>
968 %<b>foo</b> = add int 1, 2
969</pre>
970
971The name of this instruction is "foo". <b>NOTE</b> that the name of any value
972may be missing (an empty string), so names should <b>ONLY</b> be used for
973debugging (making the source code easier to read, debugging printouts), they
974should not be used to keep track of values or map between them. For this
975purpose, use a <tt>std::map</tt> of pointers to the <tt>Value</tt> itself
976instead.<p>
977
978One important aspect of LLVM is that there is no distinction between an SSA
979variable and the operation that produces it. Because of this, any reference to
980the value produced by an instruction (or the value available as an incoming
981argument, for example) is represented as a direct pointer to the class that
982represents this value. Although this may take some getting used to, it
983simplifies the representation and makes it easier to manipulate.<p>
984
985
986<!-- _______________________________________________________________________ -->
987</ul><h4><a name="m_Value"><hr size=0>Important Public Members of
988the <tt>Value</tt> class</h4><ul>
989
990<li><tt>Value::use_iterator</tt> - Typedef for iterator over the use-list<br>
991 <tt>Value::use_const_iterator</tt>
992 - Typedef for const_iterator over the use-list<br>
993 <tt>unsigned use_size()</tt> - Returns the number of users of the value.<br>
994 <tt>bool use_empty()</tt> - Returns true if there are no users.<br>
995 <tt>use_iterator use_begin()</tt>
996 - Get an iterator to the start of the use-list.<br>
997 <tt>use_iterator use_end()</tt>
998 - Get an iterator to the end of the use-list.<br>
999 <tt><a href="#User">User</a> *use_back()</tt>
1000 - Returns the last element in the list.<p>
1001
1002These 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>
1003
1004<li><tt><a href="#Type">Type</a> *getType() const</tt><p>
1005This method returns the Type of the Value.
1006
1007<li><tt>bool hasName() const</tt><br>
1008 <tt>std::string getName() const</tt><br>
1009 <tt>void setName(const std::string &amp;Name)</tt><p>
1010
1011This family of methods is used to access and assign a name to a <tt>Value</tt>,
1012be aware of the <a href="#nameWarning">precaution above</a>.<p>
1013
1014
1015<li><tt>void replaceAllUsesWith(Value *V)</tt><p>
1016
1017This method traverses the use list of a <tt>Value</tt> changing all <a
Misha Brukmanc4f5bb02002-09-18 02:21:57 +0000[diff] [blame]1018href="#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]1019instead. For example, if you detect that an instruction always produces a
1020constant value (for example through constant folding), you can replace all uses
1021of the instruction with the constant like this:<p>
1022
1023<pre>
1024 Inst-&gt;replaceAllUsesWith(ConstVal);
1025</pre><p>
1026
1027
1028
1029<!-- ======================================================================= -->
1030</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1031<tr><td>&nbsp;</td><td width="100%">&nbsp;
1032<font color="#EEEEFF" face="Georgia,Palatino"><b>
1033<a name="User">The <tt>User</tt> class</a>
1034</b></font></td></tr></table><ul>
1035
1036<tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt></b><br>
1037doxygen info: <a href="/doxygen/classUser.html">User Class</a><br>
1038Superclass: <a href="#Value"><tt>Value</tt></a><p>
1039
1040
1041The <tt>User</tt> class is the common base class of all LLVM nodes that may
1042refer to <a href="#Value"><tt>Value</tt></a>s. It exposes a list of "Operands"
1043that are all of the <a href="#Value"><tt>Value</tt></a>s that the User is
1044referring to. The <tt>User</tt> class itself is a subclass of
1045<tt>Value</tt>.<p>
1046
1047The operands of a <tt>User</tt> point directly to the LLVM <a
1048href="#Value"><tt>Value</tt></a> that it refers to. Because LLVM uses Static
1049Single Assignment (SSA) form, there can only be one definition referred to,
1050allowing this direct connection. This connection provides the use-def
1051information in LLVM.<p>
1052
1053<!-- _______________________________________________________________________ -->
1054</ul><h4><a name="m_User"><hr size=0>Important Public Members of
1055the <tt>User</tt> class</h4><ul>
1056
1057The <tt>User</tt> class exposes the operand list in two ways: through an index
1058access interface and through an iterator based interface.<p>
1059
1060<li><tt>Value *getOperand(unsigned i)</tt><br>
1061 <tt>unsigned getNumOperands()</tt><p>
1062
1063These two methods expose the operands of the <tt>User</tt> in a convenient form
1064for direct access.<p>
1065
1066<li><tt>User::op_iterator</tt> - Typedef for iterator over the operand list<br>
1067 <tt>User::op_const_iterator</tt>
1068 <tt>use_iterator op_begin()</tt>
1069 - Get an iterator to the start of the operand list.<br>
1070 <tt>use_iterator op_end()</tt>
1071 - Get an iterator to the end of the operand list.<p>
1072
1073Together, these methods make up the iterator based interface to the operands of
1074a <tt>User</tt>.<p>
1075
1076
1077
1078<!-- ======================================================================= -->
1079</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1080<tr><td>&nbsp;</td><td width="100%">&nbsp;
1081<font color="#EEEEFF" face="Georgia,Palatino"><b>
1082<a name="Instruction">The <tt>Instruction</tt> class</a>
1083</b></font></td></tr></table><ul>
1084
1085<tt>#include "<a
1086href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt></b><br>
1087doxygen info: <a href="/doxygen/classInstruction.html">Instruction Class</a><br>
1088Superclasses: <a href="#User"><tt>User</tt></a>, <a
1089href="#Value"><tt>Value</tt></a><p>
1090
1091The <tt>Instruction</tt> class is the common base class for all LLVM
1092instructions. It provides only a few methods, but is a very commonly used
1093class. The primary data tracked by the <tt>Instruction</tt> class itself is the
1094opcode (instruction type) and the parent <a
1095href="#BasicBlock"><tt>BasicBlock</tt></a> the <tt>Instruction</tt> is embedded
1096into. To represent a specific type of instruction, one of many subclasses of
1097<tt>Instruction</tt> are used.<p>
1098
1099Because the <tt>Instruction</tt> class subclasses the <a
1100href="#User"><tt>User</tt></a> class, its operands can be accessed in the same
1101way as for other <a href="#User"><tt>User</tt></a>s (with the
1102<tt>getOperand()</tt>/<tt>getNumOperands()</tt> and
1103<tt>op_begin()</tt>/<tt>op_end()</tt> methods).<p>
1104
Chris Lattner17635252002-09-12 17:18:46 +0000[diff] [blame]1105An important file for the <tt>Instruction</tt> class is the
1106<tt>llvm/Instruction.def</tt> file. This file contains some meta-data about the
1107various different types of instructions in LLVM. It describes the enum values
1108that are used as opcodes (for example <tt>Instruction::Add</tt> and
1109<tt>Instruction::SetLE</tt>), as well as the concrete sub-classes of
1110<tt>Instruction</tt> that implement the instruction (for example <tt><a
1111href="#BinaryOperator">BinaryOperator</a></tt> and <tt><a
1112href="#SetCondInst">SetCondInst</a></tt>). Unfortunately, the use of macros in
1113this file confused doxygen, so these enum values don't show up correctly in the
1114<a href="/doxygen/classInstruction.html">doxygen output</a>.<p>
1115
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1116
1117<!-- _______________________________________________________________________ -->
1118</ul><h4><a name="m_Instruction"><hr size=0>Important Public Members of
1119the <tt>Instruction</tt> class</h4><ul>
1120
1121<li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt><p>
1122
1123Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that this
1124<tt>Instruction</tt> is embedded into.<p>
1125
1126<li><tt>bool hasSideEffects()</tt><p>
1127
1128Returns true if the instruction has side effects, i.e. it is a <tt>call</tt>,
1129<tt>free</tt>, <tt>invoke</tt>, or <tt>store</tt>.<p>
1130
1131<li><tt>unsigned getOpcode()</tt><p>
1132
1133Returns the opcode for the <tt>Instruction</tt>.<p>
1134
Chris Lattner17635252002-09-12 17:18:46 +0000[diff] [blame]1135<li><tt><a href="#Instruction">Instruction</a> *clone() const</tt><p>
1136
1137Returns another instance of the specified instruction, identical in all ways to
1138the original except that the instruction has no parent (ie it's not embedded
1139into a <a href="#BasicBlock"><tt>BasicBlock</tt></a>), and it has no name.<p>
1140
1141
1142
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1143<!--
1144
1145\subsection{Subclasses of Instruction :}
1146\begin{itemize}
1147<li>BinaryOperator : This subclass of Instruction defines a general interface to the all the instructions involvong binary operators in LLVM.
1148 \begin{itemize}
1149 <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.
1150 \end{itemize}
1151<li>TerminatorInst : This subclass of Instructions defines an interface for all instructions that can terminate a BasicBlock.
1152 \begin{itemize}
1153 <li> <tt>unsigned getNumSuccessors()</tt>: Returns the number of successors for this terminator instruction.
1154 <li><tt>BasicBlock *getSuccessor(unsigned i)</tt>: As the name suggests returns the ith successor BasicBlock.
1155 <li><tt>void setSuccessor(unsigned i, BasicBlock *B)</tt>: sets BasicBlock B as the ith succesor to this terminator instruction.
1156 \end{itemize}
1157
1158<li>PHINode : This represents the PHI instructions in the SSA form.
1159 \begin{itemize}
1160 <li><tt> unsigned getNumIncomingValues()</tt>: Returns the number of incoming edges to this PHI node.
1161 <li><tt> Value *getIncomingValue(unsigned i)</tt>: Returns the ith incoming Value.
1162 <li><tt>void setIncomingValue(unsigned i, Value *V)</tt>: Sets the ith incoming Value as V
1163 <li><tt>BasicBlock *getIncomingBlock(unsigned i)</tt>: Returns the Basic Block corresponding to the ith incoming Value.
1164 <li><tt> void addIncoming(Value *D, BasicBlock *BB)</tt>:
1165 Add an incoming value to the end of the PHI list
1166 <li><tt> int getBasicBlockIndex(const BasicBlock *BB) const</tt>:
1167 Returns the first index of the specified basic block in the value list for this PHI. Returns -1 if no instance.
1168 \end{itemize}
1169<li>CastInst : In LLVM all casts have to be done through explicit cast instructions. CastInst defines the interface to the cast instructions.
1170<li>CallInst : This defines an interface to the call instruction in LLVM. ARguments to the function are nothing but operands of the instruction.
1171 \begin{itemize}
1172 <li>: <tt>Function *getCalledFunction()</tt>: Returns a handle to the function that is being called by this Function.
1173 \end{itemize}
1174<li>LoadInst, StoreInst, GetElemPtrInst : These subclasses represent load, store and getelementptr instructions in LLVM.
1175 \begin{itemize}
1176 <li><tt>Value * getPointerOperand ()</tt>: Returns the Pointer Operand which is typically the 0th operand.
1177 \end{itemize}
1178<li>BranchInst : This is a subclass of TerminatorInst and defines the interface for conditional and unconditional branches in LLVM.
1179 \begin{itemize}
1180 <li><tt>bool isConditional()</tt>: Returns true if the branch is a conditional branch else returns false
1181 <li> <tt>Value *getCondition()</tt>: Returns the condition if it is a conditional branch else returns null.
1182 <li> <tt>void setUnconditionalDest(BasicBlock *Dest)</tt>: Changes the current branch to an unconditional one targetting the specified block.
1183 \end{itemize}
1184
1185\end{itemize}
1186
1187-->
1188
1189
1190<!-- ======================================================================= -->
1191</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1192<tr><td>&nbsp;</td><td width="100%">&nbsp;
1193<font color="#EEEEFF" face="Georgia,Palatino"><b>
1194<a name="BasicBlock">The <tt>BasicBlock</tt> class</a>
1195</b></font></td></tr></table><ul>
1196
1197<tt>#include "<a
1198href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt></b><br>
1199doxygen info: <a href="/doxygen/classBasicBlock.html">BasicBlock Class</a><br>
1200Superclass: <a href="#Value"><tt>Value</tt></a><p>
1201
1202
1203This class represents a single entry multiple exit section of the code, commonly
1204known as a basic block by the compiler community. The <tt>BasicBlock</tt> class
1205maintains a list of <a href="#Instruction"><tt>Instruction</tt></a>s, which form
1206the body of the block. Matching the language definition, the last element of
1207this list of instructions is always a terminator instruction (a subclass of the
1208<a href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).<p>
1209
1210In addition to tracking the list of instructions that make up the block, the
1211<tt>BasicBlock</tt> class also keeps track of the <a
1212href="#Function"><tt>Function</tt></a> that it is embedded into.<p>
1213
1214Note that <tt>BasicBlock</tt>s themselves are <a
1215href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions
1216like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type
1217<tt>label</tt>.<p>
1218
1219
1220<!-- _______________________________________________________________________ -->
1221</ul><h4><a name="m_BasicBlock"><hr size=0>Important Public Members of
1222the <tt>BasicBlock</tt> class</h4><ul>
1223
1224<li><tt>BasicBlock(const std::string &amp;Name = "", <a
1225href="#Function">Function</a> *Parent = 0)</tt><p>
1226
1227The <tt>BasicBlock</tt> constructor is used to create new basic blocks for
1228insertion into a function. The constructor simply takes a name for the new
1229block, and optionally a <a href="#Function"><tt>Function</tt></a> to insert it
1230into. If the <tt>Parent</tt> parameter is specified, the new
1231<tt>BasicBlock</tt> is automatically inserted at the end of the specified <a
1232href="#Function"><tt>Function</tt></a>, if not specified, the BasicBlock must be
1233manually inserted into the <a href="#Function"><tt>Function</tt></a>.<p>
1234
1235<li><tt>BasicBlock::iterator</tt> - Typedef for instruction list iterator<br>
1236 <tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
1237 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
1238 <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
1239
1240These methods and typedefs are forwarding functions that have the same semantics
1241as the standard library methods of the same names. These methods expose the
1242underlying instruction list of a basic block in a way that is easy to
1243manipulate. To get the full complement of container operations (including
1244operations to update the list), you must use the <tt>getInstList()</tt>
1245method.<p>
1246
1247<li><tt>BasicBlock::InstListType &amp;getInstList()</tt><p>
1248
1249This method is used to get access to the underlying container that actually
1250holds the Instructions. This method must be used when there isn't a forwarding
1251function in the <tt>BasicBlock</tt> class for the operation that you would like
1252to perform. Because there are no forwarding functions for "updating"
1253operations, you need to use this if you want to update the contents of a
1254<tt>BasicBlock</tt>.<p>
1255
1256<li><tt><A href="#Function">Function</a> *getParent()</tt><p>
1257
1258Returns a pointer to <a href="#Function"><tt>Function</tt></a> the block is
1259embedded into, or a null pointer if it is homeless.<p>
1260
1261<li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt><p>
1262
1263Returns a pointer to the terminator instruction that appears at the end of the
1264<tt>BasicBlock</tt>. If there is no terminator instruction, or if the last
1265instruction in the block is not a terminator, then a null pointer is
1266returned.<p>
1267
1268
1269<!-- ======================================================================= -->
1270</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1271<tr><td>&nbsp;</td><td width="100%">&nbsp;
1272<font color="#EEEEFF" face="Georgia,Palatino"><b>
1273<a name="GlobalValue">The <tt>GlobalValue</tt> class</a>
1274</b></font></td></tr></table><ul>
1275
1276<tt>#include "<a
1277href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt></b><br>
1278doxygen info: <a href="/doxygen/classGlobalValue.html">GlobalValue Class</a><br>
1279Superclasses: <a href="#User"><tt>User</tt></a>, <a
1280href="#Value"><tt>Value</tt></a><p>
1281
1282Global values (<A href="#GlobalVariable"><tt>GlobalVariable</tt></a>s or <a
1283href="#Function"><tt>Function</tt></a>s) are the only LLVM values that are
1284visible in the bodies of all <a href="#Function"><tt>Function</tt></a>s.
1285Because they are visible at global scope, they are also subject to linking with
1286other globals defined in different translation units. To control the linking
1287process, <tt>GlobalValue</tt>s know their linkage rules. Specifically,
1288<tt>GlobalValue</tt>s know whether they have internal or external linkage.<p>
1289
1290If a <tt>GlobalValue</tt> has internal linkage (equivalent to being
1291<tt>static</tt> in C), it is not visible to code outside the current translation
1292unit, and does not participate in linking. If it has external linkage, it is
1293visible to external code, and does participate in linking. In addition to
1294linkage information, <tt>GlobalValue</tt>s keep track of which <a
1295href="#Module"><tt>Module</tt></a> they are currently part of.<p>
1296
1297Because <tt>GlobalValue</tt>s are memory objects, they are always referred to by
1298their address. As such, the <a href="#Type"><tt>Type</tt></a> of a global is
1299always a pointer to its contents. This is explained in the LLVM Language
1300Reference Manual.<p>
1301
1302
1303<!-- _______________________________________________________________________ -->
1304</ul><h4><a name="m_GlobalValue"><hr size=0>Important Public Members of
1305the <tt>GlobalValue</tt> class</h4><ul>
1306
1307<li><tt>bool hasInternalLinkage() const</tt><br>
1308 <tt>bool hasExternalLinkage() const</tt><br>
1309 <tt>void setInternalLinkage(bool HasInternalLinkage)</tt><p>
1310
1311These methods manipulate the linkage characteristics of the
1312<tt>GlobalValue</tt>.<p>
1313
1314<li><tt><a href="#Module">Module</a> *getParent()</tt><p>
1315
1316This returns the <a href="#Module"><tt>Module</tt></a> that the GlobalValue is
1317currently embedded into.<p>
1318
1319
1320
1321<!-- ======================================================================= -->
1322</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1323<tr><td>&nbsp;</td><td width="100%">&nbsp;
1324<font color="#EEEEFF" face="Georgia,Palatino"><b>
1325<a name="Function">The <tt>Function</tt> class</a>
1326</b></font></td></tr></table><ul>
1327
1328<tt>#include "<a
1329href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt></b><br>
1330doxygen info: <a href="/doxygen/classFunction.html">Function Class</a><br>
1331Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
1332href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a><p>
1333
1334The <tt>Function</tt> class represents a single procedure in LLVM. It is
1335actually one of the more complex classes in the LLVM heirarchy because it must
1336keep track of a large amount of data. The <tt>Function</tt> class keeps track
1337of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <a
1338href="#Argument"><tt>Argument</tt></a>s, and a <a
1339href="#SymbolTable"><tt>SymbolTable</tt></a>.<p>
1340
1341The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most commonly
1342used part of <tt>Function</tt> objects. The list imposes an implicit ordering
1343of the blocks in the function, which indicate how the code will be layed out by
1344the backend. Additionally, the first <a
1345href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node for the
1346<tt>Function</tt>. It is not legal in LLVM explicitly branch to this initial
1347block. There are no implicit exit nodes, and in fact there may be multiple exit
1348nodes from a single <tt>Function</tt>. If the <a
1349href="#BasicBlock"><tt>BasicBlock</tt></a> list is empty, this indicates that
1350the <tt>Function</tt> is actually a function declaration: the actual body of the
1351function hasn't been linked in yet.<p>
1352
1353In addition to a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, the
1354<tt>Function</tt> class also keeps track of the list of formal <a
1355href="#Argument"><tt>Argument</tt></a>s that the function receives. This
1356container manages the lifetime of the <a href="#Argument"><tt>Argument</tt></a>
1357nodes, just like the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list does for
1358the <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.<p>
1359
1360The <a href="#SymbolTable"><tt>SymbolTable</tt></a> is a very rarely used LLVM
1361feature that is only used when you have to look up a value by name. Aside from
1362that, the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is used internally to
1363make sure that there are not conflicts between the names of <a
1364href="#Instruction"><tt>Instruction</tt></a>s, <a
1365href="#BasicBlock"><tt>BasicBlock</tt></a>s, or <a
1366href="#Argument"><tt>Argument</tt></a>s in the function body.<p>
1367
1368
1369<!-- _______________________________________________________________________ -->
1370</ul><h4><a name="m_Function"><hr size=0>Important Public Members of
1371the <tt>Function</tt> class</h4><ul>
1372
1373<li><tt>Function(const <a href="#FunctionType">FunctionType</a> *Ty, bool isInternal, const std::string &amp;N = "")</tt><p>
1374
1375Constructor used when you need to create new <tt>Function</tt>s to add the the
1376program. The constructor must specify the type of the function to create and
1377whether or not it should start out with internal or external linkage.<p>
1378
1379<li><tt>bool isExternal()</tt><p>
1380
1381Return whether or not the <tt>Function</tt> has a body defined. If the function
1382is "external", it does not have a body, and thus must be resolved by linking
1383with a function defined in a different translation unit.<p>
1384
1385
1386<li><tt>Function::iterator</tt> - Typedef for basic block list iterator<br>
1387 <tt>Function::const_iterator</tt> - Typedef for const_iterator.<br>
1388 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
1389 <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
1390
1391These are forwarding methods that make it easy to access the contents of a
1392<tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
1393list.<p>
1394
1395<li><tt>Function::BasicBlockListType &amp;getBasicBlockList()</tt><p>
1396
1397Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s. This is
1398neccesary to use when you need to update the list or perform a complex action
1399that doesn't have a forwarding method.<p>
1400
1401
1402<li><tt>Function::aiterator</tt> - Typedef for the argument list iterator<br>
1403 <tt>Function::const_aiterator</tt> - Typedef for const_iterator.<br>
1404 <tt>abegin()</tt>, <tt>aend()</tt>, <tt>afront()</tt>, <tt>aback()</tt>,
1405 <tt>asize()</tt>, <tt>aempty()</tt>, <tt>arbegin()</tt>, <tt>arend()</tt><p>
1406
1407These are forwarding methods that make it easy to access the contents of a
1408<tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a> list.<p>
1409
1410<li><tt>Function::ArgumentListType &amp;getArgumentList()</tt><p>
1411
1412Returns the list of <a href="#Argument"><tt>Argument</tt></a>s. This is
1413neccesary to use when you need to update the list or perform a complex action
1414that doesn't have a forwarding method.<p>
1415
1416
1417
1418<li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryNode()</tt><p>
1419
1420Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
1421function. Because the entry block for the function is always the first block,
1422this returns the first block of the <tt>Function</tt>.<p>
1423
1424<li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
1425 <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt><p>
1426
1427This traverses the <a href="#Type"><tt>Type</tt></a> of the <tt>Function</tt>
1428and returns the return type of the function, or the <a
1429href="#FunctionType"><tt>FunctionType</tt></a> of the actual function.<p>
1430
1431
1432<li><tt>bool hasSymbolTable() const</tt><p>
1433
1434Return true if the <tt>Function</tt> has a symbol table allocated to it and if
1435there is at least one entry in it.<p>
1436
1437<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p>
1438
1439Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
1440<tt>Function</tt> or a null pointer if one has not been allocated (because there
1441are no named values in the function).<p>
1442
1443<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTableSure()</tt><p>
1444
1445Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
1446<tt>Function</tt> or allocate a new <a
1447href="#SymbolTable"><tt>SymbolTable</tt></a> if one is not already around. This
1448should only be used when adding elements to the <a
1449href="#SymbolTable"><tt>SymbolTable</tt></a>, so that empty symbol tables are
1450not left laying around.<p>
1451
1452
1453
1454<!-- ======================================================================= -->
1455</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1456<tr><td>&nbsp;</td><td width="100%">&nbsp;
1457<font color="#EEEEFF" face="Georgia,Palatino"><b>
1458<a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a>
1459</b></font></td></tr></table><ul>
1460
1461<tt>#include "<a
1462href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt></b><br>
1463doxygen info: <a href="/doxygen/classGlobalVariable.html">GlobalVariable Class</a><br>
1464Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
1465href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a><p>
1466
Chris Lattner0377de42002-09-06 14:50:55 +0000[diff] [blame]1467Global variables are represented with the (suprise suprise)
1468<tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are
1469also subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such
1470are always referenced by their address (global values must live in memory, so
1471their "name" refers to their address). Global variables may have an initial
1472value (which must be a <a href="#Constant"><tt>Constant</tt></a>), and if they
1473have an initializer, they may be marked as "constant" themselves (indicating
1474that their contents never change at runtime).<p>
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1475
1476
1477<!-- _______________________________________________________________________ -->
Chris Lattner0377de42002-09-06 14:50:55 +0000[diff] [blame]1478</ul><h4><a name="m_GlobalVariable"><hr size=0>Important Public Members of the
1479<tt>GlobalVariable</tt> class</h4><ul>
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1480
1481<li><tt>GlobalVariable(const <a href="#Type">Type</a> *Ty, bool isConstant, bool
1482isInternal, <a href="#Constant">Constant</a> *Initializer = 0, const std::string
1483&amp;Name = "")</tt><p>
1484
Chris Lattner0377de42002-09-06 14:50:55 +0000[diff] [blame]1485Create a new global variable of the specified type. If <tt>isConstant</tt> is
1486true then the global variable will be marked as unchanging for the program, and
1487if <tt>isInternal</tt> is true the resultant global variable will have internal
1488linkage. Optionally an initializer and name may be specified for the global variable as well.<p>
1489
1490
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1491<li><tt>bool isConstant() const</tt><p>
1492
1493Returns true if this is a global variable is known not to be modified at
1494runtime.<p>
1495
Chris Lattner0377de42002-09-06 14:50:55 +0000[diff] [blame]1496
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1497<li><tt>bool hasInitializer()</tt><p>
1498
1499Returns true if this <tt>GlobalVariable</tt> has an intializer.<p>
1500
Chris Lattner0377de42002-09-06 14:50:55 +0000[diff] [blame]1501
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1502<li><tt><a href="#Constant">Constant</a> *getInitializer()</tt><p>
1503
Chris Lattner0377de42002-09-06 14:50:55 +0000[diff] [blame]1504Returns the intial value for a <tt>GlobalVariable</tt>. It is not legal to call
1505this method if there is no initializer.<p>
1506
1507
1508<!-- ======================================================================= -->
1509</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1510<tr><td>&nbsp;</td><td width="100%">&nbsp;
1511<font color="#EEEEFF" face="Georgia,Palatino"><b>
1512<a name="Module">The <tt>Module</tt> class</a>
1513</b></font></td></tr></table><ul>
1514
1515<tt>#include "<a
1516href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt></b><br>
1517doxygen info: <a href="/doxygen/classModule.html">Module Class</a><p>
1518
1519The <tt>Module</tt> class represents the top level structure present in LLVM
1520programs. An LLVM module is effectively either a translation unit of the
1521original program or a combination of several translation units merged by the
1522linker. The <tt>Module</tt> class keeps track of a list of <a
1523href="#Function"><tt>Function</tt></a>s, a list of <a
1524href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
1525href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it contains a few
1526helpful member functions that try to make common operations easy.<p>
1527
1528
1529<!-- _______________________________________________________________________ -->
1530</ul><h4><a name="m_Module"><hr size=0>Important Public Members of the
1531<tt>Module</tt> class</h4><ul>
1532
1533<li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
1534 <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
1535 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
1536 <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
1537
1538These are forwarding methods that make it easy to access the contents of a
1539<tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
1540list.<p>
1541
1542<li><tt>Module::FunctionListType &amp;getFunctionList()</tt><p>
1543
1544Returns the list of <a href="#Function"><tt>Function</tt></a>s. This is
1545neccesary to use when you need to update the list or perform a complex action
1546that doesn't have a forwarding method.<p>
1547
1548<!-- Global Variable -->
1549<hr size=0>
1550
1551<li><tt>Module::giterator</tt> - Typedef for global variable list iterator<br>
1552 <tt>Module::const_giterator</tt> - Typedef for const_iterator.<br>
1553 <tt>gbegin()</tt>, <tt>gend()</tt>, <tt>gfront()</tt>, <tt>gback()</tt>,
1554 <tt>gsize()</tt>, <tt>gempty()</tt>, <tt>grbegin()</tt>, <tt>grend()</tt><p>
1555
1556These are forwarding methods that make it easy to access the contents of a
1557<tt>Module</tt> object's <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>
1558list.<p>
1559
1560<li><tt>Module::GlobalListType &amp;getGlobalList()</tt><p>
1561
1562Returns the list of <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s.
1563This is neccesary to use when you need to update the list or perform a complex
1564action that doesn't have a forwarding method.<p>
1565
1566
1567<!-- Symbol table stuff -->
1568<hr size=0>
1569
1570<li><tt>bool hasSymbolTable() const</tt><p>
1571
1572Return true if the <tt>Module</tt> has a symbol table allocated to it and if
1573there is at least one entry in it.<p>
1574
1575<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p>
1576
1577Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
1578<tt>Module</tt> or a null pointer if one has not been allocated (because there
1579are no named values in the function).<p>
1580
1581<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTableSure()</tt><p>
1582
1583Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
1584<tt>Module</tt> or allocate a new <a
1585href="#SymbolTable"><tt>SymbolTable</tt></a> if one is not already around. This
1586should only be used when adding elements to the <a
1587href="#SymbolTable"><tt>SymbolTable</tt></a>, so that empty symbol tables are
1588not left laying around.<p>
1589
1590
1591<!-- Convenience methods -->
1592<hr size=0>
1593
1594<li><tt><a href="#Function">Function</a> *getFunction(const std::string &amp;Name, const <a href="#FunctionType">FunctionType</a> *Ty)</tt><p>
1595
1596Look up the specified function in the <tt>Module</tt> <a
1597href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return
1598<tt>null</tt>.<p>
1599
1600
1601<li><tt><a href="#Function">Function</a> *getOrInsertFunction(const std::string
1602 &amp;Name, const <a href="#FunctionType">FunctionType</a> *T)</tt><p>
1603
1604Look up the specified function in the <tt>Module</tt> <a
1605href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an
1606external declaration for the function and return it.<p>
1607
1608
1609<li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt><p>
1610
1611If there is at least one entry in the <a
1612href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a
1613href="#Type"><tt>Type</tt></a>, return it. Otherwise return the empty
1614string.<p>
1615
1616
1617<li><tt>bool addTypeName(const std::string &Name, const <a href="#Type">Type</a>
1618*Ty)</tt><p>
1619
1620Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a> mapping
1621<tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this name, true
1622is returned and the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is not
1623modified.<p>
1624
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1625
1626<!-- ======================================================================= -->
1627</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1628<tr><td>&nbsp;</td><td width="100%">&nbsp;
1629<font color="#EEEEFF" face="Georgia,Palatino"><b>
1630<a name="Constant">The <tt>Constant</tt> class and subclasses</a>
1631</b></font></td></tr></table><ul>
1632
1633Constant represents a base class for different types of constants. It is
1634subclassed by ConstantBool, ConstantInt, ConstantSInt, ConstantUInt,
1635ConstantArray etc for representing the various types of Constants.<p>
1636
1637
1638<!-- _______________________________________________________________________ -->
1639</ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul>
1640
1641<li><tt>bool isConstantExpr()</tt>: Returns true if it is a ConstantExpr
1642
1643
1644
1645
1646\subsection{Important Subclasses of Constant}
1647\begin{itemize}
1648<li>ConstantSInt : This subclass of Constant represents a signed integer constant.
1649 \begin{itemize}
1650 <li><tt>int64_t getValue () const</tt>: Returns the underlying value of this constant.
1651 \end{itemize}
1652<li>ConstantUInt : This class represents an unsigned integer.
1653 \begin{itemize}
1654 <li><tt>uint64_t getValue () const</tt>: Returns the underlying value of this constant.
1655 \end{itemize}
1656<li>ConstantFP : This class represents a floating point constant.
1657 \begin{itemize}
1658 <li><tt>double getValue () const</tt>: Returns the underlying value of this constant.
1659 \end{itemize}
1660<li>ConstantBool : This represents a boolean constant.
1661 \begin{itemize}
1662 <li><tt>bool getValue () const</tt>: Returns the underlying value of this constant.
1663 \end{itemize}
1664<li>ConstantArray : This represents a constant array.
1665 \begin{itemize}
1666 <li><tt>const std::vector<Use> &amp;getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
1667 \end{itemize}
1668<li>ConstantStruct : This represents a constant struct.
1669 \begin{itemize}
1670 <li><tt>const std::vector<Use> &amp;getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
1671 \end{itemize}
1672<li>ConstantPointerRef : This represents a constant pointer value that is initialized to point to a global value, which lies at a constant fixed address.
1673 \begin{itemize}
1674<li><tt>GlobalValue *getValue()</tt>: Returns the global value to which this pointer is pointing to.
1675 \end{itemize}
1676\end{itemize}
1677
1678
1679<!-- ======================================================================= -->
1680</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1681<tr><td>&nbsp;</td><td width="100%">&nbsp;
1682<font color="#EEEEFF" face="Georgia,Palatino"><b>
1683<a name="Type">The <tt>Type</tt> class and Derived Types</a>
1684</b></font></td></tr></table><ul>
1685
1686Type as noted earlier is also a subclass of a Value class. Any primitive
1687type (like int, short etc) in LLVM is an instance of Type Class. All
1688other types are instances of subclasses of type like FunctionType,
1689ArrayType etc. DerivedType is the interface for all such dervied types
1690including FunctionType, ArrayType, PointerType, StructType. Types can have
1691names. They can be recursive (StructType). There exists exactly one instance
1692of any type structure at a time. This allows using pointer equality of Type *s for comparing types.
1693
1694<!-- _______________________________________________________________________ -->
1695</ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul>
1696
1697<li><tt>PrimitiveID getPrimitiveID () const</tt>: Returns the base type of the type.
1698<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.
1699<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.
1700<li><tt> bool isInteger () const</tt>: Equilivent to isSigned() || isUnsigned(), but with only a single virtual function invocation.
1701<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.
1702
1703<li><tt>bool isFloatingPoint ()</tt>: Return true if this is one of the two floating point types.
1704<li><tt>bool isRecursive () const</tt>: Returns rue if the type graph contains a cycle.
1705<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.
1706<li><tt>bool isPrimitiveType () const</tt>: Returns true if it is a primitive type.
1707<li><tt>bool isDerivedType () const</tt>: Returns true if it is a derived type.
1708<li><tt>const Type * getContainedType (unsigned i) const</tt>:
1709This 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.
1710<li><tt>unsigned getNumContainedTypes () const</tt>: Return the number of types in the derived type.
1711
1712
1713
1714\subsection{Derived Types}
1715\begin{itemize}
1716<li>SequentialType : This is subclassed by ArrayType and PointerType
1717 \begin{itemize}
1718 <li><tt>const Type * getElementType () const</tt>: Returns the type of each of the elements in the sequential type.
1719 \end{itemize}
1720<li>ArrayType : This is a subclass of SequentialType and defines interface for array types.
1721 \begin{itemize}
1722 <li><tt>unsigned getNumElements () const</tt>: Returns the number of elements in the array.
1723 \end{itemize}
1724<li>PointerType : Subclass of SequentialType for pointer types.
1725<li>StructType : subclass of DerivedTypes for struct types
1726<li>FunctionType : subclass of DerivedTypes for function types.
1727 \begin{itemize}
1728
1729 <li><tt>bool isVarArg () const</tt>: Returns true if its a vararg function
1730 <li><tt> const Type * getReturnType () const</tt>: Returns the return type of the function.
1731 <li><tt> const ParamTypes &amp;getParamTypes () const</tt>: Returns a vector of parameter types.
1732 <li><tt>const Type * getParamType (unsigned i)</tt>: Returns the type of the ith parameter.
1733 <li><tt> const unsigned getNumParams () const</tt>: Returns the number of formal parameters.
1734 \end{itemize}
1735\end{itemize}
1736
1737
1738
1739
1740<!-- ======================================================================= -->
1741</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
1742<tr><td>&nbsp;</td><td width="100%">&nbsp;
1743<font color="#EEEEFF" face="Georgia,Palatino"><b>
1744<a name="Argument">The <tt>Argument</tt> class</a>
1745</b></font></td></tr></table><ul>
1746
1747This subclass of Value defines the interface for incoming formal arguments to a
1748function. A Function maitanis a list of its formal arguments. An argument has a
1749pointer to the parent Function.
1750
1751
1752
1753
1754<!-- *********************************************************************** -->
1755</ul>
1756<!-- *********************************************************************** -->
1757
1758<hr><font size-1>
1759<address>By: <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and
1760<a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
1761<!-- Created: Tue Aug 6 15:00:33 CDT 2002 -->
1762<!-- hhmts start -->
Joel Stanley4b287932002-09-29 17:31:54 +0000[diff] [blame^]1763Last modified: Sun Sep 29 12:31:23 CDT 2002
Chris Lattner9355b472002-09-06 02:50:58 +0000[diff] [blame]1764<!-- hhmts end -->
1765</font></body></html>