llvm-spirv

Compiles LuisaCompute AST kernels to Vulkan SPIR-V through LLVM's SPIR-V target.

1.0k|108|Updated Nov 20, 2020
One-click install
npx skills add https://github.com/LuisaGroup/LuisaCompute --skill llvm-spirv
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: llvm-spirv
Source: https://github.com/LuisaGroup/LuisaCompute/tree/main/.agents/skills/llvm-spirv
Command: npx skills add https://github.com/LuisaGroup/LuisaCompute --skill llvm-spirv

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It provides an experimental alternative Vulkan codegen path that lowers LuisaCompute AST functions to LLVM IR and emits SPIR-V modules, while enforcing a fail-closed runtime-interface boundary so unsupported kernels are rejected instead of silently miscompiled.

Core Features & Use Cases

  • AST-to-SPIR-V compilation: Lowers Luisa AST kernels through LLVM IR to a spirv64-unknown-vulkan1.2 module via the LLVM-free public facade lc::llvm_codegen::compile_spirv.
  • Fail-closed resource preflight: validate_llvm_vulkan_resource_model rejects kernel arguments, textures, bindless arrays, acceleration structures, and shader printing before lowering, so only no-argument, no-print compute kernels compile.
  • Build integration: Guides CMake (luisa-compute-spirv-llvm) and XMake (lc-spirv-llvm) configuration with component-aware LLVM discovery, ABI checks, and private LLVM headers.
  • Use Case: When extending the backend to support a new AST operation, follow the documented pipeline: implement LLVM IR lowering, extend the property preflight, validate the Vulkan binding shape, and add an end-to-end SPIR-V validator test.

Quick Start

Compile a no-argument compute kernel through the public facade and validate the returned SPIR-V module with SPIRV-Tools under SPV_ENV_VULKAN_1_2.

Frequently Asked Questions about llvm-spirv

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I compile a LuisaCompute kernel to SPIR-V with LLVM?

Call lc::llvm_codegen::compile_spirv(kernel, option) through the public header spirv_llvm/spirv_llvm.h. The facade runs target registration, AST lowering, aggregate legalization, post-processing, and Vulkan validation, returning SPIR-V words and properties.

What is the difference between the LLVM SPIR-V backend and the XIR SPIR-V backend?

They are mutually exclusive Vulkan codegen paths selected at build time. The LLVM path lowers AST through LLVM IR, embeds constants in the module, and uses the LLVM_SPIRV artifact dialect, while the native XIR path has its own optimizer and exact per-argument role plan.

Which kernels does the LLVM SPIR-V backend currently support?

Only no-argument, no-print compute kernels whose operations are implemented by the visitor. The resource preflight rejects all kernel arguments, textures, bindless arrays, acceleration structures, custom resources, and shader printing before lowering.

How do I enable the LLVM SPIR-V backend in CMake or XMake?

In CMake set LUISA_COMPUTE_ENABLE_VK_AST_LLVM_SPIRV=ON and LUISA_COMPUTE_ENABLE_VK_XIR_SPIRV=OFF. In XMake set lc_vk_backend_use_ast_llvm_spirv=true with lc_llvm_path pointing to an LLVM prefix or llvm-config.

Why does the LLVM SPIR-V backend reject my kernel with buffer arguments?

The property preflight validate_llvm_vulkan_resource_model intentionally rejects every kernel argument because no real descriptor ABI exists yet. Provisional global-variable lowering exists, but the preflight blocks those kernels until the Vulkan binding shape is validated.

Can I expose LLVM headers through the public spirv_llvm facade?

No. The facade must stay LLVM-header-free so consumers do not inherit LLVM include directories or preprocessor definitions. Keep LLVM includes private and fix link failures through proper component linkage instead.