Blame - docs/ProgrammersManual.html - fp2-dev/platform/external/llvm

blob: 63e803ba71cacb51323a372fe815c277540a4a6c [file] [log] [blame]

Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
				2	<html><head><title>LLVM Programmer's Manual</title></head>
				3
				4	<body bgcolor=white>
				5
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	6	<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				7	<tr><td>  <font size=+3 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>LLVM Programmer's Manual</b></font></td>
				8	</tr></table>
				9
				10	<ol>
				11	<li><a href="#introduction">Introduction</a>
				12	<li><a href="#general">General Information</a>
				13	<ul>
				14	<li><a href="#stl">The C++ Standard Template Library</a>
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	15	<!--
				16	<li>The <tt>-time-passes</tt> option
				17	<li>How to use the LLVM Makefile system
				18	<li>How to write a regression test
				19	-->
				20	</ul>
				21	<li><a href="#apis">Important and useful LLVM APIs</a>
				22	<ul>
Chris Lattner	1d43fd4	2002-09-09 05:53:21 +0000	[diff] [blame]	23	<li><a href="#isa">The <tt>isa<></tt>, <tt>cast<></tt> and
				24	<tt>dyn_cast<></tt> templates</a>
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	25	<li><a href="#DEBUG">The <tt>DEBUG()</tt> macro &
				26	<tt>-debug</tt> option</a>
				27	<li><a href="#Statistic">The <tt>Statistic</tt> template &
				28	<tt>-stats</tt> option</a>
				29	<!--
				30	<li>The <tt>InstVisitor</tt> template
				31	<li>The general graph API
				32	-->
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	33	</ul>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	34	<li><a href="#common">Helpful Hints for Common Operations</a>
				35	<ul>
				36	<li><a href="#inspection">Basic Inspection and Traversal Routines</a>
				37	<ul>
				38	<li><a href="#iterate_function">Iterating over the <tt>BasicBlock</tt>s
				39	in a <tt>Function</tt></a>
				40	<li><a href="#iterate_basicblock">Iterating over the <tt>Instruction</tt>s
				41	in a <tt>BasicBlock</tt></a>
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	42	<li><a href="#iterate_institer">Iterating over the <tt>Instruction</tt>s
				43	in a <tt>Function</tt></a>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	44	<li><a href="#iterate_convert">Turning an iterator into a class
				45	pointer</a>
Chris Lattner	f1ebdc3	2002-09-06 22:09:21 +0000	[diff] [blame]	46	<li><a href="#iterate_complex">Finding call sites: a more complex
				47	example</a>
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	48	<li><a href="#iterate_chains">Iterating over def-use & use-def
				49	chains</a>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	50	</ul>
				51	<li><a href="#simplechanges">Making simple changes</a>
				52	<ul>
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	53	<li><a href="#schanges_creating">Creating and inserting new
				54	<tt>Instruction</tt>s</a>
				55	<li><a href="#schanges_deleting">Deleting
				56	<tt>Instruction</tt>s</a>
				57	<li><a href="#schanges_replacing">Replacing an
				58	<tt>Instruction</tt> with another <tt>Value</tt></a>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	59	</ul>
				60	<!--
				61	<li>Working with the Control Flow Graph
				62	<ul>
				63	<li>Accessing predecessors and successors of a <tt>BasicBlock</tt>
				64	<li>
				65	<li>
				66	</ul>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	67	-->
				68	</ul>
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	69	<li><a href="#coreclasses">The Core LLVM Class Hierarchy Reference</a>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	70	<ul>
				71	<li><a href="#Value">The <tt>Value</tt> class</a>
				72	<ul>
				73	<li><a href="#User">The <tt>User</tt> class</a>
				74	<ul>
				75	<li><a href="#Instruction">The <tt>Instruction</tt> class</a>
				76	<ul>
				77	<li>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	78	</ul>
				79	<li><a href="#GlobalValue">The <tt>GlobalValue</tt> class</a>
				80	<ul>
				81	<li><a href="#BasicBlock">The <tt>BasicBlock</tt> class</a>
				82	<li><a href="#Function">The <tt>Function</tt> class</a>
				83	<li><a href="#GlobalVariable">The <tt>GlobalVariable</tt> class</a>
				84	</ul>
				85	<li><a href="#Module">The <tt>Module</tt> class</a>
				86	<li><a href="#Constant">The <tt>Constant</tt> class</a>
				87	<ul>
				88	<li>
				89	<li>
				90	</ul>
				91	</ul>
				92	<li><a href="#Type">The <tt>Type</tt> class</a>
				93	<li><a href="#Argument">The <tt>Argument</tt> class</a>
				94	</ul>
				95	<li>The <tt>SymbolTable</tt> class
				96	<li>The <tt>ilist</tt> and <tt>iplist</tt> classes
				97	<ul>
				98	<li>Creating, inserting, moving and deleting from LLVM lists
				99	</ul>
				100	<li>Important iterator invalidation semantics to be aware of
				101	</ul>
				102
Chris Lattner	6b121f1	2002-09-10 15:20:46 +0000	[diff] [blame]	103	<p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
				104	<a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a>, and
Chris Lattner	f1ebdc3	2002-09-06 22:09:21 +0000	[diff] [blame]	105	<a href="mailto:jstanley@cs.uiuc.edu">Joel Stanley</a></b><p>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	106	</ol>
				107
				108
				109	<!-- *********************************************************************** -->
				110	<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				111	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				112	<a name="introduction">Introduction
				113	</b></font></td></tr></table><ul>
				114	<!-- *********************************************************************** -->
				115
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	116	This document is meant to highlight some of the important classes and interfaces
				117	available in the LLVM source-base. This manual is not intended to explain what
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	118	LLVM is, how it works, and what LLVM code looks like. It assumes that you know
				119	the basics of LLVM and are interested in writing transformations or otherwise
				120	analyzing or manipulating the code.<p>
				121
				122	This document should get you oriented so that you can find your way in the
				123	continuously growing source code that makes up the LLVM infrastructure. Note
				124	that this manual is not intended to serve as a replacement for reading the
				125	source code, so if you think there should be a method in one of these classes to
				126	do something, but it's not listed, check the source. Links to the <a
				127	href="/doxygen/">doxygen</a> sources are provided to make this as easy as
				128	possible.<p>
				129
				130	The first section of this document describes general information that is useful
				131	to know when working in the LLVM infrastructure, and the second describes the
				132	Core LLVM classes. In the future this manual will be extended with information
				133	describing how to use extension libraries, such as dominator information, CFG
				134	traversal routines, and useful utilities like the <tt><a
				135	href="/doxygen/InstVisitor_8h-source.html">InstVisitor</a></tt> template.<p>
				136
				137
				138	<!-- *********************************************************************** -->
				139	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				140	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				141	<a name="general">General Information
				142	</b></font></td></tr></table><ul>
				143	<!-- *********************************************************************** -->
				144
				145	This section contains general information that is useful if you are working in
				146	the LLVM source-base, but that isn't specific to any particular API.<p>
				147
				148
				149	<!-- ======================================================================= -->
				150	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				151	<tr><td> </td><td width="100%">
				152	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				153	<a name="stl">The C++ Standard Template Library</a>
				154	</b></font></td></tr></table><ul>
				155
				156	LLVM makes heavy use of the C++ Standard Template Library (STL), perhaps much
				157	more than you are used to, or have seen before. Because of this, you might want
				158	to do a little background reading in the techniques used and capabilities of the
				159	library. There are many good pages that discuss the STL, and several books on
				160	the subject that you can get, so it will not be discussed in this document.<p>
				161
				162	Here are some useful links:<p>
				163	<ol>
Chris Lattner	ab0577b	2002-09-22 21:25:12 +0000	[diff] [blame]	164	<li><a href="http://www.dinkumware.com/refxcpp.html">Dinkumware C++
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	165	Library reference</a> - an excellent reference for the STL and other parts of
Chris Lattner	e9ddc7f	2002-10-21 02:38:02 +0000	[diff] [blame]	166	the standard C++ library.
				167
				168	<li><a href="http://www.tempest-sw.com/cpp/">C++ In a Nutshell</a> - This is an
				169	O'Reilly book in the making. It has a decent <a
				170	href="http://www.tempest-sw.com/cpp/ch13-libref.html">Standard Library
				171	Reference</a> that rivals Dinkumware's, and is actually free until the book is
				172	published.
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	173
				174	<li><a href="http://www.parashift.com/c++-faq-lite/">C++ Frequently Asked
				175	Questions</a>
				176
				177	<li><a href="http://www.sgi.com/tech/stl/">SGI's STL Programmer's Guide</a> -
				178	Contains a useful <a
				179	href="http://www.sgi.com/tech/stl/stl_introduction.html">Introduction to the
				180	STL</a>.
				181
				182	<li><a href="http://www.research.att.com/~bs/C++.html">Bjarne Stroustrup's C++
				183	Page</a>
				184
				185	</ol><p>
				186
				187	You are also encouraged to take a look at the <a
				188	href="CodingStandards.html">LLVM Coding Standards</a> guide which focuses on how
				189	to write maintainable code more than where to put your curly braces.<p>
				190
				191
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	192	<!-- *********************************************************************** -->
				193	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				194	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				195	<a name="apis">Important and useful LLVM APIs
				196	</b></font></td></tr></table><ul>
				197	<!-- *********************************************************************** -->
				198
				199	Here we highlight some LLVM APIs that are generally useful and good to know
				200	about when writing transformations.<p>
				201
Chris Lattner	1d43fd4	2002-09-09 05:53:21 +0000	[diff] [blame]	202	<!-- ======================================================================= -->
				203	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				204	<tr><td> </td><td width="100%">
				205	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				206	<a name="isa">The isa<>, cast<> and dyn_cast<> templates</a>
				207	</b></font></td></tr></table><ul>
				208
Chris Lattner	979d9b7	2002-09-10 00:39:05 +0000	[diff] [blame]	209	The LLVM source-base makes extensive use of a custom form of RTTI. These
				210	templates have many similarities to the C++ <tt>dynamic_cast<></tt>
				211	operator, but they don't have some drawbacks (primarily stemming from the fact
				212	that <tt>dynamic_cast<></tt> only works on classes that have a v-table).
				213	Because they are used so often, you must know what they do and how they work.
				214	All of these templates are defined in the <a
				215	href="/doxygen/Casting_8h-source.html"><tt>Support/Casting.h</tt></a> file (note
				216	that you very rarely have to include this file directly).<p>
