第 12 课:自定义 Dialect 的工程结构

好,继续第 12 课。

这节我们开始把前面“概念上的 Toy Dialect”放进一个真实一点的 MLIR 工程结构里。重点不是一下子把所有 CMake 细节背下来,而是先看懂:一个自定义 Dialect 在源码工程里通常由哪些文件组成,这些文件彼此怎么连接。

第 12 课:自定义 Dialect 的工程结构

假设我们做一个:

Toy Dialect

目录可以设计成:

Toy/
├── CMakeLists.txt
├── ToyDialect.h
├── ToyDialect.cpp
├── ToyDialect.td
├── ToyOps.h
├── ToyOps.cpp
└── ToyOps.td

先记住两类文件:

.td

负责“描述”。

.h / .cpp

负责“真正编译进程序里的 C++ 代码”。


1. ToyDialect.td

这个文件主要定义:

Toy Dialect 本身

例如概念上:

include "mlir/IR/DialectBase.td"

def Toy_Dialect : Dialect {
  let name = "toy";
  let cppNamespace = "::toy";
}

这里:

name = "toy"

决定 MLIR 文本里写:

toy.add
toy.mul

而:

cppNamespace = "::toy"

决定 C++ 里大概是:

toy::AddOp
toy::MulOp

2. ToyOps.td

这个文件主要定义:

Toy Dialect 里的 Operations

比如:

include "ToyDialect.td"
include "mlir/IR/OpBase.td"

class Toy_Op<string mnemonic, list<Trait> traits = []>
    : Op<Toy_Dialect, mnemonic, traits>;

然后定义:

def Toy_AddOp : Toy_Op<"add"> {
  let arguments = (ins
    I32:$lhs,
    I32:$rhs
  );

  let results = (outs
    I32:$result
  );
}

以及:

def Toy_MulOp : Toy_Op<"mul"> {
  let arguments = (ins
    I32:$lhs,
    I32:$rhs
  );

  let results = (outs
    I32:$result
  );
}

所以:

ToyDialect.td

回答:

“toy 是什么 Dialect?”

而:

ToyOps.td

回答:

“toy 里面有哪些 Operation?”


3. 为什么 Dialect 和 Ops 分开?

因为一个 Dialect 可能非常大。

例如:

MyDialect
├── 50 个 Operation
├── 10 个 Type
├── 20 个 Attribute
└── 一堆 Interface

如果全部写一个 .td:

几千行

会很难维护。

所以通常拆成:

Dialect.td
Ops.td
Types.td
Attributes.td
Interfaces.td

这是大型 MLIR 工程里很常见的组织方式。


4. ToyDialect.h

这是 C++ 头文件。

概念上大概:

#pragma once

#include "mlir/IR/Dialect.h"

#include "ToyDialect.h.inc"

这里:

ToyDialect.h.inc

不是你手写的。

它来自:

ToyDialect.td
        ↓
mlir-tblgen
        ↓
ToyDialect.h.inc

也就是说:

.td

经过 TableGen 后生成:

.inc

然后我们的 C++ 头文件把它 include 进来。


5. 为什么是 .inc?

LLVM/MLIR 很喜欢这种:

.inc

文件。

因为它表示:

这段代码不是独立编译单元,而是要被其他 .h / .cpp include 进去。

比如:

ToyOps.h.inc
ToyOps.cpp.inc

这些通常都是:

自动生成

不要手改。

因为下一次构建时会重新生成。


6. ToyOps.h

Operation 的 C++ 声明通常在这里接进来。

概念上:

#pragma once

#include "mlir/IR/OpDefinition.h"

#include "ToyDialect.h"

#define GET_OP_CLASSES
#include "ToyOps.h.inc"

这里:

#define GET_OP_CLASSES

是 LLVM/MLIR 这种 .inc 代码生成模式里很常见的技巧。

大意就是:

告诉这个生成文件:现在我要展开 Operation 类声明。

于是最终 C++ 就能看到:

toy::AddOp
toy::MulOp
toy::ConstOp
toy::PrintOp

7. ToyOps.cpp

对应实现文件。

通常会:

#include "ToyOps.h"

然后:

#define GET_OP_CLASSES
#include "ToyOps.cpp.inc"

这里会接入 TableGen 自动生成的实现。

