[docs] Update Optimization Options (#20216)

Added `iree-opt-level` to docs and add tip pointing to the "Optimization
Options" page.

---------

Signed-off-by: Ian Wood <[email protected]>
Signed-off-by: Elias Joseph <[email protected]>

Author: IanWood1

docs/website/docs/guides/deployment-configurations/bare-metal.md

@@ -61,6 +61,8 @@ for example command-line instructions of some common architectures.
 You can replace the MLIR file with the other MLIR model files, following the
 [instructions](./cpu.md#compile-a-program).
 
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-optimization-options.md"
+
 ### Compiling the bare-metal model for static-library support
 
 See the [static_library](https://github.com/iree-org/iree/tree/main/samples/static_library)

docs/website/docs/guides/deployment-configurations/cpu.md

@@ -130,6 +130,8 @@ iree-compile \
     When not cross compiling, passing `--iree-llvmcpu-target-cpu=host` is
     usually sufficient on most devices.
 
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-optimization-options.md"
+
 #### Choosing CPU targets
 
 The `--iree-llvmcpu-target-triple` flag tells the compiler to generate code

docs/website/docs/guides/deployment-configurations/gpu-cuda.md

@@ -95,6 +95,8 @@ iree-compile \
     mobilenetv2.mlir -o mobilenet_cuda.vmfb
 ```
 
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-optimization-options.md"
+
 #### Choosing CUDA targets
 
 Canonically a CUDA target (`iree-cuda-target`) matching the LLVM NVPTX

docs/website/docs/guides/deployment-configurations/gpu-rocm.md

@@ -167,6 +167,8 @@ iree-compile \
     mobilenetv2.mlir -o mobilenet_rocm.vmfb
 ```
 
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-optimization-options.md"
+
 ???+ tip "Tip - HIP bitcode files"
 
     That IREE comes with bundled bitcode files, which are used for linking

docs/website/docs/guides/deployment-configurations/gpu-vulkan.md

@@ -165,6 +165,8 @@ iree-compile \
     mobilenetv2.mlir -o mobilenet_vulkan.vmfb
 ```
 
+--8<-- "docs/website/docs/guides/deployment-configurations/snippets/_iree-optimization-options.md"
+
 #### Choosing Vulkan targets
 
 The `--iree-vulkan-target` specifies the GPU architecture to target. It

docs/website/docs/guides/deployment-configurations/snippets/_iree-optimization-options.md

@@ -0,0 +1,6 @@
+???+ tip "Tip - Compiler Optimizations"
+
+    Use `--iree-opt-level=[O0,O1,O2,O3]` to enable additional compiler
+    optimizations. The default value of `O0` enables only minimal optimizations
+    while higher levels enable progressively more aggressive optimizations. See
+    [Optimization Options](../../reference/optimization-options.md) for more details.

docs/website/docs/reference/optimization-options.md

@@ -16,6 +16,80 @@ These flags can be passed to the:
   constructor
 * `ireeCompilerOptionsSetFlags()` compiler C API function
 
+## Optimization level
+
+As in other compilers like clang and gcc, IREE provides a high level optimization
+level flag (`iree-opt-level`) that enables different sets of underlying options.
+
+`iree-opt-level` specifies the optimization level for the entire compilation
+flow. Lower optimization levels prioritize debuggability and stability, while
+higher levels focus on maximizing performance. By default, `iree-opt-level` is
+set to `O0` (minimal or no optimizations).
+
+!!! note
+
+    Not all flags that control performance are nested under `iree-opt-level`.
+    See [High level program optimizations](#high-level-program-optimizations)
+    below for subflags not covered by optimization flags.
+
+This flag takes the following values:
+
+| Optimization Level | Pros | Cons |
+|-------------------|------|------|
+| **O0** (Default, Minimal Optimizations) | <ul style="list-style-type:none;"><li>✔️ Fastest compilation time.</li><li>✔️ Generated code is easier to debug.</li><li>✔️ Keeps assertions enabled</li></ul> | <ul style="list-style-type:none;"><li>❌ Poor runtime performance.</li><li>❌ Higher runtime memory usage.</li><li>❌ Larger code size due to lack of optimization.</li></ul> |
+| **O1** (Basic Optimizations) | <ul style="list-style-type:none;"><li>✔️ Enables optimizations, allowing for better runtime performance.</li><li>✔️ Optimizations are compatible with all backends.</li></ul> | <ul style="list-style-type:none;"><li>➖ Only applies conservative optimizations.</li><li>❌ Reduced debuggability.</li></ul> |
+| **O2** (Optimizations without full backend support) | <ul style="list-style-type:none;"><li>✔️ Even more aggressive optimizations.</li><li>✔️ Strikes a balance between optimization level and compatibility.</li></ul> | <ul style="list-style-type:none;"><li>➖ Some optimizations may not be supported by all backends.</li><li>❌ Reduced debuggability.</li></ul> |
+| **O3** (Aggressive Optimization) | <ul style="list-style-type:none;"><li>✔️ Highest runtime performance.</li><li>✔️ Enables advanced and aggressive transformations.</li><li>✔️ Exploits backend-specific optimizations for optimal efficiency.</li></ul> | <ul style="list-style-type:none;"><li>➖ Longer compile times.</li><li>❌ Some optimizations may be unstable.</li><li>❌ Reduced debuggability.</li></ul> |
+
+Although `iree-opt-level` sets the default for each subflag, they can be
+explicitly set on or off independently.
+
+For example:
+
+```bash
+# Apply the default optimizations of `O2` but don't remove assertions.
+iree-compile --iree-opt-level=O2 --iree-strip-assertions=false
+
+# Minimize optimizations, but still preform aggressive fusion.
+iree-compile --iree-opt-level=O0 --iree-dispatch-creation-enable-aggressive-fusion=true
+```
+
+### Pipeline-level control
+
+In addition to `iree-opt-level`, IREE provides optimization controls at the
+pipeline level. These flags allow fine-grained tuning of specific compilation
+stages while still respecting the topmost optimization level unless explicitly
+overridden.
+
+#### Dispatch Creation (`iree-dispatch-creation-opt-level`)
+
+- `iree-dispatch-creation-enable-aggressive-fusion` (enabled at `O2`)
+
+    Enables more aggressive fusion opportunities not yet supported by all backends
+
+#### Global Optimization (`iree-global-optimization-opt-level`)
+
+- `iree-opt-strip-assertions` (enabled at `O1`)
+
+    Strips all `std.assert` ops in the input program after useful information for
+    optimization analysis has been extracted. Assertions provide useful
+    user-visible error messages but can prevent critical optimizations.
+    Assertions are not, however, a substitution for control flow and frontends
+    that want to check errors in optimized release builds should do so via
+    actual code - similar to when one would `if (foo) return false;` vs.
+    `assert(foo);` in a normal program.
+
+- `iree-opt-outer-dim-concat` (enabled at `O1`)
+
+    Transpose concat operations to ocurr along the outermost dimension. The
+    resulting concat will now be contiguous and the inserted transposes can
+    possibly be fused with surrounding ops.
+
+- `iree-opt-aggressively-propagate-transposes` (enabled at `O3`)
+
+    Enables more transpose propagation by allowing transposes to be propagated
+    to `linalg` named ops even when the resulting op will be a `linalg.generic`.
+
 ## High level program optimizations
 
 ### Constant evaluation (`--iree-opt-const-eval` (on))
@@ -56,12 +130,3 @@ and constant data rewritten to lower precision types.
 
 This feature is actively evolving and will be the subject of dedicated
 documentation when ready.
-
-### Strip Debug Assertions (`--iree-opt-strip-assertions` (off))
-
-Strips all `std.assert` ops in the input program after useful information for
-optimization analysis has been extracted. Assertions provide useful user-visible
-error messages but can prevent critical optimizations. Assertions are not,
-however, a substitution for control flow and frontends that want to check errors
-in optimized release builds should do so via actual code - similar to when one
-would `if (foo) return false;` vs. `assert(foo);` in a normal program.