[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 ─────────────────────────────┐ │
----------------
slackito wrote:

typo: "sanboxir"

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