llvm.org GIT mirror llvm / bc94ace
Adding document describing the use of the -opt-bisect-limit option. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@279881 91177308-0d34-0410-b5e6-96231b3b80d8 Andrew Kaylor 3 years ago
2 changed file(s) with 201 addition(s) and 0 deletion(s). Raw diff Collapse all Expand all
0 ====================================================
1 Using -opt-bisect-limit to debug optimization errors
2 ====================================================
3 .. contents::
4 :local:
5 :depth: 1
7 Introduction
8 ============
10 The -opt-bisect-limit option provides a way to disable all optimization passes
11 above a specified limit without modifying the way in which the Pass Managers
12 are populated. The intention of this option is to assist in tracking down
13 problems where incorrect transformations during optimization result in incorrect
14 run-time behavior.
16 This feature is implemented on an opt-in basis. Passes which can be safely
17 skipped while still allowing correct code generation call a function to
18 check the opt-bisect limit before performing optimizations. Passes which
19 either must be run or do not modify the IR do not perform this check and are
20 therefore never skipped. Generally, this means analysis passes, passes
21 that are run at CodeGenOpt::None and passes which are required for register
22 allocation.
24 The -opt-bisect-limit option can be used with any tool, including front ends
25 such as clang, that uses the core LLVM library for optimization and code
26 generation. The exact syntax for invoking the option is discussed below.
28 This feature is not intended to replace other debugging tools such as bugpoint.
29 Rather it provides an alternate course of action when reproducing the problem
30 requires a complex build infrastructure that would make using bugpoint
31 impractical or when reproducing the failure requires a sequence of
32 transformations that is difficult to replicate with tools like opt and llc.
35 Getting Started
36 ===============
38 The -opt-bisect-limit command line option can be passed directly to tools such
39 as opt, llc and lli. The syntax is as follows:
41 ::
43 [other options] -opt-bisect-limit=
45 If a value of -1 is used the tool will perform all optimizations but a message
46 will be printed to stderr for each optimization that could be skipped
47 indicating the index value that is associated with that optimization. To skip
48 optimizations, pass the value of the last optimization to be performed as the
49 opt-bisect-limit. All optimizations with a higher index value will be skipped.
51 In order to use the -opt-bisect-limit option with a driver that provides a
52 wrapper around the LLVM core library, an additional prefix option may be
53 required, as defined by the driver. For example, to use this option with
54 clang, the "-mllvm" prefix must be used. A typical clang invocation would look
55 like this:
57 ::
59 clang -O2 -mllvm -opt-bisect-limit=256 my_file.c
61 The -opt-bisect-limit option may also be applied to link-time optimizations by
62 using a prefix to indicate that this is a plug-in option for the linker. The
63 following syntax will set a bisect limit for LTO transformations:
65 ::
67 clang -flto -Wl,-plugin-opt,-opt-bisect-limit=256 my_file.o my_other_file.o
69 LTO passes are run by a library instance invoked by the linker. Therefore any
70 passes run in the primary driver compilation phase are not affected by options
71 passed via '-Wl,-plugin-opt' and LTO passes are not affected by options
72 passed to the driver-invoked LLVM invocation via '-mllvm'.
75 Bisection Index Values
76 ======================
78 The granularity of the optimizations associated with a single index value is
79 variable. Depending on how the optimization pass has been instrumented the
80 value may be associated with as much as all transformations that would have
81 been performed by an optimization pass on an IR unit for which it is invoked
82 (for instance, during a single call of runOnFunction for a FunctionPass) or as
83 little as a single transformation. The index values may also be nested so that
84 if an invocation of the pass is not skipped individual transformations within
85 that invocation may still be skipped.
87 The order of the values assigned is guaranteed to remain stable and consistent
88 from one run to the next up to and including the value specified as the limit.
89 Above the limit value skipping of optimizations can cause a change in the
90 numbering, but because all optimizations above the limit are skipped this
91 is not a problem.
93 When an opt-bisect index value refers to an entire invocation of the run
94 function for a pass, the pass will query whether or not it should be skipped
95 each time it is invoked and each invocation will be assigned a unique value.
96 For example, if a FunctionPass is used with a module containing three functions
97 a different index value will be assigned to the pass for each of the functions
98 as the pass is run. The pass may be run on two functions but skipped for the
99 third.
101 If the pass internally performs operations on a smaller IR unit the pass must be
102 specifically instrumented to enable bisection at this finer level of granularity
103 (see below for details).
106 Example Usage
107 =============
109 .. code-block:: console
111 $ opt -O2 -o test-opt.bc -opt-bisect-limit=16 test.ll
113 BISECT: running pass (1) Simplify the CFG on function (g)
114 BISECT: running pass (2) SROA on function (g)
115 BISECT: running pass (3) Early CSE on function (g)
116 BISECT: running pass (4) Infer set function attributes on module (test.ll)
117 BISECT: running pass (5) Interprocedural Sparse Conditional Constant Propagation on module (test.ll)
118 BISECT: running pass (6) Global Variable Optimizer on module (test.ll)
119 BISECT: running pass (7) Promote Memory to Register on function (g)
120 BISECT: running pass (8) Dead Argument Elimination on module (test.ll)
121 BISECT: running pass (9) Combine redundant instructions on function (g)
122 BISECT: running pass (10) Simplify the CFG on function (g)
123 BISECT: running pass (11) Remove unused exception handling info on SCC (<>)
124 BISECT: running pass (12) Function Integration/Inlining on SCC (<>)
125 BISECT: running pass (13) Deduce function attributes on SCC (<>)
126 BISECT: running pass (14) Remove unused exception handling info on SCC (f)
127 BISECT: running pass (15) Function Integration/Inlining on SCC (f)
128 BISECT: running pass (16) Deduce function attributes on SCC (f)
129 BISECT: NOT running pass (17) Remove unused exception handling info on SCC (g)
130 BISECT: NOT running pass (18) Function Integration/Inlining on SCC (g)
131 BISECT: NOT running pass (19) Deduce function attributes on SCC (g)
132 BISECT: NOT running pass (20) SROA on function (g)
133 BISECT: NOT running pass (21) Early CSE on function (g)
134 BISECT: NOT running pass (22) Speculatively execute instructions if target has divergent branches on function (g)
135 ... etc. ...
138 Pass Skipping Implementation
139 ============================
141 The -opt-bisect-limit implementation depends on individual passes opting in to
142 the opt-bisect process. The OptBisect object that manages the process is
143 entirely passive and has no knowledge of how any pass is implemented. When a
144 pass is run if the pass may be skipped, it should call the OptBisect object to
145 see if it should be skipped.
147 The OptBisect object is intended to be accessed through LLVMContext and each
148 Pass base class contains a helper function that abstracts the details in order
149 to make this check uniform across all passes. These helper functions are:
151 .. code-block:: c++
153 bool ModulePass::skipModule(Module &M);
154 bool CallGraphSCCPass::skipSCC(CallGraphSCC &SCC);
155 bool FunctionPass::skipFunction(const Function &F);
156 bool BasicBlockPass::skipBasicBlock(const BasicBlock &BB);
157 bool LoopPass::skipLoop(const Loop *L);
159 A MachineFunctionPass should use FunctionPass::skipFunction() as such:
161 .. code-block:: c++
163 bool MyMachineFunctionPass::runOnMachineFunction(Function &MF) {
164 if (skipFunction(*MF.getFunction())
165 return false;
166 // Otherwise, run the pass normally.
167 }
169 In addition to checking with the OptBisect class to see if the pass should be
170 skipped, the skipFunction(), skipLoop() and skipBasicBlock() helper functions
171 also look for the presence of the "optnone" function attribute. The calling
172 pass will be unable to determine whether it is being skipped because the
173 "optnone" attribute is present or because the opt-bisect-limit has been
174 reached. This is desirable because the behavior should be the same in either
175 case.
177 The majority of LLVM passes which can be skipped have already been instrumented
178 in the manner described above. If you are adding a new pass or believe you
179 have found a pass which is not being included in the opt-bisect process but
180 should be, you can add it as described above.
183 Adding Finer Granularity
184 ========================
186 Once the pass in which an incorrect transformation is performed has been
187 determined, it may be useful to perform further analysis in order to determine
188 which specific transformation is causing the problem. Ideally all passes
189 would be instrumented to allow skipping of individual transformations. This
190 functionality is available through the OptBisect object but it is impractical
191 to proactively instrument every existing pass. It is hoped that as developers
192 find that they need a pass to be instrumented they will add the instrumentation
193 and contribute it back to the LLVM source base.
195 Helper functions will be added to simplify this level of instrumentation, but
196 this work is not yet completed. For more information, contact Andy Kaylor.
178178 Extensions
179179 LibFuzzer
180180 ScudoHardenedAllocator
181 OptBisect
182183 :doc:`LLVM Language Reference Manual `
183184 Defines the LLVM intermediate representation and the assembly form of the
225226 :doc:`ScudoHardenedAllocator`
226227 A library that implements a security-hardened `malloc()`.
229 :doc:`OptBisect`
230 A command line option for debugging optimization-induced failures.
228232 Subsystem Documentation
229233 =======================