From 986e0c952fa0d15a08683bd5de5d1024f5f417e7 Mon Sep 17 00:00:00 2001 From: Chris Lattner Date: Sun, 22 Sep 2002 19:38:40 +0000 Subject: [PATCH] Add information about the DEBUG() macro and the Statistic template git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@3880 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/ProgrammersManual.html | 180 ++++++++++++++++++++++++++++++++---- 1 file changed, 161 insertions(+), 19 deletions(-) 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 @@
  • General Information +
  • Important and useful LLVM APIs +
  • Helpful Hints for Common Operations -
  • Useful LLVM APIs - -
  • The Core LLVM Class Hierarchy Reference @@ -183,6 +183,16 @@ href="CodingStandards.html">LLVM Coding Standards guide which focuses on how to write maintainable code more than where to put your curly braces.

    + + +
    +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.

    + + +
       + +The DEBUG() macro & -debug option +

      + +Often when working on your pass you will put a bunch of debugging printouts and +other code into your pass. After you get it working, you want to remove +it... but you may need it again in the future (to work out new bugs that you run +across).

      + +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.

      + + + +

    +
       + +The Statistic template & -stats +option +
      + +The "StatisticReporter.h" +file provides a template named Statistic that is used as a unified way +to keeping track of what the LLVM compiler is doing and how effective various +optimizations are. It is useful to see what optimizations are contributing to +making a particular program run faster.

      + +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:

      + +

        +
      1. Define your statistic like this:

        + +

        +static Statistic<> NumXForms("mypassname\t- 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).

        + +

      2. Whenever you make a transformation, bump the counter:

        + +

        +   ++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 -
      - +