Lines Matching full:pass
2 Writing an LLVM Pass
8 Introduction --- What is a pass?
11 The LLVM Pass Framework is an important part of the LLVM system, because LLVM
17 All LLVM passes are subclasses of the `Pass
19 functionality by overriding virtual methods inherited from ``Pass``. Depending
20 on how your pass works, you should inherit from the :ref:`ModulePass
21 <writing-an-llvm-pass-ModulePass>` , :ref:`CallGraphSCCPass
22 <writing-an-llvm-pass-CallGraphSCCPass>`, :ref:`FunctionPass
23 <writing-an-llvm-pass-FunctionPass>` , or :ref:`LoopPass
24 <writing-an-llvm-pass-LoopPass>`, or :ref:`RegionPass
25 <writing-an-llvm-pass-RegionPass>`, or :ref:`BasicBlockPass
26 <writing-an-llvm-pass-BasicBlockPass>` classes, which gives the system more
27 information about what your pass does, and how it can be combined with other
28 passes. One of the main features of the LLVM Pass Framework is that it
30 pass meets (which are indicated by which class they derive from).
32 We start by showing you how to construct a pass, everything from setting up the
39 Here we describe how to write the "hello world" of passes. The "Hello" pass is
42 inspects it. The source code and files for this pass are available in the LLVM
45 .. _writing-an-llvm-pass-makefile:
53 (``Makefile``) that will compile the source code for the new pass. To do this,
58 # Makefile for hello pass
80 If you are used CMake to build LLVM, see :ref:`cmake-out-of-source-pass`.
83 the pass itself.
85 .. _writing-an-llvm-pass-basiccode:
90 Now that we have a way to compile our new pass, we just have to write it.
95 #include "llvm/Pass.h"
99 Which are needed because we are writing a `Pass
125 Next, we declare our pass itself:
132 <writing-an-llvm-pass-FunctionPass>`. The different builtin pass subclasses
133 are described in detail :ref:`later <writing-an-llvm-pass-pass-classes>`, but
141 This declares pass identifier used by LLVM to identify pass. This allows LLVM
154 We declare a :ref:`runOnFunction <writing-an-llvm-pass-runOnFunction>` method,
156 <writing-an-llvm-pass-FunctionPass>`. This is where we are supposed to do our
163 We initialize pass ID here. LLVM uses ID's address to identify a pass, so
168 static RegisterPass<Hello> X("hello", "Hello World Pass",
170 false /* Analysis Pass */);
172 Lastly, we :ref:`register our class <writing-an-llvm-pass-registration>`
174 World Pass". The last two arguments describe its behavior: if a pass walks CFG
175 without modifying it then the third argument is set to ``true``; if a pass is
176 an analysis pass, for example dominator tree pass, then ``true`` is supplied as
183 #include "llvm/Pass.h"
203 static RegisterPass<Hello> X("hello", "Hello World Pass", false, false);
212 Running a pass with ``opt``
216 :program:`opt` command to run an LLVM program through your pass. Because you
217 registered your pass with ``RegisterPass``, you will be able to use the
232 The :option:`-load` option specifies that :program:`opt` should load your pass
234 (which is one reason you need to :ref:`register your pass
235 <writing-an-llvm-pass-registration>`). Because the Hello pass does not modify
255 -hello - Hello World Pass
260 The pass name gets added as the information string for your pass, giving some
261 documentation to users of :program:`opt`. Now that you have a working pass,
264 pass is. The :ref:`PassManager <writing-an-llvm-pass-passmanager>` provides a
266 information about the execution time of your pass along with the other passes
276 ... Pass execution timing report ...
280 ---User Time--- --System Time-- --User+System-- ---Wall Time--- --- Pass Name ---
284 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0000 ( 0.0%) 0.0033 ( 6.9%) Hello World Pass
289 that the LLVM emitted by your pass is still valid and well formed LLVM, which
295 .. _writing-an-llvm-pass-pass-classes:
297 Pass classes and requirements
300 One of the first things that you should do when designing a new pass is to
301 decide what class you should subclass for your pass. The :ref:`Hello World
302 <writing-an-llvm-pass-basiccode>` example uses the :ref:`FunctionPass
303 <writing-an-llvm-pass-FunctionPass>` class for its implementation, but we did
307 When choosing a superclass for your ``Pass``, you should choose the **most
309 listed. This gives the LLVM Pass Infrastructure information necessary to
316 The most plain and boring type of pass is the "`ImmutablePass
317 <http://llvm.org/doxygen/classllvm_1_1ImmutablePass.html>`_" class. This pass
322 Although this pass class is very infrequently used, it is important for
329 .. _writing-an-llvm-pass-ModulePass:
336 ``ModulePass`` indicates that your pass uses the entire program as a unit,
341 A module pass can use function level passes (e.g. dominators) using the
343 provide the function to retrieve analysis result for, if the function pass does
359 The ``runOnModule`` method performs the interesting work of the pass. It
363 .. _writing-an-llvm-pass-CallGraphSCCPass:
373 optimize execution of ``CallGraphSCCPass``\ es. If your pass meets the
375 :ref:`FunctionPass <writing-an-llvm-pass-FunctionPass>` or :ref:`BasicBlockPass
376 <writing-an-llvm-pass-BasicBlockPass>`, you should derive from
391 <writing-an-llvm-pass-runOnSCC>` (including global data).
410 overlap with any other pass executions (thus it should be very fast).
412 .. _writing-an-llvm-pass-runOnSCC:
421 The ``runOnSCC`` method performs the interesting work of the pass, and should
433 when the pass framework has finished calling :ref:`runOnSCC
434 <writing-an-llvm-pass-runOnSCC>` for every SCC in the program being compiled.
436 .. _writing-an-llvm-pass-FunctionPass:
455 <writing-an-llvm-pass-runOnFunction>` (including global data).
458 World <writing-an-llvm-pass-basiccode>` pass for example).
463 .. _writing-an-llvm-pass-doInitialization-mod:
477 overlap with any other pass executions (thus it should be very fast).
480 <http://llvm.org/doxygen/LowerAllocations_8cpp-source.html>`_ pass. This pass
486 .. _writing-an-llvm-pass-runOnFunction:
496 transformation or analysis work of your pass. As usual, a ``true`` value
499 .. _writing-an-llvm-pass-doFinalization-mod:
509 when the pass framework has finished calling :ref:`runOnFunction
510 <writing-an-llvm-pass-runOnFunction>` for every function in the program being
513 .. _writing-an-llvm-pass-LoopPass:
523 interface. Implementing a loop pass is usually straightforward.
538 pass executions (thus it should be very fast). ``LPPassManager`` interface
541 .. _writing-an-llvm-pass-runOnLoop:
551 transformation or analysis work of your pass. As usual, a ``true`` value
563 when the pass framework has finished calling :ref:`runOnLoop
564 <writing-an-llvm-pass-runOnLoop>` for every loop in the program being compiled.
566 .. _writing-an-llvm-pass-RegionPass:
571 ``RegionPass`` is similar to :ref:`LoopPass <writing-an-llvm-pass-LoopPass>`,
578 ``RegionPass`` to implement your own region pass. All these methods should
591 pass executions (thus it should be very fast). ``RPPassManager`` interface
594 .. _writing-an-llvm-pass-runOnRegion:
604 transformation or analysis work of your pass. As usual, a true value should be
616 when the pass framework has finished calling :ref:`runOnRegion
617 <writing-an-llvm-pass-runOnRegion>` for every region in the program being
620 .. _writing-an-llvm-pass-BasicBlockPass:
626 <writing-an-llvm-pass-FunctionPass>` , except that they must limit their scope
632 <writing-an-llvm-pass-runOnBasicBlock>`.
635 <writing-an-llvm-pass-FunctionPass>`.
639 <writing-an-llvm-pass-doInitialization-mod>` and :ref:`doFinalization(Module &)
640 <writing-an-llvm-pass-doFinalization-mod>` methods that :ref:`FunctionPass's
641 <writing-an-llvm-pass-FunctionPass>` have, but also have the following virtual
656 pass executions (thus it should be very fast).
658 .. _writing-an-llvm-pass-runOnBasicBlock:
680 when the pass framework has finished calling :ref:`runOnBasicBlock
681 <writing-an-llvm-pass-runOnBasicBlock>` for every ``BasicBlock`` in the program
704 <writing-an-llvm-pass-runOnMachineFunction>` (including global data).
706 .. _writing-an-llvm-pass-runOnMachineFunction:
727 .. _writing-an-llvm-pass-registration:
729 Pass registration
732 In the :ref:`Hello World <writing-an-llvm-pass-basiccode>` example pass we
733 illustrated how pass registration works, and discussed some of the reasons that
738 template parameter is the name of the pass that is to be used on the command
739 line to specify that the pass should be added to a program (for example, with
741 pass, which is to be used for the :option:`-help` output of programs, as well
742 as for debug output generated by the :option:`--debug-pass` option.
744 If you want your pass to be easily dumpable, you should implement the virtual
762 in certain circumstances (such as calling the ``Pass::dump()`` from a
766 .. _writing-an-llvm-pass-interaction:
773 :ref:`optimize the execution of passes <writing-an-llvm-pass-passmanager>` it
775 between the various passes. To track this, each pass can declare the set of
776 passes that are required to be executed before the current pass, and the passes
777 which are invalidated by the current pass.
780 computed before your pass is run. Running arbitrary transformation passes can
782 specifies. If a pass does not implement the :ref:`getAnalysisUsage
783 <writing-an-llvm-pass-getAnalysisUsage>` method, it defaults to not having any
786 .. _writing-an-llvm-pass-getAnalysisUsage:
800 pass may call any of the following methods on the ``AnalysisUsage`` object:
805 If your pass requires a previous pass to be executed (an analysis for example),
806 pass.
810 edges in the CFG when your pass has been run.
817 transitively required pass should be alive as long as the requiring pass is.
826 simple constant folding pass would not modify the CFG, so it can't possibly
832 ``setPreservesAll`` method can be called to indicate that the pass does not
837 :ref:`BasicBlockPass <writing-an-llvm-pass-BasicBlockPass>`\ es).
840 ``BreakCriticalEdges``. This pass knows how to update a small set of loop and
855 .. _writing-an-llvm-pass-getAnalysis:
860 The ``Pass::getAnalysis<>`` method is automatically inherited by your class,
862 with the :ref:`getAnalysisUsage <writing-an-llvm-pass-getAnalysisUsage>`
863 method. It takes a single template argument that specifies which pass class
864 you want, and returns a reference to that pass. For example:
873 This method call returns a reference to the pass desired. You may get a
876 <writing-an-llvm-pass-getAnalysisUsage>` implementation. This method can be
880 A module level pass can use function level analysis info using this interface.
891 In above example, ``runOnFunction`` for ``DominatorTree`` is called by pass
892 manager before returning a reference to the desired pass.
894 If your pass is capable of updating analyses if they exist (e.g.,
910 fancier. All of the pass relationships that we have seen so far are very
911 simple: one pass depends on one other specific pass to be run before it can
922 situations like this, the LLVM Pass Infrastructure supports the notion of
930 just like passes, but unlike passes, they need not derive from the ``Pass``
935 ``AnalysisUsage::addRequired()`` and ``Pass::getAnalysis()`` methods. In order
937 <writing-an-llvm-pass-passmanager>` scans the available passes to see if any
939 default implementation is created for the pass to use. All standard rules for
940 :ref:`interaction between passes <writing-an-llvm-pass-interaction>` still
943 Although :ref:`Pass Registration <writing-an-llvm-pass-registration>` is
946 <writing-an-llvm-pass-RegisterAnalysisGroup>` template to join the
949 <writing-an-llvm-pass-RegisterAnalysisGroup>`.
954 (the `basicaa <http://llvm.org/doxygen/structBasicAliasAnalysis.html>`_ pass)
959 example the `gcse <http://llvm.org/doxygen/structGCSE.html>`_ pass), do not
965 and added to the pass sequence. Issuing the command ``opt -somefancyaa -gcse
966 ...`` will cause the ``gcse`` pass to use the ``somefancyaa`` alias analysis
969 .. _writing-an-llvm-pass-RegisterAnalysisGroup:
975 itself, while the ``INITIALIZE_AG_PASS`` is used to add pass implementations to
1020 <http://llvm.org/doxygen/structBasicAliasAnalysis.html>`_ pass is the default
1023 Pass Statistics
1032 .. _writing-an-llvm-pass-passmanager:
1039 passes, ensures their :ref:`prerequisites <writing-an-llvm-pass-interaction>`
1049 which analyses are needed to be run for a pass. An important part of work
1052 <writing-an-llvm-pass-releaseMemory>` allocated to holding analysis results
1058 of consecutive :ref:`FunctionPass <writing-an-llvm-pass-FunctionPass>`, it
1060 <writing-an-llvm-pass-FunctionPass>` on the first function, then all of the
1061 :ref:`FunctionPasses <writing-an-llvm-pass-FunctionPass>` on the second
1070 :ref:`interesting enhancements <writing-an-llvm-pass-SMP>` in the future.
1075 unimplemented :ref:`getAnalysisUsage <writing-an-llvm-pass-getAnalysisUsage>`
1077 not allowing any analysis results to live across the execution of your pass.
1079 The ``PassManager`` class exposes a ``--debug-pass`` command line options that
1080 is useful for debugging pass execution, seeing how things work, and diagnosing
1082 information about all of the variants of the ``--debug-pass`` option, just type
1085 By using the --debug-pass=Structure option, for example, we can see how our
1086 :ref:`Hello World <writing-an-llvm-pass-basiccode>` pass interacts with other
1091 $ opt -load ../../Debug+Asserts/lib/Hello.so -gcse -licm --debug-pass=Structure < hello.bc > /dev/null
1092 Module Pass Manager
1093 Function Pass Manager
1111 dominator and immediate dominator information to do its job. The LICM pass
1114 pass, it is immediately destroyed. The dominator sets are then reused to
1115 compute natural loop information, which is then used by the LICM pass.
1117 After the LICM pass, the module verifier runs (which is automatically added by
1124 <writing-an-llvm-pass-basiccode>` pass in between the two passes:
1128 $ opt -load ../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
1129 Module Pass Manager
1130 Function Pass Manager
1137 Hello World Pass
1138 -- Hello World Pass
1153 Here we see that the :ref:`Hello World <writing-an-llvm-pass-basiccode>` pass
1154 has killed the Dominator Set pass, even though it doesn't modify the code at
1156 <writing-an-llvm-pass-getAnalysisUsage>` method to our pass:
1165 Now when we run our pass, we get this output:
1169 $ opt -load ../../Debug+Asserts/lib/Hello.so -gcse -hello -licm --debug-pass=Structure < hello.bc > /dev/null
1170 Pass Arguments: -gcse -hello -licm
1171 Module Pass Manager
1172 Function Pass Manager
1178 Hello World Pass
1179 -- Hello World Pass
1196 .. _writing-an-llvm-pass-releaseMemory:
1206 and how long to keep them around for. Because the lifetime of the pass object
1211 If you are writing an analysis or any other pass that retains a significant
1212 amount of state (for use by another pass which "requires" your pass and uses
1213 the :ref:`getAnalysis <writing-an-llvm-pass-getAnalysis>` method) you should
1216 class, before the next call of ``run*`` in your pass.
1226 feedback to the user. This is where pass registration comes into play.
1228 The fundamental mechanisms for pass registration are the
1236 information provided about a particular pass. This information includes the
1238 to create an instance of the pass. A global static constructor of one of these
1240 destructor *unregisters*. Thus a pass that is statically linked in the tool
1241 will be registered at start up. A dynamically loaded pass will register on
1250 pass.
1252 Implement your register allocator machine pass. In your register allocator
1310 Then you need to declare the registry. Example: if your pass registry is
1325 cl::desc("my pass option help"));
1336 functions in shared objects. Here are some suggestions to debugging your pass
1343 Setting a breakpoint in your pass
1361 time to load. Be patient. Since we cannot set a breakpoint in our pass yet
1363 and have it stop before it invokes our pass, but after it has loaded the shared
1370 Breakpoint 1 at 0x2413bc: file Pass.cpp, line 70.
1373 Breakpoint 1, PassManager::run (this=0xffbef174, M=@0x70b298) at Pass.cpp:70
1378 free to set breakpoints in your pass so that you can trace through execution or
1389 pass is dynamically loaded however, it somehow completely loses this
1394 above, you have succeeded in getting some breakpoints planted in your pass.
1398 already set in your pass, run the program, and re-set the breakpoints once
1408 Although the LLVM Pass Infrastructure is very capable as it stands, and does
1412 .. _writing-an-llvm-pass-SMP:
1422 create multiple instances of each pass object, and allow the separate instances
