Implementation:Ggml org Ggml Vulkan shader gen

Metadata

Field	Value
Page Type	Implementation (API Doc)
Knowledge Sources	GGML
Domains	ML_Infrastructure, GPU_Computing, Build_Tooling
Last Updated	2025-05-15 12:00 GMT

Overview

Standalone build tool that compiles GLSL compute shaders into SPIR-V and generates C++ source files with embedded shader binary data for the Vulkan backend.

Description

vulkan-shaders-gen.cpp is a build-time executable (1204 lines) that bridges GLSL shader source and C++ compilation. It provides:

1. Shader compilation: Invokes the glslc compiler (from the Vulkan SDK) to compile GLSL compute shaders into SPIR-V binary format. Uses a thread pool with up to 64 concurrent processes (ASYNCIO_CONCURRENCY) for parallel compilation.
2. Quantization type support: Maintains a comprehensive list of quantization type names (f32, f16, q4_0, q4_1, q5_0, q5_1, q8_0, q2_k through q6_k, iq1_s through iq4_nl, mxfp4, bf16) that are used to generate type-specific shader variants.
3. Matrix multiplication variants: Supports MatMulIdType variants (NONE, DEFAULT, SUBGROUP) for different GPU capabilities (e.g., subgroup operations for cooperative matrix multiply).
4. Cross-platform subprocess execution: Implements subprocess management for both Windows (via CreateProcess) and Unix (via fork/exec), capturing stdout and stderr for error reporting.
5. C++ code generation: Generates a .hpp header file and a .cpp source file containing embedded SPIR-V binary data as C++ arrays. This allows the Vulkan backend to load shaders without filesystem access at runtime.
6. Dependency tracking: Generates depfiles for incremental builds, so shaders are only recompiled when their sources change.

Usage

This tool is invoked by the CMake build system during compilation. It is not used at runtime. The generated ggml-vulkan-shaders.hpp and .cpp files are compiled into the Vulkan backend library.

Code Reference

Source Location

GGML repo, file: src/ggml-vulkan/vulkan-shaders/vulkan-shaders-gen.cpp (1204 lines).

Signatures

// Command-line executable with main()
int main(int argc, char ** argv);

// Internal functions:
void execute_command(std::vector<std::string> & command, std::string & stdout_str, std::string & stderr_str);

Import

// This is a standalone executable; no library import is needed.
// At build time, invoked as:
//   vulkan-shaders-gen --glslc <path> --input <shader.comp> --output <dir> --target-hpp <file> --target-cpp <file>

I/O Contract

Inputs

Parameter	Type	Required	Description
--glslc	command-line arg	Yes	Path to the glslc GLSL-to-SPIR-V compiler executable.
--input	command-line arg	Yes	Path to the input GLSL shader file.
--output	command-line arg	Yes	Directory for intermediate SPIR-V output files (default: /tmp).
--target-hpp	command-line arg	Yes	Path for the generated C++ header file containing shader declarations.
--target-cpp	command-line arg	Yes	Path for the generated C++ source file containing embedded SPIR-V data.

Outputs

Output	Type	Description
C++ header file	file (.hpp)	Declares extern arrays and size constants for each compiled shader variant.
C++ source file	file (.cpp)	Defines arrays containing the raw SPIR-V binary data for each shader variant.
SPIR-V binaries	files (.spv)	Intermediate compiled shader files in the output directory.

Usage Examples

# Build-time invocation by CMake:
vulkan-shaders-gen \
    --glslc /usr/bin/glslc \
    --input src/ggml-vulkan/vulkan-shaders/mul_mat.comp \
    --output /tmp/vulkan-shaders \
    --target-hpp build/ggml-vulkan-shaders.hpp \
    --target-cpp build/ggml-vulkan-shaders.cpp

// The generated header is included by the Vulkan backend:
#include "ggml-vulkan-shaders.hpp"

// Shaders are then available as embedded arrays, e.g.:
// extern const unsigned char mul_mat_f32_f32_data[];
// extern const unsigned int  mul_mat_f32_f32_len;

Related Pages

• Principle:Ggml_org_Ggml_Vulkan_GPU_Computation
• Implementation:Ggml_org_Ggml_Vulkan_backend
• Implementation:Ggml_org_Ggml_Vulkan_backend_api