[llvm] [LoopFusion] Document LoopFusion Pass (PR #192926)

[Nikita Popov via llvm-commits]

================
@@ -0,0 +1,491 @@
+====================================================
+Loop Fusion in LLVM
+====================================================
+
+1. Introduction
+===============
+
+Loop fusion (also called loop jamming) is a compiler optimization that
+merges two adjacent loops into a single loop, provided the
+transformation preserves the program's original semantics. The
+motivation is straightforward: by executing the bodies of two loops in
+a single pass over the iteration space, we reduce loop overhead (fewer
+branch instructions, fewer induction variable updates), improve
+temporal data locality (data written by the first loop body and read
+by the second is still in cache), and create new opportunities for
+subsequent optimizations such as instruction scheduling and register
+allocation.
+
+LLVM's implementation resides in
+``llvm/lib/Transforms/Scalar/LoopFuse.cpp`` and is based on
+Christopher Barton's MSc thesis, *"Code Transformations to Augment the
+Scope of Loop Fusion in a Production Compiler"*. The pass operates one
+LLVM IR, leveraging several core analysis frameworks -- 
+Scalar Evolution (SCEV), Dependence Analysis
+(DA), and Dominator/Post-Dominator Trees -- to determine legality and
+perform the CFG rewiring that fuses two loops into one.
+
+2. Prerequisite Concepts
----------------
nikic wrote:

I think this section is too extensive -- there should be no need to explain what terms like loop rotation or dominance mean in this context. This is all basic terminology that is not specific to loop fusion.

I think the only parts of this that are somewhat relevant is the definition of "control flow equivalent", the dependence terminology and the mention of peeling to align trip counts.

And even those mostly already get covered later anyway, e.g. "No Negative-Distance Dependencies" has the dependence terminology as well.

https://github.com/llvm/llvm-project/pull/192926