spirv_codegen

Lowers XIR kernels to validated SPIR-V 1.5 for the Vulkan backend.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It guides work on LuisaCompute's native XIR-to-SPIR-V code generator, where incorrect legalization, descriptor binding, or control-flow emission produces invalid Vulkan shaders that fail validation or misbehave at runtime.

Core Features & Use Cases

  • Compilation pipeline guidance: Documents the two compile entries (compile_spirv, compile_spirv_xir), the mandatory AST-to-XIR legalization pipeline, and the fail-closed dialect validation boundary.
  • Structured control flow and Phi emission: Explains the frozen ControlFlowPlan, native OpPhi emission, and rules for loop headers, merges, and forwarding blocks.
  • Vulkan ABI and target features: Covers descriptor set layout, bindless heaps, buffer layout fallback planning, ray-query traversal loops, and the persisted required-feature mask contract.
  • Use Case: When adding a new XIR opcode or fixing a SPIR-V validation failure in the Vulkan backend, follow this Skill to classify the opcode in the dialect, update the opcode-matrix test, and emit code that passes SPV_ENV_VULKAN_1_2 validation.

Quick Start

Ask the AI to add support for a new XIR opcode in the native SPIR-V codegen following the dialect boundary and validation rules in this skill.

Frequently Asked Questions about spirv_codegen

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

FAQPage Schema
How do I add a new XIR opcode to the SPIR-V codegen?

Classify the opcode in `validate_spirv_xir_codegen_dialect` as supported, semantic no-op, or unsupported, then validate operand counts, types, and storage classes. Add a focused diagnostic, update the opcode-matrix test, and add an exact codegen test if accepted.

How does the native SPIR-V path differ from the LLVM SPIR-V path?

The native path in `spirv_codegen/` lowers XIR directly with glslang's `spv::Builder`, while `spirv_llvm/` implements a separate AST-to-LLVM-to-SPIR-V pipeline. This skill covers only the native path enabled by `LUISA_COMPUTE_ENABLE_VK_XIR_SPIRV`.

Why does SPIR-V validation fail after XIR emission?

The pre-optimization module must already be valid; the optimizer is never a repair step. Check dialect handoff violations such as mismatched load/store types, invalid texture texel widths, or Phi placement rules before blaming SPIRV-Tools.

Does the codegen support VariablePointers for callable arguments?

No. Callable ABI failures are solved by fixed-point specialization of buffer, bindless, and resource arguments at call sites, not by enabling `VariablePointers` globally. Only safe opaque/resource modes remain as callable parameters.

How are Vulkan target features tracked and persisted?

Emission calls `_require_target_feature` at each semantic site, then capability-owned bits are reconciled from the final validated binary while emission-owned bits stay provisional. The persisted mask is checked exactly against the enabled logical-device features on load.

When should OpSpecConstantOp be used for constant arithmetic?

Never in this backend. The runtime exposes no specialization-constant ABI, so ordinary XIR arithmetic emits ordinary SPIR-V instructions, and constant folding belongs in the XIR or SPIRV-Tools optimization layers.