1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
<!---======================= begin_copyright_notice ============================
Copyright (C) 2021 Intel Corporation
SPDX-License-Identifier: MIT
============================= end_copyright_notice ==========================-->
## Producing shader dumps
Shader dumps (further abbreviated as *dumps*) are intermediate compilation snapshots created during IGC runtime. They are the main IGC debugging tool. For example: producing dumps from two consecutive builds and comparing them will show exactly what effect the change has had on the compilation process.
### Enabling the functionality
To produce shader dumps you need to set an environmental variable:
```bash
export IGC_ShaderDumpEnable=1
```
When this is set simply run any application that uses IGC to compile shaders and IGC will produce dumps in the default directory `/tmp/IntelIGC`.
To compile a standalone `*.cl` shader file use `ocloc` compiler frontend executable from [Intel Compute Runtime](https://github.com/intel/compute-runtime) repository.
### List of dump products
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. |
There are also additional products that are not a part of compilation pipeline:
| Additional products | Description |
|-|-|
|`*_options.txt` file | Options passed to `clBuildProgram`. |
|`*.cos` files | "Patch tokens" - information about kernels that is passed between IGC and Intel Compute Runtime. |
#### 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.
### Additional options
To customize the process use configuration flags. Here are some of them:
|Flag|Description|
|-|-|
|`IGC_DumpToCustomDir`| Path to a directory to produce dumps to. |
|`IGC_ShaderDumpEnableAll`| Dump LLVM passes between stages. |
|`IGC_ShaderDumpPidDisable`| Do not append PID to dumps directory. |
You can learn more about dumping options in configuration flags documentation [here](https://github.com/intel/intel-graphics-compiler/blob/master/documentation/configuration_flags.md).
## Disabling compilation passes
This functionality allows disabling specific passes from IGC compilation runtime. IGC debug build is required.
Disabling some of the passes from the compilation stack can cause a compilation crash, as some passes are essential.
### `ShaderPassDisable` flag overview
#### Print out information about compilation passes
Print all passes' IDs, names, and their occurrence number with flag `IGC_ShaderDisplayAllPassesNames=1`. Note: this does not correspond 1:1 to what the shader dumps are called.
Example output:
```bash
Pass number Pass name Pass occurrence
0 CheckInstrTypes 1
1 Types Legalization Pass 1
2 Target Library Information 1
3 Dead Code Elimination 1
...
...
...
225 Layout 1
226 TimeStatsCounter Start/Stop 6
227 EmitPass 1
228 EmitPass 2
229 EmitPass 3
230 DebugInfoPass 1
```
#### `ShaderPassDisable` flag syntax
```bash
ShaderPassDisable="TOKEN1;TOKEN2;..."
TOKEN:
* Pass number PASS_NUMBER example: 14
* Range PASS_NUMBER_START-PASS_NUMBER_STOP example: 10-50
* Open range PASS_NUMBER_START- example: 60-
* Pass name PASS_NAME example: BreakConstantExprPass
* Specific pass occurrence PASS_NAME:occurrence example: BreakConstantExprPass:0
* Specific pass occurrences range PASS_NAME:OCCURRANCE_START-OCCURRANCE_STOP example: BreakConstantExprPass:2-4
* Specific pass occurrences open range PASS_NAME:OCCURRANCE_START- example: BreakConstantExprPass:3-
```
Example:
```bash
IGC_ShaderPassDisable="9;17-19;239-;Error Check;ResolveOCLAtomics:2;Dead Code Elimination:3-5;BreakConstantExprPass:7-"
You want to skip pass ID 9
You want to skip passes from 17 to 19
You want to skip passes from 239 to end
You want to skip all occurrence of Error Check
You want to skip pass ResolveOCLAtomics occurrence 2
You want to skip pass Dead Code Elimination from occurrence 3 to occurrence 5
You want to skip pass BreakConstantExprPass from occurrence 7 to end
Pass number Pass name Pass occurrence skippedBy
9 LowerInvokeSIMD 1 PassNumber
17 CorrectlyRoundedDivSqrt 1 Range
18 CodeAssumption 1 Range
19 JointMatrixFuncsResolutionPass 1 Range
32 Error Check 1 PassName
65 ResolveOCLAtomics 2 SpecificPassOccurrence
75 Dead Code Elimination 3 SpecificPassOccurrenceRange
77 Error Check 2 PassName
121 Dead Code Elimination 4 SpecificPassOccurrenceRange
143 Dead Code Elimination 5 SpecificPassOccurrenceRange
145 BreakConstantExprPass 7 SpecificPassOccurrenceOpenRange
181 BreakConstantExprPass 8 SpecificPassOccurrenceOpenRange
183 BreakConstantExprPass 9 SpecificPassOccurrenceOpenRange
189 BreakConstantExprPass 10 SpecificPassOccurrenceOpenRange
214 BreakConstantExprPass 11 SpecificPassOccurrenceOpenRange
221 BreakConstantExprPass 12 SpecificPassOccurrenceOpenRange
239 Layout 1 OpenRange
240 TimeStatsCounter Start/Stop 6 OpenRange
241 EmitPass 1 OpenRange
242 EmitPass 2 OpenRange
243 EmitPass 3 OpenRange
244 DebugInfoPass 1 OpenRange
```
#### Implementation of `ShaderPassDisable`
Implementation of `ShaderPassDisable` flag can be found [here](https://github.com/intel/intel-graphics-compiler/blob/master/IGC/common/LLVMUtils.cpp#L81)
## Shader overriding
This is a more advanced debugging functionality that allows overriding most of the compilation steps with own dumps during IGC runtime. This option requires Debug IGC build.
### Basic overview
After producing the dumps once a step can be modified manually and then injected into the compiler pipeline during next executions.
Let us say we would like to modify the `*_afterUnification.ll` step produced by some particular IGC compilation to see how the compilation proceeded. We can patch IGC itself but it may be difficult or not worth the effort. A simpler solution is to use shader overriding and inject modified `*_afterUnification.ll` dump.
### Enabling overriding
To enable overrides you need to set an environmental variable:
```bash
export IGC_ShaderOverride=1
```
### Overriding dumps
To inject a dump into a compilation pipeline:
1. Produce shader dumps normally.
2. Choose a dump to be injected and modify it however is needed.
3. Copy modified dump to the `/tmp/IntelIGC/ShaderOverride` directory.
4. The hash in the name of the dump being injected needs to be the same as the dumps produced normally by the program.
The next time a compilation is run IGC will take files from this directory and override its running compilation. If the process is successful a log message `OVERRIDEN: ...` will be printed to `stdout`.
|
