blob: dfd8a20128faf85d7e6df1b1c32b33988cd1b746 [file] [log] [blame]
Misha Brukman13fd15c2004-01-15 00:14:41 +00001<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
Chris Lattner261efe92003-11-25 01:02:51 +00003<html>
4<head>
5 <title>LLVM Programmer's Manual</title>
Misha Brukman13fd15c2004-01-15 00:14:41 +00006 <link rel="stylesheet" href="llvm.css" type="text/css">
Chris Lattner261efe92003-11-25 01:02:51 +00007</head>
Misha Brukman13fd15c2004-01-15 00:14:41 +00008<body>
9
10<div class="doc_title">
11 LLVM Programmer's Manual
12</div>
13
Chris Lattner9355b472002-09-06 02:50:58 +000014<ol>
Misha Brukman13fd15c2004-01-15 00:14:41 +000015 <li><a href="#introduction">Introduction</a></li>
Chris Lattner9355b472002-09-06 02:50:58 +000016 <li><a href="#general">General Information</a>
Chris Lattner261efe92003-11-25 01:02:51 +000017 <ul>
18 <li><a href="#stl">The C++ Standard Template Library</a><!--
Chris Lattner986e0c92002-09-22 19:38:40 +000019 <li>The <tt>-time-passes</tt> option
20 <li>How to use the LLVM Makefile system
21 <li>How to write a regression test
Chris Lattner261efe92003-11-25 01:02:51 +000022--> </li>
Chris Lattner84b7f8d2003-08-01 22:20:59 +000023 </ul>
Chris Lattner261efe92003-11-25 01:02:51 +000024 </li>
25 <li><a href="#apis">Important and useful LLVM APIs</a>
26 <ul>
27 <li><a href="#isa">The <tt>isa&lt;&gt;</tt>, <tt>cast&lt;&gt;</tt>
28and <tt>dyn_cast&lt;&gt;</tt> templates</a> </li>
29 <li><a href="#DEBUG">The <tt>DEBUG()</tt> macro &amp; <tt>-debug</tt>
30option</a>
31 <ul>
32 <li><a href="#DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE</tt>
33and the <tt>-debug-only</tt> option</a> </li>
34 </ul>
35 </li>
36 <li><a href="#Statistic">The <tt>Statistic</tt> template &amp; <tt>-stats</tt>
37option</a><!--
Chris Lattner986e0c92002-09-22 19:38:40 +000038 <li>The <tt>InstVisitor</tt> template
39 <li>The general graph API
Chris Lattner261efe92003-11-25 01:02:51 +000040--> </li>
41 </ul>
42 </li>
Chris Lattnerae7f7592002-09-06 18:31:18 +000043 <li><a href="#common">Helpful Hints for Common Operations</a>
Chris Lattnerae7f7592002-09-06 18:31:18 +000044 <ul>
Chris Lattner261efe92003-11-25 01:02:51 +000045 <li><a href="#inspection">Basic Inspection and Traversal Routines</a>
46 <ul>
47 <li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s
48in a <tt>Function</tt></a> </li>
49 <li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s
50in a <tt>BasicBlock</tt></a> </li>
51 <li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s
52in a <tt>Function</tt></a> </li>
53 <li><a href="#iterate_convert">Turning an iterator into a
54class pointer</a> </li>
55 <li><a href="#iterate_complex">Finding call sites: a more
56complex example</a> </li>
57 <li><a href="#calls_and_invokes">Treating calls and invokes
58the same way</a> </li>
59 <li><a href="#iterate_chains">Iterating over def-use &amp;
60use-def chains</a> </li>
61 </ul>
62 </li>
63 <li><a href="#simplechanges">Making simple changes</a>
64 <ul>
65 <li><a href="#schanges_creating">Creating and inserting new
66 <tt>Instruction</tt>s</a> </li>
67 <li><a href="#schanges_deleting">Deleting <tt>Instruction</tt>s</a> </li>
68 <li><a href="#schanges_replacing">Replacing an <tt>Instruction</tt>
69with another <tt>Value</tt></a> </li>
70 </ul>
Chris Lattnerae7f7592002-09-06 18:31:18 +000071<!--
72 <li>Working with the Control Flow Graph
73 <ul>
74 <li>Accessing predecessors and successors of a <tt>BasicBlock</tt>
75 <li>
76 <li>
77 </ul>
Chris Lattner261efe92003-11-25 01:02:51 +000078--> </li>
79 </ul>
80 </li>
Joel Stanley9b96c442002-09-06 21:55:13 +000081 <li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
Chris Lattner9355b472002-09-06 02:50:58 +000082 <ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +000083 <li><a href="#Value">The <tt>Value</tt> class</a>
84 <ul>
85 <li><a href="#User">The <tt>User</tt> class</a>
Chris Lattner9355b472002-09-06 02:50:58 +000086 <ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +000087 <li><a href="#Instruction">The <tt>Instruction</tt> class</a>
Chris Lattner261efe92003-11-25 01:02:51 +000088 <ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +000089 <li><a href="#GetElementPtrInst">The <tt>GetElementPtrInst</tt>
90 class</a></li>
91 </ul></li>
92 <li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a>
93 <ul>
94 <li><a href="#BasicBlock">The <tt>BasicBlock</tt>class</a></li>
95 <li><a href="#Function">The <tt>Function</tt> class</a></li>
96 <li><a href="#GlobalVariable">The <tt>GlobalVariable</tt>
97 class</a></li>
98 </ul></li>
99 <li><a href="#Module">The <tt>Module</tt> class</a></li>
100 <li><a href="#Constant">The <tt>Constant</tt> class</a>
101 <ul>
Chris Lattner261efe92003-11-25 01:02:51 +0000102 <li> <br>
103 </li>
104 <li> <br>
105 </li>
106 </ul>
107 </li>
108 </ul>
109 </li>
110 <li><a href="#Type">The <tt>Type</tt> class</a> </li>
111 <li><a href="#Argument">The <tt>Argument</tt> class</a> </li>
Chris Lattner9355b472002-09-06 02:50:58 +0000112 </ul>
Chris Lattner261efe92003-11-25 01:02:51 +0000113 </li>
114 <li>The <tt>SymbolTable</tt> class </li>
115 <li>The <tt>ilist</tt> and <tt>iplist</tt> classes
Chris Lattner9355b472002-09-06 02:50:58 +0000116 <ul>
Chris Lattner261efe92003-11-25 01:02:51 +0000117 <li>Creating, inserting, moving and deleting from LLVM lists </li>
Chris Lattner9355b472002-09-06 02:50:58 +0000118 </ul>
Chris Lattner261efe92003-11-25 01:02:51 +0000119 </li>
120 <li>Important iterator invalidation semantics to be aware of </li>
Chris Lattner9355b472002-09-06 02:50:58 +0000121 </ul>
Chris Lattner261efe92003-11-25 01:02:51 +0000122 </li>
Chris Lattner9355b472002-09-06 02:50:58 +0000123</ol>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000124
125<div class="doc_text">
126 <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
127 <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>, and <a
128 href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a></b></p>
129</div>
130
Chris Lattner9355b472002-09-06 02:50:58 +0000131<!-- *********************************************************************** -->
Misha Brukman13fd15c2004-01-15 00:14:41 +0000132<div class="doc_section">
133 <a name="introduction">Introduction </a>
134</div>
Chris Lattner9355b472002-09-06 02:50:58 +0000135<!-- *********************************************************************** -->
Misha Brukman13fd15c2004-01-15 00:14:41 +0000136
137<div class="doc_text">
138
139<p>This document is meant to highlight some of the important classes and
Chris Lattner261efe92003-11-25 01:02:51 +0000140interfaces available in the LLVM source-base. This manual is not
141intended to explain what LLVM is, how it works, and what LLVM code looks
142like. It assumes that you know the basics of LLVM and are interested
143in writing transformations or otherwise analyzing or manipulating the
Misha Brukman13fd15c2004-01-15 00:14:41 +0000144code.</p>
145
146<p>This document should get you oriented so that you can find your
Chris Lattner261efe92003-11-25 01:02:51 +0000147way in the continuously growing source code that makes up the LLVM
148infrastructure. Note that this manual is not intended to serve as a
149replacement for reading the source code, so if you think there should be
150a method in one of these classes to do something, but it's not listed,
151check the source. Links to the <a href="/doxygen/">doxygen</a> sources
152are provided to make this as easy as possible.</p>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000153
154<p>The first section of this document describes general information that is
155useful to know when working in the LLVM infrastructure, and the second describes
156the Core LLVM classes. In the future this manual will be extended with
157information describing how to use extension libraries, such as dominator
158information, CFG traversal routines, and useful utilities like the <tt><a
159href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> template.</p>
160
161</div>
162
Chris Lattner9355b472002-09-06 02:50:58 +0000163<!-- *********************************************************************** -->
Misha Brukman13fd15c2004-01-15 00:14:41 +0000164<div class="doc_section">
165 <a name="general">General Information</a>
166</div>
167<!-- *********************************************************************** -->
168
169<div class="doc_text">
170
171<p>This section contains general information that is useful if you are working
172in the LLVM source-base, but that isn't specific to any particular API.</p>
173
174</div>
175
176<!-- ======================================================================= -->
177<div class="doc_subsection">
178 <a name="stl">The C++ Standard Template Library</a>
179</div>
180
181<div class="doc_text">
182
183<p>LLVM makes heavy use of the C++ Standard Template Library (STL),
Chris Lattner261efe92003-11-25 01:02:51 +0000184perhaps much more than you are used to, or have seen before. Because of
185this, you might want to do a little background reading in the
186techniques used and capabilities of the library. There are many good
187pages that discuss the STL, and several books on the subject that you
Misha Brukman13fd15c2004-01-15 00:14:41 +0000188can get, so it will not be discussed in this document.</p>
189
190<p>Here are some useful links:</p>
191
192<ol>
193
194<li><a href="http://www.dinkumware.com/refxcpp.html">Dinkumware C++ Library
195reference</a> - an excellent reference for the STL and other parts of the
196standard C++ library.</li>
197
198<li><a href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> - This is an
199O'Reilly book in the making. It has a decent <a
200href="http://www.tempest-sw.com/cpp/ch13-libref.html">Standard Library
201Reference</a> that rivals Dinkumware's, and is actually free until the book is
202published.</li>
203
204<li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently Asked
205Questions</a></li>
206
207<li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's Guide</a> -
208Contains a useful <a
209href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction to the
210STL</a>.</li>
211
212<li><a href="http://www.research.att.com/%7Ebs/C++.html">Bjarne Stroustrup's C++
213Page</a></li>
214
215</ol>
216
217<p>You are also encouraged to take a look at the <a
218href="CodingStandards.html">LLVM Coding Standards</a> guide which focuses on how
219to write maintainable code more than where to put your curly braces.</p>
220
221</div>
222
223<!-- ======================================================================= -->
224<div class="doc_subsection">
225 <a name="stl">Other useful references</a>
226</div>
227
228<div class="doc_text">
229
230<p>LLVM is currently using CVS as its source versioning system. You may find
231this reference handy:</p>
232
233<ol>
234<li><a href="http://www.psc.edu/%7Esemke/cvs_branches.html">CVS
Chris Lattner261efe92003-11-25 01:02:51 +0000235Branch and Tag Primer</a></li>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000236</ol>
237
238</div>
239
Chris Lattner9355b472002-09-06 02:50:58 +0000240<!-- *********************************************************************** -->
Misha Brukman13fd15c2004-01-15 00:14:41 +0000241<div class="doc_section">
242 <a name="apis">Important and useful LLVM APIs</a>
243</div>
244<!-- *********************************************************************** -->
245
246<div class="doc_text">
247
248<p>Here we highlight some LLVM APIs that are generally useful and good to
249know about when writing transformations.</p>
250
251</div>
252
253<!-- ======================================================================= -->
254<div class="doc_subsection">
255 <a name="isa">The isa&lt;&gt;, cast&lt;&gt; and dyn_cast&lt;&gt; templates</a>
256</div>
257
258<div class="doc_text">
259
260<p>The LLVM source-base makes extensive use of a custom form of RTTI.
Chris Lattner261efe92003-11-25 01:02:51 +0000261These templates have many similarities to the C++ <tt>dynamic_cast&lt;&gt;</tt>
262operator, but they don't have some drawbacks (primarily stemming from
263the fact that <tt>dynamic_cast&lt;&gt;</tt> only works on classes that
264have a v-table). Because they are used so often, you must know what they
265do and how they work. All of these templates are defined in the <a
266 href="/doxygen/Casting_8h-source.html"><tt>Support/Casting.h</tt></a>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000267file (note that you very rarely have to include this file directly).</p>
268
269<dl>
270 <dt><tt>isa&lt;&gt;</tt>: </dt>
271
272 <dd>The <tt>isa&lt;&gt;</tt> operator works exactly like the Java
273 "<tt>instanceof</tt>" operator. It returns true or false depending on whether
274 a reference or pointer points to an instance of the specified class. This can
275 be very useful for constraint checking of various sorts (example below).</dd>
276
277 <dt><tt>cast&lt;&gt;</tt>: </dt>
278
279 <dd>The <tt>cast&lt;&gt;</tt> operator is a "checked cast" operation. It
280 converts a pointer or reference from a base class to a derived cast, causing
281 an assertion failure if it is not really an instance of the right type. This
282 should be used in cases where you have some information that makes you believe
283 that something is of the right type. An example of the <tt>isa&lt;&gt;</tt>
284 and <tt>cast&lt;&gt;</tt> template is:
285
286 <pre>static bool isLoopInvariant(const <a href="#Value">Value</a> *V, const
287 Loop *L) {<br> if (isa&lt;<a href="#Constant">Constant</a>&gt;(V) || isa&lt;<a
288 href="#Argument">Argument</a>&gt;(V) || isa&lt;<a
289 href="#GlobalValue">GlobalValue</a>&gt;(V))<br> return true;<br><br> <i>//
290 Otherwise, it must be an instruction...</i><br> return
291 !L-&gt;contains(cast&lt;<a
292 href="#Instruction">Instruction</a>&gt;(V)-&gt;getParent());<br></pre>
293
294 <p>Note that you should <b>not</b> use an <tt>isa&lt;&gt;</tt> test followed
295 by a <tt>cast&lt;&gt;</tt>, for that use the <tt>dyn_cast&lt;&gt;</tt>
296 operator.</p>
297
298 </dd>
299
300 <dt><tt>dyn_cast&lt;&gt;</tt>:</dt>
301
302 <dd>The <tt>dyn_cast&lt;&gt;</tt> operator is a "checking cast" operation. It
303 checks to see if the operand is of the specified type, and if so, returns a
304 pointer to it (this operator does not work with references). If the operand is
305 not of the correct type, a null pointer is returned. Thus, this works very
306 much like the <tt>dynamic_cast</tt> operator in C++, and should be used in the
307 same circumstances. Typically, the <tt>dyn_cast&lt;&gt;</tt> operator is used
308 in an <tt>if</tt> statement or some other flow control statement like this:
309
310 <pre> if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast&lt;<a
311 href="#AllocationInst">AllocationInst</a>&gt;(Val)) {<br> ...<br> }<br></pre>
312
313 <p> This form of the <tt>if</tt> statement effectively combines together a
314 call to <tt>isa&lt;&gt;</tt> and a call to <tt>cast&lt;&gt;</tt> into one
315 statement, which is very convenient.</p>
316
317 <p> Another common example is:</p>
318
319 <pre> <i>// Loop over all of the phi nodes in a basic block</i><br>
320 BasicBlock::iterator BBI = BB-&gt;begin();<br> for (; <a
321 href="#PhiNode">PHINode</a> *PN = dyn_cast&lt;<a
322 href="#PHINode">PHINode</a>&gt;(BBI); ++BBI)<br> cerr &lt;&lt; *PN;<br></pre>
323
324 <p>Note that the <tt>dyn_cast&lt;&gt;</tt> operator, like C++'s
325 <tt>dynamic_cast</tt> or Java's <tt>instanceof</tt> operator, can be abused.
326 In particular you should not use big chained <tt>if/then/else</tt> blocks to
327 check for lots of different variants of classes. If you find yourself
328 wanting to do this, it is much cleaner and more efficient to use the
329 InstVisitor class to dispatch over the instruction type directly.</p>
330
Chris Lattner261efe92003-11-25 01:02:51 +0000331 </dd>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000332
Chris Lattner261efe92003-11-25 01:02:51 +0000333 <dt><tt>cast_or_null&lt;&gt;</tt>: </dt>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000334
335 <dd>The <tt>cast_or_null&lt;&gt;</tt> operator works just like the
336 <tt>cast&lt;&gt;</tt> operator, except that it allows for a null pointer as
337 an argument (which it then propagates). This can sometimes be useful,
338 allowing you to combine several null checks into one.</dd>
339
Chris Lattner261efe92003-11-25 01:02:51 +0000340 <dt><tt>dyn_cast_or_null&lt;&gt;</tt>: </dt>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000341
342 <dd>The <tt>dyn_cast_or_null&lt;&gt;</tt> operator works just like the
343 <tt>dyn_cast&lt;&gt;</tt> operator, except that it allows for a null pointer
344 as an argument (which it then propagates). This can sometimes be useful,
345 allowing you to combine several null checks into one.</dd>
346
Chris Lattner261efe92003-11-25 01:02:51 +0000347 </dl>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000348
349<p>These five templates can be used with any classes, whether they have a
350v-table or not. To add support for these templates, you simply need to add
351<tt>classof</tt> static methods to the class you are interested casting
352to. Describing this is currently outside the scope of this document, but there
353are lots of examples in the LLVM source base.</p>
354
355</div>
356
357<!-- ======================================================================= -->
358<div class="doc_subsection">
359 <a name="DEBUG">The <tt>DEBUG()</tt> macro &amp; <tt>-debug</tt> option</a>
360</div>
361
362<div class="doc_text">
363
364<p>Often when working on your pass you will put a bunch of debugging printouts
365and other code into your pass. After you get it working, you want to remove
366it... but you may need it again in the future (to work out new bugs that you run
367across).</p>
368
369<p> Naturally, because of this, you don't want to delete the debug printouts,
370but you don't want them to always be noisy. A standard compromise is to comment
371them out, allowing you to enable them if you need them in the future.</p>
372
373<p>The "<tt><a href="/doxygen/Debug_8h-source.html">Support/Debug.h</a></tt>"
374file provides a macro named <tt>DEBUG()</tt> that is a much nicer solution to
375this problem. Basically, you can put arbitrary code into the argument of the
376<tt>DEBUG</tt> macro, and it is only executed if '<tt>opt</tt>' (or any other
377tool) is run with the '<tt>-debug</tt>' command line argument:</p>
378
Chris Lattner261efe92003-11-25 01:02:51 +0000379 <pre> ... <br> DEBUG(std::cerr &lt;&lt; "I am here!\n");<br> ...<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000380
381<p>Then you can run your pass like this:</p>
382
Chris Lattner261efe92003-11-25 01:02:51 +0000383 <pre> $ opt &lt; a.bc &gt; /dev/null -mypass<br> &lt;no output&gt;<br> $ opt &lt; a.bc &gt; /dev/null -mypass -debug<br> I am here!<br> $<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000384
385<p>Using the <tt>DEBUG()</tt> macro instead of a home-brewed solution allows you
386to not have to create "yet another" command line option for the debug output for
387your pass. Note that <tt>DEBUG()</tt> macros are disabled for optimized builds,
388so they do not cause a performance impact at all (for the same reason, they
389should also not contain side-effects!).</p>
390
391<p>One additional nice thing about the <tt>DEBUG()</tt> macro is that you can
392enable or disable it directly in gdb. Just use "<tt>set DebugFlag=0</tt>" or
393"<tt>set DebugFlag=1</tt>" from the gdb if the program is running. If the
394program hasn't been started yet, you can always just run it with
395<tt>-debug</tt>.</p>
396
397</div>
398
399<!-- _______________________________________________________________________ -->
400<div class="doc_subsubsection">
401 <a name="DEBUG_TYPE">Fine grained debug info with <tt>DEBUG_TYPE()</tt> and
402 the <tt>-debug-only</tt> option</a>
403</div>
404
405<div class="doc_text">
406
407<p>Sometimes you may find yourself in a situation where enabling <tt>-debug</tt>
408just turns on <b>too much</b> information (such as when working on the code
409generator). If you want to enable debug information with more fine-grained
410control, you define the <tt>DEBUG_TYPE</tt> macro and the <tt>-debug</tt> only
411option as follows:</p>
412
Chris Lattner261efe92003-11-25 01:02:51 +0000413 <pre> ...<br> DEBUG(std::cerr &lt;&lt; "No debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE "foo"<br> DEBUG(std::cerr &lt;&lt; "'foo' debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE "bar"<br> DEBUG(std::cerr &lt;&lt; "'bar' debug type\n");<br> #undef DEBUG_TYPE<br> #define DEBUG_TYPE ""<br> DEBUG(std::cerr &lt;&lt; "No debug type (2)\n");<br> ...<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000414
415<p>Then you can run your pass like this:</p>
416
Chris Lattner261efe92003-11-25 01:02:51 +0000417 <pre> $ opt &lt; a.bc &gt; /dev/null -mypass<br> &lt;no output&gt;<br> $ opt &lt; a.bc &gt; /dev/null -mypass -debug<br> No debug type<br> 'foo' debug type<br> 'bar' debug type<br> No debug type (2)<br> $ opt &lt; a.bc &gt; /dev/null -mypass -debug-only=foo<br> 'foo' debug type<br> $ opt &lt; a.bc &gt; /dev/null -mypass -debug-only=bar<br> 'bar' debug type<br> $<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000418
419<p>Of course, in practice, you should only set <tt>DEBUG_TYPE</tt> at the top of
420a file, to specify the debug type for the entire module (if you do this before
421you <tt>#include "Support/Debug.h"</tt>, you don't have to insert the ugly
422<tt>#undef</tt>'s). Also, you should use names more meaningful than "foo" and
423"bar", because there is no system in place to ensure that names do not
424conflict. If two different modules use the same string, they will all be turned
425on when the name is specified. This allows, for example, all debug information
426for instruction scheduling to be enabled with <tt>-debug-type=InstrSched</tt>,
Chris Lattner261efe92003-11-25 01:02:51 +0000427even if the source lives in multiple files.</p>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000428
429</div>
430
431<!-- ======================================================================= -->
432<div class="doc_subsection">
433 <a name="Statistic">The <tt>Statistic</tt> template &amp; <tt>-stats</tt>
434 option</a>
435</div>
436
437<div class="doc_text">
438
439<p>The "<tt><a
440href="/doxygen/Statistic_8h-source.html">Support/Statistic.h</a></tt>" file
441provides a template named <tt>Statistic</tt> that is used as a unified way to
442keep track of what the LLVM compiler is doing and how effective various
443optimizations are. It is useful to see what optimizations are contributing to
444making a particular program run faster.</p>
445
446<p>Often you may run your pass on some big program, and you're interested to see
447how many times it makes a certain transformation. Although you can do this with
448hand inspection, or some ad-hoc method, this is a real pain and not very useful
449for big programs. Using the <tt>Statistic</tt> template makes it very easy to
450keep track of this information, and the calculated information is presented in a
451uniform manner with the rest of the passes being executed.</p>
452
453<p>There are many examples of <tt>Statistic</tt> uses, but the basics of using
454it are as follows:</p>
455
456<ol>
Chris Lattner261efe92003-11-25 01:02:51 +0000457 <li>Define your statistic like this:
Chris Lattner261efe92003-11-25 01:02:51 +0000458 <pre>static Statistic&lt;&gt; NumXForms("mypassname", "The # of times I did stuff");<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000459
460 <p>The <tt>Statistic</tt> template can emulate just about any data-type,
461 but if you do not specify a template argument, it defaults to acting like
462 an unsigned int counter (this is usually what you want).</p></li>
463
Chris Lattner261efe92003-11-25 01:02:51 +0000464 <li>Whenever you make a transformation, bump the counter:
Chris Lattner261efe92003-11-25 01:02:51 +0000465 <pre> ++NumXForms; // I did stuff<br></pre>
Chris Lattner261efe92003-11-25 01:02:51 +0000466 </li>
467 </ol>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000468
469 <p>That's all you have to do. To get '<tt>opt</tt>' to print out the
470 statistics gathered, use the '<tt>-stats</tt>' option:</p>
471
Chris Lattner261efe92003-11-25 01:02:51 +0000472 <pre> $ opt -stats -mypassname &lt; program.bc &gt; /dev/null<br> ... statistic output ...<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000473
Chris Lattner261efe92003-11-25 01:02:51 +0000474 <p> When running <tt>gccas</tt> on a C file from the SPEC benchmark
475suite, it gives a report that looks like this:</p>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000476
Chris Lattner261efe92003-11-25 01:02:51 +0000477 <pre> 7646 bytecodewriter - Number of normal instructions<br> 725 bytecodewriter - Number of oversized instructions<br> 129996 bytecodewriter - Number of bytecode bytes written<br> 2817 raise - Number of insts DCEd or constprop'd<br> 3213 raise - Number of cast-of-self removed<br> 5046 raise - Number of expression trees converted<br> 75 raise - Number of other getelementptr's formed<br> 138 raise - Number of load/store peepholes<br> 42 deadtypeelim - Number of unused typenames removed from symtab<br> 392 funcresolve - Number of varargs functions resolved<br> 27 globaldce - Number of global variables removed<br> 2 adce - Number of basic blocks removed<br> 134 cee - Number of branches revectored<br> 49 cee - Number of setcc instruction eliminated<br> 532 gcse - Number of loads removed<br> 2919 gcse - Number of instructions removed<br> 86 indvars - Number of canonical indvars added<br> 87 indvars - Number of aux indvars removed<br> 25 instcombine - Number of dead inst eliminate<br> 434 instcombine - Number of insts combined<br> 248 licm - Number of load insts hoisted<br> 1298 licm - Number of insts hoisted to a loop pre-header<br> 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)<br> 75 mem2reg - Number of alloca's promoted<br> 1444 cfgsimplify - Number of blocks simplified<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000478
479<p>Obviously, with so many optimizations, having a unified framework for this
480stuff is very nice. Making your pass fit well into the framework makes it more
481maintainable and useful.</p>
482
483</div>
484
485<!-- *********************************************************************** -->
486<div class="doc_section">
487 <a name="common">Helpful Hints for Common Operations</a>
488</div>
489<!-- *********************************************************************** -->
490
491<div class="doc_text">
492
493<p>This section describes how to perform some very simple transformations of
494LLVM code. This is meant to give examples of common idioms used, showing the
495practical side of LLVM transformations. <p> Because this is a "how-to" section,
496you should also read about the main classes that you will be working with. The
497<a href="#coreclasses">Core LLVM Class Hierarchy Reference</a> contains details
498and descriptions of the main classes that you should know about.</p>
499
500</div>
501
502<!-- NOTE: this section should be heavy on example code -->
503<!-- ======================================================================= -->
504<div class="doc_subsection">
505 <a name="inspection">Basic Inspection and Traversal Routines</a>
506</div>
507
508<div class="doc_text">
509
510<p>The LLVM compiler infrastructure have many different data structures that may
511be traversed. Following the example of the C++ standard template library, the
512techniques used to traverse these various data structures are all basically the
513same. For a enumerable sequence of values, the <tt>XXXbegin()</tt> function (or
514method) returns an iterator to the start of the sequence, the <tt>XXXend()</tt>
515function returns an iterator pointing to one past the last valid element of the
516sequence, and there is some <tt>XXXiterator</tt> data type that is common
517between the two operations.</p>
518
519<p>Because the pattern for iteration is common across many different aspects of
520the program representation, the standard template library algorithms may be used
521on them, and it is easier to remember how to iterate. First we show a few common
522examples of the data structures that need to be traversed. Other data
523structures are traversed in very similar ways.</p>
524
525</div>
526
527<!-- _______________________________________________________________________ -->
528<div class="subsubsection">
529 <a name="iterate_function">Iterating over the </a><a
530 href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a
531 href="#Function"><tt>Function</tt></a>
532</div>
533
534<div class="doc_text">
535
536<p>It's quite common to have a <tt>Function</tt> instance that you'd like to
537transform in some way; in particular, you'd like to manipulate its
538<tt>BasicBlock</tt>s. To facilitate this, you'll need to iterate over all of
539the <tt>BasicBlock</tt>s that constitute the <tt>Function</tt>. The following is
540an example that prints the name of a <tt>BasicBlock</tt> and the number of
541<tt>Instruction</tt>s it contains:</p>
542
Chris Lattner261efe92003-11-25 01:02:51 +0000543 <pre> // func is a pointer to a Function instance<br> for (Function::iterator i = func-&gt;begin(), e = func-&gt;end(); i != e; ++i) {<br><br> // print out the name of the basic block if it has one, and then the<br> // number of instructions that it contains<br><br> cerr &lt;&lt; "Basic block (name=" &lt;&lt; i-&gt;getName() &lt;&lt; ") has " <br> &lt;&lt; i-&gt;size() &lt;&lt; " instructions.\n";<br> }<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000544
545<p>Note that i can be used as if it were a pointer for the purposes of
Joel Stanley9b96c442002-09-06 21:55:13 +0000546invoking member functions of the <tt>Instruction</tt> class. This is
547because the indirection operator is overloaded for the iterator
Chris Lattner7496ec52003-08-05 22:54:23 +0000548classes. In the above code, the expression <tt>i-&gt;size()</tt> is
Misha Brukman13fd15c2004-01-15 00:14:41 +0000549exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.</p>
550
551</div>
552
553<!-- _______________________________________________________________________ -->
554<div class="subsubsection">
555 <a name="iterate_basicblock">Iterating over the </a><a
556 href="#Instruction"><tt>Instruction</tt></a>s in a <a
557 href="#BasicBlock"><tt>BasicBlock</tt></a>
558</div>
559
560<div class="doc_text">
561
562<p>Just like when dealing with <tt>BasicBlock</tt>s in <tt>Function</tt>s, it's
563easy to iterate over the individual instructions that make up
564<tt>BasicBlock</tt>s. Here's a code snippet that prints out each instruction in
565a <tt>BasicBlock</tt>:</p>
566
Chris Lattner261efe92003-11-25 01:02:51 +0000567 <pre> // blk is a pointer to a BasicBlock instance<br> for (BasicBlock::iterator i = blk-&gt;begin(), e = blk-&gt;end(); i != e; ++i)<br> // the next statement works since operator&lt;&lt;(ostream&amp;,...) <br> // is overloaded for Instruction&amp;<br> cerr &lt;&lt; *i &lt;&lt; "\n";<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000568
569<p>However, this isn't really the best way to print out the contents of a
570<tt>BasicBlock</tt>! Since the ostream operators are overloaded for virtually
571anything you'll care about, you could have just invoked the print routine on the
572basic block itself: <tt>cerr &lt;&lt; *blk &lt;&lt; "\n";</tt>.</p>
573
574<p>Note that currently operator&lt;&lt; is implemented for <tt>Value*</tt>, so
575it will print out the contents of the pointer, instead of the pointer value you
576might expect. This is a deprecated interface that will be removed in the
577future, so it's best not to depend on it. To print out the pointer value for
578now, you must cast to <tt>void*</tt>.</p>
579
580</div>
581
582<!-- _______________________________________________________________________ -->
583<div class="subsubsection">
584 <a name="iterate_institer">Iterating over the </a><a
585 href="#Instruction"><tt>Instruction</tt></a>s in a <a
586 href="#Function"><tt>Function</tt></a>
587</div>
588
589<div class="doc_text">
590
591<p>If you're finding that you commonly iterate over a <tt>Function</tt>'s
592<tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s <tt>Instruction</tt>s,
593<tt>InstIterator</tt> should be used instead. You'll need to include <a
594href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>,
595and then instantiate <tt>InstIterator</tt>s explicitly in your code. Here's a
596small example that shows how to dump all instructions in a function to stderr
597(<b>Note:</b> Dereferencing an <tt>InstIterator</tt> yields an
598<tt>Instruction*</tt>, <i>not</i> an <tt>Instruction&amp;</tt>!):</p>
599
Chris Lattner261efe92003-11-25 01:02:51 +0000600 <pre>#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"<br>...<br>// Suppose F is a ptr to a function<br>for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)<br> cerr &lt;&lt; **i &lt;&lt; "\n";<br></pre>
Joel Stanleye7be6502002-09-09 15:50:33 +0000601Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a
602worklist with its initial contents. For example, if you wanted to
Chris Lattner261efe92003-11-25 01:02:51 +0000603initialize a worklist to contain all instructions in a <tt>Function</tt>
604F, all you would need to do is something like:
605 <pre>std::set&lt;Instruction*&gt; worklist;<br>worklist.insert(inst_begin(F), inst_end(F));<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000606
607<p>The STL set <tt>worklist</tt> would now contain all instructions in the
608<tt>Function</tt> pointed to by F.</p>
609
610</div>
611
612<!-- _______________________________________________________________________ -->
613<div class="doc_subsubsection">
614 <a name="iterate_convert">Turning an iterator into a class pointer (and
615 vice-versa)</a>
616</div>
617
618<div class="doc_text">
619
620<p>Sometimes, it'll be useful to grab a reference (or pointer) to a class
Joel Stanley9b96c442002-09-06 21:55:13 +0000621instance when all you've got at hand is an iterator. Well, extracting
622a reference or a pointer from an iterator is very straightforward.
Chris Lattner261efe92003-11-25 01:02:51 +0000623Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and <tt>j</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000624is a <tt>BasicBlock::const_iterator</tt>:</p>
625
Chris Lattner261efe92003-11-25 01:02:51 +0000626 <pre> Instruction&amp; inst = *i; // grab reference to instruction reference<br> Instruction* pinst = &amp;*i; // grab pointer to instruction reference<br> const Instruction&amp; inst = *j;<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000627
628<p>However, the iterators you'll be working with in the LLVM framework are
629special: they will automatically convert to a ptr-to-instance type whenever they
630need to. Instead of dereferencing the iterator and then taking the address of
631the result, you can simply assign the iterator to the proper pointer type and
632you get the dereference and address-of operation as a result of the assignment
633(behind the scenes, this is a result of overloading casting mechanisms). Thus
634the last line of the last example,</p>
635
Chris Lattner261efe92003-11-25 01:02:51 +0000636 <pre>Instruction* pinst = &amp;*i;</pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000637
638<p>is semantically equivalent to</p>
639
Chris Lattner261efe92003-11-25 01:02:51 +0000640 <pre>Instruction* pinst = i;</pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000641
642<p>It's also possible to turn a class pointer into the corresponding iterator.
643Usually, this conversion is quite inexpensive. The following code snippet
644illustrates use of the conversion constructors provided by LLVM iterators. By
645using these, you can explicitly grab the iterator of something without actually
646obtaining it via iteration over some structure:</p>
647
Chris Lattner261efe92003-11-25 01:02:51 +0000648 <pre>void printNextInstruction(Instruction* inst) {<br> BasicBlock::iterator it(inst);<br> ++it; // after this line, it refers to the instruction after *inst.<br> if (it != inst-&gt;getParent()-&gt;end()) cerr &lt;&lt; *it &lt;&lt; "\n";<br>}<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000649
650<p>Of course, this example is strictly pedagogical, because it'd be much
651better to explicitly grab the next instruction directly from inst.</p>
652
653</div>
654
655<!--_______________________________________________________________________-->
656<div class="doc_subsubsection">
657 <a name="iterate_complex">Finding call sites: a slightly more complex
658 example</a>
659</div>
660
661<div class="doc_text">
662
663<p>Say that you're writing a FunctionPass and would like to count all the
664locations in the entire module (that is, across every <tt>Function</tt>) where a
665certain function (i.e., some <tt>Function</tt>*) is already in scope. As you'll
666learn later, you may want to use an <tt>InstVisitor</tt> to accomplish this in a
667much more straightforward manner, but this example will allow us to explore how
668you'd do it if you didn't have <tt>InstVisitor</tt> around. In pseudocode, this
669is what we want to do:</p>
670
Chris Lattner261efe92003-11-25 01:02:51 +0000671 <pre>initialize callCounter to zero<br>for each Function f in the Module<br> for each BasicBlock b in f<br> for each Instruction i in b<br> if (i is a CallInst and calls the given function)<br> increment callCounter<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000672
673<p>And the actual code is (remember, since we're writing a
674<tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply has to
675override the <tt>runOnFunction</tt> method...):</p>
676
Chris Lattner261efe92003-11-25 01:02:51 +0000677 <pre>Function* targetFunc = ...;<br><br>class OurFunctionPass : public FunctionPass {<br> public:<br> OurFunctionPass(): callCounter(0) { }<br><br> virtual runOnFunction(Function&amp; F) {<br> for (Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {<br> for (BasicBlock::iterator i = b-&gt;begin(); ie = b-&gt;end(); i != ie; ++i) {<br> if (<a
678 href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a>&lt;<a
679 href="#CallInst">CallInst</a>&gt;(&amp;*i)) {<br> // we know we've encountered a call instruction, so we<br> // need to determine if it's a call to the<br> // function pointed to by m_func or not.<br> <br> if (callInst-&gt;getCalledFunction() == targetFunc)<br> ++callCounter;<br> }<br> }<br> }<br> <br> private:<br> unsigned callCounter;<br>};<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000680
681</div>
682
Brian Gaekef1972c62003-11-07 19:25:45 +0000683<!--_______________________________________________________________________-->
Misha Brukman13fd15c2004-01-15 00:14:41 +0000684<div class="doc_subsubsection">
685 <a name="calls_and_invokes">Treating calls and invokes the same way</a>
686</div>
687
688<div class="doc_text">
689
690<p>You may have noticed that the previous example was a bit oversimplified in
691that it did not deal with call sites generated by 'invoke' instructions. In
692this, and in other situations, you may find that you want to treat
693<tt>CallInst</tt>s and <tt>InvokeInst</tt>s the same way, even though their
694most-specific common base class is <tt>Instruction</tt>, which includes lots of
695less closely-related things. For these cases, LLVM provides a handy wrapper
696class called <a
697href="http://llvm.cs.uiuc.edu/doxygen/classCallSite.html"><tt>CallSite
698</tt></a>. It is essentially a wrapper around an <tt>Instruction</tt> pointer,
699with some methods that provide functionality common to <tt>CallInst</tt>s and
700<tt>InvokeInst</tt>s.</p>
701
702<p>This class is supposed to have "value semantics". So it should be passed by
703value, not by reference; it should not be dynamically allocated or deallocated
704using <tt>operator new</tt> or <tt>operator delete</tt>. It is efficiently
705copyable, assignable and constructable, with costs equivalents to that of a bare
706pointer. (You will notice, if you look at its definition, that it has only a
707single data member.)</p>
708
709</div>
710
Chris Lattner1a3105b2002-09-09 05:49:39 +0000711<!--_______________________________________________________________________-->
Misha Brukman13fd15c2004-01-15 00:14:41 +0000712<div class="doc_subsubsection">
713 <a name="iterate_chains">Iterating over def-use &amp; use-def chains</a>
714</div>
715
716<div class="doc_text">
717
718<p>Frequently, we might have an instance of the <a
719href="/doxygen/classValue.html">Value Class</a> and we want to determine which
720<tt>User</tt>s use the <tt>Value</tt>. The list of all <tt>User</tt>s of a
721particular <tt>Value</tt> is called a <i>def-use</i> chain. For example, let's
722say we have a <tt>Function*</tt> named <tt>F</tt> to a particular function
723<tt>foo</tt>. Finding all of the instructions that <i>use</i> <tt>foo</tt> is as
724simple as iterating over the <i>def-use</i> chain of <tt>F</tt>:</p>
725
Chris Lattner261efe92003-11-25 01:02:51 +0000726 <pre>Function* F = ...;<br><br>for (Value::use_iterator i = F-&gt;use_begin(), e = F-&gt;use_end(); i != e; ++i) {<br> if (Instruction *Inst = dyn_cast&lt;Instruction&gt;(*i)) {<br> cerr &lt;&lt; "F is used in instruction:\n";<br> cerr &lt;&lt; *Inst &lt;&lt; "\n";<br> }<br>}<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000727
728<p>Alternately, it's common to have an instance of the <a
729href="/doxygen/classUser.html">User Class</a> and need to know what
730<tt>Value</tt>s are used by it. The list of all <tt>Value</tt>s used by a
731<tt>User</tt> is known as a <i>use-def</i> chain. Instances of class
732<tt>Instruction</tt> are common <tt>User</tt>s, so we might want to iterate over
733all of the values that a particular instruction uses (that is, the operands of
734the particular <tt>Instruction</tt>):</p>
735
Chris Lattner261efe92003-11-25 01:02:51 +0000736 <pre>Instruction* pi = ...;<br><br>for (User::op_iterator i = pi-&gt;op_begin(), e = pi-&gt;op_end(); i != e; ++i) {<br> Value* v = *i;<br> ...<br>}<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000737
Chris Lattner1a3105b2002-09-09 05:49:39 +0000738<!--
739 def-use chains ("finding all users of"): Value::use_begin/use_end
740 use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
Misha Brukman13fd15c2004-01-15 00:14:41 +0000741-->
742
743</div>
744
745<!-- ======================================================================= -->
746<div class="doc_subsection">
747 <a name="simplechanges">Making simple changes</a>
748</div>
749
750<div class="doc_text">
751
752<p>There are some primitive transformation operations present in the LLVM
Joel Stanley753eb712002-09-11 22:32:24 +0000753infrastructure that are worth knowing about. When performing
Chris Lattner261efe92003-11-25 01:02:51 +0000754transformations, it's fairly common to manipulate the contents of basic
755blocks. This section describes some of the common methods for doing so
Misha Brukman13fd15c2004-01-15 00:14:41 +0000756and gives example code.</p>
757
758</div>
759
Chris Lattner261efe92003-11-25 01:02:51 +0000760<!--_______________________________________________________________________-->
Misha Brukman13fd15c2004-01-15 00:14:41 +0000761<div class="doc_subsubsection">
762 <a name="schanges_creating">Creating and inserting new
763 <tt>Instruction</tt>s</a>
764</div>
765
766<div class="doc_text">
767
768<p><i>Instantiating Instructions</i></p>
769
770<p>Creation of <tt>Instruction</tt>s is straightforward: simply call the
771constructor for the kind of instruction to instantiate and provide the necessary
772parameters. For example, an <tt>AllocaInst</tt> only <i>requires</i> a
773(const-ptr-to) <tt>Type</tt>. Thus:</p>
774
775<pre>AllocaInst* ai = new AllocaInst(Type::IntTy);</pre>
776
777<p>will create an <tt>AllocaInst</tt> instance that represents the allocation of
778one integer in the current stack frame, at runtime. Each <tt>Instruction</tt>
779subclass is likely to have varying default parameters which change the semantics
780of the instruction, so refer to the <a
781href="/doxygen/classInstruction.html">doxygen documentation for the subclass of
782Instruction</a> that you're interested in instantiating.</p>
783
784<p><i>Naming values</i></p>
785
786<p>It is very useful to name the values of instructions when you're able to, as
787this facilitates the debugging of your transformations. If you end up looking
788at generated LLVM machine code, you definitely want to have logical names
789associated with the results of instructions! By supplying a value for the
790<tt>Name</tt> (default) parameter of the <tt>Instruction</tt> constructor, you
791associate a logical name with the result of the instruction's execution at
792runtime. For example, say that I'm writing a transformation that dynamically
793allocates space for an integer on the stack, and that integer is going to be
794used as some kind of index by some other code. To accomplish this, I place an
795<tt>AllocaInst</tt> at the first point in the first <tt>BasicBlock</tt> of some
796<tt>Function</tt>, and I'm intending to use it within the same
797<tt>Function</tt>. I might do:</p>
798
799 <pre>AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");</pre>
800
801<p>where <tt>indexLoc</tt> is now the logical name of the instruction's
802execution value, which is a pointer to an integer on the runtime stack.</p>
803
804<p><i>Inserting instructions</i></p>
805
806<p>There are essentially two ways to insert an <tt>Instruction</tt>
807into an existing sequence of instructions that form a <tt>BasicBlock</tt>:</p>
808
Joel Stanley9dd1ad62002-09-18 03:17:23 +0000809<ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000810 <li>Insertion into an explicit instruction list
811
812 <p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within that
813 <tt>BasicBlock</tt>, and a newly-created instruction we wish to insert
814 before <tt>*pi</tt>, we do the following: </p>
815
816 <pre> BasicBlock *pb = ...;<br> Instruction *pi = ...;<br> Instruction *newInst = new Instruction(...);<br> pb-&gt;getInstList().insert(pi, newInst); // inserts newInst before pi in pb<br></pre></li>
817
818 <li>Insertion into an implicit instruction list
819
820 <p><tt>Instruction</tt> instances that are already in <tt>BasicBlock</tt>s
821 are implicitly associated with an existing instruction list: the instruction
822 list of the enclosing basic block. Thus, we could have accomplished the same
823 thing as the above code without being given a <tt>BasicBlock</tt> by doing:
824 </p>
825
826 <pre> Instruction *pi = ...;<br> Instruction *newInst = new Instruction(...);<br> pi-&gt;getParent()-&gt;getInstList().insert(pi, newInst);<br></pre>
827
828 <p>In fact, this sequence of steps occurs so frequently that the
829 <tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes provide
830 constructors which take (as a default parameter) a pointer to an
831 <tt>Instruction</tt> which the newly-created <tt>Instruction</tt> should
832 precede. That is, <tt>Instruction</tt> constructors are capable of
833 inserting the newly-created instance into the <tt>BasicBlock</tt> of a
834 provided instruction, immediately before that instruction. Using an
835 <tt>Instruction</tt> constructor with a <tt>insertBefore</tt> (default)
836 parameter, the above code becomes:</p>
837
838 <pre>Instruction* pi = ...;<br>Instruction* newInst = new Instruction(..., pi);<br></pre>
839
840 <p>which is much cleaner, especially if you're creating a lot of
841instructions and adding them to <tt>BasicBlock</tt>s.</p></li>
842</ul>
843
844</div>
845
846<!--_______________________________________________________________________-->
847<div class="doc_subsubsection">
848 <a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a>
849</div>
850
851<div class="doc_text">
852
853<p>Deleting an instruction from an existing sequence of instructions that form a
854<a href="#BasicBlock"><tt>BasicBlock</tt></a> is very straightforward. First,
855you must have a pointer to the instruction that you wish to delete. Second, you
856need to obtain the pointer to that instruction's basic block. You use the
857pointer to the basic block to get its list of instructions and then use the
858erase function to remove your instruction. For example:</p>
859
Chris Lattner261efe92003-11-25 01:02:51 +0000860 <pre> <a href="#Instruction">Instruction</a> *I = .. ;<br> <a
861 href="#BasicBlock">BasicBlock</a> *BB = I-&gt;getParent();<br> BB-&gt;getInstList().erase(I);<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000862
863</div>
864
865<!--_______________________________________________________________________-->
866<div class="doc_subsubsection">
867 <a name="schanges_replacing">Replacing an <tt>Instruction</tt> with another
868 <tt>Value</tt></a>
869</div>
870
871<div class="doc_text">
872
873<p><i>Replacing individual instructions</i></p>
874
875<p>Including "<a href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h</a>"
Chris Lattner261efe92003-11-25 01:02:51 +0000876permits use of two very useful replace functions: <tt>ReplaceInstWithValue</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000877and <tt>ReplaceInstWithInst</tt>.</p>
878
Chris Lattner261efe92003-11-25 01:02:51 +0000879<h4><a name="schanges_deleting">Deleting <tt>Instruction</tt>s</a></h4>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000880
Chris Lattner261efe92003-11-25 01:02:51 +0000881<ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000882 <li><tt>ReplaceInstWithValue</tt>
883
884 <p>This function replaces all uses (within a basic block) of a given
885 instruction with a value, and then removes the original instruction. The
886 following example illustrates the replacement of the result of a particular
887 <tt>AllocaInst</tt> that allocates memory for a single integer with an null
888 pointer to an integer.</p>
889
890 <pre>AllocaInst* instToReplace = ...;<br>BasicBlock::iterator ii(instToReplace);<br>ReplaceInstWithValue(instToReplace-&gt;getParent()-&gt;getInstList(), ii,<br> Constant::getNullValue(PointerType::get(Type::IntTy)));<br></pre></li>
891
892 <li><tt>ReplaceInstWithInst</tt>
893
894 <p>This function replaces a particular instruction with another
895 instruction. The following example illustrates the replacement of one
896 <tt>AllocaInst</tt> with another.</p>
897
898 <pre>AllocaInst* instToReplace = ...;<br>BasicBlock::iterator ii(instToReplace);<br>ReplaceInstWithInst(instToReplace-&gt;getParent()-&gt;getInstList(), ii,<br> new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt"));<br></pre></li>
Chris Lattner261efe92003-11-25 01:02:51 +0000899</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000900
901<p><i>Replacing multiple uses of <tt>User</tt>s and <tt>Value</tt>s</i></p>
902
903<p>You can use <tt>Value::replaceAllUsesWith</tt> and
904<tt>User::replaceUsesOfWith</tt> to change more than one use at a time. See the
905doxygen documentation for the <a href="/doxygen/classValue.html">Value Class</a>
906and <a href="/doxygen/classUser.html">User Class</a>, respectively, for more
907information.</p>
908
909<!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
910include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
911ReplaceInstWithValue, ReplaceInstWithInst -->
912
913</div>
914
Chris Lattner9355b472002-09-06 02:50:58 +0000915<!-- *********************************************************************** -->
Misha Brukman13fd15c2004-01-15 00:14:41 +0000916<div class="doc_section">
917 <a name="coreclasses">The Core LLVM Class Hierarchy Reference </a>
918</div>
919<!-- *********************************************************************** -->
920
921<div class="doc_text">
922
923<p>The Core LLVM classes are the primary means of representing the program
Chris Lattner261efe92003-11-25 01:02:51 +0000924being inspected or transformed. The core LLVM classes are defined in
925header files in the <tt>include/llvm/</tt> directory, and implemented in
Misha Brukman13fd15c2004-01-15 00:14:41 +0000926the <tt>lib/VMCore</tt> directory.</p>
927
928</div>
929
930<!-- ======================================================================= -->
931<div class="doc_subsection">
932 <a name="Value">The <tt>Value</tt> class</a>
933</div>
934
935<div>
936
937<p><tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt>
938<br>
939doxygen info: <a href="/doxygen/classValue.html">Value Class</a></p>
940
941<p>The <tt>Value</tt> class is the most important class in the LLVM Source
942base. It represents a typed value that may be used (among other things) as an
943operand to an instruction. There are many different types of <tt>Value</tt>s,
944such as <a href="#Constant"><tt>Constant</tt></a>s,<a
945href="#Argument"><tt>Argument</tt></a>s. Even <a
946href="#Instruction"><tt>Instruction</tt></a>s and <a
947href="#Function"><tt>Function</tt></a>s are <tt>Value</tt>s.</p>
948
949<p>A particular <tt>Value</tt> may be used many times in the LLVM representation
950for a program. For example, an incoming argument to a function (represented
951with an instance of the <a href="#Argument">Argument</a> class) is "used" by
952every instruction in the function that references the argument. To keep track
953of this relationship, the <tt>Value</tt> class keeps a list of all of the <a
954href="#User"><tt>User</tt></a>s that is using it (the <a
955href="#User"><tt>User</tt></a> class is a base class for all nodes in the LLVM
956graph that can refer to <tt>Value</tt>s). This use list is how LLVM represents
957def-use information in the program, and is accessible through the <tt>use_</tt>*
958methods, shown below.</p>
959
960<p>Because LLVM is a typed representation, every LLVM <tt>Value</tt> is typed,
961and this <a href="#Type">Type</a> is available through the <tt>getType()</tt>
962method. In addition, all LLVM values can be named. The "name" of the
963<tt>Value</tt> is a symbolic string printed in the LLVM code:</p>
964
Chris Lattner261efe92003-11-25 01:02:51 +0000965 <pre> %<b>foo</b> = add int 1, 2<br></pre>
Misha Brukman13fd15c2004-01-15 00:14:41 +0000966
967<p><a name="#nameWarning">The name of this instruction is "foo".</a> <b>NOTE</b>
968that the name of any value may be missing (an empty string), so names should
969<b>ONLY</b> be used for debugging (making the source code easier to read,
970debugging printouts), they should not be used to keep track of values or map
971between them. For this purpose, use a <tt>std::map</tt> of pointers to the
972<tt>Value</tt> itself instead.</p>
973
974<p>One important aspect of LLVM is that there is no distinction between an SSA
975variable and the operation that produces it. Because of this, any reference to
976the value produced by an instruction (or the value available as an incoming
977argument, for example) is represented as a direct pointer to the class that
978represents this value. Although this may take some getting used to, it
979simplifies the representation and makes it easier to manipulate.</p>
980
981</div>
982
983<!-- _______________________________________________________________________ -->
984<div class="doc_subsubsection">
985 <a name="m_Value">Important Public Members of the <tt>Value</tt> class</a>
986</div>
987
988<div class="doc_text">
989
Chris Lattner261efe92003-11-25 01:02:51 +0000990<ul>
991 <li><tt>Value::use_iterator</tt> - Typedef for iterator over the
992use-list<br>
993 <tt>Value::use_const_iterator</tt> - Typedef for const_iterator over
994the use-list<br>
995 <tt>unsigned use_size()</tt> - Returns the number of users of the
996value.<br>
Chris Lattner9355b472002-09-06 02:50:58 +0000997 <tt>bool use_empty()</tt> - Returns true if there are no users.<br>
Chris Lattner261efe92003-11-25 01:02:51 +0000998 <tt>use_iterator use_begin()</tt> - Get an iterator to the start of
999the use-list.<br>
1000 <tt>use_iterator use_end()</tt> - Get an iterator to the end of the
1001use-list.<br>
1002 <tt><a href="#User">User</a> *use_back()</tt> - Returns the last
1003element in the list.
1004 <p> These methods are the interface to access the def-use
1005information in LLVM. As with all other iterators in LLVM, the naming
1006conventions follow the conventions defined by the <a href="#stl">STL</a>.</p>
Chris Lattner261efe92003-11-25 01:02:51 +00001007 </li>
1008 <li><tt><a href="#Type">Type</a> *getType() const</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001009 <p>This method returns the Type of the Value.</p>
Chris Lattner261efe92003-11-25 01:02:51 +00001010 </li>
1011 <li><tt>bool hasName() const</tt><br>
Chris Lattner9355b472002-09-06 02:50:58 +00001012 <tt>std::string getName() const</tt><br>
Chris Lattner261efe92003-11-25 01:02:51 +00001013 <tt>void setName(const std::string &amp;Name)</tt>
1014 <p> This family of methods is used to access and assign a name to a <tt>Value</tt>,
1015be aware of the <a href="#nameWarning">precaution above</a>.</p>
Chris Lattner261efe92003-11-25 01:02:51 +00001016 </li>
1017 <li><tt>void replaceAllUsesWith(Value *V)</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001018
1019 <p>This method traverses the use list of a <tt>Value</tt> changing all <a
1020 href="#User"><tt>User</tt>s</a> of the current value to refer to
1021 "<tt>V</tt>" instead. For example, if you detect that an instruction always
1022 produces a constant value (for example through constant folding), you can
1023 replace all uses of the instruction with the constant like this:</p>
1024
Chris Lattner261efe92003-11-25 01:02:51 +00001025 <pre> Inst-&gt;replaceAllUsesWith(ConstVal);<br></pre>
Chris Lattner261efe92003-11-25 01:02:51 +00001026</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001027
1028</div>
1029
1030<!-- ======================================================================= -->
1031<div class="doc_subsection">
1032 <a name="User">The <tt>User</tt> class</a>
1033</div>
1034
1035<div class="doc_text">
1036
1037<p>
1038<tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt><br>
Chris Lattner9355b472002-09-06 02:50:58 +00001039doxygen info: <a href="/doxygen/classUser.html">User Class</a><br>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001040Superclass: <a href="#Value"><tt>Value</tt></a></p>
1041
1042<p>The <tt>User</tt> class is the common base class of all LLVM nodes that may
1043refer to <a href="#Value"><tt>Value</tt></a>s. It exposes a list of "Operands"
1044that are all of the <a href="#Value"><tt>Value</tt></a>s that the User is
1045referring to. The <tt>User</tt> class itself is a subclass of
1046<tt>Value</tt>.</p>
1047
1048<p>The operands of a <tt>User</tt> point directly to the LLVM <a
1049href="#Value"><tt>Value</tt></a> that it refers to. Because LLVM uses Static
1050Single Assignment (SSA) form, there can only be one definition referred to,
1051allowing this direct connection. This connection provides the use-def
1052information in LLVM.</p>
1053
1054</div>
1055
1056<!-- _______________________________________________________________________ -->
1057<div class="doc_subsubsection">
1058 <a name="m_User">Important Public Members of the <tt>User</tt> class</a>
1059</div>
1060
1061<div class="doc_text">
1062
1063<p>The <tt>User</tt> class exposes the operand list in two ways: through
1064an index access interface and through an iterator based interface.</p>
1065
Chris Lattner261efe92003-11-25 01:02:51 +00001066<ul>
Chris Lattner261efe92003-11-25 01:02:51 +00001067 <li><tt>Value *getOperand(unsigned i)</tt><br>
1068 <tt>unsigned getNumOperands()</tt>
1069 <p> These two methods expose the operands of the <tt>User</tt> in a
Misha Brukman13fd15c2004-01-15 00:14:41 +00001070convenient form for direct access.</p></li>
1071
Chris Lattner261efe92003-11-25 01:02:51 +00001072 <li><tt>User::op_iterator</tt> - Typedef for iterator over the operand
1073list<br>
1074 <tt>User::op_const_iterator</tt> <tt>use_iterator op_begin()</tt> -
1075Get an iterator to the start of the operand list.<br>
1076 <tt>use_iterator op_end()</tt> - Get an iterator to the end of the
1077operand list.
1078 <p> Together, these methods make up the iterator based interface to
Misha Brukman13fd15c2004-01-15 00:14:41 +00001079the operands of a <tt>User</tt>.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001080</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001081
1082</div>
1083
1084<!-- ======================================================================= -->
1085<div class="doc_subsection">
1086 <a name="Instruction">The <tt>Instruction</tt> class</a>
1087</div>
1088
1089<div class="doc_text">
1090
1091<p><tt>#include "</tt><tt><a
1092href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt><br>
1093doxygen info: <a href="/doxygen/classInstruction.html">Instruction Class</a><br>
1094Superclasses: <a href="#User"><tt>User</tt></a>, <a
1095href="#Value"><tt>Value</tt></a></p>
1096
1097<p>The <tt>Instruction</tt> class is the common base class for all LLVM
1098instructions. It provides only a few methods, but is a very commonly used
1099class. The primary data tracked by the <tt>Instruction</tt> class itself is the
1100opcode (instruction type) and the parent <a
1101href="#BasicBlock"><tt>BasicBlock</tt></a> the <tt>Instruction</tt> is embedded
1102into. To represent a specific type of instruction, one of many subclasses of
1103<tt>Instruction</tt> are used.</p>
1104
1105<p> Because the <tt>Instruction</tt> class subclasses the <a
1106href="#User"><tt>User</tt></a> class, its operands can be accessed in the same
1107way as for other <a href="#User"><tt>User</tt></a>s (with the
1108<tt>getOperand()</tt>/<tt>getNumOperands()</tt> and
1109<tt>op_begin()</tt>/<tt>op_end()</tt> methods).</p> <p> An important file for
1110the <tt>Instruction</tt> class is the <tt>llvm/Instruction.def</tt> file. This
1111file contains some meta-data about the various different types of instructions
1112in LLVM. It describes the enum values that are used as opcodes (for example
1113<tt>Instruction::Add</tt> and <tt>Instruction::SetLE</tt>), as well as the
1114concrete sub-classes of <tt>Instruction</tt> that implement the instruction (for
1115example <tt><a href="#BinaryOperator">BinaryOperator</a></tt> and <tt><a
1116href="#SetCondInst">SetCondInst</a></tt>). Unfortunately, the use of macros in
1117this file confuses doxygen, so these enum values don't show up correctly in the
1118<a href="/doxygen/classInstruction.html">doxygen output</a>.</p>
1119
1120</div>
1121
1122<!-- _______________________________________________________________________ -->
1123<div class="doc_subsubsection">
1124 <a name="m_Instruction">Important Public Members of the <tt>Instruction</tt>
1125 class</a>
1126</div>
1127
1128<div class="doc_text">
1129
Chris Lattner261efe92003-11-25 01:02:51 +00001130<ul>
1131 <li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001132 <p>Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that
1133this <tt>Instruction</tt> is embedded into.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001134 <li><tt>bool mayWriteToMemory()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001135 <p>Returns true if the instruction writes to memory, i.e. it is a
1136 <tt>call</tt>,<tt>free</tt>,<tt>invoke</tt>, or <tt>store</tt>.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001137 <li><tt>unsigned getOpcode()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001138 <p>Returns the opcode for the <tt>Instruction</tt>.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001139 <li><tt><a href="#Instruction">Instruction</a> *clone() const</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001140 <p>Returns another instance of the specified instruction, identical
Chris Lattner261efe92003-11-25 01:02:51 +00001141in all ways to the original except that the instruction has no parent
1142(ie it's not embedded into a <a href="#BasicBlock"><tt>BasicBlock</tt></a>),
Misha Brukman13fd15c2004-01-15 00:14:41 +00001143and it has no name</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001144</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001145
1146</div>
1147
1148<!-- ======================================================================= -->
1149<div class="doc_subsection">
1150 <a name="BasicBlock">The <tt>BasicBlock</tt> class</a>
1151</div>
1152
1153<div class="doc_text">
1154
1155<p><tt>#include "<a href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt><br>
Chris Lattner9355b472002-09-06 02:50:58 +00001156doxygen info: <a href="/doxygen/classBasicBlock.html">BasicBlock Class</a><br>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001157Superclass: <a href="#Value"><tt>Value</tt></a></p>
1158
1159<p>This class represents a single entry multiple exit section of the code,
1160commonly known as a basic block by the compiler community. The
1161<tt>BasicBlock</tt> class maintains a list of <a
1162href="#Instruction"><tt>Instruction</tt></a>s, which form the body of the block.
1163Matching the language definition, the last element of this list of instructions
1164is always a terminator instruction (a subclass of the <a
1165href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).</p>
1166
1167<p>In addition to tracking the list of instructions that make up the block, the
1168<tt>BasicBlock</tt> class also keeps track of the <a
1169href="#Function"><tt>Function</tt></a> that it is embedded into.</p>
1170
1171<p>Note that <tt>BasicBlock</tt>s themselves are <a
1172href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions
1173like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type
1174<tt>label</tt>.</p>
1175
1176</div>
1177
1178<!-- _______________________________________________________________________ -->
1179<div class="doc_subsubsection">
1180 <a name="m_BasicBlock">Important Public Members of the <tt>BasicBlock</tt>
1181 class</a>
1182</div>
1183
1184<div class="doc_text">
1185
Chris Lattner261efe92003-11-25 01:02:51 +00001186<ul>
1187 <li><tt>BasicBlock(const std::string &amp;Name = "", </tt><tt><a
1188 href="#Function">Function</a> *Parent = 0)</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001189 <p>The <tt>BasicBlock</tt> constructor is used to create new basic
Chris Lattner261efe92003-11-25 01:02:51 +00001190blocks for insertion into a function. The constructor optionally takes
1191a name for the new block, and a <a href="#Function"><tt>Function</tt></a>
1192to insert it into. If the <tt>Parent</tt> parameter is specified, the
1193new <tt>BasicBlock</tt> is automatically inserted at the end of the
1194specified <a href="#Function"><tt>Function</tt></a>, if not specified,
1195the BasicBlock must be manually inserted into the <a href="#Function"><tt>Function</tt></a>.</p>
Chris Lattner261efe92003-11-25 01:02:51 +00001196 </li>
1197 <li><tt>BasicBlock::iterator</tt> - Typedef for instruction list
1198iterator<br>
Chris Lattner9355b472002-09-06 02:50:58 +00001199 <tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
Chris Lattner261efe92003-11-25 01:02:51 +00001200 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,<tt>size()</tt>,<tt>empty()</tt>,<tt>rbegin()</tt>,<tt>rend()
1201- </tt>STL style functions for accessing the instruction list.
1202 <p> These methods and typedefs are forwarding functions that have
1203the same semantics as the standard library methods of the same names.
1204These methods expose the underlying instruction list of a basic block in
1205a way that is easy to manipulate. To get the full complement of
1206container operations (including operations to update the list), you must
Misha Brukman13fd15c2004-01-15 00:14:41 +00001207use the <tt>getInstList()</tt> method.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001208 <li><tt>BasicBlock::InstListType &amp;getInstList()</tt>
1209 <p> This method is used to get access to the underlying container
1210that actually holds the Instructions. This method must be used when
1211there isn't a forwarding function in the <tt>BasicBlock</tt> class for
1212the operation that you would like to perform. Because there are no
1213forwarding functions for "updating" operations, you need to use this if
Misha Brukman13fd15c2004-01-15 00:14:41 +00001214you want to update the contents of a <tt>BasicBlock</tt>.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001215 <li><tt><a href="#Function">Function</a> *getParent()</tt>
1216 <p> Returns a pointer to <a href="#Function"><tt>Function</tt></a>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001217the block is embedded into, or a null pointer if it is homeless.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001218 <li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt>
1219 <p> Returns a pointer to the terminator instruction that appears at
1220the end of the <tt>BasicBlock</tt>. If there is no terminator
1221instruction, or if the last instruction in the block is not a
Misha Brukman13fd15c2004-01-15 00:14:41 +00001222terminator, then a null pointer is returned.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001223</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001224
1225</div>
1226
1227<!-- ======================================================================= -->
1228<div class="doc_subsection">
1229 <a name="GlobalValue">The <tt>GlobalValue</tt> class</a>
1230</div>
1231
1232<div class="doc_text">
1233
1234<p><tt>#include "<a
1235href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt><br>
1236doxygen info: <a href="/doxygen/classGlobalValue.html">GlobalValue Class</a><br>
1237Superclasses: <a href="#User"><tt>User</tt></a>, <a
1238href="#Value"><tt>Value</tt></a></p>
1239
1240<p>Global values (<a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s or <a
1241href="#Function"><tt>Function</tt></a>s) are the only LLVM values that are
1242visible in the bodies of all <a href="#Function"><tt>Function</tt></a>s.
1243Because they are visible at global scope, they are also subject to linking with
1244other globals defined in different translation units. To control the linking
1245process, <tt>GlobalValue</tt>s know their linkage rules. Specifically,
1246<tt>GlobalValue</tt>s know whether they have internal or external linkage, as
1247defined by the <tt>LinkageTypes</tt> enumerator.</p>
1248
1249<p>If a <tt>GlobalValue</tt> has internal linkage (equivalent to being
1250<tt>static</tt> in C), it is not visible to code outside the current translation
1251unit, and does not participate in linking. If it has external linkage, it is
1252visible to external code, and does participate in linking. In addition to
1253linkage information, <tt>GlobalValue</tt>s keep track of which <a
1254href="#Module"><tt>Module</tt></a> they are currently part of.</p>
1255
1256<p>Because <tt>GlobalValue</tt>s are memory objects, they are always referred to
1257by their <b>address</b>. As such, the <a href="#Type"><tt>Type</tt></a> of a
1258global is always a pointer to its contents. It is important to remember this
1259when using the <tt>GetElementPtrInst</tt> instruction because this pointer must
1260be dereferenced first. For example, if you have a <tt>GlobalVariable</tt> (a
1261subclass of <tt>GlobalValue)</tt> that is an array of 24 ints, type <tt>[24 x
1262int]</tt>, then the <tt>GlobalVariable</tt> is a pointer to that array. Although
1263the address of the first element of this array and the value of the
1264<tt>GlobalVariable</tt> are the same, they have different types. The
1265<tt>GlobalVariable</tt>'s type is <tt>[24 x int]</tt>. The first element's type
1266is <tt>int.</tt> Because of this, accessing a global value requires you to
1267dereference the pointer with <tt>GetElementPtrInst</tt> first, then its elements
1268can be accessed. This is explained in the <a href="LangRef.html#globalvars">LLVM
1269Language Reference Manual</a>.</p>
1270
1271</div>
1272
1273<!-- _______________________________________________________________________ -->
1274<div class="doc_subsubsection">
1275 <a name="m_GlobalValue">Important Public Members of the <tt>GlobalValue</tt>
1276 class</a>
1277</div>
1278
1279<div class="doc_text">
1280
Chris Lattner261efe92003-11-25 01:02:51 +00001281<ul>
1282 <li><tt>bool hasInternalLinkage() const</tt><br>
Chris Lattner9355b472002-09-06 02:50:58 +00001283 <tt>bool hasExternalLinkage() const</tt><br>
Chris Lattner261efe92003-11-25 01:02:51 +00001284 <tt>void setInternalLinkage(bool HasInternalLinkage)</tt>
1285 <p> These methods manipulate the linkage characteristics of the <tt>GlobalValue</tt>.</p>
1286 <p> </p>
1287 </li>
1288 <li><tt><a href="#Module">Module</a> *getParent()</tt>
1289 <p> This returns the <a href="#Module"><tt>Module</tt></a> that the
Misha Brukman13fd15c2004-01-15 00:14:41 +00001290GlobalValue is currently embedded into.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001291</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001292
1293</div>
1294
1295<!-- ======================================================================= -->
1296<div class="doc_subsection">
1297 <a name="Function">The <tt>Function</tt> class</a>
1298</div>
1299
1300<div class="doc_text">
1301
1302<p><tt>#include "<a
1303href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt><br> doxygen
1304info: <a href="/doxygen/classFunction.html">Function Class</a><br> Superclasses:
1305<a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
1306href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p>
1307
1308<p>The <tt>Function</tt> class represents a single procedure in LLVM. It is
1309actually one of the more complex classes in the LLVM heirarchy because it must
1310keep track of a large amount of data. The <tt>Function</tt> class keeps track
1311of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <a
1312href="#Argument"><tt>Argument</tt></a>s, and a <a
1313href="#SymbolTable"><tt>SymbolTable</tt></a>.</p>
1314
1315<p>The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most
1316commonly used part of <tt>Function</tt> objects. The list imposes an implicit
1317ordering of the blocks in the function, which indicate how the code will be
1318layed out by the backend. Additionally, the first <a
1319href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node for the
1320<tt>Function</tt>. It is not legal in LLVM to explicitly branch to this initial
1321block. There are no implicit exit nodes, and in fact there may be multiple exit
1322nodes from a single <tt>Function</tt>. If the <a
1323href="#BasicBlock"><tt>BasicBlock</tt></a> list is empty, this indicates that
1324the <tt>Function</tt> is actually a function declaration: the actual body of the
1325function hasn't been linked in yet.</p>
1326
1327<p>In addition to a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, the
1328<tt>Function</tt> class also keeps track of the list of formal <a
1329href="#Argument"><tt>Argument</tt></a>s that the function receives. This
1330container manages the lifetime of the <a href="#Argument"><tt>Argument</tt></a>
1331nodes, just like the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list does for
1332the <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.</p>
1333
1334<p>The <a href="#SymbolTable"><tt>SymbolTable</tt></a> is a very rarely used
1335LLVM feature that is only used when you have to look up a value by name. Aside
1336from that, the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is used
1337internally to make sure that there are not conflicts between the names of <a
1338href="#Instruction"><tt>Instruction</tt></a>s, <a
1339href="#BasicBlock"><tt>BasicBlock</tt></a>s, or <a
1340href="#Argument"><tt>Argument</tt></a>s in the function body.</p>
1341
1342</div>
1343
1344<!-- _______________________________________________________________________ -->
1345<div class="doc_subsubsection">
1346 <a name="m_Function">Important Public Members of the <tt>Function</tt>
1347 class</a>
1348</div>
1349
1350<div class="doc_text">
1351
Chris Lattner261efe92003-11-25 01:02:51 +00001352<ul>
1353 <li><tt>Function(const </tt><tt><a href="#FunctionType">FunctionType</a>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001354 *Ty, bool isInternal, const std::string &amp;N = "", Module* Parent = 0)</tt>
1355
1356 <p>Constructor used when you need to create new <tt>Function</tt>s to add
1357 the the program. The constructor must specify the type of the function to
1358 create and whether or not it should start out with internal or external
1359 linkage. The&nbsp;<a href="#FunctionType"><tt>FunctionType</tt></a> argument
1360 specifies the formal arguments and return value for the function. The same
1361 <a href="#FunctionTypel"><tt>FunctionType</tt></a> value can be used to
1362 create multiple functions. The <tt>Parent</tt> argument specifies the Module
1363 in which the function is defined. If this argument is provided, the function
1364 will automatically be inserted into that module's list of
1365 functions.</p></li>
1366
Chris Lattner261efe92003-11-25 01:02:51 +00001367 <li><tt>bool isExternal()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001368
1369 <p>Return whether or not the <tt>Function</tt> has a body defined. If the
1370 function is "external", it does not have a body, and thus must be resolved
1371 by linking with a function defined in a different translation unit.</p></li>
1372
Chris Lattner261efe92003-11-25 01:02:51 +00001373 <li><tt>Function::iterator</tt> - Typedef for basic block list iterator<br>
Chris Lattner9355b472002-09-06 02:50:58 +00001374 <tt>Function::const_iterator</tt> - Typedef for const_iterator.<br>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001375
1376 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
1377 <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt>
1378
1379 <p>These are forwarding methods that make it easy to access the contents of
1380 a <tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
1381 list.</p></li>
1382
Chris Lattner261efe92003-11-25 01:02:51 +00001383 <li><tt>Function::BasicBlockListType &amp;getBasicBlockList()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001384
1385 <p>Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s. This
1386 is necessary to use when you need to update the list or perform a complex
1387 action that doesn't have a forwarding method.</p></li>
1388
Chris Lattner261efe92003-11-25 01:02:51 +00001389 <li><tt>Function::aiterator</tt> - Typedef for the argument list
1390iterator<br>
Chris Lattner9355b472002-09-06 02:50:58 +00001391 <tt>Function::const_aiterator</tt> - Typedef for const_iterator.<br>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001392
1393 <tt>abegin()</tt>, <tt>aend()</tt>, <tt>afront()</tt>, <tt>aback()</tt>,
1394 <tt>asize()</tt>, <tt>aempty()</tt>, <tt>arbegin()</tt>, <tt>arend()</tt>
1395
1396 <p>These are forwarding methods that make it easy to access the contents of
1397 a <tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a>
1398 list.</p></li>
1399
Chris Lattner261efe92003-11-25 01:02:51 +00001400 <li><tt>Function::ArgumentListType &amp;getArgumentList()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001401
1402 <p>Returns the list of <a href="#Argument"><tt>Argument</tt></a>s. This is
1403 necessary to use when you need to update the list or perform a complex
1404 action that doesn't have a forwarding method.</p></li>
1405
Chris Lattner261efe92003-11-25 01:02:51 +00001406 <li><tt><a href="#BasicBlock">BasicBlock</a> &amp;getEntryBlock()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001407
1408 <p>Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
1409 function. Because the entry block for the function is always the first
1410 block, this returns the first block of the <tt>Function</tt>.</p></li>
1411
Chris Lattner261efe92003-11-25 01:02:51 +00001412 <li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
1413 <tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001414
1415 <p>This traverses the <a href="#Type"><tt>Type</tt></a> of the
1416 <tt>Function</tt> and returns the return type of the function, or the <a
1417 href="#FunctionType"><tt>FunctionType</tt></a> of the actual
1418 function.</p></li>
1419
Chris Lattner261efe92003-11-25 01:02:51 +00001420 <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001421
Chris Lattner261efe92003-11-25 01:02:51 +00001422 <p> Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001423 for this <tt>Function</tt>.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001424</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001425
1426</div>
1427
1428<!-- ======================================================================= -->
1429<div class="doc_subsection">
1430 <a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a>
1431</div>
1432
1433<div class="doc_text">
1434
1435<p><tt>#include "<a
1436href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt>
1437<br>
Chris Lattner261efe92003-11-25 01:02:51 +00001438doxygen info: <a href="/doxygen/classGlobalVariable.html">GlobalVariable
Misha Brukman13fd15c2004-01-15 00:14:41 +00001439Class</a><br> Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
1440href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a></p>
1441
1442<p>Global variables are represented with the (suprise suprise)
1443<tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are also
1444subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such are
1445always referenced by their address (global values must live in memory, so their
1446"name" refers to their address). See <a
1447href="#GlobalValue"><tt>GlobalValue</tt></a> for more on this. Global variables
1448may have an initial value (which must be a <a
1449href="#Constant"><tt>Constant</tt></a>), and if they have an initializer, they
1450may be marked as "constant" themselves (indicating that their contents never
1451change at runtime).</p>
1452
1453</div>
1454
1455<!-- _______________________________________________________________________ -->
1456<div class="doc_subsubsection">
1457 <a name="m_GlobalVariable">Important Public Members of the
1458 <tt>GlobalVariable</tt> class</a>
1459</div>
1460
1461<div class="doc_text">
1462
Chris Lattner261efe92003-11-25 01:02:51 +00001463<ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001464 <li><tt>GlobalVariable(const </tt><tt><a href="#Type">Type</a> *Ty, bool
1465 isConstant, LinkageTypes&amp; Linkage, <a href="#Constant">Constant</a>
1466 *Initializer = 0, const std::string &amp;Name = "", Module* Parent = 0)</tt>
1467
1468 <p>Create a new global variable of the specified type. If
1469 <tt>isConstant</tt> is true then the global variable will be marked as
1470 unchanging for the program. The Linkage parameter specifies the type of
1471 linkage (internal, external, weak, linkonce, appending) for the variable. If
1472 the linkage is InternalLinkage, WeakLinkage, or LinkOnceLinkage,&nbsp; then
1473 the resultant global variable will have internal linkage. AppendingLinkage
1474 concatenates together all instances (in different translation units) of the
1475 variable into a single variable but is only applicable to arrays. &nbsp;See
1476 the <a href="LangRef.html#modulestructure">LLVM Language Reference</a> for
1477 further details on linkage types. Optionally an initializer, a name, and the
1478 module to put the variable into may be specified for the global variable as
1479 well.</p></li>
1480
Chris Lattner261efe92003-11-25 01:02:51 +00001481 <li><tt>bool isConstant() const</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001482
1483 <p>Returns true if this is a global variable that is known not to
1484 be modified at runtime.</p></li>
1485
Chris Lattner261efe92003-11-25 01:02:51 +00001486 <li><tt>bool hasInitializer()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001487
1488 <p>Returns true if this <tt>GlobalVariable</tt> has an intializer.</p></li>
1489
Chris Lattner261efe92003-11-25 01:02:51 +00001490 <li><tt><a href="#Constant">Constant</a> *getInitializer()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001491
1492 <p>Returns the intial value for a <tt>GlobalVariable</tt>. It is not legal
1493 to call this method if there is no initializer.</p></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001494</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001495
1496</div>
1497
1498<!-- ======================================================================= -->
1499<div class="doc_subsection">
1500 <a name="Module">The <tt>Module</tt> class</a>
1501</div>
1502
1503<div class="doc_text">
1504
1505<p><tt>#include "<a
1506href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt><br> doxygen info:
1507<a href="/doxygen/classModule.html">Module Class</a></p>
1508
1509<p>The <tt>Module</tt> class represents the top level structure present in LLVM
1510programs. An LLVM module is effectively either a translation unit of the
1511original program or a combination of several translation units merged by the
1512linker. The <tt>Module</tt> class keeps track of a list of <a
1513href="#Function"><tt>Function</tt></a>s, a list of <a
1514href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
1515href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it contains a few
1516helpful member functions that try to make common operations easy.</p>
1517
1518</div>
1519
1520<!-- _______________________________________________________________________ -->
1521<div class="doc_subsubsection">
1522 <a name="m_Module">Important Public Members of the <tt>Module</tt> class</a>
1523</div>
1524
1525<div class="doc_text">
1526
Chris Lattner261efe92003-11-25 01:02:51 +00001527<ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001528 <li><tt>Module::Module(std::string name = "")</tt></li>
Chris Lattner261efe92003-11-25 01:02:51 +00001529</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001530
1531<p>Constructing a <a href="#Module">Module</a> is easy. You can optionally
1532provide a name for it (probably based on the name of the translation unit).</p>
1533
Chris Lattner261efe92003-11-25 01:02:51 +00001534<ul>
1535 <li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
Chris Lattner0377de42002-09-06 14:50:55 +00001536 <tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001537
1538 <tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
1539 <tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt>
1540
1541 <p>These are forwarding methods that make it easy to access the contents of
1542 a <tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
1543 list.</p></li>
1544
Chris Lattner261efe92003-11-25 01:02:51 +00001545 <li><tt>Module::FunctionListType &amp;getFunctionList()</tt>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001546
1547 <p> Returns the list of <a href="#Function"><tt>Function</tt></a>s. This is
1548 necessary to use when you need to update the list or perform a complex
1549 action that doesn't have a forwarding method.</p>
1550
1551 <p><!-- Global Variable --></p></li>
Chris Lattnerc75ff9a2002-10-01 23:17:09 +00001552</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001553
1554<hr>
1555
Chris Lattnerc75ff9a2002-10-01 23:17:09 +00001556<ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001557 <li><tt>Module::giterator</tt> - Typedef for global variable list iterator<br>
1558
1559 <tt>Module::const_giterator</tt> - Typedef for const_iterator.<br>
1560
1561 <tt>gbegin()</tt>, <tt>gend()</tt>, <tt>gfront()</tt>, <tt>gback()</tt>,
1562 <tt>gsize()</tt>, <tt>gempty()</tt>, <tt>grbegin()</tt>, <tt>grend()</tt>
1563
1564 <p> These are forwarding methods that make it easy to access the contents of
1565 a <tt>Module</tt> object's <a
1566 href="#GlobalVariable"><tt>GlobalVariable</tt></a> list.</p></li>
1567
1568 <li><tt>Module::GlobalListType &amp;getGlobalList()</tt>
1569
1570 <p>Returns the list of <a
1571 href="#GlobalVariable"><tt>GlobalVariable</tt></a>s. This is necessary to
1572 use when you need to update the list or perform a complex action that
1573 doesn't have a forwarding method.</p>
1574
1575 <p><!-- Symbol table stuff --> </p></li>
Chris Lattnerc75ff9a2002-10-01 23:17:09 +00001576</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001577
1578<hr>
1579
1580<ul>
1581 <li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt>
1582
1583 <p>Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
1584 for this <tt>Module</tt>.</p>
1585
1586 <p><!-- Convenience methods --></p></li>
1587</ul>
1588
1589<hr>
1590
1591<ul>
1592 <li><tt><a href="#Function">Function</a> *getFunction(const std::string
1593 &amp;Name, const <a href="#FunctionType">FunctionType</a> *Ty)</tt>
1594
1595 <p>Look up the specified function in the <tt>Module</tt> <a
1596 href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return
1597 <tt>null</tt>.</p></li>
1598
1599 <li><tt><a href="#Function">Function</a> *getOrInsertFunction(const
1600 std::string &amp;Name, const <a href="#FunctionType">FunctionType</a> *T)</tt>
1601
1602 <p>Look up the specified function in the <tt>Module</tt> <a
1603 href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an
1604 external declaration for the function and return it.</p></li>
1605
1606 <li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt>
1607
1608 <p>If there is at least one entry in the <a
1609 href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a
1610 href="#Type"><tt>Type</tt></a>, return it. Otherwise return the empty
1611 string.</p></li>
1612
1613 <li><tt>bool addTypeName(const std::string &amp;Name, const <a
1614 href="#Type">Type</a> *Ty)</tt>
1615
1616 <p>Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a>
1617 mapping <tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this
1618 name, true is returned and the <a
1619 href="#SymbolTable"><tt>SymbolTable</tt></a> is not modified.</p></li>
1620</ul>
1621
1622</div>
1623
1624<!-- ======================================================================= -->
1625<div class="doc_subsection">
1626 <a name="Constant">The <tt>Constant</tt> class and subclasses</a>
1627</div>
1628
1629<div class="doc_text">
1630
1631<p>Constant represents a base class for different types of constants. It
1632is subclassed by ConstantBool, ConstantInt, ConstantSInt, ConstantUInt,
1633ConstantArray etc for representing the various types of Constants.</p>
1634
1635</div>
1636
1637<!-- _______________________________________________________________________ -->
1638<div class="doc_subsubsection">
1639 <a name="m_Value">Important Public Methods</a>
1640</div>
1641
1642<div class="doc_text">
1643
Chris Lattnerc75ff9a2002-10-01 23:17:09 +00001644<ul>
Chris Lattner261efe92003-11-25 01:02:51 +00001645 <li><tt>bool isConstantExpr()</tt>: Returns true if it is a
1646ConstantExpr
1647 <hr> Important Subclasses of Constant
1648 <p> </p>
1649 <ul>
1650 <li>ConstantSInt : This subclass of Constant represents a signed
1651integer constant.
1652 <ul>
1653 <li><tt>int64_t getValue() const</tt>: Returns the underlying value of
1654this constant. </li>
1655 </ul>
1656 </li>
1657 <li>ConstantUInt : This class represents an unsigned integer.
1658 <ul>
1659 <li><tt>uint64_t getValue() const</tt>: Returns the underlying value
1660of this constant. </li>
1661 </ul>
1662 </li>
1663 <li>ConstantFP : This class represents a floating point constant.
1664 <ul>
1665 <li><tt>double getValue() const</tt>: Returns the underlying value of
1666this constant. </li>
1667 </ul>
1668 </li>
1669 <li>ConstantBool : This represents a boolean constant.
1670 <ul>
1671 <li><tt>bool getValue() const</tt>: Returns the underlying value of
1672this constant. </li>
1673 </ul>
1674 </li>
1675 <li>ConstantArray : This represents a constant array.
1676 <ul>
1677 <li><tt>const std::vector&lt;Use&gt; &amp;getValues() const</tt>:
1678Returns a Vecotr of component constants that makeup this array. </li>
1679 </ul>
1680 </li>
1681 <li>ConstantStruct : This represents a constant struct.
1682 <ul>
1683 <li><tt>const std::vector&lt;Use&gt; &amp;getValues() const</tt>:
1684Returns a Vecotr of component constants that makeup this array. </li>
1685 </ul>
1686 </li>
1687 <li>ConstantPointerRef : This represents a constant pointer value
1688that is initialized to point to a global value, which lies at a
1689constant fixed address.
1690 <ul>
1691 <li><tt>GlobalValue *getValue()</tt>: Returns the global
1692value to which this pointer is pointing to. </li>
1693 </ul>
1694 </li>
1695 </ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001696 </li>
Chris Lattnerc75ff9a2002-10-01 23:17:09 +00001697</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001698
1699</div>
1700
1701<!-- ======================================================================= -->
1702<div class="doc_subsection">
1703 <a name="Type">The <tt>Type</tt> class and Derived Types</a>
1704</div>
1705
1706<div class="doc_text">
1707
1708<p>Type as noted earlier is also a subclass of a Value class. Any primitive
1709type (like int, short etc) in LLVM is an instance of Type Class. All other
1710types are instances of subclasses of type like FunctionType, ArrayType
1711etc. DerivedType is the interface for all such dervied types including
1712FunctionType, ArrayType, PointerType, StructType. Types can have names. They can
1713be recursive (StructType). There exists exactly one instance of any type
1714structure at a time. This allows using pointer equality of Type *s for comparing
1715types.</p>
1716
1717</div>
1718
1719<!-- _______________________________________________________________________ -->
1720<div class="doc_subsubsection">
1721 <a name="m_Value">Important Public Methods</a>
1722</div>
1723
1724<div class="doc_text">
1725
Chris Lattnerc75ff9a2002-10-01 23:17:09 +00001726<ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001727
1728 <li><tt>PrimitiveID getPrimitiveID() const</tt>: Returns the base type of the
1729 type.</li>
1730
1731 <li><tt>bool isSigned() const</tt>: Returns whether an integral numeric type
1732 is signed. This is true for SByteTy, ShortTy, IntTy, LongTy. Note that this is
1733 not true for Float and Double. </li>
1734
1735 <li><tt>bool isUnsigned() const</tt>: Returns whether a numeric type is
1736 unsigned. This is not quite the complement of isSigned... nonnumeric types
1737 return false as they do with isSigned. This returns true for UByteTy,
1738 UShortTy, UIntTy, and ULongTy. </li>
1739
1740 <li><tt>bool isInteger() const</tt>: Equilivent to isSigned() || isUnsigned(),
1741 but with only a single virtual function invocation.</li>
1742
1743 <li><tt>bool isIntegral() const</tt>: Returns true if this is an integral
1744 type, which is either Bool type or one of the Integer types.</li>
1745
1746 <li><tt>bool isFloatingPoint()</tt>: Return true if this is one of the two
1747 floating point types.</li>
1748
1749 <li><tt>bool isRecursive() const</tt>: Returns rue if the type graph contains
1750 a cycle.</li>
1751
1752 <li><tt>isLosslesslyConvertableTo (const Type *Ty) const</tt>: Return true if
1753 this type can be converted to 'Ty' without any reinterpretation of bits. For
1754 example, uint to int.</li>
1755
1756 <li><tt>bool isPrimitiveType() const</tt>: Returns true if it is a primitive
1757 type.</li>
1758
1759 <li><tt>bool isDerivedType() const</tt>: Returns true if it is a derived
1760 type.</li>
1761
1762 <li><tt>const Type * getContainedType (unsigned i) const</tt>: This method is
1763 used to implement the type iterator. For derived types, this returns the types
1764 'contained' in the derived type, returning 0 when 'i' becomes invalid. This
1765 allows the user to iterate over the types in a struct, for example, really
1766 easily.</li>
1767
1768 <li><tt>unsigned getNumContainedTypes() const</tt>: Return the number of types
1769 in the derived type.
1770
1771 <hr>
1772 <p>Derived Types</p>
1773
Chris Lattner261efe92003-11-25 01:02:51 +00001774 <ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001775 <li>SequentialType : This is subclassed by ArrayType and PointerType
Chris Lattner261efe92003-11-25 01:02:51 +00001776 <ul>
1777 <li><tt>const Type * getElementType() const</tt>: Returns the type of
1778each of the elements in the sequential type. </li>
1779 </ul>
1780 </li>
1781 <li>ArrayType : This is a subclass of SequentialType and defines
1782interface for array types.
1783 <ul>
1784 <li><tt>unsigned getNumElements() const</tt>: Returns the number of
1785elements in the array. </li>
1786 </ul>
1787 </li>
1788 <li>PointerType : Subclass of SequentialType for pointer types. </li>
1789 <li>StructType : subclass of DerivedTypes for struct types </li>
1790 <li>FunctionType : subclass of DerivedTypes for function types.
1791 <ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001792 <li><tt>bool isVarArg() const</tt>: Returns true if its a vararg
1793 function</li>
Chris Lattner261efe92003-11-25 01:02:51 +00001794 <li><tt> const Type * getReturnType() const</tt>: Returns the
Misha Brukman13fd15c2004-01-15 00:14:41 +00001795 return type of the function.</li>
Chris Lattner261efe92003-11-25 01:02:51 +00001796 <li><tt> const ParamTypes &amp;getParamTypes() const</tt>:
Misha Brukman13fd15c2004-01-15 00:14:41 +00001797 Returns a vector of parameter types.</li>
Chris Lattner261efe92003-11-25 01:02:51 +00001798 <li><tt>const Type * getParamType (unsigned i)</tt>: Returns
Misha Brukman13fd15c2004-01-15 00:14:41 +00001799 the type of the ith parameter.</li>
Chris Lattner261efe92003-11-25 01:02:51 +00001800 <li><tt> const unsigned getNumParams() const</tt>: Returns the
Misha Brukman13fd15c2004-01-15 00:14:41 +00001801 number of formal parameters.</li>
Chris Lattner261efe92003-11-25 01:02:51 +00001802 </ul>
1803 </li>
1804 </ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001805 </li>
Chris Lattnerc75ff9a2002-10-01 23:17:09 +00001806</ul>
Misha Brukman13fd15c2004-01-15 00:14:41 +00001807
1808</div>
1809
1810<!-- ======================================================================= -->
1811<div class="doc_subsection">
1812 <a name="Argument">The <tt>Argument</tt> class</a>
1813</div>
1814
1815<div class="doc_text">
1816
1817<p>This subclass of Value defines the interface for incoming formal
Chris Lattner261efe92003-11-25 01:02:51 +00001818arguments to a function. A Function maitanis a list of its formal
Misha Brukman13fd15c2004-01-15 00:14:41 +00001819arguments. An argument has a pointer to the parent Function.</p>
1820
1821</div>
1822
Chris Lattner9355b472002-09-06 02:50:58 +00001823<!-- *********************************************************************** -->
Misha Brukman13fd15c2004-01-15 00:14:41 +00001824<hr>
1825<address>
1826 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1827 src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
1828 <a href="http://validator.w3.org/check/referer"><img
1829 src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!" /></a>
1830
1831 <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and
1832 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1833 <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
1834 Last modified: $Date$
1835</address>
1836
Chris Lattner261efe92003-11-25 01:02:51 +00001837</body>
1838</html>