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