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

blob: 548a6828c116fef112b9c4db5d4268ac1c3dac16 [file] [log] [blame]

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