diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index fe93c4ac19f..083c9c934fa 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -24,6 +24,7 @@ in a BasicBlock
@@ -188,9 +189,9 @@ This section describes how to perform some very simple transformations of LLVM code. This is meant to give examples of common idioms used, showing the practical side of LLVM transformations.
-Because this is a "howto" section, you should also read about the main classes +Because this is a "how-to" section, you should also read about the main classes that you will be working with. The Core LLVM Class -Heirarchy Reference contains details and descriptions of the main classes +Hierarchy Reference contains details and descriptions of the main classes that you should know about.
@@ -211,23 +212,189 @@ Instruction. Common patterns for all levels. -->
+ // func is a pointer to a Function instance + 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 + + cerr << "Basic block (name=" << i->getName() << ") has " + << i->size() << " instructions.\n"; + } ++ +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 +exactly equivalent to (*i).size() just like you'd expect.
+ // blk is a pointer to a BasicBlock instance + 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 << endl; + } ++ +However, this isn't really the best way to print out the contents of a +BasicBlock! Since the ostream operators are overloaded for +virtually anything you'll care about, you could have just invoked the +print routine on the basic block itself: cerr << blk << +endl;. You might expect this to print out the pointer value of +blk, but operator<< is overloaded for BasicBlock* as well: if you +really want to print the pointer value explicitly, you'll have to +cast.
+ Instruction& inst = *i; // grab reference to instruction reference + Instruction* pinst = &*i; // grab pointer to instruction reference + const Instruction& inst = *j; ++However, the iterators you'll be working with in the LLVM framework +are special: they will automatically convert to a ptr-to-instance type +whenever they need to. Instead of dereferencing the iterator and then +taking the address of the result, you can simply assign the iterator +to the proper pointer type and you get the dereference and address-of +operation as a result of the assignment (behind the scenes, this is a +result of overloading casting mechanisms). Thus the last line of the +last example, + +
Instruction* pinst = &*i;+ +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+ +The following code snippet illustrates use of the conversion +constructors provided by LLVM iterators. By using these, you can +explicitly grab the iterator of something without actually obtaining +it via iteration over some structure: + +(&*bbi); +
+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 << endl; +} ++ +Of course, this example is strictly pedagogical, because it'd be +better to do something like + +
if(inst->getNext()) cerr << inst->getNext() << endl;+ + +
+initialize callCounter to zero +for each Function f in the Module + for each BasicBlock b in f + for each Instruction i in b + if(i is a CallInst and foo is the function it calls) + increment callCounter ++ +And the actual code is (remember, since we're writing a +FunctionPass our FunctionPass-derived class simply +has to override the runOnFunction method...): + +
+ +// Assume callCounter is a private member of the pass class being written, +// and has been initialized in the pass class constructor. + +virtual runOnFunction(Function& F) { + + // Remember, we assumed that the signature of foo was "int foo(int)"; + // the first thing we'll do is grab the pointer to that function (as a + // Function*) so we can use it later when we're examining the + // parameters of a CallInst. All of the code before the call to + // Module::getOrInsertFunction() is in preparation to do symbol-table + // to find the function pointer. + + vector+ +We could then print out the value of callCounter (if we wanted to) +inside the doFinalization method of our FunctionPass. @@ -249,7 +416,7 @@ pointerparams; + params.push_back(Type::IntTy); + const FunctionType* fooType = FunctionType::get(Type::IntTy, params); + Function* foo = F.getParent()->getOrInsertFunction("foo", fooType); + + // Start iterating and (as per the pseudocode), increment callCounter. + + for(Function::iterator b = F.begin(), be = F.end(); b != be; ++b) { + for(BasicBlock::iterator i = b->begin(); ie = b->end(); i != ie; ++i) { + if(CallInst* callInst = dyn_cast (&*inst)) { + // we know we've encountered a call instruction, so we + // need to determine if it's a call to foo or not + + if(callInst->getCalledFunction() == foo) + ++callCounter; + } + } + } +} +
-The Core LLVM Class Heirarchy Reference +The Core LLVM Class Hierarchy Reference |
Because LLVM is a typed representation, every LLVM Value is typed, and @@ -1071,6 +1238,6 @@ pointer to the parent Function. Chris Lattner -Last modified: Fri Sep 6 13:30:36 CDT 2002 +Last modified: Fri Sep 6 16:37:49 EDT 2002