第 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/.cppinclude 进去。
比如:
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 定义。

评论
登录后参与技术讨论,分享你的经验与见解。
登录 / 注册暂无评论