llvm-spirv

name	llvm-spirv
description	Experimental Vulkan AST-to-LLVM-to-SPIR-V backend, its fail-closed runtime-interface boundary, LLVM build integration, and validation path.

LLVM SPIR-V Codegen

The experimental backend lives in src/backends/common/spirv_llvm/. It lowers a Luisa AST Function to LLVM IR and asks LLVM's native SPIR-V target to emit a spirv64-unknown-vulkan1.2 module.

This is not the native XIR-to-SPIR-V path. The two Vulkan codegen selections are mutually exclusive:

• CMake: LUISA_COMPUTE_ENABLE_VK_AST_LLVM_SPIRV=ON and LUISA_COMPUTE_ENABLE_VK_XIR_SPIRV=OFF;
• XMake: lc_vk_backend_use_ast_llvm_spirv=true, with lc_llvm_path pointing to an LLVM installation/build prefix or its llvm-config.

The public entry is deliberately LLVM-header-free:

#include <spirv_llvm/spirv_llvm.h>

auto result = lc::llvm_codegen::compile_spirv(kernel, option);

Do not expose an LLVM type through spirv_llvm.h or llvm_codegen_result.h; consumers of the static facade must not inherit LLVM include directories or unrelated LLVM preprocessor definitions.

Current support boundary

The Vulkan descriptor interface is preflighted before AST lowering by validate_llvm_vulkan_resource_model. At present it rejects:

• every kernel argument, including ordinary value arguments and direct buffers;
• textures, bindless arrays, acceleration structures, custom/indirect resources, and their global heaps;
• shader printing.

Consequently the current end-to-end Vulkan contract is intentionally narrow: no-argument, no-print compute kernels whose operations are implemented by the visitor. The successful interface contains only the fixed 16-entry immutable sampler property. Do not describe the visitor's partial resource stubs as runtime support, and do not bypass this preflight merely because LLVM happens to emit some SPIR-V for an address-space global.

Unsupported AST operations call LUISA_NOT_IMPLEMENTED or otherwise fail closed. Returning zero, undef, or a no-op is not an acceptable way to claim support. When expanding the backend, implement the LLVM IR lowering, extend the property preflight, validate the Vulkan runtime binding shape, and add an end-to-end SPIR-V validator test together.

Source map

Files	Responsibility
spirv_llvm.h/.cpp	LLVM-free facade and once-only SPIR-V target registration
llvm_codegen_result.h	SPIR-V words, properties, printer records, and global bindless flags returned to Vulkan
llvm_codegen_stack_data.h/.cpp	Per-compilation state and mutex-protected reusable state pool
llvm_codegen_utility.h/.cpp	Type/constant/function lowering, module legalization, target-machine emission, post-processing, and validation
llvm_state_visitor.h/.cpp	AST expression and statement lowering through llvm::IRBuilder<>
llvm_compat.h	API-detection boundary for LLVM-version differences such as nullable terminator lookup
vulkan_binding_properties.h	Pure property planner and fail-closed resource-model support check
CMakeLists.txt / xmake.lua	Component-aware LLVM discovery and static-facade linkage

Compilation pipeline

LLVMCodegenUtility::CompileSPIRV owns the complete path:

1. Create a fresh LLVM context/module/builder and register LLVM's SPIR-V target exactly once with std::call_once.
2. Initialize a spirv64-unknown-vulkan1.2 target machine and its data layout.
3. Detect prospective bindless/property usage from the AST, validate the current Vulkan resource-model boundary, and freeze the property plan before visiting the AST.
4. Lower the kernel and reachable callables to LLVM IR. A compute entry is named main, has no function parameters, and carries hlsl.shader=compute plus hlsl.numthreads attributes.
5. Before target emission, recursively scalarize aggregate loads/stores, lower aggregate returns to void plus an out pointer, scalarize again, and verify the LLVM module.
6. Emit object bytes through LLVM's legacy pass manager. The expected output is raw SPIR-V words; an ELF result is not silently accepted as valid SPIR-V and will fail the final validator (there is no ELF section extractor yet).
7. Strip LLVM's Addresses/Linkage capabilities and linkage decorations, and convert OpPtrAccessChain forms to their logical-addressing counterparts.
8. Validate the returned module with SPIRV-Tools under SPV_ENV_VULKAN_1_2.

Unlike the native path, this backend currently has no SPIRV-Tools optimizer stage and does not produce the native exact per-argument role plan. Vulkan serializes it as LLVM_SPIRV, embeds constants directly in the module, and uses the backend's conservative SPIR-V artifact feature requirements.

Function and control-flow rules

• Vulkan entry points have no LLVM function parameters. The current code has provisional global-variable lowering for arguments, but the property preflight rejects those kernels until a real descriptor ABI exists.
• Callable arguments remain LLVM function parameters.
• Save and restore the builder insertion point, current function, and variable map around recursive callable generation.
• Probe incomplete blocks through llvm_compat.h::terminator_or_null; do not guess the API from an LLVM major version.
• Verify the full module before invoking LLVM target passes. Per-function verification warnings are useful during construction but do not replace the module check.
• Aggregate legalization is mandatory because the LLVM SPIR-V target cannot reliably legalize the aggregate memory/return forms produced here.

