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:
// 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 to
Instruction* 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";
}
Of course, this example is strictly pedagogical, because it'd be much
@@ -496,8 +696,8 @@ more complex example
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} +