Llvm Spirv

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

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.