intel-graphics-compiler/documentation/shader_dumps_instruction.md

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:

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 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.
*.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.

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:

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

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:

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

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:

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.