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

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