diff --git a/docs/ProgrammersManual.html b/docs/ProgrammersManual.html index 8378b5c06e2..58ad5a1bce5 100644 --- a/docs/ProgrammersManual.html +++ b/docs/ProgrammersManual.html @@ -12,8 +12,24 @@
+ +
+Important and useful LLVM APIs + |
+
@@ -292,13 +302,145 @@ 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 "StatisticReporter.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' 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. + + + +
+ +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: + +
+ +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. +
|