Here are some useful links:
+ +
| +Important and useful LLVM APIs + |
+
|
@@ -221,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 @@ -252,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; @@ -269,7 +292,7 @@ dispatch over the instruction type directly.
@@ -277,7 +300,7 @@ to combine several null checks into one.
@@ -286,16 +309,206 @@ These five templates can be used with any classes, whether they have a v-table or not. To add support for these templates, you simply need to add classof static methods to the class you are interested casting to. Describing this is currently outside the scope of this document, but there are -lots of examples in the LLVM sourcebase. +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 cannonical 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
@@ -360,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.
@@ -375,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";
@@ -412,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";
@@ -459,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
@@ -480,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
@@ -493,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 *Inst = dyn_cast<Instruction>(*i)) {
+ cerr << "F is used in instruction:\n";
+ cerr << *Inst << "\n";
+ }
+}
+
+
+Alternately, it's common to have an instance of the User Class and need to know what
+Values are used by it. The list of all Values used
+by a User is known as a use-def chain. Instances of
+class Instruction are common Users, so we might want
+to iterate over all of the values that a particular instruction uses
+(that is, the operands of the particular Instruction):
+
+
+Instruction* pi = ...;
+
+for (User::op_iterator i = pi->op_begin(), e = pi->op_end(); i != e; ++i) {
+ Value* v = *i;
+ ...
+}
+
+
+
+
+Creation of Instructions is straightforward: simply call the +constructor for the kind of instruction to instantiate and provide the +necessary parameters. For example, an AllocaInst only +requires a (const-ptr-to) Type. Thus: + +
AllocaInst* ai = new AllocaInst(Type::IntTy);+ +will create an AllocaInst instance that represents the +allocation of one integer in the current stack frame, at runtime. +Each Instruction subclass is likely to have varying default +parameters which change the semantics of the instruction, so refer to +the doxygen documentation for +the subclass of Instruction that you're interested in +instantiating. + +
Naming values
+ ++It is very useful to name the values of instructions when you're able +to, as this facilitates the debugging of your transformations. If you +end up looking at generated LLVM machine code, you definitely want to +have logical names associated with the results of instructions! By +supplying a value for the Name (default) parameter of the +Instruction constructor, you associate a logical name with +the result of the instruction's execution at runtime. For example, +say that I'm writing a transformation that dynamically allocates space +for an integer on the stack, and that integer is going to be used as +some kind of index by some other code. To accomplish this, I place an +AllocaInst at the first point in the first +BasicBlock of some Function, and I'm intending to +use it within the same Function. I might do: + +
AllocaInst* pa = new AllocaInst(Type::IntTy, 0, "indexLoc");+ +where indexLoc is now the logical name of the instruction's +execution value, which is a pointer to an integer on the runtime +stack. + + +
Inserting instructions
+ ++There are essentially two ways to insert an Instruction into +an existing sequence of instructions that form a BasicBlock: +
Given a BasicBlock* pb, an Instruction* pi within +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 ++ + +
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); ++In fact, this sequence of steps occurs so frequently that the +Instruction class and Instruction-derived classes +provide constructors which take (as a default parameter) a pointer to +an Instruction which the newly-created Instruction +should precede. That is, Instruction constructors are +capable of inserting the newly-created instance into the +BasicBlock of a provided instruction, immediately before that +instruction. Using an Instruction constructor with a +insertBefore (default) parameter, the above code becomes: +
+Instruction* pi = ...; +Instruction* newInst = new Instruction(..., pi); ++which is much cleaner, especially if you're creating a lot of +instructions and adding them to BasicBlocks. + + +
+ +For example:
+ +
+ Instruction *I = .. ; + BasicBlock *BB = I->getParent(); + BB->getInstList().erase(I); +
+ +
Replacing individual instructions
++Including "llvm/Transforms/Utils/BasicBlockUtils.h" permits use of two very useful replace functions: +ReplaceInstWithValue and ReplaceInstWithInst. + +
This function replaces all uses (within a basic block) of a given +instruction with a value, and then removes the original instruction. +The following example illustrates the replacement of the result of a +particular AllocaInst that allocates memory for a single +integer with an null pointer to an integer.
+ ++AllocaInst* instToReplace = ...; +BasicBlock::iterator ii(instToReplace); +ReplaceInstWithValue(instToReplace->getParent()->getInstList(), ii, + Constant::getNullValue(PointerType::get(Type::IntTy))); ++ +
This function replaces a particular instruction with another +instruction. The following example illustrates the replacement of one +AllocaInst with another.
+ +
+AllocaInst* instToReplace = ...; +BasicBlock::iterator ii(instToReplace); +ReplaceInstWithInst(instToReplace->getParent()->getInstList(), ii, + new AllocaInst(Type::IntTy, 0, "ptrToReplacedInt")); ++ +
Replacing multiple uses of Users and + Values
+ +You can use Value::replaceAllUsesWith and +User::replaceUsesOfWith to change more than one use at a +time. See the doxygen documentation for the Value Class and User Class, respectively, for more +information. + +