X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FWritingAnLLVMPass.html;h=dc70d036c8aeb98edb2fb2cc32673918b458a2e4;hb=fc592231941dadb60cc419613adbd41a0b48b321;hp=d1cf63cae8f5baae4f9429ff59286b81c8c343da;hpb=480e2efb2e3638cd202551ed53fb456d6179d5e0;p=oota-llvm.git
diff --git a/docs/WritingAnLLVMPass.html b/docs/WritingAnLLVMPass.html
index d1cf63cae8f..dc70d036c8a 100644
--- a/docs/WritingAnLLVMPass.html
+++ b/docs/WritingAnLLVMPass.html
@@ -19,19 +19,32 @@
Pass Registration
@@ -125,9 +138,7 @@ First thing you need to do is create a new directory somewhere in the LLVM
source base. For this example, we'll assume that you made
"lib/Transforms/Hello". The first thing you must do is set up a build
script (Makefile) that will compile the source code for the new pass. To do
-this, copy this into "Makefile" (be very careful that there are no
-extra space characters at the end of the lines though... that seems to confuse
-gmake):
+this, copy this into "Makefile":
# Makefile for hello pass
@@ -194,7 +205,7 @@ Next, we declare our pass itself:
This declares a "Hello" class that is a subclass of FunctionPass.
-The different builting pass subclasses are described in detail later, but for now, know that FunctionPass's
operate a function at a time.
@@ -297,7 +308,7 @@ OPTIONS:
-gcse - Global Common Subexpression Elimination
-globaldce - Dead Global Elimination
-hello - Hello World Pass
- -indvars - Cannonicalize Induction Variables
+ -indvars - Canonicalize Induction Variables
-inline - Function Integration/Inlining
-instcombine - Combine redundant instructions
...
@@ -356,11 +367,32 @@ available, from the most general to the most specific.
When choosing a superclass for your Pass, you should choose the most
specific class possible, while still being able to meet the requirements
-listed. This gives the LLVM Pass Infrastructure information neccesary to
+listed. This gives the LLVM Pass Infrastructure information necessary to
optimize how passes are run, so that the resultant compiler isn't unneccesarily
slow.
+
+
+
+The most plain and boring type of pass is the "ImmutablePass"
+class. This pass type is used for passes that do not have to be run, do not
+change state, and never need to be updated. This is not a normal type of
+transformation or analysis, but can provide information about the current
+compiler configuration.
+
+Although this pass class is very infrequently used, it is important for
+providing information about the current target machine being compiled for, and
+other static information that can affect the various transformations.
+
+ImmutablePass's never invalidate other transformations, are never
+invalidated, and are never "run".
+
@@ -404,7 +436,7 @@ In contrast to direct Pass subclasses, direct FunctionPass
subclasses do have a predictable, local behavior that can be expected by the
system. All FunctionPass execute on each function in the program
-independant of all of the other functions in the program.
+independent of all of the other functions in the program.
FunctionPass's do not require that they are executed in a particular
order, and FunctionPass's do not modify external functions.
@@ -424,8 +456,8 @@ may overload three virtual methods to do their work. All of these methods
should return true if they modified the program, or false if they didn't.
-
virtual bool doInitialization(Module &M);
@@ -433,17 +465,18 @@ method
The doIninitialize method is allowed to do most of the things that
FunctionPass's are not allowed to do. They can add and remove
-functions, get pointers to functions, etc. The doInitialize method is
-designed to do simple initialization type of stuff that does not depend on the
-functions being processed. The doInitialization function call is not
-scheduled to overlap with any other pass executions.
+functions, get pointers to functions, etc. The doInitialization method
+is designed to do simple initialization type of stuff that does not depend on
+the functions being processed. The doInitialization method call is not
+scheduled to overlap with any other pass executions (thus it should be very
+fast).
A good example of how this method should be used is the LowerAllocations
pass. This pass converts malloc and free instructions into
-platform dependant malloc() and free() function calls. It
+platform dependent malloc() and free() function calls. It
uses the doInitialization method to get a reference to the malloc and
-free functions that it needs, adding prototypes to the module if neccesary.
+free functions that it needs, adding prototypes to the module if necessary.
@@ -457,11 +490,11 @@ transformation or analysis work of your pass. As usual, a true value should be
returned if the function is modified.
-
virtual bool doFinalization(Module &M);
-
+
The doFinalization method is an infrequently used method that is called
when the pass framework has finished calling not allowed to do any of the following:
BasicBlockPass's are useful for traditional local and "peephole"
optimizations. They may override the same doInitialization and doFinalization methods that FunctionPass's have, but also have a
-runOnBasicBlock method:
+href="#doInitialization_mod">doInitialization(Module &)
and doFinalization(Module &) methods that FunctionPass's have, but also have the following virtual methods that may also be implemented:
+
+
+
+ virtual bool doInitialization(Function &F);
+
+
+The doIninitialize method is allowed to do most of the things that
+BasicBlockPass's are not allowed to do, but that
+FunctionPass's can. The doInitialization method is designed
+to do simple initialization type of stuff that does not depend on the
+BasicBlocks being processed. The doInitialization method call is not
+scheduled to overlap with any other pass executions (thus it should be very
+fast).
+
@@ -511,6 +560,69 @@ parameter, and are not allowed to modify the CFG. A true value must be returned
if the basic block is modified.
+
+
+ virtual bool doFinalization(Function &F);
+
+
+The doFinalization method is an infrequently used method that is called
+when the pass framework has finished calling runOnBasicBlock for every BasicBlock in the
+program being compiled. This can be used to perform per-function
+finalization.
+
+
+
+
+
+A MachineFunctionPass executes on the machine-dependent
+representation of each LLVM function in the program,
+independent of all of the other functions in the program.
+A MachineFunctionPass is also a FunctionPass, so all
+the restrictions that apply to a FunctionPass also apply to it.
+MachineFunctionPasses also have additional restrictions. In
+particular, MachineFunctionPasses are not allowed to do any of
+the following:
+
+
+- Modify any LLVM Instructions, BasicBlocks or Functions.
+
- Modify a MachineFunction other than the one currently being processed.
+
- Add or remove MachineFunctions from the current Module.
+
- Add or remove global variables from the current Module.
+
- Maintain state across invocations of
+ runOnMachineFunction (including global data)
+
+
+
+
+
+ virtual bool runOnMachineFunction(MachineFunction &MF) = 0;
+
+
+runOnMachineFunction can be considered the main entry point
+of a MachineFunctionPass; that is, you should override this
+method to do the work of your MachineFunctionPass.
+
+The runOnMachineFunction method is called on every
+MachineFunction in a Module, so that the
+MachineFunctionPass may perform optimizations on the
+machine-dependent representation of the function. If you want to get
+at the LLVM Function for the MachineFunction you're
+working on, use MachineFunction's getFunction()
+accessor method -- but remember, you may not modify the LLVM
+Function or its contents from a
+MachineFunctionPass.
+
@@ -635,14 +747,14 @@ href="http://llvm.cs.uiuc.edu/doxygen/classAnalysisUsage.html">AnalysisUsage
// setPreservesAll - Call this if the pass does not modify its input at all
void AnalysisUsage::setPreservesAll();
- // preservesCFG - This function should be called by the pass, iff they do not:
+ // setPreservesCFG - This function should be called by the pass, iff they do not:
//
// 1. Add or remove basic blocks from the function
// 2. Modify terminator instructions in any way.
//
// This is automatically implied for BasicBlockPass's
//
- void AnalysisUsage::preservesCFG();
+ void AnalysisUsage::setPreservesCFG();
Some examples of how to use these methods are:
@@ -661,7 +773,7 @@ and:
// This example modifies the program, but does not modify the CFG
void LICM::getAnalysisUsage(AnalysisUsage &AU) const {
- AU.preservesCFG();
+ AU.setPreservesCFG();
AU.addRequired<LoopInfo>();
}
@@ -1047,9 +1159,8 @@ want:
(gdb) break PassManager::run
Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.
-(gdb) run test.bc -load /shared/lattner/cvs/llvm/lib/Debug/[libname].so -[passoption]
-Starting program: /shared/lattner/cvs/llvm/tools/Debug/opt test.bc
- -load /shared/lattner/cvs/llvm/lib/Debug/[libname].so -[passoption]
+(gdb) run test.bc -load $(LLVMTOP)/llvm/lib/Debug/[libname].so -[passoption]
+Starting program: opt test.bc -load $(LLVMTOP)/llvm/lib/Debug/[libname].so -[passoption]
Breakpoint 1, PassManager::run (this=0xffbef174, M=@0x70b298) at Pass.cpp:70
70 bool PassManager::run(Module &M) { return PM->run(M); }
(gdb)
@@ -1102,12 +1213,12 @@ where we are going:
-Multiple CPU machines are becoming more command and compilation can never be
+Multiple CPU machines are becoming more common and compilation can never be
fast enough: obviously we should allow for a multithreaded compiler. Because of
the semantics defined for passes above (specifically they cannot maintain state
across invocations of their run* methods), a nice clean way to
implement a multithreaded compiler would be for the PassManager class
-to create multiple instances of each pass object, and allow the seperate
+to create multiple instances of each pass object, and allow the separate
instances to be hacking on different parts of the program at the same time.
This implementation would prevent each of the passes from having to implement
@@ -1162,8 +1273,10 @@ href="#Pass">Pass, only the other way around.
Chris Lattner
+The LLVM Compiler Infrastructure
+
-Last modified: Thu Sep 5 15:06:01 CDT 2002
+Last modified: Mon Oct 27 12:00:00 CDT 2003
|