xir_passes

Author and test XIR transformation passes for the LuisaCompute compiler IR.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Writing compiler transformation passes for LuisaCompute's XIR intermediate representation requires deep knowledge of non-obvious API conventions, terminator semantics, and mutation patterns; this Skill captures that hard-won knowledge so you avoid common pitfalls like invalid casts, wrong setter names, and unsafe instruction-list mutation.

Core Features & Use Cases

  • Pass authoring conventions: Standard <Name>Info POD interface, module/function entry points, PassReport statistics, and PassPipeline integration with fixed-point sub-pipelines.
  • API reference and pitfalls catalogue: Complete terminator inventory (BranchInst, SwitchInst, LoopInst, RayQueryLoopInst, etc.), XIRBuilder usage, two-phase collect-rewrite mutation idiom, and a list of mistakes that compile but break passes.
  • Memory-effect classification: Purity tables for GVN, DCE, and SCCP passes using get_memory_info(), plus LLVM pass equivalents for cross-referencing implementations.
  • Use Case: You need to implement a new CFG simplification pass under src/xir/passes/. This Skill tells you exactly where to put the header and implementation, how to register it in CMake, how to write Boost.UT tests with reachable test blocks, and which API traps to avoid.

Quick Start

Use the xir_passes skill to help me implement a new XIR transformation pass under src/xir/passes/ with proper registration and unit tests.

Frequently Asked Questions about xir_passes

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

FAQPage Schema
How do I write a new XIR transformation pass in LuisaCompute?

Create a header in include/luisa/xir/passes/ and implementation in src/xir/passes/, register it in src/xir/CMakeLists.txt, and expose a <Name>Info POD with function-level and module-level entry points. Add tests in src/tests/unit/xir/ following existing test_xir_pass_* files.

How do I safely mutate XIR instructions while iterating basic blocks?

Use the two-phase collect-rewrite idiom: first traverse blocks to collect target instructions into a vector, then mutate them in a second loop. Never modify the instruction list during traversal, and wrap in a fixed-point loop if rewrites create new candidates.

Does XIR have LLVM-style cast or cast_or_null helpers?

No, XIR does not provide cast_or_null or LLVM-style cast. Use v->isa<SomeType>() followed by static_cast<SomeType*>(v), and use func->definition() to safely obtain a FunctionDefinition pointer that returns nullptr for external functions.

Why does my XIR pass skip basic blocks I created in a test?

traverse_basic_blocks only visits blocks reachable from body_block. Orphan test blocks are silently skipped, so wire them up with br or cond_br from the entry block, for example using a constant-true conditional branch.

Which XIR instructions are safe to remove in dead code elimination?

Only pure or memory-reading instructions with empty use lists are removable, such as ARITHMETIC, CAST, GEP, LOAD, and RESOURCE_QUERY. Never remove stores, atomics, calls to definitions, prints, or asserts; use get_memory_info() from helpers.h to check effects.

What LLVM passes correspond to XIR passes for reference?

The skill includes a mapping table: dce maps to LLVM DCE.cpp, gvn to GVN.cpp, mem2reg to Mem2Reg.cpp, restructure_cfg to StructurizeCFG.cpp, and licm to LICM.cpp. XIR-specific passes like autodiff and convergence_region have no LLVM equivalent.