X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;f=docs%2FProgrammersManual.html;h=61fc213190b912d66393cb92a7a2815ae7accb3f;hb=367373053b4c50cf84ec54d2300ddab14c60063e;hp=28a5079385735da767b9ffd2d13f19c0774c3564;hpb=a9030cb414dfc4d2e709e4ade2c06fe80ae9ab72;p=oota-llvm.git diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 28a50793857..61fc213190b 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -12,8 +12,28 @@
Here are some useful links:
+ +
+Important and useful LLVM APIs + |
+
@@ -224,7 +244,7 @@ static bool isLoopInvariant(const Value *V, const Loop *L)
return true;
// Otherwise, it must be an instruction...
- return !L->contains(cast<Instruction>(V)->getParent());
+ return !L->contains(cast<Instruction>(V)->getParent());
Note that you should not use an isa<> test followed by a @@ -255,8 +275,8 @@ Another common example is:
// Loop over all of the phi nodes in a basic block - BasicBlock::iterator BBI = BB->begin(); - for (; PHINode *PN = dyn_cast<PHINode>(&*BBI); ++BBI) + BasicBlock::iterator BBI = BB->begin(); + for (; PHINode *PN = dyn_cast<PHINode>(BBI); ++BBI) cerr << *PN; @@ -292,13 +312,203 @@ Describing this is currently outside the scope of this document, but there are lots of examples in the LLVM source base. + +
+ +Naturally, because of this, you don't want to delete the debug printouts, but +you don't want them to always be noisy. A standard compromise is to comment +them out, allowing you to enable them if you need them in the future. + +The "Support/Debug.h" file +provides a macro named DEBUG() that is a much nicer solution to this +problem. Basically, you can put arbitrary code into the argument of the +DEBUG macro, and it is only executed if 'opt' (or any other +tool) is run with the '-debug' command line argument: + + + ... + DEBUG(std::cerr << "I am here!\n"); + ... + + +Then you can run your pass like this: + + + $ opt < a.bc > /dev/null -mypass + <no output> + $ opt < a.bc > /dev/null -mypass -debug + I am here! + $ + + +Using the DEBUG() macro instead of a home-brewed solution allows you to +now have to create "yet another" command line option for the debug output for +your pass. Note that DEBUG() macros are disabled for optimized builds, +so they do not cause a performance impact at all (for the same reason, they +should also not contain side-effects!). + +One additional nice thing about the DEBUG() macro is that you can +enable or disable it directly in gdb. Just use "set DebugFlag=0" or +"set DebugFlag=1" from the gdb if the program is running. If the +program hasn't been started yet, you can always just run it with +-debug. + + +
|
+ +The Statistic template & -stats +option + |
+ +Often you may run your pass on some big program, and you're interested to see +how many times it makes a certain transformation. Although you can do this with +hand inspection, or some ad-hoc method, this is a real pain and not very useful +for big programs. Using the Statistic template makes it very easy to +keep track of this information, and the calculated information is presented in a +uniform manner with the rest of the passes being executed.
+ +There are many examples of Statistic users, but this basics of using it +are as follows:
+ +
+ +
+static Statistic<> NumXForms("mypassname", "The # of times I did stuff"); +
+ +The Statistic template can emulate just about any data-type, but if you +do not specify a template argument, it defaults to acting like an unsigned int +counter (this is usually what you want).
+ +
+ +
+ ++NumXForms; // I did stuff +
+ +
+ +That's all you have to do. To get 'opt' to print out the statistics +gathered, use the '-stats' option:
+ +
+ $ opt -stats -mypassname < program.bc > /dev/null + ... statistic output ... +
+ +When running gccas on a C file from the SPEC benchmark suite, it gives +a report that looks like this:
+ +
+ 7646 bytecodewriter - Number of normal instructions + 725 bytecodewriter - Number of oversized instructions + 129996 bytecodewriter - Number of bytecode bytes written + 2817 raise - Number of insts DCEd or constprop'd + 3213 raise - Number of cast-of-self removed + 5046 raise - Number of expression trees converted + 75 raise - Number of other getelementptr's formed + 138 raise - Number of load/store peepholes + 42 deadtypeelim - Number of unused typenames removed from symtab + 392 funcresolve - Number of varargs functions resolved + 27 globaldce - Number of global variables removed + 2 adce - Number of basic blocks removed + 134 cee - Number of branches revectored + 49 cee - Number of setcc instruction eliminated + 532 gcse - Number of loads removed + 2919 gcse - Number of instructions removed + 86 indvars - Number of canonical indvars added + 87 indvars - Number of aux indvars removed + 25 instcombine - Number of dead inst eliminate + 434 instcombine - Number of insts combined + 248 licm - Number of load insts hoisted + 1298 licm - Number of insts hoisted to a loop pre-header + 3 licm - Number of insts hoisted to multiple loop preds (bad, no loop pre-header) + 75 mem2reg - Number of alloca's promoted + 1444 cfgsimplify - Number of blocks simplified +
+ +Obviously, with so many optimizations, having a unified framework for this stuff +is very nice. Making your pass fit well into the framework makes it more +maintainable and useful.
+
Helpful Hints for Common Operations - |
// func is a pointer to a Function instance - for(Function::iterator i = func->begin(), e = func->end(); i != e; ++i) { + for (Function::iterator i = func->begin(), e = func->end(); i != e; ++i) { // print out the name of the basic block if it has one, and then the // number of instructions that it contains @@ -363,7 +573,7 @@ contains: Note that i can be used as if it were a pointer for the purposes of invoking member functions of the Instruction class. This is because the indirection operator is overloaded for the iterator -classes. In the above code, the expression i->size() is +classes. In the above code, the expression i->size() is exactly equivalent to (*i).size() just like you'd expect. @@ -378,7 +588,7 @@ that prints out each instruction in a BasicBlock:Of course, this example is strictly pedagogical, because it'd be much @@ -496,8 +696,8 @@ more complex example// blk is a pointer to a BasicBlock instance - for(BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i) + for (BasicBlock::iterator i = blk->begin(), e = blk->end(); i != e; ++i) // the next statement works since operator<<(ostream&,...) // is overloaded for Instruction& cerr << *i << "\n"; @@ -415,7 +625,7 @@ stderr (Note: Dereferencing an InstIterator yields an #include "llvm/Support/InstIterator.h" ... // Suppose F is a ptr to a function -for(inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i) +for (inst_iterator i = inst_begin(F), e = inst_end(F); i != e; ++i) cerr << **i << "\n";@@ -462,16 +672,6 @@ is semantically equivalent toInstruction* pinst = i;-Caveat emptor: The above syntax works only when you're not -working with dyn_cast. The template definition of dyn_cast isn't implemented to handle this yet, so you'll -still need the following in order for things to work properly: - --BasicBlock::iterator bbi = ...; -BranchInst* b = dyn_cast<BranchInst>(&*bbi); -- It's also possible to turn a class pointer into the corresponding iterator. Usually, this conversion is quite inexpensive. The following code snippet illustrates use of the conversion constructors @@ -483,7 +683,7 @@ over some structure: void printNextInstruction(Instruction* inst) { BasicBlock::iterator it(inst); ++it; // after this line, it refers to the instruction after *inst. - if(it != inst->getParent()->end()) cerr << *it << "\n"; + if (it != inst->getParent()->end()) cerr << *it << "\n"; }
Function* F = ...; -for(Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) { - if(Instruction* i = dyn_cast<Instruction>(*i)) { - cerr << "F is used in instruction:\n\t"; - cerr << *i << "\n"; +for (Value::use_iterator i = F->use_begin(), e = F->use_end(); i != e; ++i) { + if (Instruction *Inst = dyn_cast<Instruction>(*i)) { + cerr << "F is used in instruction:\n"; + cerr << *Inst << "\n"; } }@@ -578,7 +778,7 @@ to iterate over all of the values that a particular instruction uses
Instruction* pi = ...; -for(User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) { +for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) { Value* v = *i; ... } @@ -661,24 +861,23 @@ that BasicBlock, and a newly-created instruction we wish to insert before *pi, we do the following:-BasicBlock* pb = ...; -Instruction* pi = ...; -Instruction* newInst = new Instruction(...); -pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb + BasicBlock *pb = ...; + Instruction *pi = ...; + Instruction *newInst = new Instruction(...); + pb->getInstList().insert(pi, newInst); // inserts newInst before pi in pb
-Instruction instances that are already in +
Instruction instances that are already in BasicBlocks are implicitly associated with an existing instruction list: the instruction list of the enclosing basic block. Thus, we could have accomplished the same thing as the above code without being given a BasicBlock by doing:
-Instruction* pi = ...; -Instruction* newInst = new Instruction(...); -pi->getParent()->getInstList().insert(pi, newInst); + Instruction *pi = ...; + Instruction *newInst = new Instruction(...); + pi->getParent()->getInstList().insert(pi, newInst);In fact, this sequence of steps occurs so frequently that the Instruction class and Instruction-derived classes @@ -695,7 +894,7 @@ Instruction* newInst = new Instruction(..., pi); which is much cleaner, especially if you're creating a lot of instructions and adding them to BasicBlocks. - + @@ -714,21 +913,64 @@ For example:
Instruction *I = .. ; - BasicBlock *BB = I->getParent(); - BB->getInstList().erase(I); + BasicBlock *BB = I->getParent(); + BB->getInstList().erase(I);
-
This method traverses the use list of a Value changing all User's of the current value to refer to "V" +href="#User">Users of the current value to refer to "V" instead. For example, if you detect that an instruction always produces a constant value (for example through constant folding), you can replace all uses of the instruction with the constant like this:
@@ -938,9 +1180,9 @@ the Instruction class
-
+
-Returns true if the instruction has side effects, i.e. it is a call, +Returns true if the instruction writes to memory, i.e. it is a call, free, invoke, or store.
@@ -988,7 +1230,7 @@ into a BasicBlock), and it has no name.
\end{itemize}
Returns the list of BasicBlocks. This is -neccesary to use when you need to update the list or perform a complex action +necessary to use when you need to update the list or perform a complex action that doesn't have a forwarding method.
@@ -1225,12 +1467,12 @@ These are forwarding methods that make it easy to access the contents of a
Returns the list of Arguments. This is -neccesary to use when you need to update the list or perform a complex action +necessary to use when you need to update the list or perform a complex action that doesn't have a forwarding method.
-
+
Returns the entry BasicBlock for the function. Because the entry block for the function is always the first block, @@ -1243,26 +1485,10 @@ This traverses the Type of the Function and returns the return type of the function, or the FunctionType of the actual function.
- -
- -Return true if the Function has a symbol table allocated to it and if -there is at least one entry in it.
-
Return a pointer to the SymbolTable for this -Function or a null pointer if one has not been allocated (because there -are no named values in the function).
- -
- -Return a pointer to the SymbolTable for this -Function or allocate a new SymbolTable if one is not already around. This -should only be used when adding elements to the SymbolTable, so that empty symbol tables are -not left laying around.
+Function.
@@ -1357,7 +1583,7 @@ list.
Returns the list of Functions. This is -neccesary to use when you need to update the list or perform a complex action +necessary to use when you need to update the list or perform a complex action that doesn't have a forwarding method.
@@ -1375,32 +1601,17 @@ list.
Returns the list of GlobalVariables. -This is neccesary to use when you need to update the list or perform a complex +This is necessary to use when you need to update the list or perform a complex action that doesn't have a forwarding method.
- -Return true if the Module has a symbol table allocated to it and if -there is at least one entry in it.
-
-Return a pointer to the SymbolTable for this -Module or a null pointer if one has not been allocated (because there -are no named values in the function).
- -
- -Return a pointer to the SymbolTable for this -Module or allocate a new SymbolTable if one is not already around. This -should only be used when adding elements to the SymbolTable, so that empty symbol tables are -not left laying around.
+Return a reference to the SymbolTable for +this Module.
@@ -1456,39 +1667,39 @@ ConstantArray etc for representing the various types of Constants.
- -\subsection{Important Subclasses of Constant} -\begin{itemize} +
+
-\subsection{Derived Types} -\begin{itemize} +