Chris Lattner	1d43fd4	2002-09-09 05:53:21 +0000	[diff] [blame]	217
Chris Lattner	979d9b7	2002-09-10 00:39:05 +0000	[diff] [blame]	218	<dl>
				219
				220	<dt><tt>isa<></tt>:
				221
				222	<dd>The <tt>isa<></tt> operator works exactly like the Java
				223	"<tt>instanceof</tt>" operator. It returns true or false depending on whether a
				224	reference or pointer points to an instance of the specified class. This can be
				225	very useful for constraint checking of various sorts (example below).<p>
				226
				227
				228	<dt><tt>cast<></tt>:
				229
				230	<dd>The <tt>cast<></tt> operator is a "checked cast" operation. It
				231	converts a pointer or reference from a base class to a derived cast, causing an
				232	assertion failure if it is not really an instance of the right type. This
				233	should be used in cases where you have some information that makes you believe
				234	that something is of the right type. An example of the <tt>isa<></tt> and
				235	<tt>cast<></tt> template is:<p>
				236
				237	<pre>
				238	static bool isLoopInvariant(const <a href="#Value">Value</a> V, const Loop L) {
				239	if (isa<<a href="#Constant">Constant</a>>(V) \|\| isa<<a href="#Argument">Argument</a>>(V) \|\| isa<<a href="#GlobalValue">GlobalValue</a>>(V))
				240	return true;
				241
				242	<i>// Otherwise, it must be an instruction...</i>
				243	return !L->contains(cast<<a href="#Instruction">Instruction</a>>(V)->getParent());
				244	</pre><p>
				245
				246	Note that you should <b>not</b> use an <tt>isa<></tt> test followed by a
				247	<tt>cast<></tt>, for that use the <tt>dyn_cast<></tt> operator.<p>
				248
				249
				250	<dt><tt>dyn_cast<></tt>:
				251
				252	<dd>The <tt>dyn_cast<></tt> operator is a "checking cast" operation. It
				253	checks to see if the operand is of the specified type, and if so, returns a
				254	pointer to it (this operator does not work with references). If the operand is
				255	not of the correct type, a null pointer is returned. Thus, this works very much
				256	like the <tt>dynamic_cast</tt> operator in C++, and should be used in the same
Chris Lattner	6b121f1	2002-09-10 15:20:46 +0000	[diff] [blame]	257	circumstances. Typically, the <tt>dyn_cast<></tt> operator is used in an
				258	<tt>if</tt> statement or some other flow control statement like this:<p>
				259
				260	<pre>
				261	if (<a href="#AllocationInst">AllocationInst</a> *AI = dyn_cast<<a href="#AllocationInst">AllocationInst</a>>(Val)) {
				262	...
				263	}
				264	</pre><p>
				265
				266	This form of the <tt>if</tt> statement effectively combines together a call to
				267	<tt>isa<></tt> and a call to <tt>cast<></tt> into one statement,
				268	which is very convenient.<p>
				269
				270	Another common example is:<p>
Chris Lattner	979d9b7	2002-09-10 00:39:05 +0000	[diff] [blame]	271
				272	<pre>
				273	<i>// Loop over all of the phi nodes in a basic block</i>
				274	BasicBlock::iterator BBI = BB->begin();
				275	for (; <a href="#PhiNode">PHINode</a> PN = dyn_cast<<a href="#PHINode">PHINode</a>>(&BBI); ++BBI)
				276	cerr << *PN;
				277	</pre><p>
				278
Chris Lattner	6b121f1	2002-09-10 15:20:46 +0000	[diff] [blame]	279	Note that the <tt>dyn_cast<></tt> operator, like C++'s
				280	<tt>dynamic_cast</tt> or Java's <tt>instanceof</tt> operator, can be abused. In
				281	particular you should not use big chained <tt>if/then/else</tt> blocks to check
				282	for lots of different variants of classes. If you find yourself wanting to do
				283	this, it is much cleaner and more efficient to use the InstVisitor class to
				284	dispatch over the instruction type directly.<p>
Chris Lattner	979d9b7	2002-09-10 00:39:05 +0000	[diff] [blame]	285
				286
Chris Lattner	6b121f1	2002-09-10 15:20:46 +0000	[diff] [blame]	287	<dt><tt>cast_or_null<></tt>:
				288
				289	<dd>The <tt>cast_or_null<></tt> operator works just like the
				290	<tt>cast<></tt> operator, except that it allows for a null pointer as an
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	291	argument (which it then propagates). This can sometimes be useful, allowing you
Chris Lattner	6b121f1	2002-09-10 15:20:46 +0000	[diff] [blame]	292	to combine several null checks into one.<p>
				293
				294
				295	<dt><tt>dyn_cast_or_null<></tt>:
				296
				297	<dd>The <tt>dyn_cast_or_null<></tt> operator works just like the
				298	<tt>dyn_cast<></tt> operator, except that it allows for a null pointer as
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	299	an argument (which it then propagates). This can sometimes be useful, allowing
Chris Lattner	6b121f1	2002-09-10 15:20:46 +0000	[diff] [blame]	300	you to combine several null checks into one.<p>
				301
Chris Lattner	979d9b7	2002-09-10 00:39:05 +0000	[diff] [blame]	302	</dl>
Chris Lattner	1d43fd4	2002-09-09 05:53:21 +0000	[diff] [blame]	303
Chris Lattner	6b121f1	2002-09-10 15:20:46 +0000	[diff] [blame]	304	These five templates can be used with any classes, whether they have a v-table
				305	or not. To add support for these templates, you simply need to add
				306	<tt>classof</tt> static methods to the class you are interested casting to.
				307	Describing this is currently outside the scope of this document, but there are
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	308	lots of examples in the LLVM source base.<p>
Chris Lattner	1d43fd4	2002-09-09 05:53:21 +0000	[diff] [blame]	309
				310
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	311	<!-- ======================================================================= -->
				312	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				313	<tr><td> </td><td width="100%">
				314	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				315	<a name="DEBUG">The <tt>DEBUG()</tt> macro & <tt>-debug</tt> option</a>
				316	</b></font></td></tr></table><ul>
				317
				318	Often when working on your pass you will put a bunch of debugging printouts and
				319	other code into your pass. After you get it working, you want to remove
				320	it... but you may need it again in the future (to work out new bugs that you run
				321	across).<p>
				322
				323	Naturally, because of this, you don't want to delete the debug printouts, but
				324	you don't want them to always be noisy. A standard compromise is to comment
				325	them out, allowing you to enable them if you need them in the future.<p>
				326
				327	The "<tt><a
Chris Lattner	8328f1d	2002-10-01 22:39:41 +0000	[diff] [blame]	328	href="/doxygen/Statistic_8h-source.html">Support/Statistic.h</a></tt>"
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	329	file provides a macro named <tt>DEBUG()</tt> that is a much nicer solution to
				330	this problem. Basically, you can put arbitrary code into the argument of the
				331	<tt>DEBUG</tt> macro, and it is only executed if '<tt>opt</tt>' is run with the
				332	'<tt>-debug</tt>' command line argument:
				333
				334	<pre>
				335	...
				336	DEBUG(std::cerr << "I am here!\n");
				337	...
				338	</pre><p>
				339
				340	Then you can run your pass like this:<p>
				341
				342	<pre>
				343	$ opt < a.bc > /dev/null -mypass
				344	<no output>
				345	$ opt < a.bc > /dev/null -mypass -debug
				346	I am here!
				347	$
				348	</pre><p>
				349
				350	Using the <tt>DEBUG()</tt> macro instead of a home brewed solution allows you to
				351	now have to create "yet another" command line option for the debug output for
Chris Lattner	a4e7c4e	2002-11-08 06:50:02 +0000	[diff] [blame]	352	your pass. Note that <tt>DEBUG()</tt> macros are disabled for optimized builds,
				353	so they do not cause a performance impact at all (for the same reason, they
				354	should also not contain side-effects!).<p>
				355
				356	One additional nice thing about the <tt>DEBUG()</tt> macro is that you can
				357	enable or disable it directly in gdb. Just use "<tt>set DebugFlag=0</tt>" or
				358	"<tt>set DebugFlag=1</tt>" from the gdb if the program is running. If the
				359	program hasn't been started yet, you can always just run it with
				360	<tt>-debug</tt>.<p>
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	361
				362
				363	<!-- ======================================================================= -->
				364	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				365	<tr><td> </td><td width="100%">
				366	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				367	<a name="Statistic">The <tt>Statistic</tt> template & <tt>-stats</tt>
				368	option</a>
				369	</b></font></td></tr></table><ul>
				370
				371	The "<tt><a
Chris Lattner	8328f1d	2002-10-01 22:39:41 +0000	[diff] [blame]	372	href="/doxygen/Statistic_8h-source.html">Support/Statistic.h</a></tt>"
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	373	file provides a template named <tt>Statistic</tt> that is used as a unified way
				374	to keeping track of what the LLVM compiler is doing and how effective various
				375	optimizations are. It is useful to see what optimizations are contributing to
				376	making a particular program run faster.<p>
				377
				378	Often you may run your pass on some big program, and you're interested to see
				379	how many times it makes a certain transformation. Although you can do this with
				380	hand inspection, or some ad-hoc method, this is a real pain and not very useful
				381	for big programs. Using the <tt>Statistic</tt> template makes it very easy to
				382	keep track of this information, and the calculated information is presented in a
				383	uniform manner with the rest of the passes being executed.<p>
				384
				385	There are many examples of <tt>Statistic</tt> users, but this basics of using it
				386	are as follows:<p>
				387
				388	<ol>
				389	<li>Define your statistic like this:<p>
				390
				391	<pre>
Chris Lattner	8328f1d	2002-10-01 22:39:41 +0000	[diff] [blame]	392	static Statistic<> NumXForms("mypassname", "The # of times I did stuff");
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	393	</pre><p>
				394
				395	The <tt>Statistic</tt> template can emulate just about any data-type, but if you
				396	do not specify a template argument, it defaults to acting like an unsigned int
				397	counter (this is usually what you want).<p>
				398
				399	<li>Whenever you make a transformation, bump the counter:<p>
				400
				401	<pre>
				402	++NumXForms; // I did stuff
				403	</pre><p>
				404
				405	</ol><p>
				406
				407	That's all you have to do. To get '<tt>opt</tt>' to print out the statistics
				408	gathered, use the '<tt>-stats</tt>' option:<p>
				409
				410	<pre>
				411	$ opt -stats -mypassname < program.bc > /dev/null
				412	... statistic output ...
				413	</pre><p>
				414
				415	When running <tt>gccas</tt> on a C file from the SPEC benchmark suite, it gives
				416	a report that looks like this:<p>
				417
				418	<pre>
				419	7646 bytecodewriter - Number of normal instructions
				420	725 bytecodewriter - Number of oversized instructions
				421	129996 bytecodewriter - Number of bytecode bytes written
				422	2817 raise - Number of insts DCEd or constprop'd
				423	3213 raise - Number of cast-of-self removed
				424	5046 raise - Number of expression trees converted
				425	75 raise - Number of other getelementptr's formed
				426	138 raise - Number of load/store peepholes
				427	42 deadtypeelim - Number of unused typenames removed from symtab
				428	392 funcresolve - Number of varargs functions resolved
				429	27 globaldce - Number of global variables removed
				430	2 adce - Number of basic blocks removed
				431	134 cee - Number of branches revectored
				432	49 cee - Number of setcc instruction eliminated
				433	532 gcse - Number of loads removed
				434	2919 gcse - Number of instructions removed
				435	86 indvars - Number of cannonical indvars added
				436	87 indvars - Number of aux indvars removed
				437	25 instcombine - Number of dead inst eliminate
				438	434 instcombine - Number of insts combined
				439	248 licm - Number of load insts hoisted
				440	1298 licm - Number of insts hoisted to a loop pre-header
				441	3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header)
				442	75 mem2reg - Number of alloca's promoted
				443	1444 cfgsimplify - Number of blocks simplified
				444	</pre><p>
				445
				446	Obviously, with so many optimizations, having a unified framework for this stuff
				447	is very nice. Making your pass fit well into the framework makes it more
				448	maintainable and useful.<p>
				449
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	450
Chris Lattner	b99344f	2002-09-06 16:40:10 +0000	[diff] [blame]	451	<!-- *********************************************************************** -->
				452	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				453	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				454	<a name="common">Helpful Hints for Common Operations
Chris Lattner	986e0c9	2002-09-22 19:38:40 +0000	[diff] [blame]	455	</b></font></td></tr></table><ul> <!--
				456	*********************************************************************** -->
