[llvm] [SandboxVec][Doc] Add documentation for the Sandbox Vectorizer (PR #133504)

[Jorge Gorbe Moya via llvm-commits]

================
@@ -0,0 +1,279 @@
+# The Sandbox Vectorizer
+
+```{contents}
+:depth: 4
+```
+
+The Sandbox Vectorizer is a framework for building modular vectorization pipelines on top of [Sandbox IR](#SandboxIR) transactional IR, with a focus on ease of development and testing.
+The default pipeline currently implements a simple SLP-style bottom-up vectorization pipeline.
+
+The transactional IR helps in several ways:
+- It enables a modular design where:
+  - Each vectorization transformation/optimization can be implemented as a separate internal pass that uses actual IR as its input and output.
+  - You can still make end-to-end profitability decisions (i.e., across multiple internal passes), even when the transformations are implemented as separate internal passes.
+  - Each transformation/optimization internal pass can be tested in isolation with lit-tests, as opposed to end-to-end tests.
+- It enables a simpler design by enabling each internal pass commit its state to the IR itself rather than updating helper data-structures that live across the pipeline.
+- Its extensive callback interface helps remove the burden of manually maintaining the vectorizer's components while the IR is being modified.
+
+## Usage
+
+The Sandbox Vectorizer is currently under development and is not enabled by default.
+So in order to use it you have to explicitly run the pass with `opt` like so:
+
+```shell
+$ opt -p=sandbox-vectorizer file.ll
+```
+
+## Internal Pass Pipeline
+
+The Sandbox Vectorizer is designed to be modular and as such it has its own internal pass-pipeline that operates on Sandbox IR.
+Each vectorization phase is implemented as a separate internal pass that runs by the Sandbox Vectorizer's internal pass manager.
+The Sandbox Vectorizer pass itself is an LLVM Function pass.
+
+The following figure shows the basic structure of the Sandbox Vectorizer LLVM Function pass.
+The first component is the conversion of `LLVM IR to Sandbox IR` which converts the LLVM Function to a `sandboxir::Function`.
+From this point on the pass operates on Sandbox IR.
+The main entry point to the internal pass pipeline is the `Sandbox IR Function Pass Manger`, which runs all registered function passes.
+The following figure lists only a single Sandbox IR function pass, the `Seed Collection Pass` which goes over the instructions in the function and collects vectorization candidates, like Stores to consecutive memory addresses, and forms a [Region](#region).
+The `Seed Collection Pass` itself contains its own Region pass pipeline, which in the following example contains a `Transaction Save` pass, a `Bottom-Up Vectorization` pass, a `Pack Reuse` pass and a `Transaction Accept/Revert` pass.
+
+```
+┌────────────────────────────────── Sandbox Vectorizer LLVM Function Pass ─────────────────────────────┐
+│                                                                                                      │
+│ ┌───────┐ ┌────────────────────────── sanboxir::Function Pass Manager ─────────────────────────────┐ │
+│ │       │ │                                                                                        │ │
+│ │       │ │ ┌────────────────────────────── Seed Collection Pass ──────────────────────────────┐   │ │
+│ │       │ │ │                                                                                  │   │ │
+│ │       │ │ │ ┌───────┐  For   ┌─────────────── sanboxir::Region Pass Manager ───────────────┐ │   │ │
+│ │LLVM IR│ │ │ │Collect│  each  │ ┌───────────┐ ┌────────────────┐ ┌───────┐ ┌──────────────┐ │ │   │ │
+│ │  to   │ │ │ │ Seeds │ Region │ │Transaction│ │   Bottom─Up    │ │ Pack  │ │ Transaction  │ │ │   │ │
+│ │Sandbox│ │ │ │Create │ ─────> │ │   Save    │ │ Vectorization  │ │ Reuse │ │Accept/Revert │ │ │   │ │
+│ │  IR   │ │ │ │Regions│        │ └───────────┘ └────────────────┘ └───────┘ └──────────────┘ │ │   │ │
+│ │       │ │ │ └───────┘        └─────────────────────────────────────────────────────────────┘ │   │ │
+│ │       │ │ │                                                                                  │...│ │
+│ │       │ │ └──────────────────────────────────────────────────────────────────────────────────┘   │ │
+│ │       │ │                                                                                        │ │
+│ └───────┘ └────────────────────────────────────────────────────────────────────────────────────────┘ │
+│                                                                                                      │
+└──────────────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+You can specify your own custom pipeline with the `-sbvec-passes=` argument to `opt`.
+The pipeline shown above is equivalent to this:
+
+```shell
+$ opt -p=sandbox-vectorizer -sbvec-passes='seed-collection<tr-save,bottom-up-vec,pack-reuse,tr-accept>' file.ll
+```
+
+If the user does not define a pipeline, the Sandbox Vectorizer will run its default pass-pipeline, which is set in the constructor of the `SandboxVectorizerPass`.
+
+## Sandbox Vectorizer Passes
+
+The passes in the vectorization pipeline can be found in `Transforms/Vectorize/SandboxVectorizer/Passes` and they are registered in `lib/Transforms/Vectorize/SandboxVectorizer/Passes/PassRegistry.def`.
+
+There are two types of passes: [Transformation Passes](#transformation-passes) that do the actual vectorization-related transformations and optimizations, and [Helper Passes](#helper-passes) that are helping with things like managing the IR transactions, and test-specific things like building regions.
+
+### Transformation Passes
+
+|  **Pass Name**            |         **File Name**       | **Type** |                     **Description**                     |
+|---------------------------|-----------------------------|----------|---------------------------------------------------------|
+| `seed-collection`         | SeedCollection.h            | Function | Collects the instructions to start vectorizing from, creates a region and runs the region-pass pipeline |
+| `bottom-up-vec`           | BottomUpVec.h               | Region   | An SLP-style bottom-up vectorizer. It can vectorize both scalars and vectors |
+| `pack-reuse`              | PackReuse.h                 | Region   | A pass that de-duplicates packs                         |
+
+### Helper Passes
+
+|  **Pass Name**            |         **File Name**       | **Type** |                     **Description**                     |
+|---------------------------|-----------------------------|----------|---------------------------------------------------------|
+| `tr-save`                 | TransactionSave.h           | Region   | Creates a checkpoint of the IR (i.e., saves state)      |
+| `tr-accept`               | TransactionAlwaysAccept.h   | Region   | Unconditionally accepts the IR state                    |
+| `tr-revert`               | TransactionAlwaysRevert.h   | Region   | Unconditionally rejects the IR state                    |
+| `tr-accept-or-revert`     | TransactionAcceptOrRevert.h | Region   | Checks cost model and either accepts or reverts the IR  |
+| `null`                    | NullPass.h                  | Region   | A test pass that prints the region instructions         |
----------------
slackito wrote:

The null pass doesn't print anything, that would be the new print-region pass in https://github.com/llvm/llvm-project/pull/131019

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