Document shader dump products overridability

Added 'Overridable' column to the dump products reference table. Documented which dump product can be overriden via ShaderOverride. Listed overridable products from recompilation outputs.

Author: varev-dev

documentation/shader_dumps_instruction.md

@@ -24,19 +24,19 @@ To compile a standalone `*.cl` shader file use `ocloc` compiler frontend executa
 
 Shader dumps include (in order of creation):
 
-| Product | Description |
-|-|-|
-| `*.cl` file | Original shader file. Passed to `clang` wrapped with `opencl-clang`. |
-| `*.spv` file | SPIR-V binary produced by `opencl-clang`. Passed to IGC's baked-in [SPIRVReader](https://github.com/intel/intel-graphics-compiler/blob/master/IGC/AdaptorOCL/SPIRV/SPIRVReader.cpp). |
-| `*.spvasm` file | Disassembled SPIR-V binary only for debugging purposes. |
-| `*_beforeUnification.ll` file | Result of `*.spv` translation. Start of IGC compilation. |
-| `*_afterUnification.ll` file | Result of all unification passes. |
-| `*_optimized.ll` file | Result of all optimization passes. |
-| `*_codegen.ll` file | Result of all codegen passes. |
-| `*.visa.ll` files | Mappings between LLVM IR ↔ vISA. May not be legal LLVM IR representation. |
-| `*.visaasm` files | vISA assembly file. |
-| `*.asm` files | Kernels in assembly form. |
-| `*.isa` files | Kernels' binaries. |
+| Product | Description | Overridable |
+|-|-|-|
+| `*.cl` file | Original shader file. Passed to `clang` wrapped with `opencl-clang`. | Skip |
+| `*.spv` file | SPIR-V binary produced by `opencl-clang`. Passed to IGC's baked-in [SPIRVReader](https://github.com/intel/intel-graphics-compiler/blob/master/IGC/AdaptorOCL/SPIRV/SPIRVReader.cpp). | Skip |
+| `*.spvasm` file | Disassembled SPIR-V binary only for debugging purposes. | Skip |
+| `*_beforeUnification.ll` file | Result of `*.spv` translation. Start of IGC compilation. | Yes |
+| `*_afterUnification.ll` file | Result of all unification passes. | Yes |
+| `*_optimized.ll` file | Result of all optimization passes. | Yes |
+| `*_codegen.ll` file | Result of all codegen passes. | Crash |
+| `*.visa.ll` files | Mappings between LLVM IR ↔ vISA. May not be legal LLVM IR representation. | Skip |
+| `*.visaasm` files | vISA assembly file. | Yes |
+| `*.asm` files | Kernels in assembly form. | Yes |
+| `*.isa` files | Kernels' binaries. | Skip |
 
 There are also additional products that are not a part of compilation pipeline:
 
@@ -48,6 +48,13 @@ There are also additional products that are not a part of compilation pipeline:
 #### Notes
 1. There is a separate SPIR-V translator for `*.cl` → `*.spv` translation (`opencl-clang`'s) and another for `*.spv` → `*.ll` translation (baked into into IGC).
 2. vISA is an intermediate language for IGC backend.
+3. Values in the *Overridable* column indicate how the ShaderOverride mechanism treats each dump product:
+    | Value | Meaning |
+    | - | - |
+    | Yes | The dump can be successfully overridden. |
+    | Crash | IGC detects the override attempt and tries to apply it, but **the process results in a crash**. |
+    | Skip | IGC **does not attempt to override** the product. Dumps with this status are ignored by the ShaderOverride mechanism. |
+4. Main dump products generated during recompilation are distinguished by an additional numeric identifier in the filename (for example: `*_1_beforeUnification.ll`). Hovever, individual compilation passes continue their numbering sequence (for example the first unification pass may start from `*_0321_Unify_after_PreprocessSPVIR.ll`).
 
 ### Additional options
 
@@ -158,6 +165,12 @@ To enable overrides you need to set an environmental variable:
 export IGC_ShaderOverride=1
 ```
 
+### Overridable and Non-Overridable dumps
+
+1. **Main dump products** that can be overridden are explicitly marked in the reference table (see the *Overridable* column in [List of dump products](#list-of-dump-products)).
+2. Passes that occur between main dump products **cannot be overridden** (for example: `*_after_DeadCodeElimination.ll`).
+3. Among **recompilation outputs**, only `.visaasm` and `.asm` dumps **can be successfully overridden** without causing a crash. Rest of the products are going to cause a crash during overriding attempt.
+
 ### Overriding dumps
 
 To inject a dump into a compilation pipeline: