[llvm] [VPlan] Document current status. (PR #85689)

[via llvm-commits]

================
@@ -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 specializedrecipes 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 branch to exit the vector loop based on VF & UF.
+
+Refer to :numref:`fig-vplan-transform-pipeline` for a 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 other 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
 =================
 
----------------
ayalz wrote:

While we're here, worth also updating _the following_:

...
:VPInstruction:
  A VPInstruction is [both a VPRecipe and a VPUser -> _a recipe characterized by a single opcode and optional flags, free of ingredients or other meta-data_]. [_remove:_ 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.

BTW, it seems that VPRecipesBase::mayReadFromMemory() and mayWriteToMemory() are missing a `case VPInstructionSC:`, similar to VPRecipeBase::mayHaveSideEffects()?
...

The Planning Process and VPlan Roadmap
======================================
Transforming the Loop Vectorizer to use VPlan follows a staged approach. First,
VPlan _[is -> 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. _[Next, VPlan will be -> 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
support compositional and iterative decision making.

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