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

blob: f9e82989537d1a401f8b8ad2ba85bbb96e326758 [file] [log] [blame]

Chris Lattner	c6bb824	2002-08-08 20:11:18 +0000	[diff] [blame]	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
				2	<html><head><title>Writing an LLVM Pass</title></head>
				3
				4	<!--
				5	I. General Structure of an LLVM Program
				6
				7	I.1 "What is a 'Value'?": Value & User class
				8	I.2 Type & Derived Types
				9	I.3 GlobalVariable, Function
				10	I.4 BasicBlock
				11	I.5 Instruction & Subclasses
				12	1.6 Argument
				13	1.7 Constants
				14
				15	III. Useful things to know about the LLVM source base:
				16
				17	III.1 Useful links that introduce the STL
				18	III.2 isa<>, cast<>, dyn_cast<>
				19	III.3 Makefiles, useful options
				20	III.4 How to use opt & analyze to debug stuff
				21	III.5 How to write a regression test
				22	III.6 DEBUG() and Statistics (-debug & -stats)
				23	III.7 The -time-passes option
				24	III.8 ... more as needed ...
				25
				26	I think that writing Section #1 would be very helpful and that's the most
				27	stable portion of the sourcebase. #3 can be started on, but will probably
				28	just grow as time goes on. I'd like to do Section #2 once I finish some
				29	changes up that effect it.
				30
				31	-->
				32
				33	<body bgcolor=white>
				34
				35	<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				36	<tr><td>  <font size=+3 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>Writing an LLVM Pass</b></font></td>
				37	</tr></table>
				38
				39
				40	<ol>
				41	<li><a href="#introduction">Introduction - What is a pass?</a>
				42	<li><a href="#quickstart">Quick Start - Writing hello world</a>
				43	<ul>
				44	<li><a href="#makefile">Setting up the build environment</a>
				45	<li><a href="#basiccode">Basic code required</a>
				46	<li><a href="#running">Running a pass with <tt>opt</tt>
				47	or <tt>analyze</tt></a>
				48	</ul>
				49	<li><a href="#passtype">Pass classes and requirements</a>
				50	<ul>
				51	<li><a href="#Pass">The <tt>Pass</tt> class</a>
				52	<ul>
				53	<li><a href="#run">The <tt>run</tt> method</a>
				54	</ul>
				55	<li><a href="#FunctionPass">The <tt>FunctionPass</tt> class</a>
				56	<ul>
				57	<li><a href="#doInitialization">The <tt>doInitialization</tt> method</a>
				58	<li><a href="#runOnFunction">The <tt>runOnFunction</tt> method</a>
				59	<li><a href="#doFinalization">The <tt>doFinalization</tt> method</a>
				60	</ul>
				61	<li><a href="#BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
				62	<ul>
				63	<li><a href="#runOnBasicBlock">The <tt>runOnBasicBlock</tt> method</a>
				64	</ul>
				65	</ul>
				66	<li><a href="#registration">Pass Registration</a>
				67	<ul>
				68	<li><a href="#print">The <tt>print</tt> method</a>
				69	</ul>
				70	<li><a href="#interaction">Specifying interactions between passes</a>
				71	<ul>
				72	<li><a href="#getAnalysisUsage">The <tt>getAnalysisUsage</tt> method</a>
				73	<li><a href="#getAnalysis">The <tt>getAnalysis</tt> method</a>
				74	</ul>
				75	<li><a href="#passmanager">What PassManager does</a>
				76	<ul>
				77	<li><a href="#releaseMemory">The <tt>releaseMemory</tt> method</a>
				78	</ul>
				79	<li><a href="#future">Future extensions planned</a>
				80	<ul>
				81	<li><a href="#SMP">Multithreaded LLVM</a>
				82	<li><a href="#ModuleSource">A new <tt>ModuleSource</tt> interface</a>
				83	<li><a href="#PassFunctionPass"><tt>Pass</tt>'s requiring <tt>FunctionPass</tt>'s</a>
				84	</ul>
Chris Lattner	38c633d	2002-08-08 20:23:41 +0000	[diff] [blame^]	85
				86	<p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></b><p>
