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

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