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

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