Target initialization

InitializeLLVMSPIRVTarget registers global LLVM state in dependency order:

LLVMInitializeSPIRVTargetInfo();
LLVMInitializeSPIRVTarget();
LLVMInitializeSPIRVTargetMC();
LLVMInitializeSPIRVAsmPrinter();

Use the declarations from <llvm/Support/TargetSelect.h>. Hand-written declarations can acquire the wrong language linkage. Keep the std::call_once guard because shader compilation may be concurrent.

The target triple is deliberately spirv64: the supported LLVM revision's spirv32 path fails in pointer-cast legalization. Vulkan logical addressing is restored by the checked post-processing step and then enforced by validation; raw EmitSPIRV() output is not the public contract.

CMake integration

The target is luisa-compute-spirv-llvm. It is created only when Vulkan and LUISA_COMPUTE_ENABLE_VK_AST_LLVM_SPIRV are enabled. The Vulkan plugin also links luisa-compute-spirv, because the shared artifact codec still needs the native/common SPIR-V validation and feature-reconciliation utilities.

src/backends/common/spirv_llvm/CMakeLists.txt must:

• find_package(LLVM CONFIG REQUIRED) without allowing LLVMConfig.cmake to overwrite the project's CMAKE_MSVC_RUNTIME_LIBRARY default;
• require an exact SPIRV token in LLVM_TARGETS_TO_BUILD and locate llvm/IR/IntrinsicsSPIRV.h in LLVM's reported include directories;
• keep LLVM includes and ordinary definitions private;
• compile-check _GLIBCXX_USE_CXX11_ABI and propagate only that ABI macro through the C++ facade when LLVM reports it;
• request core, support, bitwriter, transformutils, analysis, codegen, target, mc, spirvcodegen, spirvdesc, spirvinfo, and spirvanalysis through LLVM's component mapper;
• use llvm_config(... USE_SHARED ...) when a monolithic LLVM target exists so target-specific archives omitted by the dylib remain linked;
• reject incompatible Windows CRT families or Debug iterator modes, and stage and install a monolithic LLVM DLL when that is the selected import.

The facade is static, so implementation link dependencies must still reach the final Vulkan plugin/test link. Do not make LLVM headers public as a workaround for a link failure.

XMake integration

The target is lc-spirv-llvm. Configuration requires an explicit lc_llvm_path. Keep lc_vk_backend_use_xir_spirv=false when selecting it: the top-level configuration rejects an explicit conflict, while the option hook forces lc_enable_xir on and normalizes the native option off. The SPIR-V targets and tests are created only when the Vulkan backend itself is enabled.

Treat the selected llvm-config as the source of truth:

• accept an executable path, install prefix, build prefix, or common source-tree build layout;
• parse --quote-paths output with os.argv, including all -I paths from --cppflags so generated intrinsics headers in development trees are found;
• require an exact SPIRV token from --targets-built;
• query --shared-mode for the complete component set before selecting --link-shared or --link-static;
• use static LLVM components on Windows because llvm-config reports DLL filenames rather than MSVC import libraries for shared mode;
• propagate shared-library rpaths on Unix and the required component system libraries on every platform;
• verify the libstdc++ ABI and, on Windows, the CRT family and Debug/non-Debug mode before compiling the facade.

Vulkan artifact boundary

The LLVM result reuses hlsl::Property and the common Vulkan artifact codec, but it is a distinct LLVM_SPIRV dialect:

• do not apply native XIR capability reconciliation or exact accel-role rules to LLVM artifacts;
• constants are embedded in SPIR-V, so there is no constant-UBO payload;
• saved arguments use the legacy/unspecified resource-role sentinel;
• loaded modules are still integrity-checked and Vulkan-validated before pipeline creation.

Tests

test_spirv_llvm_facade is registered only when the LLVM facade target exists. It compiles a no-argument kernel through the public header, checks the fixed sampler property, and independently validates/disassembles the returned module for Vulkan 1.2. test_vk_shader_binary_contract separately covers the common artifact boundary under the LUISA_AST_LLVM_TO_SPIRV dialect define.

When adding support, include at least:

1. a pure property-preflight rejection/acceptance test;
2. a public-facade compile test;
3. independent SPV_ENV_VULKAN_1_2 validation;
4. a Vulkan artifact round trip when properties or feature contracts change;
5. a runtime Vulkan test before claiming descriptor or dispatch support.

Diagnostics and pitfalls

• EmitSPIRV() writes llvm_ir_debug.ll in the process working directory.
• Missing SPIR-V intrinsics or target components are configuration errors, not reasons to guess library filenames or add every LLVM archive.
• getDeclarationIfExists() may return null. Handle that at the operation's semantic boundary; never call through a null intrinsic declaration.
• Do not call EmitSPIRV() directly from Vulkan. Only the public facade runs required post-processing and Vulkan validation.
• Do not report an AST opcode as supported merely because a visitor case exists; it must survive resource preflight, LLVM verification, SPIR-V emission, Vulkan validation, artifact loading, and runtime dispatch.