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