[llvm] [SandboxVec][Doc] Add documentation for the Sandbox Vectorizer (PR #133504)
Jorge Gorbe Moya via llvm-commits
llvm-commits at lists.llvm.org
Fri Mar 28 17:22:30 PDT 2025
================
@@ -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 |
+| `print-instruction-count` | PrintInstructionCount.h | Region | A test pass that counts instructions |
+| `regions-from-metadata` | RegionsFromMetadata.h | Function | Builds regions from IR metadata and runs a pipeline of region passes for each one of them. Used in lit tests for testing region passes in isolation |
+| `regions-from-bbs` | RegionsFromBBs.h | Function | Builds a region for each BB, adding all BB instructions into each region. Used in lit tests for stress-testing region passes in isolation |
+
+## Region
+
+In a traditional compiler pass pipeline, transformations usually operate at a function level with function passes.
+This introduces an issue in passes like the vectorizer that operate on small sections of a function (that we refer to as "Regions") but apply a pipeline of transformations on each section horizontally, and evaluate profitability end-to-end on each region as shown below:
+
+```
+ Function
+┌─────────┐ Transform Transform ... Transform
+│ │ A B Z
+│┌───────┐│ ┌───────┐ ┌───────┐ ┌───────┐ Evaluate
+││Region1││ ─> │ │ ─> │ │ ... ─> │ │ Profitability
+│└───────┘│ └───────┘ └───────┘ └───────┘
+│ │
+│┌───────┐│ ┌───────┐ ┌───────┐ ┌───────┐ Evaluate
+││Region2││ ─> │ │ ─> │ │ ... ─> │ │ Profitability
+│└───────┘│ └───────┘ └───────┘ └───────┘
+│ │
+│ │
+└─────────┘
+```
+
+If transformations like `A`, `B`, etc. are implemented as function passes, then they will apply their transformations across the whole function, spanning multiple regions, as they have not been designed to stay within a region.
+The problem is that profitability evaluation will average out the profitability across all regions within the function, leading to a sub-optimal outcome.
+
+This is the problem that the "Region" structure is solving.
+It provides a way of tagging the instructions within a Region with metadata and also provides the necessary APIs for iterating through the Region instructions and operating on them.
+
+The Region allows us to implement the vectorization pipeline as a pipeline of Region passes, each one operating on a specific code section.
+At the end of the region pass pipeline we can evaluate profitability across multiple region passes in the pipeline (if needed) but within a Region, and either accept or revert the transformations.
+
+### Adding Instructions to the Region
+
+The Region grows automatically and is maintained transparently:
+Whenever you create a new instruction it is automatically added to the Region, and whenever an instruction is deleted it gets removed from the Region.
+The reasoning is that vectorization passes work: (i) by creating new vector instructions, (ii) by adding necessary packing/unpacking instructions, or (iii) by deleting the original instructions that got replaced by the vectorized ones.
+
+Internally this is done with the help of the callback API of Sandbox IR.
+The current Region gets notified that either an instruction got created or removed and the Region is maintained accordingly.
+
+### Region Example
+
+The following example defines a Region (with `!0 = distinct !{!"sandboxregion"}`), containing two instructions: `%i1 = add i8 %v, 1` and `%i2 = add i8 %v, 2` in no particular order.
+
+```llvm
+ define void @region_example(i8 %v) {
+ %i0 = add i8 %v, 0
+ %i1 = add i8 %v, 1, !sandboxvec !0
+ %i2 = add i8 %v, 2, !sandboxvec !0
+ ret void
+ }
+ !0 = distinct !{!"sandboxregion"}
+```
+
+The Region class API allows you to iterate through the region instructions like with a range loop:
+
+```c++
+ for (auto *I : Rgn)
+ // Do something with `I`
+```
+
+### Region Auxiliary Vector
+
+On top of tagging instructions the Region has a second functionality: it also supports a way of defining an ordered list of instructions.
+This helps passes communicate such instruction lists from one pass to another, if needed, in an explicit way that is encoded in IR metadata.
+This removes the need for sharing helper data-structures across passes.
+The end result is that you can fully describe such ordered list of instructions in IR and can reproduce the pass behavior using just IR as input, allowing you to test it with lit tests.
+
+The Region API for the auxiliary vector is straightforward.
+It provides the `getAux()` getter method that simply returns the auxiliary vector.
+
+The auxiliary vector instructions are marked with `!sandboxaux` followed by an index, which in the following example are `!1`and `!2` which correspond to 0 and 1 respectively.
+So the following example defines one region (region `!0`) containing all three `add` instructions, two of which belong to the auxiliary vector: `[%i1 = add i8 %v, 1, %i2 = add i8 %v, 2]`.
+
+```llvm
+ define void @region_aux_example(i8 %v) {
+ %i0 = add i8 %v, 0 !sandboxvec !0
+ %i1 = add i8 %v, 1, !sandboxvec !0, !sandboxaux !1
+ %i2 = add i8 %v, 2, !sandboxvec !0, !sandboxaux !2
+ ret void
+ }
+ !0 = distinct !{!"sandboxregion"}
+ !1 = !{i32 0}
+ !2 = !{i32 1}
+```
+
+The auxiliary vector is currently used by the Seed Collection pass to communicate a group of seed instructions to the Bottom-Up-Vectorizer pass.
+
+## Testing Sandbox Vectorizer Passes In Isolation
+
+One of the great things about the Sandbox Vectorizer is that it allows you to test each internal pass in isolation with lit-tests.
+
+Testing Function passes are straightforward, just run `FUNCTION_PASS` in isolation with `-sbvec-passes`, like so:
----------------
slackito wrote:
Should be "Testing Function passes is straightforward".
https://github.com/llvm/llvm-project/pull/133504
More information about the llvm-commits
mailing list