docs/WritingAnLLVMPass.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html><head><title>Writing an LLVM Pass</title></head>
   3
   4 <!--
   5 I. General Structure of an LLVM Program
   6
   7 I.1 "What is a 'Value'?": Value & User class
   8 I.2 Type & Derived Types
   9 I.3 GlobalVariable, Function
  10 I.4 BasicBlock
  11 I.5 Instruction & Subclasses
  12 1.6 Argument
  13 1.7 Constants
  14
  15 III. Useful things to know about the LLVM source base:
  16
  17 III.1 Useful links that introduce the STL
  18 III.2 isa<>, cast<>, dyn_cast<>
  19 III.3 Makefiles, useful options
  20 III.4 How to use opt & analyze to debug stuff
  21 III.5 How to write a regression test
  22 III.6 DEBUG() and Statistics (-debug & -stats)
  23 III.7 The -time-passes option
  24 III.8 ... more as needed ...
  25
  26 I think that writing Section #1 would be very helpful and that's the most
  27 stable portion of the sourcebase.  #3 can be started on, but will probably
  28 just grow as time goes on.  I'd like to do Section #2 once I finish some
  29 changes up that effect it.
  30
  31 -->
  32
  33 <body bgcolor=white>
  34
  35 <table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
  36 <tr><td>&nbsp; <font size=+3 color="#EEEEFF" face="Georgia,Palatino,Times,Roman"><b>Writing an LLVM Pass</b></font></td>
  37 </tr></table>
  38
  39
  40 <ol>
  41   <li><a href="#introduction">Introduction - What is a pass?</a>
  42   <li><a href="#quickstart">Quick Start - Writing hello world</a>
  43     <ul>
  44     <li><a href="#makefile">Setting up the build environment</a>
  45     <li><a href="#basiccode">Basic code required</a>
  46     <li><a href="#running">Running a pass with <tt>opt</tt>
  47          or <tt>analyze</tt></a>
  48     </ul>
  49   <li><a href="#passtype">Pass classes and requirements</a>
  50      <ul>
  51      <li><a href="#Pass">The <tt>Pass</tt> class</a>
  52         <ul>
  53         <li><a href="#run">The <tt>run</tt> method</a>
  54         </ul>
  55      <li><a href="#FunctionPass">The <tt>FunctionPass</tt> class</a>
  56         <ul>
  57         <li><a href="#doInitialization">The <tt>doInitialization</tt> method</a>
  58         <li><a href="#runOnFunction">The <tt>runOnFunction</tt> method</a>
  59         <li><a href="#doFinalization">The <tt>doFinalization</tt> method</a>
  60         </ul>
  61      <li><a href="#BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
  62         <ul>
  63         <li><a href="#runOnBasicBlock">The <tt>runOnBasicBlock</tt> method</a>
  64         </ul>
  65      </ul>
  66   <li><a href="#registration">Pass Registration</a>
  67      <ul>
  68      <li><a href="#print">The <tt>print</tt> method</a>
  69      </ul>
  70   <li><a href="#interaction">Specifying interactions between passes</a>
  71      <ul>
  72      <li><a href="#getAnalysisUsage">The <tt>getAnalysisUsage</tt> method</a>
  73      <li><a href="#getAnalysis">The <tt>getAnalysis</tt> method</a>
  74      </ul>
  75   <li><a href="#passmanager">What PassManager does</a>
  76     <ul>
  77     <li><a href="#releaseMemory">The <tt>releaseMemory</tt> method</a>
  78     </ul>
  79   <li><a href="#future">Future extensions planned</a>
  80     <ul>
  81     <li><a href="#SMP">Multithreaded LLVM</a>
  82     <li><a href="#ModuleSource">A new <tt>ModuleSource</tt> interface</a>
  83     <li><a href="#PassFunctionPass"><tt>Pass</tt>'s requiring <tt>FunctionPass</tt>'s</a>
  84     </ul>
  85
  86   <p><b>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></b><p>
  87 </ol><p>
  88
  89
  90
  91 <!-- *********************************************************************** -->
  92 <table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
  93 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
  94 <a name="introduction">Introduction - What is a pass?
  95 </b></font></td></tr></table><ul>
  96 <!-- *********************************************************************** -->
  97
  98 The LLVM Pass Framework is an important part of the LLVM system, because LLVM
  99 passes are where the interesting parts of the compiler exist.  Passes perform
 100 the transformations and optimizations that make up the compiler, they build
 101 the analysis results that are used by these transformations, and they are, above
 102 all, a structuring technique for compiler code.<p>
 103
 104 All LLVM passes are subclasses of the <tt><a
 105 href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt> class, which
 106 implement functionality by overriding virtual methods inherited from
 107 <tt>Pass</tt>.  Depending on how your pass works, you may be able to inherit
 108 from the <tt><a
 109 href="http://llvm.cs.uiuc.edu/doxygen/structFunctionPass.html">FunctionPass</a></tt>
 110 or <tt><a
 111 href="http://llvm.cs.uiuc.edu/doxygen/structBasicBlockPass.html">BasicBlockPass</a></tt>,
 112 which gives the system more information about what your pass does, and how it
 113 can be combined with other passes.  One of the main features of the LLVM Pass
 114 Framework is that it schedules passes to run in an efficient way based on the
 115 constraints that your pass has.<p>
 116
 117 We start by showing you how to construct a pass, everything from setting up the
 118 code, to compiling, loading, and executing it.  After the basics are down, more
 119 advanced features are discussed.<p>
 120
 121
 122 <!-- *********************************************************************** -->
 123 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 124 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 125 <a name="quickstart">Quick Start - Writing hello world
 126 </b></font></td></tr></table><ul>
 127 <!-- *********************************************************************** -->
 128
 129 Here we describe how to write the "hello world" of passes.  The "Hello" pass is
 130 designed to simply print out the name of non-external functions that exist in
 131 the program being compiled.  It does not modify the program at all, just
 132 inspects it.  The source code and files for this pass are available in the LLVM
 133 source tree in the <tt>lib/Transforms/Hello</tt> directory.<p>
 134
 135
 136 <!-- ======================================================================= -->
 137 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 138 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 139 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 140 <a name="makefile">Setting up the build environment
 141 </b></font></td></tr></table><ul>
 142
 143 First thing you need to do is create a new directory somewhere in the LLVM
 144 source base.  For this example, we'll assume that you made
 145 "<tt>lib/Transforms/Hello</tt>".  The first thing you must do is set up a build
 146 script (Makefile) that will compile the source code for the new pass.  To do
 147 this, copy this into "<tt>Makefile</tt>":<p>
 148
 149 </ul><hr><ul><pre>
 150 # Makefile for hello pass
 151 LEVEL = ../../..                    # Path to top level of LLVM heirarchy
 152 LIBRARYNAME = hello                 # Name of the library to build
 153 SHARED_LIBRARY = 1                  # Build a dynamically loadable shared object
 154
 155 include $(LEVEL)/Makefile.common    # Include the makefile implementation stuff
 156 </pre></ul><hr><ul><p>
 157
 158 This makefile specifies that all of the <tt>.cpp</tt> files in the current
 159 directory are to be compiled and linked together into a
 160 <tt>lib/Debug/libhello.so</tt> shared object that can be dynamically loaded by
 161 the <tt>opt</tt> or <tt>analyze</tt> tools.<p>
 162
 163 Now that we have the build scripts set up, we just need to write the code for
 164 the pass itself.<p>
 165
 166
 167 <!-- ======================================================================= -->
 168 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 169 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 170 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 171 <a name="basiccode">Basic code required
 172 </b></font></td></tr></table><ul>
 173
 174 Now that we have a way to compile our new pass, we just have to write it.  Start
 175 out with:<p>
 176
 177 <pre>
 178 <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
 179 <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Function_8h-source.html">llvm/Function.h</a>"
 180 </pre>
 181
 182 Which are needed because we are writing a <tt><a
 183 href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt>, and we are
 184 operating on <tt><a
 185 href="http://llvm.cs.uiuc.edu/doxygen/classFunction.html">Function</a></tt>'s.<p>
 186
 187 Next we have:<p>
 188
 189 <pre>
 190 <b>namespace</b> {
 191 </pre><p>
 192
 193 ... which starts out an anonymous namespace.  Anonymous namespaces are to C++
 194 what the "<tt>static</tt>" keyword is to C (at global scope).  It makes the
 195 things declared inside of the anonymous namespace only visible to the current
 196 file.  If you're not familiar with them, consult a decent C++ book for more
 197 information.<p>
 198
 199 Next, we declare our pass itself:<p>
 200
 201 <pre>
 202   <b>struct</b> Hello : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
 203 </pre><p>
 204
 205 This declares a "<tt>Hello</tt>" class that is a subclass of <tt><a
 206 href="http://llvm.cs.uiuc.edu/doxygen/structFunctionPass.html">FunctionPass</a></tt>.
 207 The different builting pass subclasses are described in detail <a
 208 href="#passtype">later</a>, but for now, know that <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s
 209 operate a function at a time.<p>
 210
 211 <pre>
 212     <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
 213       std::cerr &lt;&lt; "<i>Hello: </i>" &lt;&lt; F.getName() &lt;&lt; "\n";
 214       <b>return false</b>;
 215     }
 216   };  <i>// end of struct Hello</i>
 217 </pre>
 218
 219 We declare a "<a href="#runOnFunction"><tt>runOnFunction</tt></a>" method, which
 220 overloads an abstract virtual method inherited from <a
 221 href="#FunctionPass"><tt>FunctionPass</tt></a>.  This is where we are supposed
 222 to do our thing, so we just print out our message with the name of each
 223 function.<p>
 224
 225 <pre>
 226   RegisterOpt&lt;Hello&gt; X("<i>hello</i>", "<i>Hello World Pass</i>");
 227 }  <i>// end of anonymous namespace</i>
 228 </pre><p>
 229
 230 Lastly, we register our class <tt>Hello</tt>, giving it a command line argument
 231 "<tt>hello</tt>", and a name "<tt>Hello World Pass</tt>".  There are several
 232 different ways of <a href="#registration">registering your pass</a>, depending
 233 on what it is to be used for.  For "optimizations" we use the
 234 <tt>RegisterOpt</tt> template.<p>
 235
 236 As a whole, the <tt>.cpp</tt> file looks like:<p>
 237
 238 <pre>
 239 <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Pass_8h-source.html">llvm/Pass.h</a>"
 240 <b>#include</b> "<a href="http://llvm.cs.uiuc.edu/doxygen/Function_8h-source.html">llvm/Function.h</a>"
 241
 242 <b>namespace</b> {
 243   <b>struct Hello</b> : <b>public</b> <a href="#FunctionPass">FunctionPass</a> {
 244     <b>virtual bool</b> <a href="#runOnFunction">runOnFunction</a>(Function &F) {
 245       std::cerr &lt;&lt; "<i>Hello: </i>" &lt;&lt; F.getName() &lt;&lt; "\n";
 246       <b>return false</b>;
 247     }
 248   };
 249
 250   RegisterOpt&lt;Hello&gt; X("<i>hello</i>", "<i>Hello World Pass</i>");
 251 }
 252 </pre><p>
 253
 254 Now that it's all together, compile the file with a simple "<tt>gmake</tt>"
 255 command in the local directory and you should get a new
 256 "<tt>lib/Debug/libhello.so</tt> file.  Note that everything in this file is
 257 contained in an anonymous namespace: this reflects the fact that passes are self
 258 contained units that do not need external interfaces (although they can have
 259 them) to be useful.<p>
 260
 261
 262 <!-- ======================================================================= -->
 263 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 264 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 265 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 266 <a name="running">Running a pass with <tt>opt</tt> or <tt>analyze</tt>
 267 </b></font></td></tr></table><ul>
 268
 269 Now that you have a brand new shiny <tt>.so</tt> file, we can use the
 270 <tt>opt</tt> command to run an LLVM program through your pass.  Because you
 271 registered your pass with the <tt>RegisterOpt</tt> template, you will be able to
 272 use the <tt>opt</tt> tool to access it, once loaded.<p>
 273
 274 To test it, follow the example at the end of the <a
 275 href="GettingStarted.html">Getting Started Guide</a> to compile "Hello World" to
 276 LLVM.  We can now run the bytecode file (<tt>hello.bc</tt>) for the program
 277 through our transformation like this (or course, any bytecode file will
 278 work):<p>
 279
 280 <pre>
 281 $ opt -load ../../../lib/Debug/libhello.so -hello &lt; hello.bc &gt; /dev/null
 282 Hello: __main
 283 Hello: puts
 284 Hello: main
 285 </pre><p>
 286
 287 The '<tt>-load</tt>' option specifies that '<tt>opt</tt>' should load your pass
 288 as a shared object, which makes '<tt>-hello</tt>' a valid command line argument
 289 (which is one reason you need to <a href="#registration">register your
 290 pass</a>).  Because the hello pass does not modify the program in any
 291 interesting way, we just throw away the result of <tt>opt</tt> (sending it to
 292 <tt>/dev/null</tt>).<p>
 293
 294 To see what happened to the other string you registered, try running
 295 <tt>opt</tt> with the <tt>--help</tt> option:<p>
 296
 297 <pre>
 298 $ opt -load ../../../lib/Debug/libhello.so --help
 299 OVERVIEW: llvm .bc -&gt; .bc modular optimizer
 300
 301 USAGE: opt [options] &lt;input bytecode&gt;
 302
 303 OPTIONS:
 304   Optimizations available:
 305 ...
 306     -funcresolve    - Resolve Functions
 307     -gcse           - Global Common Subexpression Elimination
 308     -globaldce      - Dead Global Elimination
 309     <b>-hello          - Hello World Pass</b>
 310     -indvars        - Cannonicalize Induction Variables
 311     -inline         - Function Integration/Inlining
 312     -instcombine    - Combine redundant instructions
 313 ...
 314 </pre><p>
 315
 316 The pass name get added as the information string for your pass, giving some
 317 documentation to users of <tt>opt</tt>.  Now that you have a working pass, you
 318 would go ahead and make it do the cool transformations you want.  Once you get
 319 it all working and tested, it may become useful to find out how fast your pass
 320 is.  The <a href="#passManager"><tt>PassManager</tt></a> provides a nice command
 321 line option (<tt>--time-passes</tt>) that allows you to get information about
 322 the execution time of your pass along with the other passes you queue up.  For
 323 example:<p>
 324
 325 <pre>
 326 $ opt -load ../../../lib/Debug/libhello.so -hello -time-passes &lt; hello.bc &gt; /dev/null
 327 Hello: __main
 328 Hello: puts
 329 Hello: main
 330 ===============================================================================
 331                       ... Pass execution timing report ...
 332 ===============================================================================
 333   Total Execution Time: 0.02 seconds (0.0479059 wall clock)
 334
 335    ---User Time---   --System Time--   --User+System--   ---Wall Time---  --- Pass Name ---
 336    0.0100 (100.0%)   0.0000 (  0.0%)   0.0100 ( 50.0%)   0.0402 ( 84.0%)  Bytecode Writer
 337    0.0000 (  0.0%)   0.0100 (100.0%)   0.0100 ( 50.0%)   0.0031 (  6.4%)  Dominator Set Construction
 338    0.0000 (  0.0%)   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0013 (  2.7%)  Module Verifier
 339  <b>  0.0000 (  0.0%)   0.0000 (  0.0%)   0.0000 (  0.0%)   0.0033 (  6.9%)  Hello World Pass</b>
 340    0.0100 (100.0%)   0.0100 (100.0%)   0.0200 (100.0%)   0.0479 (100.0%)  TOTAL
 341 </pre><p>
 342
 343 As you can see, our implementation above is pretty fast :).  The additional
 344 passes listed are automatically inserted by the '<tt>opt</tt>' tool to verify
 345 that the LLVM emitted by your pass is still valid and well formed LLVM, which
 346 hasn't been broken somehow.
 347
 348 Now that you have seen the basics of the mechanics behind passes, we can talk
 349 about some more details of how they work and how to use them.<p>
 350
 351
 352
 353 <!-- *********************************************************************** -->
 354 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 355 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 356 <a name="passtype">Pass classes and requirements
 357 </b></font></td></tr></table><ul>
 358 <!-- *********************************************************************** -->
 359
 360 One of the first things that you should do when designing a new pass is to
 361 decide what class you should subclass for your pass.  The <a
 362 href="#basiccode">Hello World</a> example uses the <tt><a
 363 href="#FunctionPass">FunctionPass</a></tt> class for its implementation, but we
 364 did not discuss why or when this should occur.  Here we talk about the classes
 365 available, from the most general to the most specific.<p>
 366
 367 When choosing a superclass for your Pass, you should choose the most specific
 368 class possible, while still being able to meet the requirements listed.  This
 369 gives the LLVM Pass Infrastructure information neccesary to optimize how passes
 370 are run, so that the resultant compiler isn't unneccesarily slow.<p>
 371
 372
 373
 374 <!-- ======================================================================= -->
 375 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 376 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 377 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 378 <a name="Pass">The <tt>Pass</tt> class
 379 </b></font></td></tr></table><ul>
 380
 381 The "<tt><a href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">Pass</a></tt>"
 382 class is the most general of all superclasses that you can use.  Deriving from
 383 <tt>Pass</tt> indicates that your pass uses the entire program as a unit,
 384 refering to function bodies in no predictable order, or adding and removing
 385 functions.  Because nothing is known about the behavior of direct <tt>Pass</tt>
 386 subclasses, no optimization can be done for their execution.<p>
 387
 388 To write a correct <tt>Pass</tt> subclass, derive from <tt>Pass</tt> and
 389 overload the <tt>run</tt> method with the following signature:<p>
 390
 391 <!-- _______________________________________________________________________ -->
 392 </ul><h4><a name="run"><hr size=0>The <tt>run</tt> method</h4><ul>
 393
 394
 395 <pre>
 396   <b>virtual bool</b> run(Module &amp;M) = 0;
 397 </pre><p>
 398
 399 The <tt>run</tt> method performs the interesting work of the pass, and should
 400 return true if the module was modified by the transformation, false
 401 otherwise.<p>
 402
 403
 404
 405 <!-- ======================================================================= -->
 406 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 407 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 408 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 409 <a name="FunctionPass">The <tt>FunctionPass</tt> class
 410 </b></font></td></tr></table><ul>
 411
 412 In contrast to direct <tt>Pass</tt> subclasses, direct <tt><a
 413 href="http://llvm.cs.uiuc.edu/doxygen/classPass.html">FunctionPass</a></tt>
 414 subclasses do have a predictable, local behavior that can be expected by the
 415 system.  All <tt>FunctionPass</tt> execute on each function in the program
 416 independant of all of the other functions in the program.
 417 <tt>FunctionPass</tt>'s do not require that they are executed in a particular
 418 order, and <tt>FunctionPass</tt>'s do not modify external functions.<p>
 419
 420 To be explicit, <tt>FunctionPass</tt> subclasses are not allowed to:<p>
 421
 422 <ol>
 423 <li>Modify a Function other than the one currently being processed.
 424 <li>Add or remove Function's from the current Module.
 425 <li>Add or remove global variables from the current Module.
 426 <li>Maintain state across invocations of
 427     <a href="#runOnFunction"><tt>runOnFunction</tt></a> (including global data)
 428 </ol><p>
 429
 430 Implementing a <tt>FunctionPass</tt> is usually straightforward (See the <a
 431 href="#basiccode">Hello World</a> pass for example).  <tt>FunctionPass</tt>'s
 432 may overload three virtual methods to do their work.  All of these methods
 433 should return true if they modified the program, or false if they didn't.<p>
 434
 435 <!-- _______________________________________________________________________ -->
 436 </ul><h4><a name="doInitialization"><hr size=0>The <tt>doInitialization</tt>
 437 method</h4><ul>
 438
 439 <pre>
 440   <b>virtual bool</b> doInitialization(Module &amp;M);
 441 </pre><p>
 442
 443 The <tt>doIninitialize</tt> method is allowed to do most of the things that
 444 <tt>FunctionPass</tt>'s are not allowed to do.  They can add and remove
 445 functions, get pointers to functions, etc.  The <tt>doInitialize</tt> method is
 446 designed to do simple initialization type of stuff that does not depend on the
 447 functions being processed.  The <tt>doInitialization</tt> function call is not
 448 scheduled to overlap with any other pass executions.<p>
 449
 450 A good example of how this method should be used is the <a
 451 href="http://llvm.cs.uiuc.edu/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations</a>
 452 pass.  This pass converts <tt>malloc</tt> and <tt>free</tt> instructions into
 453 platform dependant <tt>malloc()</tt> and <tt>free()</tt> function calls.  It
 454 uses the <tt>doInitialization</tt> method to get a reference to the malloc and
 455 free functions that it needs, adding prototypes to the module if neccesary.<p>
 456
 457 <!-- _______________________________________________________________________ -->
 458 </ul><h4><a name="runOnFunction"><hr size=0>The <tt>runOnFunction</tt> method</h4><ul>
 459
 460 <pre>
 461   <b>virtual bool</b> runOnFunction(Function &amp;F) = 0;
 462 </pre><p>
 463
 464 The <tt>runOnFunction</tt> method must be implemented by your subclass to do the
 465 transformation or analysis work of your pass.  As usual, a true value should be
 466 returned if the function is modified.<p>
 467
 468 <!-- _______________________________________________________________________ -->
 469 </ul><h4><a name="doFinalization"><hr size=0>The <tt>doFinalization</tt> method</h4><ul>
 470
 471 <pre>
 472   <b>virtual bool</b> doFinalization(Module &amp;M);
 473 </pre</p>
 474
 475 The <tt>doFinalization</tt> method is an infrequently used method that is called
 476 when the pass framework has finished calling <a
 477 href="#runOnFunction"><tt>runOnFunction</tt></a> for every function in the
 478 program being compiled.<p>
 479
 480
 481
 482 <!-- ======================================================================= -->
 483 </ul><table width="100%" bgcolor="#441188" border=0 cellpadding=4 cellspacing=0>
 484 <tr><td>&nbsp;</td><td width="100%">&nbsp;
 485 <font color="#EEEEFF" face="Georgia,Palatino"><b>
 486 <a name="BasicBlockPass">The <tt>BasicBlockPass</tt> class</a>
 487 </b></font></td></tr></table><ul>
 488
 489 <tt>BasicBlockPass</tt>'s are just like <a
 490 href="#FunctionPass"><tt>FunctionPass</tt></a>'s, except that they must limit
 491 their scope of inspection and modification to a single basic block at a time.
 492 As such, they are <b>not</b> allowed to do any of the following:<p>
 493
 494 <ol>
 495 <li>Modify or inspect any basic blocks outside of the current one
 496 <li>Maintain state across invocations of
 497     <a href="#runOnBasicBlock"><tt>runOnBasicBlock</tt></a>
 498 <li>Modify the constrol flow graph (by altering terminator instructions)
 499 <li>Any of the things verboten for
 500     <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s.
 501 </ol><p>
 502
 503 <tt>BasicBlockPass</tt>'s are useful for traditional local and "peephole"
 504 optimizations.  They may override the same <a
 505 href="#doInitialization"><tt>doInitialization</tt></a> and <a
 506 href="#doFinalization"><tt>doFinalization</tt></a> methods that <a
 507 href="#FunctionPass"><tt>FunctionPass</tt></a>'s have, but also have a
 508 <tt>runOnBasicBlock</tt> method:<p>
 509
 510 <!-- _______________________________________________________________________ -->
 511 </ul><h4><a name="runOnBasicBlock"><hr size=0>The <tt>runOnBasicBlock</tt> method</h4><ul>
 512
 513 <pre>
 514   <b>virtual bool</b> runOnBasicBlock(BasicBlock &amp;BB) = 0;
 515 </pre><p>
 516
 517 Override this function to do the work of the <tt>BasicBlockPass</tt>.  This
 518 function is not allowed to inspect or modify basic blocks other than the
 519 parameter, and are not allowed to modify the CFG.  A true value must be returned
 520 if the basic block is modified.<p>
 521
 522
 523 <!-- *********************************************************************** -->
 524 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 525 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 526 <a name="registration">Pass registration
 527 </b></font></td></tr></table><ul>
 528 <!-- *********************************************************************** -->
 529
 530 In the <a href="#basiccode">Hello World</a> example pass we illustrated how pass
 531 registration works, and discussed some of the reasons that it is used and what
 532 it does.  Here we discuss how and why passes are registered.<p>
 533
 534 Passes can be registered in several different ways.  Depending on the general
 535 classification of the pass, you should use one of the following templates to
 536 register the pass:<p>
 537
 538 <ul>
 539 <li><b><tt>RegisterOpt</tt></b> - This template should be used when you are
 540 registering a pass that logically should be available for use in the
 541 '<tt>opt</tt>' utility.<p>
 542
 543 <li><b><tt>RegisterAnalysis</tt></b> - This template should be used when you are
 544 registering a pass that logically should be available for use in the
 545 '<tt>analysis</tt>' utility.<p>
 546
 547 <li><b><tt>RegisterLLC</tt></b> - This template should be used when you are
 548 registering a pass that logically should be available for use in the
 549 '<tt>llc</tt>' utility.<p>
 550
 551 <li><b><tt>RegisterPass</tt></b> - This is the generic form of the
 552 <tt>Register*</tt> templates that should be used if you want your pass listed by
 553 multiple or no utilities.  This template takes an extra third argument that
 554 specifies which tools it should be listed in.  See the <a
 555 href="http://llvm.cs.uiuc.edu/doxygen/PassSupport_8h-source.html">PassSupport.h</a>
 556 file for more information.<p>
 557 </ul><p>
 558
 559 Regardless of how you register your pass, you must specify at least two
 560 parameters.  The first parameter is the name of the pass that is to be used on
 561 the command line to specify that the pass should be added to a program (for
 562 example <tt>opt</tt> or <tt>analyze</tt>).  The second argument is the name of
 563 the pass, which is to be used for the <tt>--help</tt> output of programs, as
 564 well as for debug output generated by the <tt>--debug-pass</tt> option.<p>
 565
 566 If you pass is constructed by its default constructor, you only ever have to
 567 pass these two arguments.  If, on the other hand, you require other information
 568 (like target specific information), you must pass an additional argument.  This
 569 argument is a pointer to a function used to create the pass.  For an example of
 570 how this works, look at the <a
 571 href="http://llvm.cs.uiuc.edu/doxygen/LowerAllocations_8cpp-source.html">LowerAllocations.cpp</a>
 572 file.<p>
 573
 574 If a pass is registered to be used by the <tt>analyze</tt> utility, you should
 575 implement the virtual <tt>print</tt> method:<p>
 576
 577 <!-- _______________________________________________________________________ -->
 578 </ul><h4><a name="print"><hr size=0>The <tt>print</tt> method</h4><ul>
 579
 580 <pre>
 581   <b>virtual void</b> print(std::ostream &amp;O, <b>const</b> Module *M) <b>const</b>;
 582 </pre><p>
 583
 584 The <tt>print</tt> method must be implemented by "analyses" in order to print a
 585 human readable version of the analysis results.  This is useful for debugging an
 586 analysis itself, as well as for other people to figure out how an analysis
 587 works.  The <tt>analyze</tt> tool uses this method to generate its output.<p>
 588
 589 The <tt>ostream</tt> parameter specifies the stream to write the results on, and
 590 the <tt>Module</tt> parameter gives a pointer to the top level module of the
 591 program that has been analyzed.  Note however that this pointer may be null in
 592 certain circumstances (such as calling the <tt>Pass::dump()</tt> from a
 593 debugger), so it should only be used to enhance debug output, it should not be
 594 depended on.<p>
 595
 596
 597 <!-- *********************************************************************** -->
 598 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 599 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 600 <a name="interaction">Specifying interactions between passes
 601 </b></font></td></tr></table><ul>
 602 <!-- *********************************************************************** -->
 603
 604 One of the main responsibilities of the <tt>PassManager</tt> is the make sure
 605 that passes interact with each other correctly.  Because <tt>PassManager</tt>
 606 tries to <a href="#passmanager">optimize the execution of passes</a> it must
 607 know how the passes interact with each other and what dependencies exist between
 608 the various passes.  To track this, each pass can declare the set of passes that
 609 are required to be executed before the current pass, and the passes which are
 610 invalidated by the current pass.<p>
 611
 612 Typically this functionality is used to require that analysis results are
 613 computed before your pass is run.  Running arbitrary transformation passes can
 614 invalidate the computed analysis results, which is what the invalidation set
 615 specifies.  If a pass does not implement the <tt><a
 616 href="#getAnalysisUsage">getAnalysisUsage</a></tt> method, it defaults to not
 617 having any prerequisite passes, and invalidating <b>all</b> other passes.<p>
 618
 619
 620 <!-- _______________________________________________________________________ -->
 621 </ul><h4><a name="getAnalysisUsage"><hr size=0>The <tt>getAnalysisUsage</tt> method</h4><ul>
 622
 623 <pre>
 624   <b>virtual void</b> getAnalysisUsage(AnalysisUsage &amp;Info) <b>const</b>;
 625 </pre><p>
 626
 627 By implementing the <tt>getAnalysisUsage</tt> method, the required and
 628 invalidated sets may be specified for your transformation.  The implementation
 629 should fill in the <tt><a
 630 href="http://llvm.cs.uiuc.edu/doxygen/classAnalysisUsage.html">AnalysisUsage</a></tt>
 631 object with information about which passes are required and not invalidated.  To do this, the following set methods are provided by the <tt><a
 632 href="http://llvm.cs.uiuc.edu/doxygen/classAnalysisUsage.html">AnalysisUsage</a></tt> class:<p>
 633
 634 <pre>
 635   <i>// addRequires - Add the specified pass to the required set for your pass.</i>
 636   <b>template</b>&lt;<b>class</b> PassClass&gt;
 637   AnalysisUsage &amp;AnalysisUsage::addRequired();
 638
 639   <i>// addPreserved - Add the specified pass to the set of analyses preserved by
 640   // this pass</i>
 641   <b>template</b>&lt;<b>class</b> PassClass&gt;
 642   AnalysisUsage &amp;AnalysisUsage::addPreserved();
 643
 644   <i>// setPreservesAll - Call this if the pass does not modify its input at all</i>
 645   <b>void</b> AnalysisUsage::setPreservesAll();
 646
 647   <i>// preservesCFG - This function should be called by the pass, iff they do not:
 648   //
 649   //  1. Add or remove basic blocks from the function
 650   //  2. Modify terminator instructions in any way.
 651   //
 652   //  This is automatically implied for <a href="#BasicBlockPass">BasicBlockPass</a>'s
 653   //</i>
 654   <b>void</b> AnalysisUsage::preservesCFG();
 655 </pre><p>
 656
 657 Some examples of how to use these methods are:<p>
 658
 659 <pre>
 660   <i>// This is an example implementation from an analysis, which does not modify
 661   // the program at all, yet has a prerequisite.</i>
 662   <b>void</b> <a href="http://llvm.cs.uiuc.edu/doxygen/structPostDominanceFrontier.html">PostDominanceFrontier</a>::getAnalysisUsage(AnalysisUsage &amp;AU) <b>const</b> {
 663     AU.setPreservesAll();
 664     AU.addRequired&lt;<a href="http://llvm.cs.uiuc.edu/doxygen/structPostDominatorTree.html">PostDominatorTree</a>&gt;();
 665   }
 666 </pre><p>
 667
 668 and:<p>
 669
 670 <pre>
 671   <i>// This example modifies the program, but does not modify the CFG</i>
 672   <b>void</b> <a href="http://llvm.cs.uiuc.edu/doxygen/structLICM.html">LICM</a>::getAnalysisUsage(AnalysisUsage &amp;AU) <b>const</b> {
 673     AU.preservesCFG();
 674     AU.addRequired&lt;<a href="http://llvm.cs.uiuc.edu/doxygen/classLoopInfo.html">LoopInfo</a>&gt;();
 675   }
 676 </pre><p>
 677
 678 <!-- _______________________________________________________________________ -->
 679 </ul><h4><a name="getAnalysis"><hr size=0>The <tt>getAnalysis&lt;&gt;</tt> method</h4><ul>
 680
 681 The <tt>Pass::getAnalysis&lt;&gt;</tt> method is inherited by your class,
 682 providing you with access to the passes that you declared that you required with
 683 the <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method.  It takes
 684 a single template argument that specifies which pass class you want, and returns
 685 a reference to that pass.<p>
 686
 687 <pre>
 688   <b>template</b>&lt;<b>typename</b> PassClass&gt;
 689   AnalysisType &amp;getAnalysis();
 690 </pre><p>
 691
 692 This method call returns a reference to the pass desired.  You may get a runtime
 693 assertion failure if you attempt to get an analysis that you did not declare as
 694 required in your <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a>
 695 implementation.  This method can be called by your <tt>run*</tt> method
 696 implementation, or by any other local method invoked by your <tt>run*</tt>
 697 method.<p>
 698
 699
 700
 701 <!-- *********************************************************************** -->
 702 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 703 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 704 <a name="passmanager">What PassManager does
 705 </b></font></td></tr></table><ul>
 706 <!-- *********************************************************************** -->
 707
 708 The <a
 709 href="http://llvm.cs.uiuc.edu/doxygen/PassManager_8h-source.html"><tt>PassManager</tt></a>
 710 <a href="http://llvm.cs.uiuc.edu/doxygen/classPassManager.html">class</a> takes
 711 a list of passes, ensures their <a href="#interaction">prerequisites</a> are set
 712 up correctly, and then schedules passes to run efficiently.  All of the LLVM
 713 tools that run passes use the <tt>PassManager</tt> for execution of these
 714 passes.<p>
 715
 716 The <tt>PassManager</tt> does two main things to try to reduce the execution
 717 time of a series of passes:<p>
 718
 719 <ol>
 720 <li><b>Share analysis results</b> - The PassManager attempts to avoid
 721 recomputing analysis results as much as possible.  This means keeping track of
 722 which analyses are available already, which analyses get invalidated, and which
 723 analyses are needed to be run for a pass.  An important part of work is that the
 724 <tt>PassManager</tt> tracks the exact lifetime of all analysis results, allowing
 725 it to <a href="#releaseMemory">free memory</a> allocated to holding analysis
 726 results as soon as they are no longer needed.<p>
 727
 728 <li><b>Pipeline the execution of passes on the program</b> - The
 729 <tt>PassManager</tt> attempts to get better cache and memory usage behavior out
 730 of a series of passes by pipelining the passes together.  This means that, given
 731 a series of consequtive <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s, it
 732 will execute all of the <a href="#FunctionPass"><tt>FunctionPass</tt></a>'s on
 733 the first function, then all of the <a
 734 href="#FunctionPass"><tt>FunctionPass</tt></a>'s on the second function,
 735 etc... until the entire program has been run through the passes.<p>
 736
 737 This improves the cache behavior of the compiler, because it is only touching
 738 the LLVM program representation for a single function at a time, instead of
 739 traversing the entire program.  It reduces the memory consumption of compiler,
 740 because, for example, only one <a
 741 href="http://llvm.cs.uiuc.edu/doxygen/structDominatorSet.html"><tt>DominatorSet</tt></a>
 742 needs to be calculated at a time.  This also makes it possible some <a
 743 href="#SMP">interesting enhancements</a> in the future.<p>
 744
 745 </ol><p>
 746
 747 The effectiveness of the <tt>PassManager</tt> is influenced directly by how much
 748 information it has about the behaviors of the passes it is scheduling.  For
 749 example, the "preserved" set is intentionally conservative in the face of an
 750 unimplemented <a href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method.
 751 Not implementing when it should be implemented will have the effect of not
 752 allowing any analysis results to live across the execution of your pass.<p>
 753
 754 The <tt>PassManager</tt> class exposes a <tt>--debug-pass</tt> command line
 755 options that is useful for debugging pass execution, seeing how things work, and
 756 diagnosing when you should be preserving more analyses than you currently are
 757 (To get information about all of the variants of the <tt>--debug-pass</tt>
 758 option, just type '<tt>opt --help-hidden</tt>').<p>
 759
 760 By using the <tt>--debug-pass=Structure</tt> option, for example, we can see how
 761 our <a href="#basiccode">Hello World</a> pass interacts with other passes.  Lets
 762 try it out with the <tt>gcse</tt> and <tt>licm</tt> passes:<p>
 763
 764 <pre>
 765 $ opt -load ../../../lib/Debug/libhello.so -gcse -licm --debug-pass=Structure &lt; hello.bc &gt; /dev/null
 766 Module Pass Manager
 767   Function Pass Manager
 768     Dominator Set Construction
 769     Immediate Dominators Construction
 770     Global Common Subexpression Elimination
 771 --  Immediate Dominators Construction
 772 --  Global Common Subexpression Elimination
 773     Natural Loop Construction
 774     Loop Invariant Code Motion
 775 --  Natural Loop Construction
 776 --  Loop Invariant Code Motion
 777     Module Verifier
 778 --  Dominator Set Construction
 779 --  Module Verifier
 780   Bytecode Writer
 781 --Bytecode Writer
 782 </pre><p>
 783
 784 This output shows us when passes are constructed and when the analysis results
 785 are known to be dead (prefixed with '<tt>--</tt>').  Here we see that GCSE uses
 786 dominator and immediate dominator information to do its job.  The LICM pass uses
 787 natural loop information, which uses dominator sets, but not immediate
 788 dominators.  Because immediate dominators are no longer useful after the GCSE
 789 pass, it is immediately destroyed.  The dominator sets are then reused to
 790 compute natural loop information, which is then used by the LICM pass.<p>
 791
 792 After the LICM pass, the module verifier runs (which is automatically added by
 793 the '<tt>opt</tt>' tool), which uses the dominator set to check that the
 794 resultant LLVM code is well formed.  After it finishes, the dominator set
 795 information is destroyed, after being computed once, and shared by three
 796 passes.<p>
 797
 798 Lets see how this changes when we run the <a href="#basiccode">Hello World</a>
 799 pass in between the two passes:<p>
 800
 801 <pre>
 802 $ opt -load ../../../lib/Debug/libhello.so -gcse -hello -licm --debug-pass=Structure &lt; hello.bc &gt; /dev/null
 803 Module Pass Manager
 804   Function Pass Manager
 805     Dominator Set Construction
 806     Immediate Dominators Construction
 807     Global Common Subexpression Elimination
 808 <b>--  Dominator Set Construction</b>
 809 --  Immediate Dominators Construction
 810 --  Global Common Subexpression Elimination
 811 <b>    Hello World Pass
 812 --  Hello World Pass
 813     Dominator Set Construction</b>
 814     Natural Loop Construction
 815     Loop Invariant Code Motion
 816 --  Natural Loop Construction
 817 --  Loop Invariant Code Motion
 818     Module Verifier
 819 --  Dominator Set Construction
 820 --  Module Verifier
 821   Bytecode Writer
 822 --Bytecode Writer
 823 Hello: __main
 824 Hello: puts
 825 Hello: main
 826 </pre><p>
 827
 828 Here we see that the <a href="#basiccode">Hello World</a> pass has killed the
 829 Dominator Set pass, even though it doesn't modify the code at all!  To fix this,
 830 we need to add the following <a
 831 href="#getAnalysisUsage"><tt>getAnalysisUsage</tt></a> method to our pass:<p>
 832
 833 <pre>
 834     <i>// We don't modify the program, so we preserve all analyses</i>
 835     <b>virtual void</b> getAnalysisUsage(AnalysisUsage &amp;AU) <b>const</b> {
 836       AU.setPreservesAll();
 837     }
 838 </pre><p>
 839
 840 Now when we run our pass, we get this output:<p>
 841
 842 <pre>
 843 $ opt -load ../../../lib/Debug/libhello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
 844 Pass Arguments:  -gcse -hello -licm
 845 Module Pass Manager
 846   Function Pass Manager
 847     Dominator Set Construction
 848     Immediate Dominators Construction
 849     Global Common Subexpression Elimination
 850 --  Immediate Dominators Construction
 851 --  Global Common Subexpression Elimination
 852     Hello World Pass
 853 --  Hello World Pass
 854     Natural Loop Construction
 855     Loop Invariant Code Motion
 856 --  Loop Invariant Code Motion
 857 --  Natural Loop Construction
 858     Module Verifier
 859 --  Dominator Set Construction
 860 --  Module Verifier
 861   Bytecode Writer
 862 --Bytecode Writer
 863 Hello: __main
 864 Hello: puts
 865 Hello: main
 866 </pre><p>
 867
 868 Which shows that we don't accidentally invalidate dominator information
 869 anymore, and therefore do not have to compute it twice.<p>
 870
 871
 872 <!-- _______________________________________________________________________ -->
 873 </ul><h4><a name="releaseMemory"><hr size=0>The <tt>releaseMemory</tt> method</h4><ul>
 874
 875 <pre>
 876   <b>virtual void</b> releaseMemory();
 877 </pre><p>
 878
 879 The <tt>PassManager</tt> automatically determines when to compute analysis
 880 results, and how long to keep them around for.  Because the lifetime of the pass
 881 object itself is effectively the entire duration of the compilation process, we
 882 need some way to free analysis results when they are no longer useful.  The
 883 <tt>releaseMemory</tt> virtual method is the way to do this.<p>
 884
 885 If you are writing an analysis or any other pass that retains a significant
 886 amount of state (for use by another pass which "requires" your pass and uses the
 887 <a href="#getAnalysis">getAnalysis</a> method) you should implement
 888 <tt>releaseMEmory</tt> to, well, release the memory allocated to maintain this
 889 internal state.  This method is called after the <tt>run*</tt> method for the
 890 class, before the next call of <tt>run*</tt> in your pass.<p>
 891
 892
 893 <!-- *********************************************************************** -->
 894 </ul><table width="100%" bgcolor="#330077" border=0 cellpadding=4 cellspacing=0>
 895 <tr><td align=center><font color="#EEEEFF" size=+2 face="Georgia,Palatino"><b>
 896 <a name="future">Future extensions planned
 897 </b></font></td></tr></table><ul>
 898 <!-- *********************************************************************** -->
 899
 900 Although the LLVM Pass Infrastructure is very capable as it stands, and does
 901 some nifty stuff, there are things we'd like to add in the future.  Here is
 902 where we are going:<p>
 903
 904 <!-- _______________________________________________________________________ -->
 905 </ul><h4><a name="SMP"><hr size=0>Multithreaded LLVM</h4><ul>
 906
 907 Multiple CPU machines are becoming more command and compilation can never be
 908 fast enough: obviously we should allow for a multithreaded compiler.  Because of
 909 the semantics defined for passes above (specifically they cannot maintain state
 910 across invocations of their <tt>run*</tt> methods), a nice clean way to
 911 implement a multithreaded compiler would be for the <tt>PassManager</tt> class
 912 to create multiple instances of each pass object, and allow the seperate
 913 instances to be hacking on different parts of the program at the same time.<p>
 914
 915 This implementation would prevent each of the passes from having to implement
 916 multithreaded constructs, requiring only the LLVM core to have locking in a few
 917 places (for global resources).  Although this is a simple extension, we simply
 918 haven't had time (or multiprocessor machines, thus a reason) to implement this.
 919 Despite that, we have kept the LLVM passes SMP ready, and you should too.<p>
 920
 921
 922 <!-- _______________________________________________________________________ -->
 923 </ul><h4><a name="ModuleSource"><hr size=0>A new <tt>ModuleSource</tt> interface</h4><ul>
 924
 925 Currently, the <tt>PassManager</tt>'s <tt>run</tt> method takes a <tt><a
 926 href="http://llvm.cs.uiuc.edu/doxygen/classModule.html">Module</a></tt> as
 927 input, and runs all of the passes on this module.  The problem with this
 928 approach is that none of the <tt>PassManager</tt> features can be used for
 929 timing and debugging the actual <b>loading</b> of the module from disk or
 930 standard input.<p>
 931
 932 To solve this problem, eventually the <tt>PassManger</tt> class will accept a
 933 <tt>ModuleSource</tt> object instead of a Module itself.  When complete, this
 934 will also allow for streaming of functions out of the bytecode representation,
 935 allowing us to avoid holding the entire program in memory at once if we only are
 936 dealing with <a href="#FunctionPass">FunctionPass</a>'s.<p>
 937
 938 As part of a different issue, eventually the bytecode loader will be extended to
 939 allow on-demand loading of functions from the bytecode representation, in order
 940 to better support the runtime reoptimizer.  The bytecode format is already
 941 capable of this, the loader just needs to be reworked a bit.<p>
 942
 943
 944 <!-- _______________________________________________________________________ -->
 945 </ul><h4><a name="PassFunctionPass"><hr size=0><tt>Pass</tt>'s requiring <tt>FunctionPass</tt>'s</h4><ul>
 946
 947 Currently it is illegal for a <a href="#Pass"><tt>Pass</tt></a> to require a <a
 948 href="#FunctionPass"><tt>FunctionPass</tt></a>.  This is because there is only
 949 one instance of the <a href="#FunctionPass"><tt>FunctionPass</tt></a> object
 950 ever created, thus nowhere to store information for all of the functions in the
 951 program at the same time.  Although this has come up a couple of times before,
 952 this has always been worked around by factoring one big complicated pass into a
 953 global and an interprocedural part, both of which are distinct.  In the future,
 954 it would be nice to have this though.<p>
 955
 956 Note that it is no problem for a <a
 957 href="#FunctionPass"><tt>FunctionPass</tt></a> to require the results of a <a
 958 href="#Pass"><tt>Pass</tt></a>, only the other way around.<p>
 959
 960
 961 <!-- *********************************************************************** -->
 962 </ul>
 963 <!-- *********************************************************************** -->
 964
 965 <hr><font size-1>
 966 <address><a href="mailto:sabre@nondot.org">Christopher Lattner</a></address>
 967 <!-- Created: Tue Aug  6 15:00:33 CDT 2002 -->
 968 <!-- hhmts start -->
 969 Last modified: Thu Aug  8 15:16:18 CDT 2002
 970 <!-- hhmts end -->
 971 </font></body></html>