# Ir Pipeline

> Ir Pipeline is an Agent Skill for development published in the LuisaGroup/LuisaCompute repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

IR and XIR compiler pipeline, AST translation, SSA-based IR, instruction set, optimization passes, and control flow representation in LuisaCompute

- Skill name: `ir_pipeline`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/LuisaGroup/LuisaCompute/blob/HEAD/.agents/skills/ir_pipeline/SKILL.md
- Repository: LuisaGroup/LuisaCompute (1,031 GitHub stars when collected)

## SKILL.md

# LuisaCompute IR and XIR Pipeline

## Overview

LuisaCompute has two intermediate representations:

| Aspect | IR (Legacy) | XIR (New/Preferred) |
|--------|-------------|---------------------|
| **Location** | `src/ir/`, `include/luisa/ir/` | `src/xir/`, `include/luisa/xir/` |
| **Implementation** | Rust-based (via `src/rust/`) | Pure C++ |
| **JSON Serialization** | `ast2json` → Rust IR | Native `xir2json`/`json2xir` |
| **Status** | Maintained for compatibility | Active development |
| **SSA Form** | Yes | Yes (with mem2reg pass) |
| **Basic Blocks** | Yes | Yes |

Both paths start from the same AST (`src/ast/`) and feed into backend codegen.

---

## Compiler Pipeline Flow

```
User C++ DSL / Python
         │
         ▼
┌─────────────────┐
│   DSL Tracing   │  src/dsl/ — captures C++ lambdas into AST
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│       AST       │  src/ast/ — expression/statement tree
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌──────────┐
│  XIR   │ │   IR     │  src/xir/ (new) / src/ir/ (legacy)
│transl. │ │transl.   │
└───┬────┘ └────┬─────┘
    │           │
    ▼           ▼
┌─────────────────┐
│  Backend Codegen│  src/backends/<name>/
│  + Compilation  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  GPU Execution  │  src/runtime/
└─────────────────┘
```

**Rust IR path**: `src/rust/luisa_compute_ir/` performs additional transforms (autodiff, DCE, SSA, vectorize) before backend codegen.

**XIR path**: Pure C++ pipeline with `ast2xir` translator and XIR optimization passes.

---

## AST → IR Translation (Legacy)

**File**: `src/ir/ast2ir.cpp`

1. **AST → JSON**: Uses `to_json(function)` to serialize AST to JSON
2. **JSON → Rust IR**: Calls Rust FFI functions:
   - `ir::luisa_compute_ir_ast_json_to_ir_kernel()` for kernels
   - `ir::luisa_compute_ir_ast_json_to_ir_callable()` for callables
   - `ir::luisa_compute_ir_ast_json_to_ir_type()` for types

```
AST Function → JSON String → Rust IR Module → CArc<KernelModule/CallableModule>
```

**Key legacy IR classes** (defined in Rust, used via C FFI):
- `ir::KernelModule` / `ir::CallableModule`
- `ir::Node` — IR nodes (intrusive linked list)
- `ir::Instruction` — Local, Call, Phi, Loop, If, Switch, RayQuery, AdScope, etc.
- `ir::Type` — Type representation
- `ir::BasicBlock` — Basic block structure

---

## AST → XIR Translation

**File**: `src/xir/translators/ast2xir.cpp`

Direct C++ implementation using `XIRBuilder` API.

### Translation Context (`AST2XIRContext`)
- Maps AST variables to XIR Values
- Tracks break/continue target blocks
- Handles autodiff adjoint variables
- Manages constant/literal caching

### Expression Translation

| AST Expression | XIR Instruction |
|----------------|-----------------|
| `UnaryExpr` | `ArithmeticOp` (UNARY_MINUS, UNARY_BIT_NOT) |
| `BinaryExpr` | `ArithmeticOp` (BINARY_ADD, etc.) |
| `MemberExpr` | `EXTRACT`/`SHUFFLE` or `GEP` |
| `AccessExpr` | `GEP` + `LOAD` |
| `LiteralExpr` | `Constant` |
| `RefExpr` | Variable lookup or `SpecialRegister` |
| `CallExpr` | Various opcodes based on `CallOp` |
| `CastExpr` | `CastInst` (STATIC_CAST, BITWISE_CAST) |

### Statement Translation

| AST Statement | XIR Control Flow |
|---------------|------------------|
| `IfStmt` | `IfInst` + true/false/merge blocks |
| `SwitchStmt` | `SwitchInst` + case/default/merge blocks |
| `ForStmt` | `LoopInst` (prepare/body/update/merge) |
| `LoopStmt` | `SimpleLoopInst` (do-while style) |
| `BreakStmt` | `BreakInst` |
| `ContinueStmt` | `ContinueInst` |
| `ReturnStmt` | `ReturnInst` |
| `AutoDiffStmt` | `AutodiffScopeInst` |

---

## XIR Core Architecture

### Value Hierarchy