Chris Lattner	b99344f	2002-09-06 16:40:10 +0000	[diff] [blame]	457
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	458	This section describes how to perform some very simple transformations of LLVM
				459	code. This is meant to give examples of common idioms used, showing the
				460	practical side of LLVM transformations.<p>
				461
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	462	Because this is a "how-to" section, you should also read about the main classes
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	463	that you will be working with. The <a href="#coreclasses">Core LLVM Class
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	464	Hierarchy Reference</a> contains details and descriptions of the main classes
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	465	that you should know about.<p>
				466
				467	<!-- NOTE: this section should be heavy on example code -->
				468
				469
				470	<!-- ======================================================================= -->
				471	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				472	<tr><td> </td><td width="100%">
				473	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				474	<a name="inspection">Basic Inspection and Traversal Routines</a>
				475	</b></font></td></tr></table><ul>
				476
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	477	The LLVM compiler infrastructure have many different data structures that may be
				478	traversed. Following the example of the C++ standard template library, the
				479	techniques used to traverse these various data structures are all basically the
				480	same. For a enumerable sequence of values, the <tt>XXXbegin()</tt> function (or
				481	method) returns an iterator to the start of the sequence, the <tt>XXXend()</tt>
				482	function returns an iterator pointing to one past the last valid element of the
				483	sequence, and there is some <tt>XXXiterator</tt> data type that is common
				484	between the two operations.<p>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	485
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	486	Because the pattern for iteration is common across many different aspects of the
				487	program representation, the standard template library algorithms may be used on
				488	them, and it is easier to remember how to iterate. First we show a few common
				489	examples of the data structures that need to be traversed. Other data
				490	structures are traversed in very similar ways.<p>
				491
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	492
				493	<!-- _______________________________________________________________________ -->
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	494	</ul><h4><a name="iterate_function"><hr size=0>Iterating over the <a
				495	href="#BasicBlock"><tt>BasicBlock</tt></a>s in a <a
				496	href="#Function"><tt>Function</tt></a> </h4><ul>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	497
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	498	It's quite common to have a <tt>Function</tt> instance that you'd like
				499	to transform in some way; in particular, you'd like to manipulate its
				500	<tt>BasicBlock</tt>s. To facilitate this, you'll need to iterate over
				501	all of the <tt>BasicBlock</tt>s that constitute the <tt>Function</tt>.
				502	The following is an example that prints the name of a
				503	<tt>BasicBlock</tt> and the number of <tt>Instruction</tt>s it
				504	contains:
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	505
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	506	<pre>
				507	// func is a pointer to a Function instance
				508	for(Function::iterator i = func->begin(), e = func->end(); i != e; ++i) {
				509
				510	// print out the name of the basic block if it has one, and then the
				511	// number of instructions that it contains
				512
Joel Stanley	72ef35e	2002-09-06 23:05:12 +0000	[diff] [blame]	513	cerr <&lt "Basic block (name=" <&lt i->getName() << ") has "
				514	<&lt i->size() <&lt " instructions.\n";
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	515	}
				516	</pre>
				517
				518	Note that i can be used as if it were a pointer for the purposes of
				519	invoking member functions of the <tt>Instruction</tt> class. This is
				520	because the indirection operator is overloaded for the iterator
				521	classes. In the above code, the expression <tt>i->size()</tt> is
				522	exactly equivalent to <tt>(*i).size()</tt> just like you'd expect.
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	523
				524	<!-- _______________________________________________________________________ -->
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	525	</ul><h4><a name="iterate_basicblock"><hr size=0>Iterating over the <a
				526	href="#Instruction"><tt>Instruction</tt></a>s in a <a
				527	href="#BasicBlock"><tt>BasicBlock</tt></a> </h4><ul>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	528
Joel Stanley	aaeb1c1	2002-09-06 23:42:40 +0000	[diff] [blame]	529	Just like when dealing with <tt>BasicBlock</tt>s in
				530	<tt>Function</tt>s, it's easy to iterate over the individual
				531	instructions that make up <tt>BasicBlock</tt>s. Here's a code snippet
				532	that prints out each instruction in a <tt>BasicBlock</tt>:
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	533
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	534	<pre>
				535	// blk is a pointer to a BasicBlock instance
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	536	for(BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i)
Chris Lattner	2b76306	2002-09-06 22:51:10 +0000	[diff] [blame]	537	// the next statement works since operator<<(ostream&,...)
				538	// is overloaded for Instruction&
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	539	cerr << *i << "\n";
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	540	</pre>
				541
				542	However, this isn't really the best way to print out the contents of a
				543	<tt>BasicBlock</tt>! Since the ostream operators are overloaded for
				544	virtually anything you'll care about, you could have just invoked the
Chris Lattner	2b76306	2002-09-06 22:51:10 +0000	[diff] [blame]	545	print routine on the basic block itself: <tt>cerr << *blk <<
				546	"\n";</tt>.<p>
				547
				548	Note that currently operator<< is implemented for <tt>Value*</tt>, so it
				549	will print out the contents of the pointer, instead of
				550	the pointer value you might expect. This is a deprecated interface that will
				551	be removed in the future, so it's best not to depend on it. To print out the
				552	pointer value for now, you must cast to <tt>void*</tt>.<p>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	553
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	554
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	555	<!-- _______________________________________________________________________ -->
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	556	</ul><h4><a name="iterate_institer"><hr size=0>Iterating over the <a
				557	href="#Instruction"><tt>Instruction</tt></a>s in a <a
				558	href="#Function"><tt>Function</tt></a></h4><ul>
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	559
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	560	If you're finding that you commonly iterate over a <tt>Function</tt>'s
				561	<tt>BasicBlock</tt>s and then that <tt>BasicBlock</tt>'s
				562	<tt>Instruction</tt>s, <tt>InstIterator</tt> should be used instead.
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	563	You'll need to include <a href="/doxygen/InstIterator_8h-source.html"><tt>llvm/Support/InstIterator.h</tt></a>, and then
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	564	instantiate <tt>InstIterator</tt>s explicitly in your code. Here's a
				565	small example that shows how to dump all instructions in a function to
				566	stderr (<b>Note:</b> Dereferencing an <tt>InstIterator</tt> yields an
				567	<tt>Instruction*</tt>, <i>not</i> an <tt>Instruction&amp</tt>!):
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	568
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	569	<pre>
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	570	#include "<a href="/doxygen/InstIterator_8h-source.html">llvm/Support/InstIterator.h</a>"
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	571	...
				572	// Suppose F is a ptr to a function
				573	for(inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i)
				574	cerr <&lt **i <&lt "\n";
				575	</pre>
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	576
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	577	Easy, isn't it? You can also use <tt>InstIterator</tt>s to fill a
				578	worklist with its initial contents. For example, if you wanted to
				579	initialize a worklist to contain all instructions in a
				580	<tt>Function</tt> F, all you would need to do is something like:
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	581
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	582	<pre>
				583	std::set<Instruction*&gt worklist;
				584	worklist.insert(inst_begin(F), inst_end(F));
				585	</pre>
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	586
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	587	The STL set <tt>worklist</tt> would now contain all instructions in
				588	the <tt>Function</tt> pointed to by F.
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	589
				590	<!-- _______________________________________________________________________ -->
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	591	</ul><h4><a name="iterate_convert"><hr size=0>Turning an iterator into a class
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	592	pointer (and vice-versa) </h4><ul>
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	593
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	594	Sometimes, it'll be useful to grab a reference (or pointer) to a class
				595	instance when all you've got at hand is an iterator. Well, extracting
				596	a reference or a pointer from an iterator is very straightforward.
				597	Assuming that <tt>i</tt> is a <tt>BasicBlock::iterator</tt> and
				598	<tt>j</tt> is a <tt>BasicBlock::const_iterator</tt>:
				599
				600	<pre>
Chris Lattner	83b5ee0	2002-09-06 22:12:58 +0000	[diff] [blame]	601	Instruction& inst = *i; // grab reference to instruction reference
				602	Instruction* pinst = &*i; // grab pointer to instruction reference
				603	const Instruction& inst = *j;
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	604	</pre>
				605	However, the iterators you'll be working with in the LLVM framework
				606	are special: they will automatically convert to a ptr-to-instance type
				607	whenever they need to. Instead of dereferencing the iterator and then
				608	taking the address of the result, you can simply assign the iterator
				609	to the proper pointer type and you get the dereference and address-of
				610	operation as a result of the assignment (behind the scenes, this is a
				611	result of overloading casting mechanisms). Thus the last line of the
				612	last example,
				613
Chris Lattner	83b5ee0	2002-09-06 22:12:58 +0000	[diff] [blame]	614	<pre>Instruction* pinst = &*i;</pre>
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	615
				616	is semantically equivalent to
				617
				618	<pre>Instruction* pinst = i;</pre>
				619
Chris Lattner	979d9b7	2002-09-10 00:39:05 +0000	[diff] [blame]	620	<b>Caveat emptor</b>: The above syntax works <i>only</i> when you're <i>not</i>
				621	working with <tt>dyn_cast</tt>. The template definition of <tt><a
				622	href="#isa">dyn_cast</a></tt> isn't implemented to handle this yet, so you'll
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	623	still need the following in order for things to work properly:
				624
				625	<pre>
				626	BasicBlock::iterator bbi = ...;
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	627	<a href="#BranchInst">BranchInst</a>* b = <a href="#isa">dyn_cast</a><<a href="#BranchInst">BranchInst</a>>(&*bbi);
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	628	</pre>
				629
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	630	It's also possible to turn a class pointer into the corresponding
				631	iterator. Usually, this conversion is quite inexpensive. The
				632	following code snippet illustrates use of the conversion constructors
				633	provided by LLVM iterators. By using these, you can explicitly grab
				634	the iterator of something without actually obtaining it via iteration
				635	over some structure:
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	636
				637	<pre>
				638	void printNextInstruction(Instruction* inst) {
				639	BasicBlock::iterator it(inst);
				640	++it; // after this line, it refers to the instruction after *inst.
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	641	if(it != inst->getParent()->end()) cerr << *it << "\n";
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	642	}
				643	</pre>
Joel Stanley	aaeb1c1	2002-09-06 23:42:40 +0000	[diff] [blame]	644	Of course, this example is strictly pedagogical, because it'd be much
				645	better to explicitly grab the next instruction directly from inst.
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	646
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	647
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	648	<!--_______________________________________________________________________-->
				649	</ul><h4><a name="iterate_complex"><hr size=0>Finding call sites: a slightly
				650	more complex example </h4><ul>
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	651
				652	Say that you're writing a FunctionPass and would like to count all the
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	653	locations in the entire module (that is, across every
Joel Stanley	d8aabb2	2002-09-09 16:29:58 +0000	[diff] [blame]	654	<tt>Function</tt>) where a certain function (i.e. some
				655	<tt>Function</tt>*) already in scope. As you'll learn later, you may
				656	want to use an <tt>InstVisitor</tt> to accomplish this in a much more
				657	straightforward manner, but this example will allow us to explore how
				658	you'd do it if you didn't have <tt>InstVisitor</tt> around. In
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	659	pseudocode, this is what we want to do:
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	660
				661	<pre>
				662	initialize callCounter to zero
				663	for each Function f in the Module
				664	for each BasicBlock b in f
				665	for each Instruction i in b
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	666	if(i is a CallInst and calls the given function)
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	667	increment callCounter
				668	</pre>
				669
				670	And the actual code is (remember, since we're writing a
Joel Stanley	d8aabb2	2002-09-09 16:29:58 +0000	[diff] [blame]	671	<tt>FunctionPass</tt>, our <tt>FunctionPass</tt>-derived class simply
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	672	has to override the <tt>runOnFunction</tt> method...):
				673
				674	<pre>
