MLIR 与多层次 IR

传统两层 IR 的困境：
  高层 IR 需要表达：张量、卷积、矩阵乘、循环分块、内存层级
  低层 IR 需要表达：寄存器、指令选择、栈帧、调用约定
  中间缺失的部分（循环结构、访存模式、并行映射）无处安放

// 一个高层次操作：linalg 卷积，语义完整、可被领域优化识别
%0 = linalg.conv_2d ins(%input, %filter : tensor<1x28x28x1xf32, tensor<3x3x1x8xf32>)
                      outs(%init : tensor<1x26x26x8xf32>) -> tensor<1x26x26x8xf32>

// 混合 IR：scf、arith、memref 三个方言共存
func.func @add(%a: memref<16xf32>, %b: memref<16xf32>) {
  %c0 = arith.constant 0 : index
  %c16 = arith.constant 16 : index
  %c1 = arith.constant 1 : index
  scf.for %i = %c0 to %c16 step %c1 {
    %x = memref.load %a[%i] : memref<16xf32>
    %y = memref.load %b[%i] : memref<16xf32>
    %s = arith.addf %x, %y : f32
    memref.store %s, %a[%i] : memref<16xf32>
  }
  return
}

// 用 TableGen 声明一个操作（简化）
def MyAddOp : MyDialect_Op<"add", [Pure]> {
  let arguments = (ins AnyType:$lhs, AnyType:$rhs);
  let results = (outs AnyType:$result);
  let assemblyFormat = "$lhs `,` $rhs attr-dict `:` type($result)";
  let hasVerifier = 1;      // 自定义验证器
}

# 用 mlir-opt 查看与操作一份 IR
mlir-opt input.mlir --canonicalize --cse -o out.mlir
mlir-opt input.mlir --pass-pipeline='builtin.module(func.func(canonicalize,cse))'

// 同一份数据的三种类型表达，代表三个不同的抽象层次
tensor<4x8xf32>              // 值语义：不可变的张量值
memref<4x8xf32>              // 内存语义：有地址的缓冲区
memref<4x8xf32, affine_map<(i,j)->(j,i)>>  // 带布局的缓冲区（转置）

// 属性承载编译期信息：仿射映射描述索引变换
#map = affine_map<(d0, d1) -> (d0 * 4 + d1)>
%0 = affine.load %buf[%i, %j] : memref<16xf32>   // 索引经 #map 变换

// 阶段一：领域操作 -> 结构层（卷积变成循环）
linalg.conv_2d ins(%in, %filt) outs(%out) -> ...
// 降级后：
scf.for %n = ... { scf.for %h = ... { scf.for %w = ... {
  scf.for %kh = ... { scf.for %kw = ... {
    // 累加计算
  }}}}}}

// 阶段二：结构层 -> 通用层（循环变成 cf 分支）
// 阶段三：通用层 -> 低层（memref 变成裸指针运算）
%ptr = llvm.getelementptr %base[%i] : (!llvm.ptr, i64) -> !llvm.ptr, f32
%v = llvm.load %ptr : !llvm.ptr -> f32

# 分步降级，每步之间可以插入自己的 pass
mlir-opt --linalg-generalize-named-ops input.mlir -o s1.mlir
mlir-opt --convert-linalg-to-loops s1.mlir -o s2.mlir
mlir-opt --convert-scf-to-cf s2.mlir -o s3.mlir
mlir-opt --convert-to-llvm s3.mlir -o s4.mlir

// pass 的嵌套运行：外层在模块上，内层在函数上
builtin.module(
  func.func(canonicalize, cse, loop-invariant-code-motion),
  convert-scf-to-cf,
  convert-to-llvm
)

// 用 C++ API 构建 pipeline
void buildPipeline(OpPassManager &pm) {
  pm.addNestedPass<func::FuncOp>(createCanonicalizerPass());
  pm.addNestedPass<func::FuncOp>(createCSEPass());
  pm.addPass(createConvertSCFToCFPass());
  pm.addPass(createConvertToLLVMPass());
  // 降级到 LLVM 之后交给 LLVM 的优化管线
  pm.addPass(createReconcileUnrealizedCastsPass());
}

# 定位 pipeline 中哪一步出了问题
mlir-opt --pass-pipeline='...' --mlir-print-ir-after-all input.mlir 2> ir_trace.log
# 或者用 crash reproducer 保存失败现场
mlir-opt --verify-diagnostics input.mlir

// 降级完成后的 llvm 方言 IR（接近 LLVM IR）
llvm.func @add(%arg0: !llvm.ptr, %arg1: !llvm.ptr) {
  %0 = llvm.mlir.constant(0 : i64) : i64
  %1 = llvm.getelementptr %arg0[%0] : (!llvm.ptr, i64) -> !llvm.ptr, f32
  %2 = llvm.load %1 : !llvm.ptr -> f32
  llvm.return
}

# 生成 LLVM IR 并交给 llc 或 clang
mlir-opt --convert-to-llvm input.mlir | mlir-translate --mlir-to-llvmir -o out.ll
llc out.ll -o out.s
clang out.ll -o out

// 在进程内 JIT 执行 MLIR
mlir::ExecutionEngineOptions opts;
opts.transformer = ...;                 // 挂载降级 pipeline
auto engine = mlir::ExecutionEngine::create(module, opts);
auto fn = engine->lookupPacked("add");

一个典型的领域编译流程：
  领域前端（自定义语法/框架图）
     |
     v
  高层方言（自定义或 stablehlo）    <- 领域优化：算子融合、常量折叠
     |
     v
  linalg 方言                       <- 分块、向量化、布局选择
     |
     v
  scf 与 memref                     <- 循环变换、内存提升
     |
     v
  llvm 方言 -> LLVM IR -> 机器码    <- 指令选择、寄存器分配

# 用 mlir-opt 快速试验一段 IR 的降级效果
mlir-opt --linalg-tile='tile-sizes=32,32' --convert-linalg-to-loops test.mlir
mlir-opt --test-vectorization test.mlir        # 观察向量化是否触发

// 陷阱：过早把张量降级成 memref，丢失了值语义，后续无法做算子融合
// 差：进入 pipeline 就是 memref 操作
// 好：保持在 tensor 上做融合，最后一步再 bufferize

// 陷阱：location 丢失导致报错无法定位
// 每个操作都应带 location，用 TableGen 的 `let hasVerifier` 之外还要注意
// 生成 IR 时传 location：builder.create<arith::AddFOp>(loc, a, b)

# 用 location 信息定位问题
mlir-opt --mlir-print-debuginfo input.mlir | grep "loc("