```
Value (base class)
├── GlobalValue (module-scoped)
│   ├── Function
│   │   ├── KernelFunction (entry point with block size)
│   │   ├── CallableFunction (user-defined functions)
│   │   └── ExternalFunction (external linkage)
│   ├── Constant (literal values)
│   ├── Undefined (placeholder for undef)
│   └── SpecialRegister (builtin variables)
│       ├── SPR_ThreadID, SPR_BlockID, SPR_DispatchID, etc.
├── FunctionScopeValue (function-scoped)
│   └── BasicBlock (container for instructions)
└── BlockScopeValue (block-scoped)
    └── Instruction (computation)
        ├── TerminatorInstruction (control flow)
        │   ├── BranchInst
        │   ├── ConditionalBranchInst
        │   ├── IfInst, SwitchInst, LoopInst, etc.
        │   └── ReturnInst
        └── Non-terminator instructions
```

### Key Classes

#### Module (`include/luisa/xir/module.h`)
- Container for all global values
- Creates/manages functions, constants, undefined values, special registers
- Uniquifies constants via hash table

#### Function (`include/luisa/xir/function.h`)
- `ArgumentList` — function parameters
- `BasicBlockList` — CFG nodes
- `FunctionDefinition` — for kernels/callables with body blocks
- Traversal: `traverse_basic_blocks()`, `traverse_instructions()`

#### BasicBlock (`include/luisa/xir/basic_block.h`)
- `InstructionList` — sequential instructions
- `is_terminated()`, `terminator()` — control flow queries
- `traverse_predecessors()`, `traverse_successors()` — CFG navigation

#### Instruction (`include/luisa/xir/instruction.h`)
- Derived via `DerivedInstruction<>` template
- `is_terminator()` — ends basic block
- `control_flow_merge()` — for structured control flow
- `clone()` — for pass transformations

#### Value & Use (`include/luisa/xir/value.h`, `use.h`)
- **SSA Form**: Each value has a `UseList` tracking all users
- `replace_all_uses_with()` — for substitution
- `is_lvalue()` — for memory operations (alloca, gep results)

---

## XIR Instruction Set

### Control Flow Instructions

| Instruction | Purpose | Blocks |
|-------------|---------|--------|
| `IfInst` | Conditional branch | true, false, merge |
| `SwitchInst` | Multi-way branch | cases, default, merge |
| `LoopInst` | For/while loops | prepare, body, update, merge |
| `SimpleLoopInst` | Do-while loops | body, merge |
| `BranchInst` | Unconditional jump | target |
| `ConditionalBranchInst` | Branches on condition | true, false |
| `ReturnInst` | Function return | — |
| `BreakInst` / `ContinueInst` | Loop control | target |
| `UnreachableInst` | Unreachable code | — |

### Memory Instructions

| Instruction | Purpose |
|-------------|---------|
| `AllocaInst` | Stack allocation (LOCAL/SHARED) |
| `LoadInst` | Read from memory |
| `StoreInst` | Write to memory |
| `GEPInst` | Get element pointer (indexing) |

### SSA Instructions

| Instruction | Purpose |
|-------------|---------|
| `PhiInst` | Phi node for SSA (block, value) pairs |

### Arithmetic Instructions (`ArithmeticOp`)

**Unary**: `UNARY_MINUS`, `UNARY_BIT_NOT`

**Binary**: `BINARY_ADD`, `SUB`, `MUL`, `DIV`, `MOD`, `BIT_AND`, `BIT_OR`, `BIT_XOR`, `SHIFT_LEFT`, `SHIFT_RIGHT`, `ROTATE_LEFT`, `ROTATE_RIGHT`, comparison ops

**Math**: `ABS`, `MIN`, `MAX`, `CLAMP`, `SATURATE`, `LERP`, `SMOOTHSTEP`, trigonometric, exponential, logarithmic

**Vector/Matrix**: `DOT`, `CROSS`, `NORMALIZE`, `MATRIX_COMP_MUL`, `MATRIX_LINALG_MUL`, `MATRIX_DETERMINANT`, `MATRIX_TRANSPOSE`, `MATRIX_INVERSE`

**Aggregate**: `AGGREGATE`, `SHUFFLE`, `EXTRACT`, `INSERT`

### Resource Instructions

| Category | Operations |
|----------|-----------|
| `ResourceQueryOp` | Buffer/texture size, bindless queries, ray tracing queries |
| `ResourceReadOp` | Buffer read, texture read, bindless read |
| `ResourceWriteOp` | Buffer write, texture write, ray tracing updates |

### Atomic Instructions (`AtomicOp`)

`EXCHANGE`, `COMPARE_EXCHANGE`, `FETCH_ADD`, `FETCH_SUB`, `FETCH_AND`, `FETCH_OR`, `FETCH_XOR`, `FETCH_MIN`, `FETCH_MAX`

### Thread Group Instructions (`ThreadGroupOp`)

Warp operations, block synchronization, shader execution reordering, raster quad derivatives

### Ray Query Instructions