Joel Stanley	d8aabb2	2002-09-09 16:29:58 +0000	[diff] [blame]	675	Function* targetFunc = ...;
				676
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	677	class OurFunctionPass : public FunctionPass {
				678	public:
Joel Stanley	d8aabb2	2002-09-09 16:29:58 +0000	[diff] [blame]	679	OurFunctionPass(): callCounter(0) { }
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	680
Chris Lattner	caa5d13	2002-09-09 19:58:18 +0000	[diff] [blame]	681	virtual runOnFunction(Function& F) {
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	682	for(Function::iterator b = F.begin(), be = F.end(); b != be; ++b) {
				683	for(BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) {
Chris Lattner	a9030cb	2002-09-16 22:08:07 +0000	[diff] [blame]	684	if (<a href="#CallInst">CallInst</a>* callInst = <a href="#isa">dyn_cast</a><<a href="#CallInst">CallInst</a>>(&*i)) {
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	685	// we know we've encountered a call instruction, so we
				686	// need to determine if it's a call to the
				687	// function pointed to by m_func or not.
				688
Joel Stanley	d8aabb2	2002-09-09 16:29:58 +0000	[diff] [blame]	689	if(callInst->getCalledFunction() == targetFunc)
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	690	++callCounter;
				691	}
				692	}
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	693	}
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	694
				695	private:
Joel Stanley	d8aabb2	2002-09-09 16:29:58 +0000	[diff] [blame]	696	unsigned callCounter;
Joel Stanley	e7be650	2002-09-09 15:50:33 +0000	[diff] [blame]	697	};
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	698	</pre>
				699
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	700	<!--_______________________________________________________________________-->
				701	</ul><h4><a name="iterate_chains"><hr size=0>Iterating over def-use &
				702	use-def chains</h4><ul>
				703
Joel Stanley	01040b2	2002-09-11 20:50:04 +0000	[diff] [blame]	704	Frequently, we might have an instance of the <a
				705	href="/doxygen/classValue.html">Value Class</a> and we want to
				706	determine which <tt>User</tt>s use the <tt>Value</tt>. The list of
				707	all <tt>User</tt>s of a particular <tt>Value</tt> is called a
				708	<i>def-use</i> chain. For example, let's say we have a
				709	<tt>Function*</tt> named <tt>F</tt> to a particular function
				710	<tt>foo</tt>. Finding all of the instructions that <i>use</i>
				711	<tt>foo</tt> is as simple as iterating over the <i>def-use</i> chain of
				712	<tt>F</tt>:
				713
				714	<pre>
				715	Function* F = ...;
				716
				717	for(Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) {
Chris Lattner	24b7092	2002-09-17 22:43:00 +0000	[diff] [blame]	718	if(Instruction* Inst = dyn_cast<Instruction>(*i)) {
				719	cerr << "F is used in instruction:\n";
				720	cerr << *Inst << "\n";
Joel Stanley	01040b2	2002-09-11 20:50:04 +0000	[diff] [blame]	721	}
				722	}
				723	</pre>
				724
				725	Alternately, it's common to have an instance of the <a
				726	href="/doxygen/classUser.html">User Class</a> and need to know what
				727	<tt>Value</tt>s are used by it. The list of all <tt>Value</tt>s used
				728	by a <tt>User</tt> is known as a <i>use-def</i> chain. Instances of
				729	class <tt>Instruction</tt> are common <tt>User</tt>s, so we might want
				730	to iterate over all of the values that a particular instruction uses
				731	(that is, the operands of the particular <tt>Instruction</tt>):
				732
				733	<pre>
				734	Instruction* pi = ...;
				735
				736	for(User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	737	Value* v = *i;
Joel Stanley	01040b2	2002-09-11 20:50:04 +0000	[diff] [blame]	738	...
				739	}
				740	</pre>
				741
				742
Chris Lattner	1a3105b	2002-09-09 05:49:39 +0000	[diff] [blame]	743	<!--
				744	def-use chains ("finding all users of"): Value::use_begin/use_end
				745	use-def chains ("finding all values used"): User::op_begin/op_end [op=operand]
				746	-->
				747
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	748	<!-- ======================================================================= -->
				749	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				750	<tr><td> </td><td width="100%">
				751	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				752	<a name="simplechanges">Making simple changes</a>
				753	</b></font></td></tr></table><ul>
				754
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	755	There are some primitive transformation operations present in the LLVM
				756	infrastructure that are worth knowing about. When performing
				757	transformations, it's fairly common to manipulate the contents of
				758	basic blocks. This section describes some of the common methods for
				759	doing so and gives example code.
				760
				761	<!--_______________________________________________________________________-->
				762	</ul><h4><a name="schanges_creating"><hr size=0>Creating and inserting
				763	new <tt>Instruction</tt>s</h4><ul>
				764
				765	<i>Instantiating Instructions</i>
				766
				767	<p>Creation of <tt>Instruction</tt>s is straightforward: simply call the
				768	constructor for the kind of instruction to instantiate and provide the
				769	necessary parameters. For example, an <tt>AllocaInst</tt> only
				770	<i>requires</i> a (const-ptr-to) <tt>Type</tt>. Thus:
				771
				772	<pre>AllocaInst* ai = new AllocaInst(Type::IntTy);</pre>
				773
				774	will create an <tt>AllocaInst</tt> instance that represents the
				775	allocation of one integer in the current stack frame, at runtime.
				776	Each <tt>Instruction</tt> subclass is likely to have varying default
				777	parameters which change the semantics of the instruction, so refer to
Chris Lattner	4e1f96b	2002-09-12 19:06:51 +0000	[diff] [blame]	778	the <a href="/doxygen/classInstruction.html">doxygen documentation for
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	779	the subclass of Instruction</a> that you're interested in
				780	instantiating.</p>
				781
				782	<p><i>Naming values</i></p>
				783
				784	<p>
				785	It is very useful to name the values of instructions when you're able
				786	to, as this facilitates the debugging of your transformations. If you
				787	end up looking at generated LLVM machine code, you definitely want to
				788	have logical names associated with the results of instructions! By
				789	supplying a value for the <tt>Name</tt> (default) parameter of the
				790	<tt>Instruction</tt> constructor, you associate a logical name with
				791	the result of the instruction's execution at runtime. For example,
				792	say that I'm writing a transformation that dynamically allocates space
				793	for an integer on the stack, and that integer is going to be used as
				794	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
				796	<tt>BasicBlock</tt> of some <tt>Function</tt>, and I'm intending to
				797	use it within the same <tt>Function</tt>. I might do:
				798
				799	<pre>AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");</pre>
				800
				801	where <tt>indexLoc</tt> is now the logical name of the instruction's
				802	execution value, which is a pointer to an integer on the runtime
				803	stack.
				804	</p>
				805
				806	<p><i>Inserting instructions</i></p>
				807
				808	<p>
				809	There are essentially two ways to insert an <tt>Instruction</tt> into
				810	an existing sequence of instructions that form a <tt>BasicBlock</tt>:
				811	<ul>
				812	<li>Insertion into an explicit instruction list
				813
				814	<p>Given a <tt>BasicBlock* pb</tt>, an <tt>Instruction* pi</tt> within
				815	that <tt>BasicBlock</tt>, and a newly-created instruction
				816	we wish to insert before <tt>*pi</tt>, we do the following:
				817
				818	<pre>
				819	BasicBlock* pb = ...;
				820	Instruction* pi = ...;
				821	Instruction* newInst = new Instruction(...);
				822	pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb
				823	</pre>
				824	</p>
				825
				826	<li>Insertion into an implicit instruction list
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	827	<p><tt>Instruction</tt> instances that are already in
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	828	<tt>BasicBlock</tt>s are implicitly associated with an existing
				829	instruction list: the instruction list of the enclosing basic block.
				830	Thus, we could have accomplished the same thing as the above code
				831	without being given a <tt>BasicBlock</tt> by doing:
				832	<pre>
				833	Instruction* pi = ...;
				834	Instruction* newInst = new Instruction(...);
				835	pi->getParent()->getInstList().insert(pi, newInst);
				836	</pre>
				837	In fact, this sequence of steps occurs so frequently that the
				838	<tt>Instruction</tt> class and <tt>Instruction</tt>-derived classes
				839	provide constructors which take (as a default parameter) a pointer to
				840	an <tt>Instruction</tt> which the newly-created <tt>Instruction</tt>
				841	should precede. That is, <tt>Instruction</tt> constructors are
				842	capable of inserting the newly-created instance into the
				843	<tt>BasicBlock</tt> of a provided instruction, immediately before that
				844	instruction. Using an <tt>Instruction</tt> constructor with a
				845	<tt>insertBefore</tt> (default) parameter, the above code becomes:
				846	<pre>
				847	Instruction* pi = ...;
				848	Instruction* newInst = new Instruction(..., pi);
				849	</pre>
				850	which is much cleaner, especially if you're creating a lot of
				851	instructions and adding them to <tt>BasicBlock</tt>s.
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	852	</p>
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	853	</p>
Chris Lattner	9ebf516	2002-09-12 19:08:16 +0000	[diff] [blame]	854	</ul>
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	855
				856	<!--_______________________________________________________________________-->
				857	</ul><h4><a name="schanges_deleting"><hr size=0>Deleting
Chris Lattner	4e1f96b	2002-09-12 19:06:51 +0000	[diff] [blame]	858	<tt>Instruction</tt>s</h4><ul>
				859
				860	Deleting an instruction from an existing sequence of instructions that form a <a
				861	href="#BasicBlock"><tt>BasicBlock</tt></a> is very straightforward. First, you
				862	must have a pointer to the instruction that you wish to delete. Second, you
				863	need to obtain the pointer to that instruction's basic block. You use the
				864	pointer to the basic block to get its list of instructions and then use the
				865	erase function to remove your instruction.<p>
				866
				867	For example:<p>
				868
				869	<pre>
				870	<a href="#Instruction">Instruction</a> *I = .. ;
Chris Lattner	7dbf683	2002-09-18 05:14:25 +0000	[diff] [blame]	871	<a href="#BasicBlock">BasicBlock</a> *BB = I->getParent();
				872	BB->getInstList().erase(I);
Chris Lattner	4e1f96b	2002-09-12 19:06:51 +0000	[diff] [blame]	873	</pre><p>
				874
Joel Stanley	753eb71	2002-09-11 22:32:24 +0000	[diff] [blame]	875	<!--_______________________________________________________________________-->
				876	</ul><h4><a name="schanges_replacing"><hr size=0>Replacing an
				877	<tt>Instruction</tt> with another <tt>Value</tt></h4><ul>
				878
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	879	<p><i>Replacing individual instructions</i></p>
				880	<p>
				881	Including "<a
Chris Lattner	7dbf683	2002-09-18 05:14:25 +0000	[diff] [blame]	882	href="/doxygen/BasicBlockUtils_8h-source.html">llvm/Transforms/Utils/BasicBlockUtils.h
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	883	</a>" permits use of two very useful replace functions:
				884	<tt>ReplaceInstWithValue</tt> and <tt>ReplaceInstWithInst</tt>.
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	885
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	886	<ul>
				887
Chris Lattner	7dbf683	2002-09-18 05:14:25 +0000	[diff] [blame]	888	<li><tt>ReplaceInstWithValue</tt>
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	889
				890	<p>This function replaces all uses (within a basic block) of a given
				891	instruction with a value, and then removes the original instruction.
				892	The following example illustrates the replacement of the result of a
				893	particular <tt>AllocaInst</tt> that allocates memory for a single
				894	integer with an null pointer to an integer.</p>
				895
				896	<pre>
				897	AllocaInst* instToReplace = ...;
Joel Stanley	4b28793	2002-09-29 17:31:54 +0000	[diff] [blame]	898	BasicBlock::iterator ii(instToReplace);
				899	ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii,
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	900	Constant::getNullValue(PointerType::get(Type::IntTy)));
				901	</pre>
				902
Chris Lattner	7dbf683	2002-09-18 05:14:25 +0000	[diff] [blame]	903	<li><tt>ReplaceInstWithInst</tt>
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	904
				905	<p>This function replaces a particular instruction with another
				906	instruction. The following example illustrates the replacement of one
				907	<tt>AllocaInst</tt> with another.<p>
				908
				909	<pre>
				910	AllocaInst* instToReplace = ...;
Joel Stanley	4b28793	2002-09-29 17:31:54 +0000	[diff] [blame]	911	BasicBlock::iterator ii(instToReplace);
				912	ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii,
