[llvm] [VPlan] Add additional guiding principles to docs. (PR #85688)

[Florian Hahn via llvm-commits]

https://github.com/fhahn created https://github.com/llvm/llvm-project/pull/85688

Update VectorizationPlan.rst to include the guiding principles outlined in "VPlan: Status Update and Future Roadmap", LLVM Developers’ Meeting 2023, https://www.youtube.com/watch?v=SzGP4PgMuLE, to the `Design Guidelines` section.

The newly added points contain references to examples of prior art that illustrate how it is applied in the current codebase.

Preview a rendered version here:
https://gist.github.com/fhahn/c4a6d7121b86904ab5e0fdf30ab54940/raw/45bea52de83f4ab500a534d2627d8d6a101cb390/VectorizationPlan-Guidelines.pdf

>From 6d0117e4aa4389cb061efe3ec3544c380bfaa7b9 Mon Sep 17 00:00:00 2001
From: Florian Hahn <flo at fhahn.com>
Date: Sat, 16 Mar 2024 21:43:47 +0100
Subject: [PATCH] [VPlan] Add additional guiding principles to docs.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update VectorizationPlan.rst to include the guiding principles outlined
in "VPlan: Status Update and Future Roadmap", LLVM Developers’ Meeting 2023,
https://www.youtube.com/watch?v=SzGP4PgMuLE, to the `Design Guidelines`
section.

The newly added points contain references to examples of prior art that
illustrate how it is applied in the current codebase.

Preview a rendered version here:
https://gist.github.com/fhahn/c4a6d7121b86904ab5e0fdf30ab54940/raw/45bea52de83f4ab500a534d2627d8d6a101cb390/VectorizationPlan-Guidelines.pdf
---
 llvm/docs/VectorizationPlan.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/llvm/docs/VectorizationPlan.rst b/llvm/docs/VectorizationPlan.rst
index 418c52eeef7f5c..de2a02384492ad 100644
--- a/llvm/docs/VectorizationPlan.rst
+++ b/llvm/docs/VectorizationPlan.rst
@@ -88,6 +88,33 @@ The design of VPlan follows several high-level guidelines:
    detection and formation involves searching for and optimizing instruction
    patterns.
 
+8. The adoption of VPlan components should be done as a gradual, always-on
+   refactoring to retain quality and integrate continuously.
+
+9. Gradually refactor into multiple VPlan-to-VPlan transforms to reduce
+   complexity:
+
+   a. Simplify initial VPlan construction, by moving complexity to
+      transformations (e.g. adjusting fixed-order recurrences as separate
+      transformation)
+
+   b. Canonicalize then specialize: initial VPlans and early transformations
+      should operate on canonical, target-independent VPlans, to enable general
+      transformations. Target-specific concepts and specialization should be
+      introduced closer to VPlan execution (e.g. introduction of
+      active-lane-mask as VPlan-to-VPlan transformation).
+
+   c. Simplify VPlan execution: reduce the complexity of recipes' *::execute*
+      implementations by breaking up complex recipes and model them more
+      accurately in VPlan. Employ gradual lowering to avoid unnecessary
+      complexity early on and keep canonical VPlans consice by modeling
+      concepts using abstract recipes. Lower or expand such abstract recipes
+      before code-gen to a series of simpler, concrete recipes with simple
+      *::execute* implementations (e.g. using predicated *VPReplicateRecipes* in
+      the early stages of the pipeline, which later get expanded to replicate
+      regions; this simplifes a number of transformations, including sinking, by
+      avoiding having to deal with replicate regions).
+
 Definitions
 ===========
 The low-level design of VPlan comprises of the following classes.