Using -opt-bisect-limit to debug optimization errors

Introduction

The -opt-bisect-limit option provides a way to disable all optimization passesabove a specified limit without modifying the way in which the Pass Managersare populated. The intention of this option is to assist in tracking downproblems where incorrect transformations during optimization result in incorrectrun-time behavior.

This feature is implemented on an opt-in basis. Passes which can be safelyskipped while still allowing correct code generation call a function tocheck the opt-bisect limit before performing optimizations. Passes whicheither must be run or do not modify the IR do not perform this check and aretherefore never skipped. Generally, this means analysis passes, passesthat are run at CodeGenOpt::None and passes which are required for registerallocation.

The -opt-bisect-limit option can be used with any tool, including front endssuch as clang, that uses the core LLVM library for optimization and codegeneration. The exact syntax for invoking the option is discussed below.

This feature is not intended to replace other debugging tools such as bugpoint.Rather it provides an alternate course of action when reproducing the problemrequires a complex build infrastructure that would make using bugpointimpractical or when reproducing the failure requires a sequence oftransformations that is difficult to replicate with tools like opt and llc.

Getting Started

The -opt-bisect-limit command line option can be passed directly to tools suchas opt, llc and lli. The syntax is as follows:

  1. <tool name> [other options] -opt-bisect-limit=<limit>

If a value of -1 is used the tool will perform all optimizations but a messagewill be printed to stderr for each optimization that could be skippedindicating the index value that is associated with that optimization. To skipoptimizations, pass the value of the last optimization to be performed as theopt-bisect-limit. All optimizations with a higher index value will be skipped.

In order to use the -opt-bisect-limit option with a driver that provides awrapper around the LLVM core library, an additional prefix option may berequired, as defined by the driver. For example, to use this option withclang, the “-mllvm” prefix must be used. A typical clang invocation would looklike this:

  1. clang -O2 -mllvm -opt-bisect-limit=256 my_file.c

The -opt-bisect-limit option may also be applied to link-time optimizations byusing a prefix to indicate that this is a plug-in option for the linker. Thefollowing syntax will set a bisect limit for LTO transformations:

  1. # When using lld, or ld64 (macOS)
  2. clang -flto -Wl,-mllvm,-opt-bisect-limit=256 my_file.o my_other_file.o
  3. # When using Gold
  4. clang -flto -Wl,-plugin-opt,-opt-bisect-limit=256 my_file.o my_other_file.o

LTO passes are run by a library instance invoked by the linker. Therefore anypasses run in the primary driver compilation phase are not affected by optionspassed via ‘-Wl,-plugin-opt’ and LTO passes are not affected by optionspassed to the driver-invoked LLVM invocation via ‘-mllvm’.

Bisection Index Values

The granularity of the optimizations associated with a single index value isvariable. Depending on how the optimization pass has been instrumented thevalue may be associated with as much as all transformations that would havebeen performed by an optimization pass on an IR unit for which it is invoked(for instance, during a single call of runOnFunction for a FunctionPass) or aslittle as a single transformation. The index values may also be nested so thatif an invocation of the pass is not skipped individual transformations withinthat invocation may still be skipped.

The order of the values assigned is guaranteed to remain stable and consistentfrom one run to the next up to and including the value specified as the limit.Above the limit value skipping of optimizations can cause a change in thenumbering, but because all optimizations above the limit are skipped thisis not a problem.

When an opt-bisect index value refers to an entire invocation of the runfunction for a pass, the pass will query whether or not it should be skippedeach time it is invoked and each invocation will be assigned a unique value.For example, if a FunctionPass is used with a module containing three functionsa different index value will be assigned to the pass for each of the functionsas the pass is run. The pass may be run on two functions but skipped for thethird.

If the pass internally performs operations on a smaller IR unit the pass must bespecifically instrumented to enable bisection at this finer level of granularity(see below for details).

Example Usage

  1. $ opt -O2 -o test-opt.bc -opt-bisect-limit=16 test.ll
  2.  
  3. BISECT: running pass (1) Simplify the CFG on function (g)
  4. BISECT: running pass (2) SROA on function (g)
  5. BISECT: running pass (3) Early CSE on function (g)
  6. BISECT: running pass (4) Infer set function attributes on module (test.ll)
  7. BISECT: running pass (5) Interprocedural Sparse Conditional Constant Propagation on module (test.ll)
  8. BISECT: running pass (6) Global Variable Optimizer on module (test.ll)
  9. BISECT: running pass (7) Promote Memory to Register on function (g)
  10. BISECT: running pass (8) Dead Argument Elimination on module (test.ll)
  11. BISECT: running pass (9) Combine redundant instructions on function (g)
  12. BISECT: running pass (10) Simplify the CFG on function (g)
  13. BISECT: running pass (11) Remove unused exception handling info on SCC (<<null function>>)
  14. BISECT: running pass (12) Function Integration/Inlining on SCC (<<null function>>)
  15. BISECT: running pass (13) Deduce function attributes on SCC (<<null function>>)
  16. BISECT: running pass (14) Remove unused exception handling info on SCC (f)
  17. BISECT: running pass (15) Function Integration/Inlining on SCC (f)
  18. BISECT: running pass (16) Deduce function attributes on SCC (f)
  19. BISECT: NOT running pass (17) Remove unused exception handling info on SCC (g)
  20. BISECT: NOT running pass (18) Function Integration/Inlining on SCC (g)
  21. BISECT: NOT running pass (19) Deduce function attributes on SCC (g)
  22. BISECT: NOT running pass (20) SROA on function (g)
  23. BISECT: NOT running pass (21) Early CSE on function (g)
  24. BISECT: NOT running pass (22) Speculatively execute instructions if target has divergent branches on function (g)
  25. ... etc. ...

Pass Skipping Implementation

The -opt-bisect-limit implementation depends on individual passes opting in tothe opt-bisect process. The OptBisect object that manages the process isentirely passive and has no knowledge of how any pass is implemented. When apass is run if the pass may be skipped, it should call the OptBisect object tosee if it should be skipped.

The OptBisect object is intended to be accessed through LLVMContext and eachPass base class contains a helper function that abstracts the details in orderto make this check uniform across all passes. These helper functions are:

  1. bool ModulePass::skipModule(Module &M);
  2. bool CallGraphSCCPass::skipSCC(CallGraphSCC &SCC);
  3. bool FunctionPass::skipFunction(const Function &F);
  4. bool LoopPass::skipLoop(const Loop *L);

A MachineFunctionPass should use FunctionPass::skipFunction() as such:

  1. bool MyMachineFunctionPass::runOnMachineFunction(Function &MF) {
  2.   if (skipFunction(*MF.getFunction())
  3.     return false;
  4.   // Otherwise, run the pass normally.
  5. }

In addition to checking with the OptBisect class to see if the pass should beskipped, the skipFunction(), skipLoop() and skipBasicBlock() helper functionsalso look for the presence of the “optnone” function attribute. The callingpass will be unable to determine whether it is being skipped because the“optnone” attribute is present or because the opt-bisect-limit has beenreached. This is desirable because the behavior should be the same in eithercase.

The majority of LLVM passes which can be skipped have already been instrumentedin the manner described above. If you are adding a new pass or believe youhave found a pass which is not being included in the opt-bisect process butshould be, you can add it as described above.

Adding Finer Granularity

Once the pass in which an incorrect transformation is performed has beendetermined, it may be useful to perform further analysis in order to determinewhich specific transformation is causing the problem. Debug counterscan be used for this purpose.