Joel Stanley	9dd1ad6	2002-09-18 03:17:23 +0000	[diff] [blame]	913	new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt");
				914	</pre>
				915
				916	</ul>
				917	<p><i>Replacing multiple uses of <tt>User</tt>s and
				918	<tt>Value</tt>s</i></p>
				919
				920	You can use <tt>Value::replaceAllUsesWith</tt> and
				921	<tt>User::replaceUsesOfWith</tt> to change more than one use at a
				922	time. See the doxygen documentation for the <a
				923	href="/doxygen/classValue.html">Value Class</a> and <a
				924	href="/doxygen/classUser.html">User Class</a>, respectively, for more
				925	information.
				926
				927	<!-- Value::replaceAllUsesWith User::replaceUsesOfWith Point out:
				928	include/llvm/Transforms/Utils/ especially BasicBlockUtils.h with:
				929	ReplaceInstWithValue, ReplaceInstWithInst
Chris Lattner	ae7f759	2002-09-06 18:31:18 +0000	[diff] [blame]	930	-->
Chris Lattner	b99344f	2002-09-06 16:40:10 +0000	[diff] [blame]	931
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	932	<!-- *********************************************************************** -->
				933	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				934	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	935	<a name="coreclasses">The Core LLVM Class Hierarchy Reference
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	936	</b></font></td></tr></table><ul>
				937	<!-- *********************************************************************** -->
				938
				939	The Core LLVM classes are the primary means of representing the program being
				940	inspected or transformed. The core LLVM classes are defined in header files in
				941	the <tt>include/llvm/</tt> directory, and implemented in the <tt>lib/VMCore</tt>
				942	directory.<p>
				943
				944
				945	<!-- ======================================================================= -->
				946	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				947	<tr><td> </td><td width="100%">
				948	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				949	<a name="Value">The <tt>Value</tt> class</a>
				950	</b></font></td></tr></table><ul>
				951
				952	<tt>#include "<a href="/doxygen/Value_8h-source.html">llvm/Value.h</a>"</tt></b><br>
				953	doxygen info: <a href="/doxygen/classValue.html">Value Class</a><p>
				954
				955
				956	The <tt>Value</tt> class is the most important class in LLVM Source base. It
				957	represents a typed value that may be used (among other things) as an operand to
				958	an instruction. There are many different types of <tt>Value</tt>s, such as <a
				959	href="#Constant"><tt>Constant</tt></a>s, <a
				960	href="#Argument"><tt>Argument</tt></a>s, and even <a
				961	href="#Instruction"><tt>Instruction</tt></a>s and <a
				962	href="#Function"><tt>Function</tt></a>s are <tt>Value</tt>s.<p>
				963
				964	A particular <tt>Value</tt> may be used many times in the LLVM representation
				965	for a program. For example, an incoming argument to a function (represented
				966	with an instance of the <a href="#Argument">Argument</a> class) is "used" by
				967	every instruction in the function that references the argument. To keep track
				968	of this relationship, the <tt>Value</tt> class keeps a list of all of the <a
				969	href="#User"><tt>User</tt></a>s that is using it (the <a
				970	href="#User"><tt>User</tt></a> class is a base class for all nodes in the LLVM
				971	graph that can refer to <tt>Value</tt>s). This use list is how LLVM represents
Joel Stanley	9b96c44	2002-09-06 21:55:13 +0000	[diff] [blame]	972	def-use information in the program, and is accessible through the <tt>use_</tt>*
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	973	methods, shown below.<p>
				974
				975	Because LLVM is a typed representation, every LLVM <tt>Value</tt> is typed, and
				976	this <a href="#Type">Type</a> is available through the <tt>getType()</tt>
				977	method. <a name="#nameWarning">In addition, all LLVM values can be named. The
				978	"name" of the <tt>Value</tt> is symbolic string printed in the LLVM code:<p>
				979
				980	<pre>
				981	%<b>foo</b> = add int 1, 2
				982	</pre>
				983
				984	The name of this instruction is "foo". <b>NOTE</b> that the name of any value
				985	may be missing (an empty string), so names should <b>ONLY</b> be used for
				986	debugging (making the source code easier to read, debugging printouts), they
				987	should not be used to keep track of values or map between them. For this
				988	purpose, use a <tt>std::map</tt> of pointers to the <tt>Value</tt> itself
				989	instead.<p>
				990
				991	One important aspect of LLVM is that there is no distinction between an SSA
				992	variable and the operation that produces it. Because of this, any reference to
				993	the value produced by an instruction (or the value available as an incoming
				994	argument, for example) is represented as a direct pointer to the class that
				995	represents this value. Although this may take some getting used to, it
				996	simplifies the representation and makes it easier to manipulate.<p>
				997
				998
				999	<!-- _______________________________________________________________________ -->
				1000	</ul><h4><a name="m_Value"><hr size=0>Important Public Members of
				1001	the <tt>Value</tt> class</h4><ul>
				1002
				1003	<li><tt>Value::use_iterator</tt> - Typedef for iterator over the use-list<br>
				1004	<tt>Value::use_const_iterator</tt>
				1005	- Typedef for const_iterator over the use-list<br>
				1006	<tt>unsigned use_size()</tt> - Returns the number of users of the value.<br>
				1007	<tt>bool use_empty()</tt> - Returns true if there are no users.<br>
				1008	<tt>use_iterator use_begin()</tt>
				1009	- Get an iterator to the start of the use-list.<br>
				1010	<tt>use_iterator use_end()</tt>
				1011	- Get an iterator to the end of the use-list.<br>
				1012	<tt><a href="#User">User</a> *use_back()</tt>
				1013	- Returns the last element in the list.<p>
				1014
				1015	These methods are the interface to access the def-use information in LLVM. As with all other iterators in LLVM, the naming conventions follow the conventions defined by the <a href="#stl">STL</a>.<p>
				1016
				1017	<li><tt><a href="#Type">Type</a> *getType() const</tt><p>
				1018	This method returns the Type of the Value.
				1019
				1020	<li><tt>bool hasName() const</tt><br>
				1021	<tt>std::string getName() const</tt><br>
				1022	<tt>void setName(const std::string &Name)</tt><p>
				1023
				1024	This family of methods is used to access and assign a name to a <tt>Value</tt>,
				1025	be aware of the <a href="#nameWarning">precaution above</a>.<p>
				1026
				1027
				1028	<li><tt>void replaceAllUsesWith(Value *V)</tt><p>
				1029
				1030	This method traverses the use list of a <tt>Value</tt> changing all <a
Misha Brukman	c4f5bb0	2002-09-18 02:21:57 +0000	[diff] [blame]	1031	href="#User"><tt>User</tt>s</a> of the current value to refer to "<tt>V</tt>"
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1032	instead. For example, if you detect that an instruction always produces a
				1033	constant value (for example through constant folding), you can replace all uses
				1034	of the instruction with the constant like this:<p>
				1035
				1036	<pre>
				1037	Inst->replaceAllUsesWith(ConstVal);
				1038	</pre><p>
				1039
				1040
				1041
				1042	<!-- ======================================================================= -->
				1043	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1044	<tr><td> </td><td width="100%">
				1045	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1046	<a name="User">The <tt>User</tt> class</a>
				1047	</b></font></td></tr></table><ul>
				1048
				1049	<tt>#include "<a href="/doxygen/User_8h-source.html">llvm/User.h</a>"</tt></b><br>
				1050	doxygen info: <a href="/doxygen/classUser.html">User Class</a><br>
				1051	Superclass: <a href="#Value"><tt>Value</tt></a><p>
				1052
				1053
				1054	The <tt>User</tt> class is the common base class of all LLVM nodes that may
				1055	refer to <a href="#Value"><tt>Value</tt></a>s. It exposes a list of "Operands"
				1056	that are all of the <a href="#Value"><tt>Value</tt></a>s that the User is
				1057	referring to. The <tt>User</tt> class itself is a subclass of
				1058	<tt>Value</tt>.<p>
				1059
				1060	The operands of a <tt>User</tt> point directly to the LLVM <a
				1061	href="#Value"><tt>Value</tt></a> that it refers to. Because LLVM uses Static
				1062	Single Assignment (SSA) form, there can only be one definition referred to,
				1063	allowing this direct connection. This connection provides the use-def
				1064	information in LLVM.<p>
				1065
				1066	<!-- _______________________________________________________________________ -->
				1067	</ul><h4><a name="m_User"><hr size=0>Important Public Members of
				1068	the <tt>User</tt> class</h4><ul>
				1069
				1070	The <tt>User</tt> class exposes the operand list in two ways: through an index
				1071	access interface and through an iterator based interface.<p>
				1072
				1073	<li><tt>Value *getOperand(unsigned i)</tt><br>
				1074	<tt>unsigned getNumOperands()</tt><p>
				1075
				1076	These two methods expose the operands of the <tt>User</tt> in a convenient form
				1077	for direct access.<p>
				1078
				1079	<li><tt>User::op_iterator</tt> - Typedef for iterator over the operand list<br>
				1080	<tt>User::op_const_iterator</tt>
				1081	<tt>use_iterator op_begin()</tt>
				1082	- Get an iterator to the start of the operand list.<br>
				1083	<tt>use_iterator op_end()</tt>
				1084	- Get an iterator to the end of the operand list.<p>
				1085
				1086	Together, these methods make up the iterator based interface to the operands of
				1087	a <tt>User</tt>.<p>
				1088
				1089
				1090
				1091	<!-- ======================================================================= -->
				1092	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1093	<tr><td> </td><td width="100%">
				1094	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1095	<a name="Instruction">The <tt>Instruction</tt> class</a>
				1096	</b></font></td></tr></table><ul>
				1097
				1098	<tt>#include "<a
				1099	href="/doxygen/Instruction_8h-source.html">llvm/Instruction.h</a>"</tt></b><br>
				1100	doxygen info: <a href="/doxygen/classInstruction.html">Instruction Class</a><br>
				1101	Superclasses: <a href="#User"><tt>User</tt></a>, <a
				1102	href="#Value"><tt>Value</tt></a><p>
				1103
				1104	The <tt>Instruction</tt> class is the common base class for all LLVM
				1105	instructions. It provides only a few methods, but is a very commonly used
				1106	class. The primary data tracked by the <tt>Instruction</tt> class itself is the
				1107	opcode (instruction type) and the parent <a
				1108	href="#BasicBlock"><tt>BasicBlock</tt></a> the <tt>Instruction</tt> is embedded
				1109	into. To represent a specific type of instruction, one of many subclasses of
				1110	<tt>Instruction</tt> are used.<p>
				1111
				1112	Because the <tt>Instruction</tt> class subclasses the <a
				1113	href="#User"><tt>User</tt></a> class, its operands can be accessed in the same
				1114	way as for other <a href="#User"><tt>User</tt></a>s (with the
				1115	<tt>getOperand()</tt>/<tt>getNumOperands()</tt> and
				1116	<tt>op_begin()</tt>/<tt>op_end()</tt> methods).<p>
				1117
Chris Lattner	1763525	2002-09-12 17:18:46 +0000	[diff] [blame]	1118	An important file for the <tt>Instruction</tt> class is the
				1119	<tt>llvm/Instruction.def</tt> file. This file contains some meta-data about the
				1120	various different types of instructions in LLVM. It describes the enum values
				1121	that are used as opcodes (for example <tt>Instruction::Add</tt> and
				1122	<tt>Instruction::SetLE</tt>), as well as the concrete sub-classes of
				1123	<tt>Instruction</tt> that implement the instruction (for example <tt><a
				1124	href="#BinaryOperator">BinaryOperator</a></tt> and <tt><a
				1125	href="#SetCondInst">SetCondInst</a></tt>). Unfortunately, the use of macros in
				1126	this file confused doxygen, so these enum values don't show up correctly in the
				1127	<a href="/doxygen/classInstruction.html">doxygen output</a>.<p>
				1128
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1129
				1130	<!-- _______________________________________________________________________ -->
				1131	</ul><h4><a name="m_Instruction"><hr size=0>Important Public Members of
				1132	the <tt>Instruction</tt> class</h4><ul>
				1133
				1134	<li><tt><a href="#BasicBlock">BasicBlock</a> *getParent()</tt><p>
				1135
				1136	Returns the <a href="#BasicBlock"><tt>BasicBlock</tt></a> that this
				1137	<tt>Instruction</tt> is embedded into.<p>
				1138
