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