如果某些 Operation 有自定义逻辑,比如:

verify()
parse()
print()
canonicalization()

也可能在这里手写。


8. ToyDialect.cpp

Dialect 自己的初始化逻辑一般在这里。

比如概念上:

#include "ToyDialect.h"
#include "ToyOps.h"

using namespace mlir;
using namespace toy;

然后初始化:

void ToyDialect::initialize() {
  addOperations<
#define GET_OP_LIST
#include "ToyOps.cpp.inc"
      >();
}

这一段非常重要。

意思是:

把 Toy Dialect 的所有 Operation 注册进 Dialect。

否则 MLIR 可能知道:

有一个 toy dialect

但不知道:

toy.add
toy.mul

这些 Operation 是谁。


9. 注册到底是什么意思?

假设 parser 看到:

%0 = toy.add %a, %b : i32

它需要问:

"toy.add" 是什么?

如果 Toy Dialect 已注册:

toy.add
     ↓
toy::AddOp

MLIR 就能构造正确的 Operation 对象。

所以:

registration

就是把:

文本名字

和:

C++ Operation 类型

关联起来。


10. 如果不注册会怎样?

如果 MLIR 不认识:

toy.add

通常会认为:

这是一个未知 Operation

是否允许它存在,还要看 parser 是否开启:

allow unregistered dialects

但正常自定义 Dialect 项目里,我们肯定希望正式注册。


11. mlir-tblgen 会生成什么?

对于:

ToyDialect.td
ToyOps.td

大致会生成:

ToyDialect.h.inc
ToyDialect.cpp.inc

ToyOps.h.inc
ToyOps.cpp.inc

可以理解:

        .td
         │
         ▼
   mlir-tblgen
         │
   ┌─────┴─────┐
   ▼           ▼
.h.inc       .cpp.inc

然后:

你自己的 .h/.cpp

再 include 它们。


12. CMake 在做什么?

这时候 CMake 就需要完成两件事:

1. 调用 mlir-tblgen
2. 把生成代码和手写 C++ 编译起来

所以 CMakeLists.txt 非常关键。

概念上会有:

set(LLVM_TARGET_DEFINITIONS ToyDialect.td)

mlir_tablegen(ToyDialect.h.inc -gen-dialect-decls)
mlir_tablegen(ToyDialect.cpp.inc -gen-dialect-defs)

add_public_tablegen_target(ToyDialectIncGen)

这组命令表示:

ToyDialect.td
      ↓
生成 Dialect declarations
生成 Dialect definitions

13. Operation 也类似

对:

ToyOps.td

可能:

set(LLVM_TARGET_DEFINITIONS ToyOps.td)

mlir_tablegen(ToyOps.h.inc -gen-op-decls)
mlir_tablegen(ToyOps.cpp.inc -gen-op-defs)

add_public_tablegen_target(ToyOpsIncGen)

所以:

-gen-op-decls

生成:

Operation 声明

而:

-gen-op-defs

生成:

Operation 定义

14. 现在把生成链串起来

比如:

ToyOps.td

里面:

def Toy_AddOp ...

经过:

mlir-tblgen

生成:

toy::AddOp

然后你就可以在 C++ 里:

toy::AddOp op;

或者:

func.walk([&](toy::AddOp op) {
});

或者:

rewriter.create<toy::AddOp>(...);

这就是 .td 到 C++ 的完整连接。


15. 一个非常重要的 mental model

你以后看到:

toy::AddOp

要想到:

它不是凭空出现的

而是:

ToyOps.td
   ↓
TableGen
   ↓
ToyOps.h.inc / ToyOps.cpp.inc
   ↓
ToyOps.h / ToyOps.cpp
   ↓
toy::AddOp

这是理解 MLIR 源码的关键。


16. 一个更完整的目录

真实项目里可能长这样:

Toy/
├── CMakeLists.txt
│
├── include/
│   └── Toy/
│       ├── ToyDialect.h
│       ├── ToyDialect.td
│       ├── ToyOps.h
│       └── ToyOps.td
│
└── lib/
    └── Toy/
        ├── ToyDialect.cpp
        └── ToyOps.cpp

为什么分:

include/

和:

lib/

因为这符合 LLVM 工程常见布局:

include
= 公共头文件

lib
= C++ 实现