Chris Lattner	c3dc212	2003-02-26 16:38:15 +0000	[diff] [blame]	1139	<li><tt>bool mayWriteToMemory()</tt><p>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1140
Chris Lattner	c3dc212	2003-02-26 16:38:15 +0000	[diff] [blame]	1141	Returns true if the instruction writes to memory, i.e. it is a <tt>call</tt>,
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1142	<tt>free</tt>, <tt>invoke</tt>, or <tt>store</tt>.<p>
				1143
				1144	<li><tt>unsigned getOpcode()</tt><p>
				1145
				1146	Returns the opcode for the <tt>Instruction</tt>.<p>
				1147
Chris Lattner	1763525	2002-09-12 17:18:46 +0000	[diff] [blame]	1148	<li><tt><a href="#Instruction">Instruction</a> *clone() const</tt><p>
				1149
				1150	Returns another instance of the specified instruction, identical in all ways to
				1151	the original except that the instruction has no parent (ie it's not embedded
				1152	into a <a href="#BasicBlock"><tt>BasicBlock</tt></a>), and it has no name.<p>
				1153
				1154
				1155
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1156	<!--
				1157
				1158	\subsection{Subclasses of Instruction :}
				1159	\begin{itemize}
				1160	<li>BinaryOperator : This subclass of Instruction defines a general interface to the all the instructions involvong binary operators in LLVM.
				1161	\begin{itemize}
				1162	<li><tt>bool swapOperands()</tt>: Exchange the two operands to this instruction. If the instruction cannot be reversed (i.e. if it's a Div), it returns true.
				1163	\end{itemize}
				1164	<li>TerminatorInst : This subclass of Instructions defines an interface for all instructions that can terminate a BasicBlock.
				1165	\begin{itemize}
				1166	<li> <tt>unsigned getNumSuccessors()</tt>: Returns the number of successors for this terminator instruction.
				1167	<li><tt>BasicBlock *getSuccessor(unsigned i)</tt>: As the name suggests returns the ith successor BasicBlock.
				1168	<li><tt>void setSuccessor(unsigned i, BasicBlock *B)</tt>: sets BasicBlock B as the ith succesor to this terminator instruction.
				1169	\end{itemize}
				1170
				1171	<li>PHINode : This represents the PHI instructions in the SSA form.
				1172	\begin{itemize}
				1173	<li><tt> unsigned getNumIncomingValues()</tt>: Returns the number of incoming edges to this PHI node.
				1174	<li><tt> Value *getIncomingValue(unsigned i)</tt>: Returns the ith incoming Value.
				1175	<li><tt>void setIncomingValue(unsigned i, Value *V)</tt>: Sets the ith incoming Value as V
				1176	<li><tt>BasicBlock *getIncomingBlock(unsigned i)</tt>: Returns the Basic Block corresponding to the ith incoming Value.
				1177	<li><tt> void addIncoming(Value D, BasicBlock BB)</tt>:
				1178	Add an incoming value to the end of the PHI list
				1179	<li><tt> int getBasicBlockIndex(const BasicBlock *BB) const</tt>:
				1180	Returns the first index of the specified basic block in the value list for this PHI. Returns -1 if no instance.
				1181	\end{itemize}
				1182	<li>CastInst : In LLVM all casts have to be done through explicit cast instructions. CastInst defines the interface to the cast instructions.
				1183	<li>CallInst : This defines an interface to the call instruction in LLVM. ARguments to the function are nothing but operands of the instruction.
				1184	\begin{itemize}
				1185	<li>: <tt>Function *getCalledFunction()</tt>: Returns a handle to the function that is being called by this Function.
				1186	\end{itemize}
				1187	<li>LoadInst, StoreInst, GetElemPtrInst : These subclasses represent load, store and getelementptr instructions in LLVM.
				1188	\begin{itemize}
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1189	<li><tt>Value * getPointerOperand()</tt>: Returns the Pointer Operand which is typically the 0th operand.
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1190	\end{itemize}
				1191	<li>BranchInst : This is a subclass of TerminatorInst and defines the interface for conditional and unconditional branches in LLVM.
				1192	\begin{itemize}
				1193	<li><tt>bool isConditional()</tt>: Returns true if the branch is a conditional branch else returns false
				1194	<li> <tt>Value *getCondition()</tt>: Returns the condition if it is a conditional branch else returns null.
				1195	<li> <tt>void setUnconditionalDest(BasicBlock *Dest)</tt>: Changes the current branch to an unconditional one targetting the specified block.
				1196	\end{itemize}
				1197
				1198	\end{itemize}
				1199
				1200	-->
				1201
				1202
				1203	<!-- ======================================================================= -->
				1204	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1205	<tr><td> </td><td width="100%">
				1206	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1207	<a name="BasicBlock">The <tt>BasicBlock</tt> class</a>
				1208	</b></font></td></tr></table><ul>
				1209
				1210	<tt>#include "<a
				1211	href="/doxygen/BasicBlock_8h-source.html">llvm/BasicBlock.h</a>"</tt></b><br>
				1212	doxygen info: <a href="/doxygen/classBasicBlock.html">BasicBlock Class</a><br>
				1213	Superclass: <a href="#Value"><tt>Value</tt></a><p>
				1214
				1215
				1216	This class represents a single entry multiple exit section of the code, commonly
				1217	known as a basic block by the compiler community. The <tt>BasicBlock</tt> class
				1218	maintains a list of <a href="#Instruction"><tt>Instruction</tt></a>s, which form
				1219	the body of the block. Matching the language definition, the last element of
				1220	this list of instructions is always a terminator instruction (a subclass of the
				1221	<a href="#TerminatorInst"><tt>TerminatorInst</tt></a> class).<p>
				1222
				1223	In addition to tracking the list of instructions that make up the block, the
				1224	<tt>BasicBlock</tt> class also keeps track of the <a
				1225	href="#Function"><tt>Function</tt></a> that it is embedded into.<p>
				1226
				1227	Note that <tt>BasicBlock</tt>s themselves are <a
				1228	href="#Value"><tt>Value</tt></a>s, because they are referenced by instructions
				1229	like branches and can go in the switch tables. <tt>BasicBlock</tt>s have type
				1230	<tt>label</tt>.<p>
				1231
				1232
				1233	<!-- _______________________________________________________________________ -->
				1234	</ul><h4><a name="m_BasicBlock"><hr size=0>Important Public Members of
				1235	the <tt>BasicBlock</tt> class</h4><ul>
				1236
				1237	<li><tt>BasicBlock(const std::string &Name = "", <a
				1238	href="#Function">Function</a> *Parent = 0)</tt><p>
				1239
				1240	The <tt>BasicBlock</tt> constructor is used to create new basic blocks for
				1241	insertion into a function. The constructor simply takes a name for the new
				1242	block, and optionally a <a href="#Function"><tt>Function</tt></a> to insert it
				1243	into. If the <tt>Parent</tt> parameter is specified, the new
				1244	<tt>BasicBlock</tt> is automatically inserted at the end of the specified <a
				1245	href="#Function"><tt>Function</tt></a>, if not specified, the BasicBlock must be
				1246	manually inserted into the <a href="#Function"><tt>Function</tt></a>.<p>
				1247
				1248	<li><tt>BasicBlock::iterator</tt> - Typedef for instruction list iterator<br>
				1249	<tt>BasicBlock::const_iterator</tt> - Typedef for const_iterator.<br>
				1250	<tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
				1251	<tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
				1252
				1253	These methods and typedefs are forwarding functions that have the same semantics
				1254	as the standard library methods of the same names. These methods expose the
				1255	underlying instruction list of a basic block in a way that is easy to
				1256	manipulate. To get the full complement of container operations (including
				1257	operations to update the list), you must use the <tt>getInstList()</tt>
				1258	method.<p>
				1259
				1260	<li><tt>BasicBlock::InstListType &getInstList()</tt><p>
				1261
				1262	This method is used to get access to the underlying container that actually
				1263	holds the Instructions. This method must be used when there isn't a forwarding
				1264	function in the <tt>BasicBlock</tt> class for the operation that you would like
				1265	to perform. Because there are no forwarding functions for "updating"
				1266	operations, you need to use this if you want to update the contents of a
				1267	<tt>BasicBlock</tt>.<p>
				1268
				1269	<li><tt><A href="#Function">Function</a> *getParent()</tt><p>
				1270
				1271	Returns a pointer to <a href="#Function"><tt>Function</tt></a> the block is
				1272	embedded into, or a null pointer if it is homeless.<p>
				1273
				1274	<li><tt><a href="#TerminatorInst">TerminatorInst</a> *getTerminator()</tt><p>
				1275
				1276	Returns a pointer to the terminator instruction that appears at the end of the
				1277	<tt>BasicBlock</tt>. If there is no terminator instruction, or if the last
				1278	instruction in the block is not a terminator, then a null pointer is
				1279	returned.<p>
				1280
				1281
				1282	<!-- ======================================================================= -->
				1283	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1284	<tr><td> </td><td width="100%">
				1285	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1286	<a name="GlobalValue">The <tt>GlobalValue</tt> class</a>
				1287	</b></font></td></tr></table><ul>
				1288
				1289	<tt>#include "<a
				1290	href="/doxygen/GlobalValue_8h-source.html">llvm/GlobalValue.h</a>"</tt></b><br>
				1291	doxygen info: <a href="/doxygen/classGlobalValue.html">GlobalValue Class</a><br>
				1292	Superclasses: <a href="#User"><tt>User</tt></a>, <a
				1293	href="#Value"><tt>Value</tt></a><p>
				1294
				1295	Global values (<A href="#GlobalVariable"><tt>GlobalVariable</tt></a>s or <a
				1296	href="#Function"><tt>Function</tt></a>s) are the only LLVM values that are
				1297	visible in the bodies of all <a href="#Function"><tt>Function</tt></a>s.
				1298	Because they are visible at global scope, they are also subject to linking with
				1299	other globals defined in different translation units. To control the linking
				1300	process, <tt>GlobalValue</tt>s know their linkage rules. Specifically,
				1301	<tt>GlobalValue</tt>s know whether they have internal or external linkage.<p>
				1302
				1303	If a <tt>GlobalValue</tt> has internal linkage (equivalent to being
				1304	<tt>static</tt> in C), it is not visible to code outside the current translation
				1305	unit, and does not participate in linking. If it has external linkage, it is
				1306	visible to external code, and does participate in linking. In addition to
				1307	linkage information, <tt>GlobalValue</tt>s keep track of which <a
				1308	href="#Module"><tt>Module</tt></a> they are currently part of.<p>
				1309
				1310	Because <tt>GlobalValue</tt>s are memory objects, they are always referred to by
				1311	their address. As such, the <a href="#Type"><tt>Type</tt></a> of a global is
				1312	always a pointer to its contents. This is explained in the LLVM Language
				1313	Reference Manual.<p>
				1314
				1315
				1316	<!-- _______________________________________________________________________ -->
				1317	</ul><h4><a name="m_GlobalValue"><hr size=0>Important Public Members of
				1318	the <tt>GlobalValue</tt> class</h4><ul>
				1319
				1320	<li><tt>bool hasInternalLinkage() const</tt><br>
				1321	<tt>bool hasExternalLinkage() const</tt><br>
				1322	<tt>void setInternalLinkage(bool HasInternalLinkage)</tt><p>
				1323
				1324	These methods manipulate the linkage characteristics of the
				1325	<tt>GlobalValue</tt>.<p>
				1326
				1327	<li><tt><a href="#Module">Module</a> *getParent()</tt><p>
				1328
				1329	This returns the <a href="#Module"><tt>Module</tt></a> that the GlobalValue is
				1330	currently embedded into.<p>
				1331
				1332
				1333
				1334	<!-- ======================================================================= -->
				1335	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1336	<tr><td> </td><td width="100%">
				1337	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1338	<a name="Function">The <tt>Function</tt> class</a>
				1339	</b></font></td></tr></table><ul>
				1340
				1341	<tt>#include "<a
				1342	href="/doxygen/Function_8h-source.html">llvm/Function.h</a>"</tt></b><br>
				1343	doxygen info: <a href="/doxygen/classFunction.html">Function Class</a><br>
				1344	Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
				1345	href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a><p>
				1346
				1347	The <tt>Function</tt> class represents a single procedure in LLVM. It is
				1348	actually one of the more complex classes in the LLVM heirarchy because it must
				1349	keep track of a large amount of data. The <tt>Function</tt> class keeps track
				1350	of a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, a list of formal <a
				1351	href="#Argument"><tt>Argument</tt></a>s, and a <a
				1352	href="#SymbolTable"><tt>SymbolTable</tt></a>.<p>
				1353
				1354	The list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s is the most commonly
				1355	used part of <tt>Function</tt> objects. The list imposes an implicit ordering
				1356	of the blocks in the function, which indicate how the code will be layed out by
				1357	the backend. Additionally, the first <a
				1358	href="#BasicBlock"><tt>BasicBlock</tt></a> is the implicit entry node for the
				1359	<tt>Function</tt>. It is not legal in LLVM explicitly branch to this initial
				1360	block. There are no implicit exit nodes, and in fact there may be multiple exit
				1361	nodes from a single <tt>Function</tt>. If the <a
				1362	href="#BasicBlock"><tt>BasicBlock</tt></a> list is empty, this indicates that
				1363	the <tt>Function</tt> is actually a function declaration: the actual body of the
				1364	function hasn't been linked in yet.<p>
				1365
				1366	In addition to a list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s, the
				1367	<tt>Function</tt> class also keeps track of the list of formal <a
				1368	href="#Argument"><tt>Argument</tt></a>s that the function receives. This
				1369	container manages the lifetime of the <a href="#Argument"><tt>Argument</tt></a>
				1370	nodes, just like the <a href="#BasicBlock"><tt>BasicBlock</tt></a> list does for
				1371	the <a href="#BasicBlock"><tt>BasicBlock</tt></a>s.<p>
				1372
				1373	The <a href="#SymbolTable"><tt>SymbolTable</tt></a> is a very rarely used LLVM
				1374	feature that is only used when you have to look up a value by name. Aside from
				1375	that, the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is used internally to
				1376	make sure that there are not conflicts between the names of <a
				1377	href="#Instruction"><tt>Instruction</tt></a>s, <a
				1378	href="#BasicBlock"><tt>BasicBlock</tt></a>s, or <a
				1379	href="#Argument"><tt>Argument</tt></a>s in the function body.<p>
				1380
				1381
				1382	<!-- _______________________________________________________________________ -->
				1383	</ul><h4><a name="m_Function"><hr size=0>Important Public Members of
				1384	the <tt>Function</tt> class</h4><ul>
				1385
				1386	<li><tt>Function(const <a href="#FunctionType">FunctionType</a> *Ty, bool isInternal, const std::string &N = "")</tt><p>
				1387
				1388	Constructor used when you need to create new <tt>Function</tt>s to add the the
				1389	program. The constructor must specify the type of the function to create and
				1390	whether or not it should start out with internal or external linkage.<p>
				1391
				1392	<li><tt>bool isExternal()</tt><p>
				1393
				1394	Return whether or not the <tt>Function</tt> has a body defined. If the function
				1395	is "external", it does not have a body, and thus must be resolved by linking
				1396	with a function defined in a different translation unit.<p>
				1397
				1398
				1399	<li><tt>Function::iterator</tt> - Typedef for basic block list iterator<br>
				1400	<tt>Function::const_iterator</tt> - Typedef for const_iterator.<br>
				1401	<tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
				1402	<tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
				1403
				1404	These are forwarding methods that make it easy to access the contents of a
				1405	<tt>Function</tt> object's <a href="#BasicBlock"><tt>BasicBlock</tt></a>
				1406	list.<p>
				1407
				1408	<li><tt>Function::BasicBlockListType &getBasicBlockList()</tt><p>
				1409
				1410	Returns the list of <a href="#BasicBlock"><tt>BasicBlock</tt></a>s. This is
				1411	neccesary to use when you need to update the list or perform a complex action
				1412	that doesn't have a forwarding method.<p>
				1413
				1414
				1415	<li><tt>Function::aiterator</tt> - Typedef for the argument list iterator<br>
				1416	<tt>Function::const_aiterator</tt> - Typedef for const_iterator.<br>
				1417	<tt>abegin()</tt>, <tt>aend()</tt>, <tt>afront()</tt>, <tt>aback()</tt>,
				1418	<tt>asize()</tt>, <tt>aempty()</tt>, <tt>arbegin()</tt>, <tt>arend()</tt><p>
				1419
				1420	These are forwarding methods that make it easy to access the contents of a
				1421	<tt>Function</tt> object's <a href="#Argument"><tt>Argument</tt></a> list.<p>
				1422
				1423	<li><tt>Function::ArgumentListType &getArgumentList()</tt><p>
				1424
				1425	Returns the list of <a href="#Argument"><tt>Argument</tt></a>s. This is
				1426	neccesary to use when you need to update the list or perform a complex action
				1427	that doesn't have a forwarding method.<p>
				1428
				1429
				1430
				1431	<li><tt><a href="#BasicBlock">BasicBlock</a> &getEntryNode()</tt><p>
				1432
				1433	Returns the entry <a href="#BasicBlock"><tt>BasicBlock</tt></a> for the
				1434	function. Because the entry block for the function is always the first block,
				1435	this returns the first block of the <tt>Function</tt>.<p>
				1436
				1437	<li><tt><a href="#Type">Type</a> *getReturnType()</tt><br>
				1438	<tt><a href="#FunctionType">FunctionType</a> *getFunctionType()</tt><p>
				1439
				1440	This traverses the <a href="#Type"><tt>Type</tt></a> of the <tt>Function</tt>
				1441	and returns the return type of the function, or the <a
				1442	href="#FunctionType"><tt>FunctionType</tt></a> of the actual function.<p>
				1443
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1444	<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p>
				1445
				1446	Return a pointer to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for this
Chris Lattner	6e6026b	2002-11-20 18:36:02 +0000	[diff] [blame]	1447	<tt>Function</tt>.<p>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1448
				1449
				1450
				1451	<!-- ======================================================================= -->
				1452	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1453	<tr><td> </td><td width="100%">
				1454	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1455	<a name="GlobalVariable">The <tt>GlobalVariable</tt> class</a>
				1456	</b></font></td></tr></table><ul>
				1457
				1458	<tt>#include "<a
				1459	href="/doxygen/GlobalVariable_8h-source.html">llvm/GlobalVariable.h</a>"</tt></b><br>
				1460	doxygen info: <a href="/doxygen/classGlobalVariable.html">GlobalVariable Class</a><br>
				1461	Superclasses: <a href="#GlobalValue"><tt>GlobalValue</tt></a>, <a
				1462	href="#User"><tt>User</tt></a>, <a href="#Value"><tt>Value</tt></a><p>
				1463
Chris Lattner	0377de4	2002-09-06 14:50:55 +0000	[diff] [blame]	1464	Global variables are represented with the (suprise suprise)
				1465	<tt>GlobalVariable</tt> class. Like functions, <tt>GlobalVariable</tt>s are
				1466	also subclasses of <a href="#GlobalValue"><tt>GlobalValue</tt></a>, and as such
				1467	are always referenced by their address (global values must live in memory, so
				1468	their "name" refers to their address). Global variables may have an initial
				1469	value (which must be a <a href="#Constant"><tt>Constant</tt></a>), and if they
				1470	have an initializer, they may be marked as "constant" themselves (indicating
				1471	that their contents never change at runtime).<p>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1472
				1473
				1474	<!-- _______________________________________________________________________ -->
Chris Lattner	0377de4	2002-09-06 14:50:55 +0000	[diff] [blame]	1475	</ul><h4><a name="m_GlobalVariable"><hr size=0>Important Public Members of the
				1476	<tt>GlobalVariable</tt> class</h4><ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1477
				1478	<li><tt>GlobalVariable(const <a href="#Type">Type</a> *Ty, bool isConstant, bool
				1479	isInternal, <a href="#Constant">Constant</a> *Initializer = 0, const std::string
				1480	&Name = "")</tt><p>
				1481
Chris Lattner	0377de4	2002-09-06 14:50:55 +0000	[diff] [blame]	1482	Create a new global variable of the specified type. If <tt>isConstant</tt> is
				1483	true then the global variable will be marked as unchanging for the program, and
				1484	if <tt>isInternal</tt> is true the resultant global variable will have internal
				1485	linkage. Optionally an initializer and name may be specified for the global variable as well.<p>
				1486
				1487
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1488	<li><tt>bool isConstant() const</tt><p>
				1489
				1490	Returns true if this is a global variable is known not to be modified at
				1491	runtime.<p>
				1492
Chris Lattner	0377de4	2002-09-06 14:50:55 +0000	[diff] [blame]	1493
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1494	<li><tt>bool hasInitializer()</tt><p>
				1495
				1496	Returns true if this <tt>GlobalVariable</tt> has an intializer.<p>
				1497
Chris Lattner	0377de4	2002-09-06 14:50:55 +0000	[diff] [blame]	1498
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1499	<li><tt><a href="#Constant">Constant</a> *getInitializer()</tt><p>
				1500
Chris Lattner	0377de4	2002-09-06 14:50:55 +0000	[diff] [blame]	1501	Returns the intial value for a <tt>GlobalVariable</tt>. It is not legal to call
				1502	this method if there is no initializer.<p>
				1503
				1504
				1505	<!-- ======================================================================= -->
				1506	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1507	<tr><td> </td><td width="100%">
				1508	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1509	<a name="Module">The <tt>Module</tt> class</a>
				1510	</b></font></td></tr></table><ul>
				1511
				1512	<tt>#include "<a
				1513	href="/doxygen/Module_8h-source.html">llvm/Module.h</a>"</tt></b><br>
				1514	doxygen info: <a href="/doxygen/classModule.html">Module Class</a><p>
				1515
				1516	The <tt>Module</tt> class represents the top level structure present in LLVM
				1517	programs. An LLVM module is effectively either a translation unit of the
				1518	original program or a combination of several translation units merged by the
				1519	linker. The <tt>Module</tt> class keeps track of a list of <a
				1520	href="#Function"><tt>Function</tt></a>s, a list of <a
				1521	href="#GlobalVariable"><tt>GlobalVariable</tt></a>s, and a <a
				1522	href="#SymbolTable"><tt>SymbolTable</tt></a>. Additionally, it contains a few
				1523	helpful member functions that try to make common operations easy.<p>
				1524
				1525
				1526	<!-- _______________________________________________________________________ -->
				1527	</ul><h4><a name="m_Module"><hr size=0>Important Public Members of the
				1528	<tt>Module</tt> class</h4><ul>
				1529
				1530	<li><tt>Module::iterator</tt> - Typedef for function list iterator<br>
				1531	<tt>Module::const_iterator</tt> - Typedef for const_iterator.<br>
				1532	<tt>begin()</tt>, <tt>end()</tt>, <tt>front()</tt>, <tt>back()</tt>,
				1533	<tt>size()</tt>, <tt>empty()</tt>, <tt>rbegin()</tt>, <tt>rend()</tt><p>
				1534
				1535	These are forwarding methods that make it easy to access the contents of a
				1536	<tt>Module</tt> object's <a href="#Function"><tt>Function</tt></a>
				1537	list.<p>
				1538
				1539	<li><tt>Module::FunctionListType &getFunctionList()</tt><p>
				1540
				1541	Returns the list of <a href="#Function"><tt>Function</tt></a>s. This is
				1542	neccesary to use when you need to update the list or perform a complex action
				1543	that doesn't have a forwarding method.<p>
				1544
				1545	<!-- Global Variable -->
				1546	<hr size=0>
				1547
				1548	<li><tt>Module::giterator</tt> - Typedef for global variable list iterator<br>
				1549	<tt>Module::const_giterator</tt> - Typedef for const_iterator.<br>
				1550	<tt>gbegin()</tt>, <tt>gend()</tt>, <tt>gfront()</tt>, <tt>gback()</tt>,
				1551	<tt>gsize()</tt>, <tt>gempty()</tt>, <tt>grbegin()</tt>, <tt>grend()</tt><p>
				1552
				1553	These are forwarding methods that make it easy to access the contents of a
				1554	<tt>Module</tt> object's <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>
				1555	list.<p>
				1556
				1557	<li><tt>Module::GlobalListType &getGlobalList()</tt><p>
				1558
				1559	Returns the list of <a href="#GlobalVariable"><tt>GlobalVariable</tt></a>s.
				1560	This is neccesary to use when you need to update the list or perform a complex
				1561	action that doesn't have a forwarding method.<p>
				1562
				1563
				1564	<!-- Symbol table stuff -->
				1565	<hr size=0>
				1566
Chris Lattner	0377de4	2002-09-06 14:50:55 +0000	[diff] [blame]	1567	<li><tt><a href="#SymbolTable">SymbolTable</a> *getSymbolTable()</tt><p>
				1568
Chris Lattner	6e6026b	2002-11-20 18:36:02 +0000	[diff] [blame]	1569	Return a reference to the <a href="#SymbolTable"><tt>SymbolTable</tt></a> for
				1570	this <tt>Module</tt>.<p>
Chris Lattner	0377de4	2002-09-06 14:50:55 +0000	[diff] [blame]	1571
				1572
				1573	<!-- Convenience methods -->
				1574	<hr size=0>
				1575
				1576	<li><tt><a href="#Function">Function</a> getFunction(const std::string &Name, const <a href="#FunctionType">FunctionType</a> Ty)</tt><p>
				1577
				1578	Look up the specified function in the <tt>Module</tt> <a
				1579	href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, return
				1580	<tt>null</tt>.<p>
				1581
				1582
				1583	<li><tt><a href="#Function">Function</a> *getOrInsertFunction(const std::string
				1584	&Name, const <a href="#FunctionType">FunctionType</a> *T)</tt><p>
				1585
				1586	Look up the specified function in the <tt>Module</tt> <a
				1587	href="#SymbolTable"><tt>SymbolTable</tt></a>. If it does not exist, add an
				1588	external declaration for the function and return it.<p>
				1589
				1590
				1591	<li><tt>std::string getTypeName(const <a href="#Type">Type</a> *Ty)</tt><p>
				1592
				1593	If there is at least one entry in the <a
				1594	href="#SymbolTable"><tt>SymbolTable</tt></a> for the specified <a
				1595	href="#Type"><tt>Type</tt></a>, return it. Otherwise return the empty
				1596	string.<p>
				1597
				1598
				1599	<li><tt>bool addTypeName(const std::string &Name, const <a href="#Type">Type</a>
				1600	*Ty)</tt><p>
				1601
				1602	Insert an entry in the <a href="#SymbolTable"><tt>SymbolTable</tt></a> mapping
				1603	<tt>Name</tt> to <tt>Ty</tt>. If there is already an entry for this name, true
				1604	is returned and the <a href="#SymbolTable"><tt>SymbolTable</tt></a> is not
				1605	modified.<p>
				1606
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1607
				1608	<!-- ======================================================================= -->
				1609	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1610	<tr><td> </td><td width="100%">
				1611	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1612	<a name="Constant">The <tt>Constant</tt> class and subclasses</a>
				1613	</b></font></td></tr></table><ul>
				1614
				1615	Constant represents a base class for different types of constants. It is
				1616	subclassed by ConstantBool, ConstantInt, ConstantSInt, ConstantUInt,
				1617	ConstantArray etc for representing the various types of Constants.<p>
				1618
				1619
				1620	<!-- _______________________________________________________________________ -->
				1621	</ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul>
				1622
				1623	<li><tt>bool isConstantExpr()</tt>: Returns true if it is a ConstantExpr
				1624
				1625
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1626	<hr>
				1627	Important Subclasses of Constant<p>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1628
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1629	<ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1630	<li>ConstantSInt : This subclass of Constant represents a signed integer constant.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1631	<ul>
				1632	<li><tt>int64_t getValue() const</tt>: Returns the underlying value of this constant.
				1633	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1634	<li>ConstantUInt : This class represents an unsigned integer.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1635	<ul>
				1636	<li><tt>uint64_t getValue() const</tt>: Returns the underlying value of this constant.
				1637	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1638	<li>ConstantFP : This class represents a floating point constant.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1639	<ul>
				1640	<li><tt>double getValue() const</tt>: Returns the underlying value of this constant.
				1641	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1642	<li>ConstantBool : This represents a boolean constant.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1643	<ul>
				1644	<li><tt>bool getValue() const</tt>: Returns the underlying value of this constant.
				1645	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1646	<li>ConstantArray : This represents a constant array.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1647	<ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1648	<li><tt>const std::vector<Use> &getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1649	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1650	<li>ConstantStruct : This represents a constant struct.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1651	<ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1652	<li><tt>const std::vector<Use> &getValues() const</tt>: Returns a Vecotr of component constants that makeup this array.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1653	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1654	<li>ConstantPointerRef : This represents a constant pointer value that is initialized to point to a global value, which lies at a constant fixed address.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1655	<ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1656	<li><tt>GlobalValue *getValue()</tt>: Returns the global value to which this pointer is pointing to.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1657	</ul>
				1658	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1659
				1660
				1661	<!-- ======================================================================= -->
				1662	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1663	<tr><td> </td><td width="100%">
				1664	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1665	<a name="Type">The <tt>Type</tt> class and Derived Types</a>
				1666	</b></font></td></tr></table><ul>
				1667
				1668	Type as noted earlier is also a subclass of a Value class. Any primitive
				1669	type (like int, short etc) in LLVM is an instance of Type Class. All
				1670	other types are instances of subclasses of type like FunctionType,
				1671	ArrayType etc. DerivedType is the interface for all such dervied types
				1672	including FunctionType, ArrayType, PointerType, StructType. Types can have
				1673	names. They can be recursive (StructType). There exists exactly one instance
				1674	of any type structure at a time. This allows using pointer equality of Type *s for comparing types.
				1675
				1676	<!-- _______________________________________________________________________ -->
				1677	</ul><h4><a name="m_Value"><hr size=0>Important Public Methods</h4><ul>
				1678
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1679	<li><tt>PrimitiveID getPrimitiveID() const</tt>: Returns the base type of the type.
				1680	<li><tt> bool isSigned() const</tt>: Returns whether an integral numeric type is signed. This is true for SByteTy, ShortTy, IntTy, LongTy. Note that this is not true for Float and Double.
				1681	<li><tt>bool isUnsigned() const</tt>: Returns whether a numeric type is unsigned. This is not quite the complement of isSigned... nonnumeric types return false as they do with isSigned. This returns true for UByteTy, UShortTy, UIntTy, and ULongTy.
				1682	<li><tt> bool isInteger() const</tt>: Equilivent to isSigned() \|\| isUnsigned(), but with only a single virtual function invocation.
				1683	<li><tt>bool isIntegral() const</tt>: Returns true if this is an integral type, which is either Bool type or one of the Integer types.
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1684
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1685	<li><tt>bool isFloatingPoint()</tt>: Return true if this is one of the two floating point types.
				1686	<li><tt>bool isRecursive() const</tt>: Returns rue if the type graph contains a cycle.
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1687	<li><tt>isLosslesslyConvertableTo (const Type *Ty) const</tt>: Return true if this type can be converted to 'Ty' without any reinterpretation of bits. For example, uint to int.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1688	<li><tt>bool isPrimitiveType() const</tt>: Returns true if it is a primitive type.
				1689	<li><tt>bool isDerivedType() const</tt>: Returns true if it is a derived type.
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1690	<li><tt>const Type * getContainedType (unsigned i) const</tt>:
				1691	This method is used to implement the type iterator. For derived types, this returns the types 'contained' in the derived type, returning 0 when 'i' becomes invalid. This allows the user to iterate over the types in a struct, for example, really easily.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1692	<li><tt>unsigned getNumContainedTypes() const</tt>: Return the number of types in the derived type.
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1693
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1694	<p>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1695
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1696	<hr>
				1697	Derived Types<p>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1698
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1699	<ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1700	<li>SequentialType : This is subclassed by ArrayType and PointerType
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1701	<ul>
				1702	<li><tt>const Type * getElementType() const</tt>: Returns the type of each of the elements in the sequential type.
				1703	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1704	<li>ArrayType : This is a subclass of SequentialType and defines interface for array types.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1705	<ul>
				1706	<li><tt>unsigned getNumElements() const</tt>: Returns the number of elements in the array.
				1707	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1708	<li>PointerType : Subclass of SequentialType for pointer types.
				1709	<li>StructType : subclass of DerivedTypes for struct types
				1710	<li>FunctionType : subclass of DerivedTypes for function types.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1711
				1712	<ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1713
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1714	<li><tt>bool isVarArg() const</tt>: Returns true if its a vararg function
				1715	<li><tt> const Type * getReturnType() const</tt>: Returns the return type of the function.
				1716	<li><tt> const ParamTypes &getParamTypes() const</tt>: Returns a vector of parameter types.
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1717	<li><tt>const Type * getParamType (unsigned i)</tt>: Returns the type of the ith parameter.
Chris Lattner	c75ff9a	2002-10-01 23:17:09 +0000	[diff] [blame]	1718	<li><tt> const unsigned getNumParams() const</tt>: Returns the number of formal parameters.
				1719	</ul>
				1720	</ul>
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1721
				1722
				1723
				1724
				1725	<!-- ======================================================================= -->
				1726	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				1727	<tr><td> </td><td width="100%">
				1728	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				1729	<a name="Argument">The <tt>Argument</tt> class</a>
				1730	</b></font></td></tr></table><ul>
				1731
				1732	This subclass of Value defines the interface for incoming formal arguments to a
				1733	function. A Function maitanis a list of its formal arguments. An argument has a
				1734	pointer to the parent Function.
				1735
				1736
				1737
				1738
				1739	<!-- *********************************************************************** -->
				1740	</ul>
				1741	<!-- *********************************************************************** -->
				1742
				1743	<hr><font size-1>
				1744	<address>By: <a href="mailto:dhurjati@cs.uiuc.edu">Dinakar Dhurjati</a> and
				1745	<a href="mailto:sabre@nondot.org">Chris Lattner</a></address>
				1746	<!-- Created: Tue Aug 6 15:00:33 CDT 2002 -->
				1747	<!-- hhmts start -->
Chris Lattner	c3dc212	2003-02-26 16:38:15 +0000	[diff] [blame]	1748	Last modified: Mon Feb 24 14:45:19 CST 2003
Chris Lattner	9355b47	2002-09-06 02:50:58 +0000	[diff] [blame]	1749	<!-- hhmts end -->
				1750	</font></body></html>