Chris Lattner	c6bb824	2002-08-08 20:11:18 +0000	[diff] [blame]	87	</ol><p>
				88
				89
				90
				91	<!-- *********************************************************************** -->
				92	<table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				93	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				94	<a name="introduction">Introduction - What is a pass?
				95	</b></font></td></tr></table><ul>
				96	<!-- *********************************************************************** -->
				97
				98	The LLVM Pass Framework is an important part of the LLVM system, because LLVM
				99	passes are where the interesting parts of the compiler exist. Passes perform
				100	the transformations and optimizations that make up the compiler, they build
				101	the analysis results that are used by these transformations, and they are, above
				102	all, a structuring technique for compiler code.<p>
				103
				104	All LLVM passes are subclasses of the <tt><a
				105	href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt> class, which
				106	implement functionality by overriding virtual methods inherited from
				107	<tt>Pass</tt>. Depending on how your pass works, you may be able to inherit
				108	from the <tt><a
				109	href="http://llvm.cs.uiuc.edu/doxygen/structFunctionPass.html">FunctionPass</a></tt>
				110	or <tt><a
				111	href="http://llvm.cs.uiuc.edu/doxygen/structBasicBlockPass.html">BasicBlockPass</a></tt>,
				112	which gives the system more information about what your pass does, and how it
				113	can be combined with other passes. One of the main features of the LLVM Pass
				114	Framework is that it schedules passes to run in an efficient way based on the
				115	constraints that your pass has.<p>
				116
				117	We start by showing you how to construct a pass, everything from setting up the
				118	code, to compiling, loading, and executing it. After the basics are down, more
				119	advanced features are discussed.<p>
				120
				121
				122	<!-- *********************************************************************** -->
				123	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				124	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				125	<a name="quickstart">Quick Start - Writing hello world
				126	</b></font></td></tr></table><ul>
				127	<!-- *********************************************************************** -->
				128
				129	Here we describe how to write the "hello world" of passes. The "Hello" pass is
				130	designed to simply print out the name of non-external functions that exist in
				131	the program being compiled. It does not modify the program at all, just
				132	inspects it. The source code and files for this pass are available in the LLVM
				133	source tree in the <tt>lib/Transforms/Hello</tt> directory.<p>
				134
				135
				136	<!-- ======================================================================= -->
				137	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				138	<tr><td> </td><td width="100%">
				139	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				140	<a name="makefile">Setting up the build environment
				141	</b></font></td></tr></table><ul>
				142
				143	First thing you need to do is create a new directory somewhere in the LLVM
				144	source base. For this example, we'll assume that you made
				145	"<tt>lib/Transforms/Hello</tt>". The first thing you must do is set up a build
				146	script (Makefile) that will compile the source code for the new pass. To do
				147	this, copy this into "<tt>Makefile</tt>":<p>
				148
				149	</ul><hr><ul><pre>
				150	# Makefile for hello pass
				151	LEVEL = ../../.. # Path to top level of LLVM heirarchy
				152	LIBRARYNAME = hello # Name of the library to build
				153	SHARED_LIBRARY = 1 # Build a dynamically loadable shared object
				154
				155	include $(LEVEL)/Makefile.common # Include the makefile implementation stuff
				156	</pre></ul><hr><ul><p>
				157
				158	This makefile specifies that all of the <tt>.cpp</tt> files in the current
				159	directory are to be compiled and linked together into a
				160	<tt>lib/Debug/libhello.so</tt> shared object that can be dynamically loaded by
				161	the <tt>opt</tt> or <tt>analyze</tt> tools.<p>
				162
				163	Now that we have the build scripts set up, we just need to write the code for
				164	the pass itself.<p>
				165
				166
				167	<!-- ======================================================================= -->
				168	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				169	<tr><td> </td><td width="100%">
				170	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				171	<a name="basiccode">Basic code required
				172	</b></font></td></tr></table><ul>
				173
				174	Now that we have a way to compile our new pass, we just have to write it. Start
				175	out with:<p>
				176
				177	<pre>
				178	<b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
				179	<b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Function_8h-source.html">llvm/Function.h</a>"
				180	</pre>
				181
				182	Which are needed because we are writing a <tt><a
				183	href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt>, and we are
				184	operating on <tt><a
				185	href="http://llvm.cs.uiuc.edu/doxygen/classFunction.html">Function</a></tt>'s.<p>
				186
				187	Next we have:<p>
				188
				189	<pre>
				190	<b>namespace</b> {
				191	</pre><p>
				192
				193	... which starts out an anonymous namespace. Anonymous namespaces are to C++
				194	what the "<tt>static</tt>" keyword is to C (at global scope). It makes the
				195	things declared inside of the anonymous namespace only visible to the current
				196	file. If you're not familiar with them, consult a decent C++ book for more
				197	information.<p>
				198
				199	Next, we declare our pass itself:<p>
				200
				201	<pre>
				202	<b>struct</b> Hello : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
				203	</pre><p>
				204
				205	This declares a "<tt>Hello</tt>" class that is a subclass of <tt><a
				206	href="http://llvm.cs.uiuc.edu/doxygen/structFunctionPass.html">FunctionPass</a></tt>.
				207	The different builting pass subclasses are described in detail <a
				208	href="#passtype">later</a>, but for now, know that <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s
				209	operate a function at a time.<p>
				210
				211	<pre>
				212	<b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
				213	std::cerr << "<i>Hello: </i>" << F.getName() << "\n";
				214	<b>return false</b>;
				215	}
				216	}; <i>// end of struct Hello</i>
				217	</pre>
				218
				219	We declare a "<a href="#runOnFunction"><tt>runOnFunction</tt></a>" method, which
				220	overloads an abstract virtual method inherited from <a
				221	href="#FunctionPass"><tt>FunctionPass</tt></a>. This is where we are supposed
				222	to do our thing, so we just print out our message with the name of each
				223	function.<p>
				224
				225	<pre>
				226	RegisterOpt<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>");
				227	} <i>// end of anonymous namespace</i>
				228	</pre><p>
				229
				230	Lastly, we register our class <tt>Hello</tt>, giving it a command line argument
				231	"<tt>hello</tt>", and a name "<tt>Hello World Pass</tt>". There are several
				232	different ways of <a href="#registration">registering your pass</a>, depending
				233	on what it is to be used for. For "optimizations" we use the
				234	<tt>RegisterOpt</tt> template.<p>
				235
				236	As a whole, the <tt>.cpp</tt> file looks like:<p>
				237
				238	<pre>
				239	<b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
				240	<b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Function_8h-source.html">llvm/Function.h</a>"
				241
				242	<b>namespace</b> {
				243	<b>struct Hello</b> : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
				244	<b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
				245	std::cerr << "<i>Hello: </i>" << F.getName() << "\n";
				246	<b>return false</b>;
				247	}
				248	};
				249
				250	RegisterOpt<Hello> X("<i>hello</i>", "<i>Hello World Pass</i>");
				251	}
				252	</pre><p>
				253
				254	Now that it's all together, compile the file with a simple "<tt>gmake</tt>"
				255	command in the local directory and you should get a new
				256	"<tt>lib/Debug/libhello.so</tt> file. Note that everything in this file is
				257	contained in an anonymous namespace: this reflects the fact that passes are self
				258	contained units that do not need external interfaces (although they can have
				259	them) to be useful.<p>
				260
				261
				262	<!-- ======================================================================= -->
				263	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				264	<tr><td> </td><td width="100%">
				265	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				266	<a name="running">Running a pass with <tt>opt</tt> or <tt>analyze</tt>
				267	</b></font></td></tr></table><ul>
				268
				269	Now that you have a brand new shiny <tt>.so</tt> file, we can use the
				270	<tt>opt</tt> command to run an LLVM program through your pass. Because you
				271	registered your pass with the <tt>RegisterOpt</tt> template, you will be able to
				272	use the <tt>opt</tt> tool to access it, once loaded.<p>
				273
				274	To test it, follow the example at the end of the <a
				275	href="GettingStarted.html">Getting Started Guide</a> to compile "Hello World" to
				276	LLVM. We can now run the bytecode file (<tt>hello.bc</tt>) for the program
				277	through our transformation like this (or course, any bytecode file will
				278	work):<p>
				279
				280	<pre>
				281	$ opt -load ../../../lib/Debug/libhello.so -hello < hello.bc > /dev/null
				282	Hello: __main
				283	Hello: puts
				284	Hello: main
				285	</pre><p>
				286
				287	The '<tt>-load</tt>' option specifies that '<tt>opt</tt>' should load your pass
				288	as a shared object, which makes '<tt>-hello</tt>' a valid command line argument
				289	(which is one reason you need to <a href="#registration">register your
				290	pass</a>). Because the hello pass does not modify the program in any
				291	interesting way, we just throw away the result of <tt>opt</tt> (sending it to
				292	<tt>/dev/null</tt>).<p>
				293
				294	To see what happened to the other string you registered, try running
				295	<tt>opt</tt> with the <tt>--help</tt> option:<p>
				296
				297	<pre>
				298	$ opt -load ../../../lib/Debug/libhello.so --help
				299	OVERVIEW: llvm .bc -> .bc modular optimizer
				300
				301	USAGE: opt [options] <input bytecode>
				302
				303	OPTIONS:
				304	Optimizations available:
				305	...
				306	-funcresolve - Resolve Functions
				307	-gcse - Global Common Subexpression Elimination
				308	-globaldce - Dead Global Elimination
				309	<b>-hello - Hello World Pass</b>
				310	-indvars - Cannonicalize Induction Variables
				311	-inline - Function Integration/Inlining
				312	-instcombine - Combine redundant instructions
				313	...
				314	</pre><p>
				315
				316	The pass name get added as the information string for your pass, giving some
				317	documentation to users of <tt>opt</tt>. Now that you have a working pass, you
				318	would go ahead and make it do the cool transformations you want. Once you get
				319	it all working and tested, it may become useful to find out how fast your pass
				320	is. The <a href="#passManager"><tt>PassManager</tt></a> provides a nice command
				321	line option (<tt>--time-passes</tt>) that allows you to get information about
				322	the execution time of your pass along with the other passes you queue up. For
				323	example:<p>
				324
				325	<pre>
				326	$ opt -load ../../../lib/Debug/libhello.so -hello -time-passes < hello.bc > /dev/null
				327	Hello: __main
				328	Hello: puts
				329	Hello: main
				330	===============================================================================
				331	... Pass execution timing report ...
				332	===============================================================================
				333	Total Execution Time: 0.02 seconds (0.0479059 wall clock)
				334
				335	---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Pass Name ---
				336	0.0100 (100.0%) 0.0000 ( 0.0%) 0.0100 ( 50.0%) 0.0402 ( 84.0%) Bytecode Writer
				337	0.0000 ( 0.0%) 0.0100 (100.0%) 0.0100 ( 50.0%) 0.0031 ( 6.4%) Dominator Set Construction
				338	0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0013 ( 2.7%) Module Verifier
				339	<b> 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0033 ( 6.9%) Hello World Pass</b>
				340	0.0100 (100.0%) 0.0100 (100.0%) 0.0200 (100.0%) 0.0479 (100.0%) TOTAL
				341	</pre><p>
				342
				343	As you can see, our implementation above is pretty fast :). The additional
				344	passes listed are automatically inserted by the '<tt>opt</tt>' tool to verify
				345	that the LLVM emitted by your pass is still valid and well formed LLVM, which
				346	hasn't been broken somehow.
				347
				348	Now that you have seen the basics of the mechanics behind passes, we can talk
				349	about some more details of how they work and how to use them.<p>
				350
				351
				352
				353	<!-- *********************************************************************** -->
				354	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				355	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				356	<a name="passtype">Pass classes and requirements
				357	</b></font></td></tr></table><ul>
				358	<!-- *********************************************************************** -->
				359
				360	One of the first things that you should do when designing a new pass is to
				361	decide what class you should subclass for your pass. The <a
				362	href="#basiccode">Hello World</a> example uses the <tt><a
				363	href="#FunctionPass">FunctionPass</a></tt> class for its implementation, but we
				364	did not discuss why or when this should occur. Here we talk about the classes
				365	available, from the most general to the most specific.<p>
				366
				367	When choosing a superclass for your Pass, you should choose the most specific
				368	class possible, while still being able to meet the requirements listed. This
				369	gives the LLVM Pass Infrastructure information neccesary to optimize how passes
				370	are run, so that the resultant compiler isn't unneccesarily slow.<p>
				371
				372
				373
				374	<!-- ======================================================================= -->
				375	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				376	<tr><td> </td><td width="100%">
				377	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				378	<a name="Pass">The <tt>Pass</tt> class
				379	</b></font></td></tr></table><ul>
				380
				381	The "<tt><a href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt>"
				382	class is the most general of all superclasses that you can use. Deriving from
				383	<tt>Pass</tt> indicates that your pass uses the entire program as a unit,
				384	refering to function bodies in no predictable order, or adding and removing
				385	functions. Because nothing is known about the behavior of direct <tt>Pass</tt>
				386	subclasses, no optimization can be done for their execution.<p>
				387
				388	To write a correct <tt>Pass</tt> subclass, derive from <tt>Pass</tt> and
				389	overload the <tt>run</tt> method with the following signature:<p>
				390
				391	<!-- _______________________________________________________________________ -->
				392	</ul><h4><a name="run"><hr size=0>The <tt>run</tt> method</h4><ul>
				393
				394
				395	<pre>
				396	<b>virtual bool</b> run(Module &M) = 0;
				397	</pre><p>
				398
				399	The <tt>run</tt> method performs the interesting work of the pass, and should
				400	return true if the module was modified by the transformation, false
				401	otherwise.<p>
				402
				403
				404
				405	<!-- ======================================================================= -->
				406	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				407	<tr><td> </td><td width="100%">
				408	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				409	<a name="FunctionPass">The <tt>FunctionPass</tt> class
				410	</b></font></td></tr></table><ul>
				411
				412	In contrast to direct <tt>Pass</tt> subclasses, direct <tt><a
				413	href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">FunctionPass</a></tt>
				414	subclasses do have a predictable, local behavior that can be expected by the
				415	system. All <tt>FunctionPass</tt> execute on each function in the program
				416	independant of all of the other functions in the program.
				417	<tt>FunctionPass</tt>'s do not require that they are executed in a particular
				418	order, and <tt>FunctionPass</tt>'s do not modify external functions.<p>
				419
				420	To be explicit, <tt>FunctionPass</tt> subclasses are not allowed to:<p>
				421
				422	<ol>
				423	<li>Modify a Function other than the one currently being processed.
				424	<li>Add or remove Function's from the current Module.
				425	<li>Add or remove global variables from the current Module.
				426	<li>Maintain state across invocations of
				427	<a href="#runOnFunction"><tt>runOnFunction</tt></a> (including global data)
				428	</ol><p>
				429
				430	Implementing a <tt>FunctionPass</tt> is usually straightforward (See the <a
				431	href="#basiccode">Hello World</a> pass for example). <tt>FunctionPass</tt>'s
				432	may overload three virtual methods to do their work. All of these methods
				433	should return true if they modified the program, or false if they didn't.<p>
				434
				435	<!-- _______________________________________________________________________ -->
				436	</ul><h4><a name="doInitialization"><hr size=0>The <tt>doInitialization</tt>
				437	method</h4><ul>
				438
				439	<pre>
				440	<b>virtual bool</b> doInitialization(Module &M);
				441	</pre><p>
				442
				443	The <tt>doIninitialize</tt> method is allowed to do most of the things that
				444	<tt>FunctionPass</tt>'s are not allowed to do. They can add and remove
				445	functions, get pointers to functions, etc. The <tt>doInitialize</tt> method is
				446	designed to do simple initialization type of stuff that does not depend on the
				447	functions being processed. The <tt>doInitialization</tt> function call is not
				448	scheduled to overlap with any other pass executions.<p>
				449
				450	A good example of how this method should be used is the <a
				451	href="http://llvm.cs.uiuc.edu/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations</a>
				452	pass. This pass converts <tt>malloc</tt> and <tt>free</tt> instructions into
				453	platform dependant <tt>malloc()</tt> and <tt>free()</tt> function calls. It
				454	uses the <tt>doInitialization</tt> method to get a reference to the malloc and
				455	free functions that it needs, adding prototypes to the module if neccesary.<p>
				456
				457	<!-- _______________________________________________________________________ -->
				458	</ul><h4><a name="runOnFunction"><hr size=0>The <tt>runOnFunction</tt> method</h4><ul>
				459
				460	<pre>
				461	<b>virtual bool</b> runOnFunction(Function &F) = 0;
				462	</pre><p>
				463
				464	The <tt>runOnFunction</tt> method must be implemented by your subclass to do the
				465	transformation or analysis work of your pass. As usual, a true value should be
				466	returned if the function is modified.<p>
				467
				468	<!-- _______________________________________________________________________ -->
				469	</ul><h4><a name="doFinalization"><hr size=0>The <tt>doFinalization</tt> method</h4><ul>
				470
				471	<pre>
				472	<b>virtual bool</b> doFinalization(Module &M);
				473	</pre</p>
				474
				475	The <tt>doFinalization</tt> method is an infrequently used method that is called
				476	when the pass framework has finished calling <a
				477	href="#runOnFunction"><tt>runOnFunction</tt></a> for every function in the
				478	program being compiled.<p>
				479
				480
				481
				482	<!-- ======================================================================= -->
				483	</ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
				484	<tr><td> </td><td width="100%">
				485	<font color="#EEEEFF" face="Georgia,Palatino"><b>
				486	<a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
				487	</b></font></td></tr></table><ul>
				488
				489	<tt>BasicBlockPass</tt>'s are just like <a
				490	href="#FunctionPass"><tt>FunctionPass</tt></a>'s, except that they must limit
				491	their scope of inspection and modification to a single basic block at a time.
				492	As such, they are <b>not</b> allowed to do any of the following:<p>
				493
				494	<ol>
				495	<li>Modify or inspect any basic blocks outside of the current one
				496	<li>Maintain state across invocations of
				497	<a href="#runOnBasicBlock"><tt>runOnBasicBlock</tt></a>
				498	<li>Modify the constrol flow graph (by altering terminator instructions)
				499	<li>Any of the things verboten for
				500	<a href="#FunctionPass"><tt>FunctionPass</tt></a>'s.
				501	</ol><p>
				502
				503	<tt>BasicBlockPass</tt>'s are useful for traditional local and "peephole"
				504	optimizations. They may override the same <a
				505	href="#doInitialization"><tt>doInitialization</tt></a> and <a
				506	href="#doFinalization"><tt>doFinalization</tt></a> methods that <a
				507	href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have a
				508	<tt>runOnBasicBlock</tt> method:<p>
				509
				510	<!-- _______________________________________________________________________ -->
				511	</ul><h4><a name="runOnBasicBlock"><hr size=0>The <tt>runOnBasicBlock</tt> method</h4><ul>
				512
				513	<pre>
				514	<b>virtual bool</b> runOnBasicBlock(BasicBlock &BB) = 0;
				515	</pre><p>
				516
				517	Override this function to do the work of the <tt>BasicBlockPass</tt>. This
				518	function is not allowed to inspect or modify basic blocks other than the
				519	parameter, and are not allowed to modify the CFG. A true value must be returned
				520	if the basic block is modified.<p>
				521
				522
				523	<!-- *********************************************************************** -->
				524	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				525	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				526	<a name="registration">Pass registration
				527	</b></font></td></tr></table><ul>
				528	<!-- *********************************************************************** -->
				529
				530	In the <a href="#basiccode">Hello World</a> example pass we illustrated how pass
				531	registration works, and discussed some of the reasons that it is used and what
				532	it does. Here we discuss how and why passes are registered.<p>
				533
				534	Passes can be registered in several different ways. Depending on the general
				535	classification of the pass, you should use one of the following templates to
				536	register the pass:<p>
				537
				538	<ul>
				539	<li><b><tt>RegisterOpt</tt></b> - This template should be used when you are
				540	registering a pass that logically should be available for use in the
				541	'<tt>opt</tt>' utility.<p>
				542
				543	<li><b><tt>RegisterAnalysis</tt></b> - This template should be used when you are
				544	registering a pass that logically should be available for use in the
				545	'<tt>analysis</tt>' utility.<p>
				546
				547	<li><b><tt>RegisterLLC</tt></b> - This template should be used when you are
				548	registering a pass that logically should be available for use in the
				549	'<tt>llc</tt>' utility.<p>
				550
				551	<li><b><tt>RegisterPass</tt></b> - This is the generic form of the
				552	<tt>Register*</tt> templates that should be used if you want your pass listed by
				553	multiple or no utilities. This template takes an extra third argument that
				554	specifies which tools it should be listed in. See the <a
				555	href="http://llvm.cs.uiuc.edu/doxygen/PassSupport_8h-source.html">PassSupport.h</a>
				556	file for more information.<p>
				557	</ul><p>
				558
				559	Regardless of how you register your pass, you must specify at least two
				560	parameters. The first parameter is the name of the pass that is to be used on
				561	the command line to specify that the pass should be added to a program (for
				562	example <tt>opt</tt> or <tt>analyze</tt>). The second argument is the name of
				563	the pass, which is to be used for the <tt>--help</tt> output of programs, as
				564	well as for debug output generated by the <tt>--debug-pass</tt> option.<p>
				565
				566	If you pass is constructed by its default constructor, you only ever have to
				567	pass these two arguments. If, on the other hand, you require other information
				568	(like target specific information), you must pass an additional argument. This
				569	argument is a pointer to a function used to create the pass. For an example of
				570	how this works, look at the <a
				571	href="http://llvm.cs.uiuc.edu/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations.cpp</a>
				572	file.<p>
				573
				574	If a pass is registered to be used by the <tt>analyze</tt> utility, you should
				575	implement the virtual <tt>print</tt> method:<p>
				576
				577	<!-- _______________________________________________________________________ -->
				578	</ul><h4><a name="print"><hr size=0>The <tt>print</tt> method</h4><ul>
				579
				580	<pre>
				581	<b>virtual void</b> print(std::ostream &O, <b>const</b> Module *M) <b>const</b>;
				582	</pre><p>
				583
				584	The <tt>print</tt> method must be implemented by "analyses" in order to print a
				585	human readable version of the analysis results. This is useful for debugging an
				586	analysis itself, as well as for other people to figure out how an analysis
				587	works. The <tt>analyze</tt> tool uses this method to generate its output.<p>
				588
				589	The <tt>ostream</tt> parameter specifies the stream to write the results on, and
				590	the <tt>Module</tt> parameter gives a pointer to the top level module of the
				591	program that has been analyzed. Note however that this pointer may be null in
				592	certain circumstances (such as calling the <tt>Pass::dump()</tt> from a
				593	debugger), so it should only be used to enhance debug output, it should not be
				594	depended on.<p>
				595
				596
				597	<!-- *********************************************************************** -->
				598	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				599	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				600	<a name="interaction">Specifying interactions between passes
				601	</b></font></td></tr></table><ul>
				602	<!-- *********************************************************************** -->
				603
				604	One of the main responsibilities of the <tt>PassManager</tt> is the make sure
				605	that passes interact with each other correctly. Because <tt>PassManager</tt>
				606	tries to <a href="#passmanager">optimize the execution of passes</a> it must
				607	know how the passes interact with each other and what dependencies exist between
				608	the various passes. To track this, each pass can declare the set of passes that
				609	are required to be executed before the current pass, and the passes which are
				610	invalidated by the current pass.<p>
				611
				612	Typically this functionality is used to require that analysis results are
				613	computed before your pass is run. Running arbitrary transformation passes can
				614	invalidate the computed analysis results, which is what the invalidation set
				615	specifies. If a pass does not implement the <tt><a
				616	href="#getAnalysisUsage">getAnalysisUsage</a></tt> method, it defaults to not
				617	having any prerequisite passes, and invalidating <b>all</b> other passes.<p>
				618
				619
				620	<!-- _______________________________________________________________________ -->
				621	</ul><h4><a name="getAnalysisUsage"><hr size=0>The <tt>getAnalysisUsage</tt> method</h4><ul>
				622
				623	<pre>
				624	<b>virtual void</b> getAnalysisUsage(AnalysisUsage &Info) <b>const</b>;
				625	</pre><p>
				626
				627	By implementing the <tt>getAnalysisUsage</tt> method, the required and
				628	invalidated sets may be specified for your transformation. The implementation
				629	should fill in the <tt><a
				630	href="http://llvm.cs.uiuc.edu/doxygen/classAnalysisUsage.html">AnalysisUsage</a></tt>
				631	object with information about which passes are required and not invalidated. To do this, the following set methods are provided by the <tt><a
				632	href="http://llvm.cs.uiuc.edu/doxygen/classAnalysisUsage.html">AnalysisUsage</a></tt> class:<p>
				633
				634	<pre>
				635	<i>// addRequires - Add the specified pass to the required set for your pass.</i>
				636	<b>template</b><<b>class</b> PassClass>
				637	AnalysisUsage &AnalysisUsage::addRequired();
				638
				639	<i>// addPreserved - Add the specified pass to the set of analyses preserved by
				640	// this pass</i>
				641	<b>template</b><<b>class</b> PassClass>
				642	AnalysisUsage &AnalysisUsage::addPreserved();
				643
				644	<i>// setPreservesAll - Call this if the pass does not modify its input at all</i>
				645	<b>void</b> AnalysisUsage::setPreservesAll();
				646
				647	<i>// preservesCFG - This function should be called by the pass, iff they do not:
				648	//
				649	// 1. Add or remove basic blocks from the function
				650	// 2. Modify terminator instructions in any way.
				651	//
				652	// This is automatically implied for <a href="#BasicBlockPass">BasicBlockPass</a>'s
				653	//</i>
				654	<b>void</b> AnalysisUsage::preservesCFG();
				655	</pre><p>
				656
				657	Some examples of how to use these methods are:<p>
				658
				659	<pre>
				660	<i>// This is an example implementation from an analysis, which does not modify
				661	// the program at all, yet has a prerequisite.</i>
				662	<b>void</b> <a href="http://llvm.cs.uiuc.edu/doxygen/structPostDominanceFrontier.html">PostDominanceFrontier</a>::getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
				663	AU.setPreservesAll();
				664	AU.addRequired<<a href="http://llvm.cs.uiuc.edu/doxygen/structPostDominatorTree.html">PostDominatorTree</a>>();
				665	}
				666	</pre><p>
				667
				668	and:<p>
				669
				670	<pre>
				671	<i>// This example modifies the program, but does not modify the CFG</i>
				672	<b>void</b> <a href="http://llvm.cs.uiuc.edu/doxygen/structLICM.html">LICM</a>::getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
				673	AU.preservesCFG();
				674	AU.addRequired<<a href="http://llvm.cs.uiuc.edu/doxygen/classLoopInfo.html">LoopInfo</a>>();
				675	}
				676	</pre><p>
				677
				678	<!-- _______________________________________________________________________ -->
				679	</ul><h4><a name="getAnalysis"><hr size=0>The <tt>getAnalysis<></tt> method</h4><ul>
				680
				681	The <tt>Pass::getAnalysis<></tt> method is inherited by your class,
				682	providing you with access to the passes that you declared that you required with
				683	the <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method. It takes
				684	a single template argument that specifies which pass class you want, and returns
				685	a reference to that pass.<p>
				686
				687	<pre>
				688	<b>template</b><<b>typename</b> PassClass>
				689	AnalysisType &getAnalysis();
				690	</pre><p>
				691
				692	This method call returns a reference to the pass desired. You may get a runtime
				693	assertion failure if you attempt to get an analysis that you did not declare as
				694	required in your <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a>
				695	implementation. This method can be called by your <tt>run*</tt> method
				696	implementation, or by any other local method invoked by your <tt>run*</tt>
				697	method.<p>
				698
				699
				700
				701	<!-- *********************************************************************** -->
				702	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				703	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				704	<a name="passmanager">What PassManager does
				705	</b></font></td></tr></table><ul>
				706	<!-- *********************************************************************** -->
				707
				708	The <a
				709	href="http://llvm.cs.uiuc.edu/doxygen/PassManager_8h-source.html"><tt>PassManager</tt></a>
				710	<a href="http://llvm.cs.uiuc.edu/doxygen/classPassManager.html">class</a> takes
				711	a list of passes, ensures their <a href="#interaction">prerequisites</a> are set
				712	up correctly, and then schedules passes to run efficiently. All of the LLVM
				713	tools that run passes use the <tt>PassManager</tt> for execution of these
				714	passes.<p>
				715
				716	The <tt>PassManager</tt> does two main things to try to reduce the execution
				717	time of a series of passes:<p>
				718
				719	<ol>
				720	<li><b>Share analysis results</b> - The PassManager attempts to avoid
				721	recomputing analysis results as much as possible. This means keeping track of
				722	which analyses are available already, which analyses get invalidated, and which
				723	analyses are needed to be run for a pass. An important part of work is that the
				724	<tt>PassManager</tt> tracks the exact lifetime of all analysis results, allowing
				725	it to <a href="#releaseMemory">free memory</a> allocated to holding analysis
				726	results as soon as they are no longer needed.<p>
				727
				728	<li><b>Pipeline the execution of passes on the program</b> - The
				729	<tt>PassManager</tt> attempts to get better cache and memory usage behavior out
				730	of a series of passes by pipelining the passes together. This means that, given
				731	a series of consequtive <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s, it
				732	will execute all of the <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s on
				733	the first function, then all of the <a
				734	href="#FunctionPass"><tt>FunctionPass</tt></a>'s on the second function,
				735	etc... until the entire program has been run through the passes.<p>
				736
				737	This improves the cache behavior of the compiler, because it is only touching
				738	the LLVM program representation for a single function at a time, instead of
				739	traversing the entire program. It reduces the memory consumption of compiler,
				740	because, for example, only one <a
				741	href="http://llvm.cs.uiuc.edu/doxygen/structDominatorSet.html"><tt>DominatorSet</tt></a>
				742	needs to be calculated at a time. This also makes it possible some <a
				743	href="#SMP">interesting enhancements</a> in the future.<p>
				744
				745	</ol><p>
				746
				747	The effectiveness of the <tt>PassManager</tt> is influenced directly by how much
				748	information it has about the behaviors of the passes it is scheduling. For
				749	example, the "preserved" set is intentionally conservative in the face of an
				750	unimplemented <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method.
				751	Not implementing when it should be implemented will have the effect of not
				752	allowing any analysis results to live across the execution of your pass.<p>
				753
				754	The <tt>PassManager</tt> class exposes a <tt>--debug-pass</tt> command line
				755	options that is useful for debugging pass execution, seeing how things work, and
				756	diagnosing when you should be preserving more analyses than you currently are
				757	(To get information about all of the variants of the <tt>--debug-pass</tt>
				758	option, just type '<tt>opt --help-hidden</tt>').<p>
				759
				760	By using the <tt>--debug-pass=Structure</tt> option, for example, we can see how
				761	our <a href="#basiccode">Hello World</a> pass interacts with other passes. Lets
				762	try it out with the <tt>gcse</tt> and <tt>licm</tt> passes:<p>
				763
				764	<pre>
				765	$ opt -load ../../../lib/Debug/libhello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
				766	Module Pass Manager
				767	Function Pass Manager
				768	Dominator Set Construction
				769	Immediate Dominators Construction
				770	Global Common Subexpression Elimination
				771	-- Immediate Dominators Construction
				772	-- Global Common Subexpression Elimination
				773	Natural Loop Construction
				774	Loop Invariant Code Motion
				775	-- Natural Loop Construction
				776	-- Loop Invariant Code Motion
				777	Module Verifier
				778	-- Dominator Set Construction
				779	-- Module Verifier
				780	Bytecode Writer
				781	--Bytecode Writer
				782	</pre><p>
				783
				784	This output shows us when passes are constructed and when the analysis results
				785	are known to be dead (prefixed with '<tt>--</tt>'). Here we see that GCSE uses
				786	dominator and immediate dominator information to do its job. The LICM pass uses
				787	natural loop information, which uses dominator sets, but not immediate
				788	dominators. Because immediate dominators are no longer useful after the GCSE
				789	pass, it is immediately destroyed. The dominator sets are then reused to
				790	compute natural loop information, which is then used by the LICM pass.<p>
				791
				792	After the LICM pass, the module verifier runs (which is automatically added by
				793	the '<tt>opt</tt>' tool), which uses the dominator set to check that the
				794	resultant LLVM code is well formed. After it finishes, the dominator set
				795	information is destroyed, after being computed once, and shared by three
				796	passes.<p>
				797
				798	Lets see how this changes when we run the <a href="#basiccode">Hello World</a>
				799	pass in between the two passes:<p>
				800
				801	<pre>
				802	$ opt -load ../../../lib/Debug/libhello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
				803	Module Pass Manager
				804	Function Pass Manager
				805	Dominator Set Construction
				806	Immediate Dominators Construction
				807	Global Common Subexpression Elimination
				808	<b>-- Dominator Set Construction</b>
				809	-- Immediate Dominators Construction
				810	-- Global Common Subexpression Elimination
				811	<b> Hello World Pass
				812	-- Hello World Pass
				813	Dominator Set Construction</b>
				814	Natural Loop Construction
				815	Loop Invariant Code Motion
				816	-- Natural Loop Construction
				817	-- Loop Invariant Code Motion
				818	Module Verifier
				819	-- Dominator Set Construction
				820	-- Module Verifier
				821	Bytecode Writer
				822	--Bytecode Writer
				823	Hello: __main
				824	Hello: puts
				825	Hello: main
				826	</pre><p>
				827
				828	Here we see that the <a href="#basiccode">Hello World</a> pass has killed the
				829	Dominator Set pass, even though it doesn't modify the code at all! To fix this,
				830	we need to add the following <a
				831	href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method to our pass:<p>
				832
				833	<pre>
				834	<i>// We don't modify the program, so we preserve all analyses</i>
				835	<b>virtual void</b> getAnalysisUsage(AnalysisUsage &AU) <b>const</b> {
				836	AU.setPreservesAll();
				837	}
				838	</pre><p>
				839
				840	Now when we run our pass, we get this output:<p>
				841
				842	<pre>
				843	$ opt -load ../../../lib/Debug/libhello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
				844	Pass Arguments: -gcse -hello -licm
				845	Module Pass Manager
				846	Function Pass Manager
				847	Dominator Set Construction
				848	Immediate Dominators Construction
				849	Global Common Subexpression Elimination
				850	-- Immediate Dominators Construction
				851	-- Global Common Subexpression Elimination
				852	Hello World Pass
				853	-- Hello World Pass
				854	Natural Loop Construction
				855	Loop Invariant Code Motion
				856	-- Loop Invariant Code Motion
				857	-- Natural Loop Construction
				858	Module Verifier
				859	-- Dominator Set Construction
				860	-- Module Verifier
				861	Bytecode Writer
				862	--Bytecode Writer
				863	Hello: __main
				864	Hello: puts
				865	Hello: main
				866	</pre><p>
				867
				868	Which shows that we don't accidentally invalidate dominator information
				869	anymore, and therefore do not have to compute it twice.<p>
				870
				871
				872	<!-- _______________________________________________________________________ -->
				873	</ul><h4><a name="releaseMemory"><hr size=0>The <tt>releaseMemory</tt> method</h4><ul>
				874
				875	<pre>
				876	<b>virtual void</b> releaseMemory();
				877	</pre><p>
				878
				879	The <tt>PassManager</tt> automatically determines when to compute analysis
				880	results, and how long to keep them around for. Because the lifetime of the pass
				881	object itself is effectively the entire duration of the compilation process, we
				882	need some way to free analysis results when they are no longer useful. The
				883	<tt>releaseMemory</tt> virtual method is the way to do this.<p>
				884
				885	If you are writing an analysis or any other pass that retains a significant
				886	amount of state (for use by another pass which "requires" your pass and uses the
				887	<a href="#getAnalysis">getAnalysis</a> method) you should implement
				888	<tt>releaseMEmory</tt> to, well, release the memory allocated to maintain this
				889	internal state. This method is called after the <tt>run*</tt> method for the
				890	class, before the next call of <tt>run*</tt> in your pass.<p>
				891
				892
				893	<!-- *********************************************************************** -->
				894	</ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
				895	<tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
				896	<a name="future">Future extensions planned
				897	</b></font></td></tr></table><ul>
				898	<!-- *********************************************************************** -->
				899
				900	Although the LLVM Pass Infrastructure is very capable as it stands, and does
				901	some nifty stuff, there are things we'd like to add in the future. Here is
				902	where we are going:<p>
				903
				904	<!-- _______________________________________________________________________ -->
				905	</ul><h4><a name="SMP"><hr size=0>Multithreaded LLVM</h4><ul>
				906
				907	Multiple CPU machines are becoming more command and compilation can never be
				908	fast enough: obviously we should allow for a multithreaded compiler. Because of
				909	the semantics defined for passes above (specifically they cannot maintain state
				910	across invocations of their <tt>run*</tt> methods), a nice clean way to
				911	implement a multithreaded compiler would be for the <tt>PassManager</tt> class
				912	to create multiple instances of each pass object, and allow the seperate
				913	instances to be hacking on different parts of the program at the same time.<p>
				914
				915	This implementation would prevent each of the passes from having to implement
				916	multithreaded constructs, requiring only the LLVM core to have locking in a few
				917	places (for global resources). Although this is a simple extension, we simply
				918	haven't had time (or multiprocessor machines, thus a reason) to implement this.
				919	Despite that, we have kept the LLVM passes SMP ready, and you should too.<p>
				920
				921
				922	<!-- _______________________________________________________________________ -->
				923	</ul><h4><a name="ModuleSource"><hr size=0>A new <tt>ModuleSource</tt> interface</h4><ul>
				924
				925	Currently, the <tt>PassManager</tt>'s <tt>run</tt> method takes a <tt><a
				926	href="http://llvm.cs.uiuc.edu/doxygen/classModule.html">Module</a></tt> as
				927	input, and runs all of the passes on this module. The problem with this
				928	approach is that none of the <tt>PassManager</tt> features can be used for
				929	timing and debugging the actual <b>loading</b> of the module from disk or
				930	standard input.<p>
				931
				932	To solve this problem, eventually the <tt>PassManger</tt> class will accept a
				933	<tt>ModuleSource</tt> object instead of a Module itself. When complete, this
				934	will also allow for streaming of functions out of the bytecode representation,
				935	allowing us to avoid holding the entire program in memory at once if we only are
				936	dealing with <a href="#FunctionPass">FunctionPass</a>'s.<p>
				937
				938	As part of a different issue, eventually the bytecode loader will be extended to
				939	allow on-demand loading of functions from the bytecode representation, in order
				940	to better support the runtime reoptimizer. The bytecode format is already
				941	capable of this, the loader just needs to be reworked a bit.<p>
				942
				943
				944	<!-- _______________________________________________________________________ -->
				945	</ul><h4><a name="PassFunctionPass"><hr size=0><tt>Pass</tt>'s requiring <tt>FunctionPass</tt>'s</h4><ul>
				946
				947	Currently it is illegal for a <a href="#Pass"><tt>Pass</tt></a> to require a <a
				948	href="#FunctionPass"><tt>FunctionPass</tt></a>. This is because there is only
				949	one instance of the <a href="#FunctionPass"><tt>FunctionPass</tt></a> object
				950	ever created, thus nowhere to store information for all of the functions in the
				951	program at the same time. Although this has come up a couple of times before,
				952	this has always been worked around by factoring one big complicated pass into a
				953	global and an interprocedural part, both of which are distinct. In the future,
				954	it would be nice to have this though.<p>
				955
				956	Note that it is no problem for a <a
				957	href="#FunctionPass"><tt>FunctionPass</tt></a> to require the results of a <a
				958	href="#Pass"><tt>Pass</tt></a>, only the other way around.<p>
				959
				960
				961	<!-- *********************************************************************** -->
				962	</ul>
				963	<!-- *********************************************************************** -->
				964
				965	<hr><font size-1>
				966	<address><a href="mailto:sabre@nondot.org">Christopher Lattner</a></address>
				967	<!-- Created: Tue Aug 6 15:00:33 CDT 2002 -->
				968	<!-- hhmts start -->
Chris Lattner	38c633d	2002-08-08 20:23:41 +0000	[diff] [blame^]	969	Last modified: Thu Aug 8 15:16:18 CDT 2002
Chris Lattner	c6bb824	2002-08-08 20:11:18 +0000	[diff] [blame]	970	<!-- hhmts end -->
				971	</font></body></html>