add comments

Author: wsmoses

enzyme/Enzyme/FunctionUtils.cpp

@@ -398,7 +398,8 @@ Function* preprocessForClone(Function *F, AAResults &AA, TargetLibraryInfo &TLI)
 
  }
  }
- 
+
+ //! Loop rotation now necessary to ensure that the condition of a loop is at the end
  {
     FunctionAnalysisManager AM;
      AM.registerPass([] { return AAManager(); });
@@ -410,29 +411,27 @@ Function* preprocessForClone(Function *F, AAResults &AA, TargetLibraryInfo &TLI)
      AM.registerPass([] { return MemorySSAAnalysis(); });
      AM.registerPass([] { return DominatorTreeAnalysis(); });
      AM.registerPass([] { return MemoryDependenceAnalysis(); });
-#if LLVM_VERSION_MAJOR > 6
+     #if LLVM_VERSION_MAJOR > 6
      AM.registerPass([] { return PhiValuesAnalysis(); });
-#endif
-#if LLVM_VERSION_MAJOR >= 8
- AM.registerPass([] { return PassInstrumentationAnalysis(); });
-#endif
+     #endif
+     #if LLVM_VERSION_MAJOR >= 8
+     AM.registerPass([] { return PassInstrumentationAnalysis(); });
+     #endif
 
- {
+     {
 
      LoopAnalysisManager LAM;
      AM.registerPass([&] { return LoopAnalysisManagerFunctionProxy(LAM); });
      LAM.registerPass([&] { return FunctionAnalysisManagerLoopProxy(AM); });
 
-     {
- //Loop rotation is necessary to ensure we are of the form body then conditional
- createFunctionToLoopPassAdaptor(LoopRotatePass()).run(*NewF, AM); 
- }
+        {
+        //Loop rotation is necessary to ensure we are of the form body then conditional
+        createFunctionToLoopPassAdaptor(LoopRotatePass()).run(*NewF, AM); 
+        }
     LAM.clear();
- }
- AM.clear();
- // Ensure there is only one exit block
- //LoopSimplifyPass().run(*NewF, AM);
- }
+    }
+    AM.clear();
+  }
 
  {
     FunctionAnalysisManager AM;

enzyme/Enzyme/GradientUtils.cpp

@@ -28,6 +28,7 @@
 
 #include <algorithm>
 
+//! Is possibleChild a child loop or the same loop as possibleParent
 static bool isParentOrSameContext(LoopContext & possibleChild, LoopContext & possibleParent) {
     if (possibleChild.header == possibleParent.header) return true;
 
@@ -37,9 +38,10 @@ static bool isParentOrSameContext(LoopContext & possibleChild, LoopContext & pos
     return false;
 }
 
-  //BB is a predecessor of branchingBlock
+  //! Given an edge from BB to branchingBlock get the corresponding block to branch to in the reverse pass
   BasicBlock* GradientUtils::getReverseOrLatchMerge(BasicBlock* BB, BasicBlock* branchingBlock) {
     assert(BB);
+    // BB should be a forward pass block, assert that
     if (reverseBlocks.find(BB) == reverseBlocks.end()) {
         llvm::errs() << *oldFunc << "\n";
         llvm::errs() << *newFunc << "\n";
@@ -812,6 +814,11 @@ bool GradientUtils::getContext(BasicBlock* BB, LoopContext& loopContext) {
     return getContextM(BB, loopContext, this->loopContexts, this->LI, this->SE, this->DT, *this);
 }
 
+//! Given a map of edges we could have taken to desired target, compute a value that determines which target should be branched to
+//  This function attempts to determine an equivalent condition from earlier in the code and use that if possible, falling back to creating a phi node of which edge was taken if necessary
+//  This function can be used in two ways:
+//   * If replacePHIs is null (usual case), this function does the branch
+//   * If replacePHIs isn't null, do not perform the branch and instead replace the PHI's with the derived condition as to whether we should branch to a particular target
 void GradientUtils::branchToCorrespondingTarget(BasicBlock* ctx, IRBuilder <>& BuilderM, const std::map<BasicBlock*, std::vector<std::pair</*pred*/BasicBlock*,/*successor*/BasicBlock*>>> &targetToPreds, const std::map<BasicBlock*,PHINode*>* replacePHIs) {
   if (replacePHIs) {
       if (replacePHIs->size() == 0) return;
@@ -1068,4 +1075,4 @@ void GradientUtils::branchToCorrespondingTarget(BasicBlock* ctx, IRBuilder <>& B
   }
   return;
 
-}
+}

enzyme/Enzyme/GradientUtils.h

@@ -808,7 +808,8 @@ class GradientUtils {
             return nullptr;
             report_fatal_error("unable to unwrap");
     }
-    
+   
+    //! Caching mechanism: creates a cache of type T in a scope given by ctx (where if ctx is in a loop there will be a corresponding number of slots)
     AllocaInst* createCacheForScope(BasicBlock* ctx, Type* T, StringRef name, CallInst** freeLocation, Instruction** lastScopeAllocLocation) {
         assert(ctx);
         assert(T);