17. Build 目录里会多出生成文件

源码目录:

source/

里你可能只有:

ToyOps.td
ToyOps.h
ToyOps.cpp

但编译以后:

build/

目录里会产生:

ToyOps.h.inc
ToyOps.cpp.inc

所以要理解一个非常重要的区别:

源码文件

和:

生成文件

不是放在同一个地方也很正常。


18. include path 为什么很重要?

你的:

#include "ToyOps.h.inc"

实际上可能是在:

build/include/...

里找生成文件。

所以 CMake 需要正确设置:

include directories

否则编译器会报:

ToyOps.h.inc: No such file or directory

这是第一次写 MLIR Dialect 时非常常见的问题。


19. 依赖顺序也重要

比如:

ToyOps.cpp

依赖:

ToyOps.cpp.inc

那在编译 ToyOps.cpp 之前:

TableGen 必须先执行

否则:

.inc 文件还没生成

编译就失败。

所以 CMake 里经常需要:

DEPENDS
ToyOpsIncGen

确保:

先 TableGen
再编译 C++

20. 一个 Dialect 的初始化流程

假设程序启动。

你可能有:

DialectRegistry registry;

然后:

registry.insert<toy::ToyDialect>();

再创建:

MLIRContext context(registry);

于是:

MLIRContext
   │
   └── 知道 ToyDialect

然后 parser 遇到:

toy.add

就能解析。


21. MLIRContext 是什么?

这里引入一个很重要的新概念:

MLIRContext

可以先理解为:

MLIR 世界运行时的核心上下文。

里面管理很多东西:

Dialect
Type
Attribute
Uniquing
Threading
Diagnostic

以后你经常会看到:

MLIRContext *context

或者:

op.getContext()

或者:

rewriter.getContext()

它相当于整个 MLIR IR 系统的“环境”。


22. 为什么 Pattern 里总传 Context?

比如前面:

RewritePatternSet patterns(&getContext());

因为 Pattern 可能需要创建:

Type
Attribute
Operation

这些东西都依赖:

MLIRContext

所以:

Context

是 MLIR C++ 编程里一个基础对象。


23. 我们的 Toy Dialect 怎么被 parser 使用?

完整流程:

程序启动
  ↓
创建 DialectRegistry
  ↓
注册 toy::ToyDialect
  ↓
创建 MLIRContext
  ↓
Parser 读取 .mlir
  ↓
看到 toy.add
  ↓
找到 ToyDialect
  ↓
找到 toy::AddOp
  ↓
构造 Operation

这样:

%0 = toy.add %a, %b : i32

才真正从文本变成内存里的:

toy::AddOp object

24. 到这里,你已经能看懂一个 Dialect 工程了

看到:

ToyDialect.td

你知道:

定义 Dialect

看到:

ToyOps.td

你知道:

定义 Operations

看到:

ToyDialect.cpp

你知道:

初始化 / 注册 Dialect

看到:

ToyOps.cpp

你知道:

Operation 自定义实现

看到:

*.inc

你知道:

TableGen 自动生成

看到:

CMakeLists.txt

你知道:

驱动 TableGen + 编译 C++

第 12 课总结

把整个工程关系记成这一张图:

          ToyDialect.td
                │
                ▼
           mlir-tblgen
                │
                ▼
      ToyDialect.*.inc
                │
                ▼
ToyDialect.h / ToyDialect.cpp
                │
                ▼
          ToyDialect

Operation 也是:

            ToyOps.td
                │
                ▼
           mlir-tblgen
                │
                ▼
         ToyOps.*.inc
                │
                ▼
      ToyOps.h / ToyOps.cpp
                │
                ▼
 toy::AddOp / MulOp / ...

然后:

ToyDialect
    ↓ register
MLIRContext
    ↓
Parser
    ↓
toy.add

最重要的一句话:

.td 是声明源头,TableGen 生成 C++ 骨架,手写 C++ 补充行为,CMake 把整个链条串起来。

下一课我们可以继续 第 13 课:真正实现一个 toy.add Operation 的完整 ODS 定义。

会开始详细讲:

arguments
results
traits
assemblyFormat
builders
verify

然后我们会让:

%0 = toy.add %a, %b : i32

从“我们想象中的语法”,变成一个真正合理的 Operation 定义。

评论

暂无评论