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