[llvm] 99de3a6 - [VPlan] Document current status. (#85689)

[via llvm-commits]

Author: Florian Hahn
Date: 2024-05-16T13:34:04+01:00
New Revision: 99de3a685170c24208b00ef83fe0416373387acc

URL: https://github.com/llvm/llvm-project/commit/99de3a685170c24208b00ef83fe0416373387acc
DIFF: https://github.com/llvm/llvm-project/commit/99de3a685170c24208b00ef83fe0416373387acc.diff

LOG: [VPlan] Document current status. (#85689)

Update VectorizationPlan.rst to include a section about the current
status of VPlan and its use in LoopVectorize, based on "VPlan: Status
Update and Future Roadmap", LLVM Developers’ Meeting 2023,
https://www.youtube.com/watch?v=SzGP4PgMuLE

PR: https://github.com/llvm/llvm-project/pull/85689

Added: 
    llvm/docs/vplan-scope.png
    llvm/docs/vplan-transform-pipeline.png

Modified: 
    llvm/docs/VectorizationPlan.rst
    llvm/docs/conf.py

Removed: 
    


################################################################################
diff  --git a/llvm/docs/VectorizationPlan.rst b/llvm/docs/VectorizationPlan.rst
index 418c52eeef7f5..6496263cf8d97 100644
--- a/llvm/docs/VectorizationPlan.rst
+++ b/llvm/docs/VectorizationPlan.rst
@@ -19,6 +19,49 @@ candidates. It serves for both optimizing candidates including estimating their
 cost reliably, and for performing their final translation into IR. This
 facilitates dealing with multiple vectorization candidates.
 
+Current Status
+==============
+VPlan is currently used to drive code-generation in LoopVectorize. VPlans are
+constructed after all cost-based and most legality-related decisions have been
+taken. As def-use chains between recipes are now fully modeled in VPlan,
+VPlan-based analyses and transformations are used to simplify and modularize
+the vectorization process [10]_. Those include transformations to
+
+1. Legalize the initial VPlan, e.g. by introducing specialized recipes for
+   reductions and interleave groups.
+
+2. Optimize the legalized VPlan, e.g. by removing redundant recipes or
+   introducing active-lane-masks.
+
+3. Apply unroll- and vectorization-factor specific optimizations, e.g. removing
+   the backedge to reiterate the vector loop based on VF & UF.
+
+Refer to :numref:`fig-vplan-transform-pipeline` for an overview of the current
+transformation pipeline.
+
+Note that some legality checks are already done in VPlan, including checking if
+all users of a fixed-order recurrence can be re-ordered. This is implemented as
+a VPlan-to-VPlan transformation that either applies a valid re-ordering or
+bails out marking the VPlan as invalid.
+
+.. _fig-vplan-transform-pipeline:
+.. figure:: ./vplan-transform-pipeline.png
+   :width: 800 px
+
+   VPlan Transformation Pipeline in 2024
+
+
+VPlan currently models the complete vector loop, as well as additional parts of
+the vectorization skeleton. Refer to :numref:`fig-vplan-scope` for an overview
+of the scope covered by VPlan.
+
+.. _fig-vplan-scope:
+.. figure:: ./vplan-scope.png
+   :width: 800 px
+
+   Scope modeled in VPlan in 2024
+
+
 High-level Design
 =================
 
@@ -160,13 +203,10 @@ The low-level design of VPlan comprises of the following classes.
   VPValues.
 
 :VPInstruction:
-  A VPInstruction is both a VPRecipe and a VPUser. It models a single
-  VPlan-level instruction to be generated if the VPlan is executed, including
-  its opcode and possibly additional characteristics. It is the basis for
-  writing instruction-level analyses and optimizations in VPlan as creating,
-  replacing or moving VPInstructions record both def-use and scheduling
-  decisions. VPInstructions also extend LLVM IR's opcodes with idiomatic
-  operations that enrich the Vectorizer's semantics.
+  A VPInstruction is a recipe characterized by a single opcode and optional
+  flags, free of ingredients or other meta-data. VPInstructions also extend
+  LLVM IR's opcodes with idiomatic operations that enrich the Vectorizer's
+  semantics.
 
 :VPTransformState:
   Stores information used for generating output IR, passed from
@@ -177,9 +217,9 @@ The Planning Process and VPlan Roadmap
 ======================================
 
 Transforming the Loop Vectorizer to use VPlan follows a staged approach. First,
-VPlan is used to record the final vectorization decisions, and to execute them:
-the Hierarchical CFG models the planned control-flow, and Recipes capture
-decisions taken inside basic-blocks. Next, VPlan will be used also as the basis
+VPlan was only used to record the final vectorization decisions, and to execute
+them: the Hierarchical CFG models the planned control-flow, and Recipes capture
+decisions taken inside basic-blocks. Currently, VPlan is used also as the basis
 for taking these decisions, effectively turning them into a series of
 VPlan-to-VPlan algorithms. Finally, VPlan will support the planning process
 itself including cost-based analyses for making these decisions, to fully
@@ -248,3 +288,6 @@ References
 
 .. [9] "Extending LoopVectorizer: OpenMP4.5 SIMD and Outer Loop
     Auto-Vectorization", Intel Vectorizer Team, LLVM Developers' Meeting 2016.
+
+.. [10] "VPlan: Status Update and Future Roadmap", Florian Hahn, LLVM
+         Developers' Meeting 2023, https://www.youtube.com/watch?v=SzGP4PgMuLE

diff  --git a/llvm/docs/conf.py b/llvm/docs/conf.py
index acbddc7b2f12b..270f5b33e9855 100644
--- a/llvm/docs/conf.py
+++ b/llvm/docs/conf.py
@@ -222,6 +222,7 @@
 # If false, no module index is generated.
 # latex_domain_indices = True
 
+numfig = True
 
 # -- Options for manual page output --------------------------------------------
 

diff  --git a/llvm/docs/vplan-scope.png b/llvm/docs/vplan-scope.png
new file mode 100644
index 0000000000000..d60b58b55b8ea
Binary files /dev/null and b/llvm/docs/vplan-scope.png 
diff er

diff  --git a/llvm/docs/vplan-transform-pipeline.png b/llvm/docs/vplan-transform-pipeline.png
new file mode 100644
index 0000000000000..3bdd433a7a59f
Binary files /dev/null and b/llvm/docs/vplan-transform-pipeline.png 
diff er