Mastering Intel IGC 2.34.4: A Hands-On Guide to Compiling Shaders and Compute Kernels

Overview

The Intel Graphics Compiler (IGC) is a critical component in Intel's graphics software stack, responsible for translating high-level shader programs (e.g., OpenCL C, SPIR-V, HLSL) into optimized machine code for Intel GPUs. Version 2.34.4 introduces numerous enhancements, including improved performance, bug fixes, and expanded feature support. This tutorial will walk you through setting up and using IGC 2.34.4, from installation to compiling your first kernel, with practical examples and troubleshooting tips.

Prerequisites

Before diving into IGC, ensure your system meets the following requirements:

• Intel GPU: Intel HD Graphics 500 series or newer (Gen9+). IGC supports integrated and discrete Intel GPUs.
• Operating System: Linux (Ubuntu 20.04+ or Fedora 33+) or Windows 10/11. This guide focuses on Linux.
• Intel Compute Runtime: Version 23.09.0 or later, which bundles IGC 2.34.4. Download from GitHub releases.
• Development Tools: Git, CMake (3.16+), and a C++ compiler (GCC 9+ or Clang 10+).
• Knowledge: Basic familiarity with command line, GPU programming concepts, and OpenCL or Vulkan.

Step-by-Step Instructions

1. Install Intel Compute Runtime

The easiest way to get IGC 2.34.4 is through the Intel Compute Runtime package. Follow these steps:

1. Add the Intel GPU repository for your Linux distribution. For Ubuntu 22.04:

   sudo apt update
   sudo apt install -y wget gnupg2
   wget -O- https://repositories.intel.com/gpu/intel-graphics.key | sudo gpg --dearmor -o /usr/share/keyrings/intel-graphics.gpg
   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy unified" | sudo tee /etc/apt/sources.list.d/intel-gpu.list
   sudo apt update

2. Install the Intel Compute Runtime:

sudo apt install intel-opencl-icd intel-level-zero-gpu level-zero

3. Verify installation by checking the IGC version:

ls /usr/lib/intel-opencl/
# Look for libigc.so, then run:
strings /usr/lib/intel-opencl/libigc.so | grep "IGC version"
# You should see "IGC version 2.34.4"

2. Compile IGC from Source (Optional)

If you need to modify IGC or get the latest code, build from source:

1. Clone the repository:

git clone https://github.com/intel/intel-graphics-compiler.git
cd intel-graphics-compiler
git checkout tags/igc-2.34.4 -b build-2.34.4

2. Initialize submodules:

git submodule update --init --recursive

3. Create a build directory and configure with CMake:

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DIGC_BUILD_OpenCL=ON

4. Build (using all cores):

make -j$(nproc)

5. Install:

sudo make install

3. Basic Usage: Compiling an OpenCL Kernel

IGC is typically invoked automatically by the OpenCL runtime, but you can use the standalone igc command-line tool for testing. First, ensure it's in your PATH (installed with Compute Runtime).

Create a simple OpenCL C kernel file kernel.cl:

__kernel void vector_add(__global const float* a, __global const float* b, __global float* c, int n) {
    int i = get_global_id(0);
    if (i < n) c[i] = a[i] + b[i];
}

Compile it to SPIR-V:

igc kernel.cl -o kernel.spv - -cl-std=CL3.0 -c

This produces a SPIR-V binary. To further compile to Intel-native ISA (GEN binary), use:

igc kernel.spv -o kernel.gen - -target=gen

You can inspect the generated assembly with the --asm flag:

igc kernel.cl --asm

4. Advanced Options and Optimizations

IGC supports many flags to optimize for specific GPU variants. For example:

• -gpu-platform: Specify GPU generation (e.g., -gpu-platform Gen12LP for Tiger Lake).
• -cl-opt-disable: Disable all optimizations (useful for debugging).
• -cl-single-precision-constant: Treat double constants as single precision.
• -Werror: Treat warnings as errors.

Example for compilation targeting ADL-P (Alder Lake):

igc kernel.cl -o kernel.bin - -target=gen -gpu-platform Gen12LP -O2

Use the -h flag to see all options.

5. Integration with Level Zero

For compute workloads, IGC works seamlessly with the Level Zero API. The Intel Compute Runtime uses IGC behind the scenes. To test, install level-zero-tools and run a sample:

sudo apt install level-zero-tools
ze_simple_compute

This compiles and runs a simple kernel. For custom kernels, use the Level Zero loader and compile SPIR-V to native code via zeModuleCreate. Refer to the Level Zero tests for examples.

Common Mistakes

1. Missing or Incompatible Drivers

Error: cannot find -lze_loader or IGC: Not supported on this GPU.

Solution: Ensure you have the latest Intel GPU drivers and that your hardware is Gen9+. Run lspci -nn | grep -i VGA and check the device ID against Intel's documentation.

2. Wrong SPIR‑V Version

IGC 2.34.4 supports SPIR‑V 1.5 (with extensions). If you compile with an older version, the shader may fail. Use the -cl-std=CL3.0 flag to generate proper SPIR‑V.

3. Missing Submodules When Building from Source

The git submodule update --init --recursive step is often forgotten, leading to build failures for missing LLVM or SPIRV‑Tools. Always run it.

4. Using Incompatible Compiler Flags

Some flags conflict (e.g., -g and -O2). Use only one optimization level (-Os, -O1, -O2). For debugging, use -O0 -g.

Summary

Intel IGC 2.34.4 brings significant improvements for GPU compute and shading. By following this guide, you have set up the compiler, compiled an OpenCL kernel, and learned about advanced options and common pitfalls. Experiment with the standalone tool and integrate it into your projects to harness Intel GPU performance. For further details, consult the official IGC GitHub repository.