`RayQueryLoopInst`, `RayQueryDispatchInst`, `RayQueryObjectReadInst`, `RayQueryObjectWriteInst`, `RayQueryPipelineInst`

### Autodiff Instructions

`AutodiffScopeInst`, `AutodiffIntrinsicInst` (requires_gradient, gradient, accumulate_gradient, backward, detach)

---

## XIR Optimization Passes

**Location**: `src/xir/passes/`

### Core Passes

| Pass | File | Purpose |
|------|------|---------|
| **DCE** | `dce.cpp` | Removes unused instructions, unreachable blocks, dead allocas; evaluates static branches |
| **Mem2Reg** | `mem2reg.cpp` | Promotes allocas to SSA registers using dominance tree and frontiers; inserts PHI nodes |
| **Dominance Tree** | `dom_tree.cpp` | Cooper et al. 2001 algorithm; computes immediate dominators and dominance frontiers |
| **Early Return Elimination** | `early_return_elimination.cpp` | Converts early returns to structured control flow |

### Analysis Passes

| Pass | File | Purpose |
|------|------|---------|
| **Call Graph** | `call_graph.cpp` | Call graph analysis |
| **Pointer Usage** | `pointer_usage.cpp` | Pointer usage analysis |
| **Lexical Scope** | `lex_scope_analysis.cpp` | Lexical scope analysis |
| **Aggregate Field Bitmask** | `aggregate_field_bitmask.cpp` | Aggregate field usage analysis |

### Transformation Passes

| Pass | File | Purpose |
|------|------|---------|
| **SROA** | `sroa.cpp` | Scalar replacement of aggregates |
| **Outline** | `outline.cpp` | Function outlining |
| **Autodiff** | `autodiff.cpp` | Autodiff transformations |
| **Lower Ray Query** | `lower_ray_query_loop.cpp` | Ray query lowering |
| **Reg2Mem** | `reg2mem.cpp` | Register to memory conversion |
| **Promote Ref Arg** | `promote_ref_arg.cpp` | Reference argument promotion |
| **Transpose GEP** | `transpose_gep.cpp` | Transpose GEP through loads/stores |
| **Trace GEP** | `trace_gep.cpp` | GEP analysis/tracing |
| **Local Load Elimination** | `local_load_elimination.cpp` | Redundant load elimination |
| **Local Store Forward** | `local_store_forward.cpp` | Store-to-load forwarding |
| **Unused Callable Removal** | `unused_callable_removal.cpp` | Dead function elimination |

---

## Control Flow Representation

XIR uses **structured control flow** with explicit merge blocks:

```
IfInst:
  - condition: Value*
  - true_block: BasicBlock*
  - false_block: BasicBlock*
  - merge_block: BasicBlock*

LoopInst:
  - prepare_block: BasicBlock*
  - body_block: BasicBlock*
  - update_block: BasicBlock*
  - merge_block: BasicBlock*
```

This design:
- Maintains SSA property
- Enables structured transformations
- Maps well to GPU shader control flow requirements
- Supports PHI nodes at merge points

---

## Metadata System

**File**: `include/luisa/xir/metadata.h`

Metadata types (`DerivedMetadataTag`):
- `NAME` — Symbol names
- `LOCATION` — Source file/line information
- `COMMENT` — Debug comments
- `CURVE_BASIS` — Ray tracing curve basis

Applied via `MetadataListMixin` to Values and Instructions.

---

## JSON Serialization

### IR (Legacy)
- Uses `ast2json` for AST serialization
- Rust IR can be serialized/deserialized
- C API: `luisa_compute_ir_ast_json_to_ir_*`

### XIR
**Files**: `src/xir/translators/xir2json.cpp`, `json2xir.cpp`

Uses yyjson library for module serialization, cross-process communication, and debugging.

---

## Key Design Patterns

1. **Intrusive Lists**: `ManagedIntrusiveList` for efficient node management
2. **CRTP**: `DerivedValue<>`, `DerivedInstruction<>`, `DerivedFunction<>`
3. **Visitor Pattern**: `traverse_basic_blocks()`, `traverse_instructions()`
4. **Builder Pattern**: `XIRBuilder` for instruction creation
5. **Mixin Pattern**: `MetadataListMixin`, `ControlFlowMergeMixin`, `InstructionOpMixin`
6. **Use-Def Chains**: `Use` objects track value users for SSA

---

## Adding a New XIR Pass

1. Create pass implementation in `src/xir/passes/<name>.cpp`
2. Create header in `include/luisa/xir/passes/<name>.h`
3. Register in `src/xir/CMakeLists.txt`
4. Follow existing pass conventions:
   - Accept `Module &` or `Function &`
   - Return `bool` indicating whether changes were made
   - Use `XIRBuilder` for instruction insertion
   - Call `replace_all_uses_with()` for value substitution

---

Source: https://www.openparable.com/skill/development/ir-pipeline (OpenParable). Cite the canonical URL above.
