Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/GameTechDev/IntelShaderAnalyzer
Command line tool for offline shader ISA inspection.
https://github.com/GameTechDev/IntelShaderAnalyzer
Last synced: 2 months ago
JSON representation
Command line tool for offline shader ISA inspection.
- Host: GitHub
- URL: https://github.com/GameTechDev/IntelShaderAnalyzer
- Owner: GameTechDev
- License: mit
- Archived: true
- Created: 2019-03-19T18:55:32.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-03T22:53:28.000Z (about 2 years ago)
- Last Synced: 2024-08-04T02:11:04.110Z (6 months ago)
- Language: C++
- Homepage:
- Size: 25.4 KB
- Stars: 118
- Watchers: 19
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
- AwesomeCppGameDev - IntelShaderAnalyzer
README
# DISCONTINUATION OF PROJECT #
This project will no longer be maintained by Intel.
Intel has ceased development and contributions including, but not limited to, maintenance, bug fixes, new releases, or updates, to this project.
Intel no longer accepts patches to this project.
## Intel Shader Analyzer
Intel Shader Analyzer is a tool for offline static analysis of shaders for Intel GPU Architectures. It allows a user to compile dxbc or HLSL code and inspect the generated GPU ISA for either DX11 and DX12.
Intel Shader Analyzer uses a dedicated driver API to compile and disassemble shaders, and may be run on any Windows 10 machine. It depends on the following graphics driver components:
* For 32-bit:
* igc32.dll
* iga32.dll
* IntelGPUCompiler32.dll
* For 64-bit:
* igc64.dll
* iga64.dll
* IntelGPUCompiler64.dll
In the initial release, these driver components are bundled with the release executable. Future driver releases will also allow Intel GPU users to run with in-situ drivers.
Besides being a functional tool, Intel Shader Analyzer is also intended to serve as a working refrence for the use of the driver compilation API, so that others may incorporate into their own tool chains as appropriate.
## Related Links
The following third-party tools integrate IntelShaderAnalyzer and provide GUIs:
* [Pyramid](https://github.com/jbarczak/pyramid)
* [Shader Playground](http://shader-playground.timjones.io/)
Below are some overviews and articles which introduce the ISA and architecture:
* [Intel Graphics ISA (micro 2016)](https://software.intel.com/sites/default/files/managed/89/92/micro-2016-ISA-tutorial.pdf)
* [Introduction to Gen Assembly](https://software.intel.com/en-us/articles/introduction-to-gen-assembly)
* [Gen11 Architecture Whitepaper](https://software.intel.com/sites/default/files/managed/db/88/The-Architecture-of-Intel-Processor-Graphics-Gen11_R1new.pdf)
Detailed ISA documentation can be found in the PRMs:
* [Skylake](https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-skl-vol07-3d_media_gpgpu.pdf)
* [KabyLake](https://01.org/sites/default/files/documentation/intel-gfx-prm-osrc-kbl-vol07-3d_media_gpgpu.pdf)
## Usage
Intel Shader Analyzer can consume HLSL input or DX bytecode, and pass them for compilation to either the DX11 or DX12 compilers. Currently, HLSL is only supported for shader model 5 shaders.
A simple HLSL command line is shown below:
IntelShaderAnalyzer.exe -s hlsl -f MyVS -p vs_5_0 shader.hlsl
By default, DX11 will be used. DX12 may be specified by using the `--api` command line switch. For example:
IntelShaderAnalyzer.exe -s hlsl --api dx12 -f MyVS -p vs_5_0 shader.hlsl
The `dxbc` source language may be used to feed dx bytecode directly to the tool. For example:
IntelShaderAnalyzer.exe -s dxbc --api dx11 shader.bin
The `dxbc` option also supports passing DXIL shaders to the DX12 backend. For example:
IntelShaderAnalyzer.exe -s dxbc --api dx12 --rootsig_file rootsig.bin shader.bin
### Root Signatures
DX12 compilation requires a root signature, so that the compiler may determine how samplers, descriptors, and constants are to be provided to the shader. Different root signatures will result in slightly different generation. Intel Shader Analyzer can obtain a root signature in several differnet ways. If more than one of them is attempted, they are applied in the order described here.
#### HLSL Attributes
The first option is to use HLSL attributes to embed a root signature in the resulting shader blob, as shown in the example below. If a root signature is found embedded in the compiled shader, it will always be used first.
```
#define MyRS1 "DescriptorTable(SRV(t0))," \
"StaticSampler(s0, addressU = TEXTURE_ADDRESS_CLAMP, " \
"filter = FILTER_MIN_MAG_MIP_LINEAR )"
Texture2D tx : register(t0);
sampler SS : register(s0);
[RootSignature(MyRS1)]
float4 main( float4 uv : uv ) : SV_Target
{
return tx.Sample( SS, uv );
}
```
#### Two-Pass Compilation
For HLSL shaders, a second option is to use the `--rootsig_macro` command line switch to compile a root signature out of the same source. Here is the same shader, without the `rootsignature` attribute:
```
#define MyRS1 "DescriptorTable(SRV(t0))," \
"StaticSampler(s0, addressU = TEXTURE_ADDRESS_CLAMP, " \
"filter = FILTER_MIN_MAG_MIP_LINEAR )"
Texture2D tx : register(t0);
sampler SS : register(s0);
float4 main( float4 uv : uv ) : SV_Target
{
return tx.Sample( SS, uv );
}
```
If the following command line is used, Intel Shader Analyzer will attempt to compile the input file a second time to obtain the root signature:
IntelShaderAnalyzer.exe -s HLSL --rootsig_macro MyRS1 --api dx12 --profile ps_5_0 filename.hlsl
#### Precompiled Root Signatures
The final option is to supply a pre-compiled, serialized root signature in a separate file, using the following command line:
IntelShaderAnalyzer.exe -s HLSL --rootsig_file rootsig.bin --api dx12 --profile ps_5_0 filename.hlsl
This option may also be used with dxbc input:
IntelShaderAnalyzer.exe -s dxbc --rootsig_file rootsig.bin --api dx12 filename.dxbc
## Command Line
### General-Purpose Options
-l
--list-asics
Print a list of supported device families.
-c
--asic
Add the specified device to the list of compile targets. The device name must be one of the ones returned by --list-asics. By default, all supported asics are compiled.
--api dx11
--api dx12
Set the target API. Default is 'dx11'. Code generation may differ between the dx11 and dx12 drivers. Supported APIs are 'dx11' and 'dx12' Compilation for DX12 requires a root signature.
--isa
Set the directory name for output ISA files. For each target device the compiler will emit a file named .asm
For example:
--isa ./output --asic Skylake
will produce a file named: ./outputSkylake.asm
The default is "./isa_".
-s [hlsl | dxbc]
Set the source language. Valid values are `hlsl` or `dxbc`. The `dxbc`source language may be used for both legacy DX11 bytecode and DXIL. Default is `dxbc`
--rootsig_file
Load a serialized DX root signature from the specified path.
### HLSL Options
--rootsig_profile
Set the compilation profile for root signature compilation. Default is: `rootsig_1_0`.
--rootsig_macro
Sets the macro name for root signature compilation. If this option is specified, and no root signature is provided. The tool will attempt to re-compile the input HLSL source to extract the root signature.
--DXLocation
Set the location of the D3D compiler DLL. The default is `d3dcompiler_47.dll`
--DXFlags
Set the flags for the HLSL compiler. Argument is a bitwise combination of D3DCOMPILE_ flags. See the [MSDN documentation](https://docs.microsoft.com/en-us/windows/desktop/direct3dhlsl/d3dcompile-constants)
-D =
-D
Add a preprocessor define
--profile
-p
Set the shader profile for HLSL compilation. Required.
--function
-f
Set the entrypoint for HLSL compilation. Optional. Default is `main`.
## Running Tests
The tests use a very simple-minded python script.
To run the tests, cd to the 'tests' directory, copy the executable into it (and the driver DLLs, as required). Then run `python run_tests.py`
The script will automatically check exit codes, but it is necessary to manually inspect the output to ensure that the tool is behaving as expected.
The tests need to be run from a bash shell, or a windows shell with GNU 'rm' utilities in the path.