snapshot before regression test
This commit is contained in:
t
301
includes/llvmlite/README.md
Normal file
301
includes/llvmlite/README.md
Normal file
@@ -0,0 +1,301 @@
|
||||
# llvmlite 设计方案
|
||||
|
||||
用 TransPyC 自身实现的轻量级 LLVM IR 文本生成库，替代 Python `llvmlite` 依赖，为自举（见 `wiki/13-bootstrapping.md` 路径 B）铺路。
|
||||
|
||||
## 1. 目标与定位
|
||||
|
||||
- **输入**：类型/值/指令的语义对象
|
||||
- **输出**：合法的 LLVM IR 文本（`.ll`），可直接喂给 `llc`
|
||||
- **不做什么**：不解析 IR、不做优化、不绑定 LLVM C API（纯文本生成）
|
||||
- **自举约束**：本库必须能用当前 TransPyC 编译器完整编译，不得依赖任何 Python 运行时
|
||||
|
||||
## 2. 核心设计决策
|
||||
|
||||
### 2.1 类型系统用 `t.REnum`（tagged union）
|
||||
|
||||
LLVM 类型变体少、无通用字段、字段都是指针/小整数、操作主要通过 `match` 分派 —— 完全契合 REnum 的 tag+union 模型。
|
||||
|
||||
### 2.2 指令 opcode 用 `t.CEnum`
|
||||
|
||||
指令类别（Binary/Unary/Cast/Memory/Terminator/Compare）与具体 opcode（Add/Sub/Load/Store/Br/Ret/...）用 `t.CEnum` 组织，类型安全且零开销。
|
||||
|
||||
### 2.3 IR 文本生成用 `viperlib.snprintf`
|
||||
|
||||
所有 IR 文本通过 `viperlib.snprintf(buf, size, fmt, *args)` 格式化写入缓冲区，避免手写逐字符拼接。`snprintf` 已支持宽度/精度/符号/`%s`/`%d`/`%x` 等，足够覆盖 IR 语法。
|
||||
|
||||
### 2.4 对象分配用普通类 + `mpool`
|
||||
|
||||
像 `mbuddy` 一样用普通类（无 `__new__`），由调用方注入 `mpool.MPool` 做批量分配。库内部不持有全局 `mbuddy`，遵循项目约定（`_mbuddy` 指针由 `os.py` 或调用方设置）。
|
||||
|
||||
---
|
||||
|
||||
## 3. 为什么 AST 不用 REnum，而 llvmlite 用？
|
||||
|
||||
用户质疑：REnum 是 tag+union（Rust enum），配合 `match` 模式匹配，按理很适合 AST。下面解释两者的适配性差异。
|
||||
|
||||
### 3.1 REnum 的硬限制（来自 `HandlesClassDef._EmitREnumLlvm`）
|
||||
|
||||
1. **无通用字段共享**：每个 variant 独立声明字段，通用字段（如 `lineno`/`child`/`next`）必须在每 variant 重复声明。
|
||||
2. **共享最大变体尺寸**：布局为 `{ i32 __tag, <max_variant_payload> }`，小变体浪费内存。
|
||||
3. **payload 仅位置绑定**：`match` 通过位置绑定 payload，不能直接 `node.child` 属性访问 payload 字段。
|
||||
4. **无方法**：variant 不能挂方法。
|
||||
|
||||
### 3.2 AST 不适合 REnum 的四个原因
|
||||
|
||||
| 维度 | AST 需求 | REnum 限制 | 冲突 |
|
||||
|------|----------|------------|------|
|
||||
| 变体数量 | 70+ 节点类型 | 共享最大变体尺寸 | 内存膨胀（每节点都占最大变体空间） |
|
||||
| 通用字段 | lineno/child/next/parent 等 ~8 个字段全节点共享 | 无通用字段共享 | 要么每 variant 重复声明（冗长），要么放弃统一访问 |
|
||||
| 访问模式 | 频繁直接 `node.child`/`node.next`/`node.lineno` | payload 仅位置绑定，需 match 分派 | 遍历代码爆炸（每次访问都要 match） |
|
||||
| 字段复用 | `int_val`/`str_val`/`op` 等字段按 vtype 复用语义 | 每 variant 独立 payload | 无法复用 |
|
||||
|
||||
AST 采用"胖节点"设计（所有节点共用一个 `AST` struct，用 `vtype` 区分）：一次 `malloc`、统一链表遍历（`child`/`next`）、字段复用。这与 REnum"每变体独立 payload"的哲学根本冲突。
|
||||
|
||||
### 3.3 llvmlite 的 LLVMType 适合 REnum 的原因
|
||||
|
||||
| 维度 | LLVMType 需求 | REnum 特性 | 契合度 |
|
||||
|------|---------------|------------|--------|
|
||||
| 变体数量 | ~10 个（Int/Ptr/Func/Array/Struct/Void/Float/Label/...） | 共享最大变体尺寸 | 浪费可接受（最大变体 ~24 字节） |
|
||||
| 通用字段 | 无（每变体字段不同） | 无通用字段共享 | 完美匹配 |
|
||||
| 访问模式 | 类型操作天然通过 match 分派（"是 Int 取 bits，是 Ptr 取 pointee"） | payload 位置绑定 + match | 天然契合 |
|
||||
| 字段尺寸 | 都是指针(8B)或小整数(4B) | 共享最大变体 | 浪费小 |
|
||||
|
||||
**结论**：REnum 是"少变体、无共性、match 分派"场景的最佳工具 —— llvmlite 类型系统正好如此，AST 正好相反。
|
||||
|
||||
---
|
||||
|
||||
## 4. 文件结构
|
||||
|
||||
```
|
||||
includes/llvmlite/
|
||||
├── __init__.py # 公共导出 + 便捷工厂函数
|
||||
├── __types.py # LLVMType (REnum) + 类型构造/打印
|
||||
├── __values.py # Value/Constant/SSA 值表示
|
||||
├── __module.py # Module 容器（函数列表 + 目标三元组 + 输出 .ll）
|
||||
├── __function.py # Function + BasicBlock + 参数管理
|
||||
├── __builder.py # IRBuilder（指令发射 + SSA 命名 + 块跳转）
|
||||
└── README.md # 本文件
|
||||
```
|
||||
|
||||
### 职责划分
|
||||
|
||||
- `__types.py`：`LLVMType` REnum 定义 + `TypePrint(buf, ty)` 将类型序列化为 IR 文本（如 `i32`/`i32*`/`{i32, i8*}`）
|
||||
- `__values.py`：`Value` 表示一个 SSA 值（`%0`/`%result`/常量），含类型指针 + 名字 + 是否常量
|
||||
- `__module.py`：`Module` 持有函数链表 + 目标三元组 + 数据布局，`ModulePrint` 输出完整 `.ll`
|
||||
- `__function.py`：`Function` 持有基本块链表 + 参数 + 返回类型；`BasicBlock` 持有指令文本缓冲
|
||||
- `__builder.py`：`IRBuilder` 游标式 API，`build_add`/`build_load`/`build_br`/... 发射指令到当前块
|
||||
|
||||
---
|
||||
|
||||
## 5. 类型系统设计（REnum）
|
||||
|
||||
```python
|
||||
import t
|
||||
from stdint import *
|
||||
|
||||
class LLVMType(t.REnum):
|
||||
# 变体 Int：整数类型
|
||||
IntBits: t.CInt # 位宽 1/8/16/32/64/128
|
||||
|
||||
# 变体 Ptr：指针类型
|
||||
PtrPointee: LLVMType | t.CPtr # 指向的类型（自引用用指针）
|
||||
|
||||
# 变体 Func：函数类型
|
||||
FuncRet: LLVMType | t.CPtr # 返回类型
|
||||
FuncParams: LLVMType | t.CPtr # 参数类型链表头
|
||||
FuncPCount: t.CInt # 参数数量
|
||||
|
||||
# 变体 Array：数组类型
|
||||
ArrayElem: LLVMType | t.CPtr # 元素类型
|
||||
ArrayCount: t.CInt # 元素数量
|
||||
|
||||
# 变体 Struct：结构体类型
|
||||
StructHead: LLVMType | t.CPtr # 字段类型链表头
|
||||
StructCount: t.CInt # 字段数量
|
||||
|
||||
# 变体 Float：浮点类型
|
||||
FloatBits: t.CInt # 16/32/64/128
|
||||
|
||||
# 变体 Void / Label / Metadata：无 payload
|
||||
# （REnum 允许空变体，仅靠 __tag 区分）
|
||||
```
|
||||
|
||||
### 类型工厂（`__init__.py` 导出）
|
||||
|
||||
```python
|
||||
def Int1() -> LLVMType | t.CPtr: ... # i1
|
||||
def Int8() -> LLVMType | t.CPtr: ... # i8
|
||||
def Int32() -> LLVMType | t.CPtr: ... # i32
|
||||
def Int64() -> LLVMType | t.CPtr: ... # i64
|
||||
def Ptr(pointee: LLVMType | t.CPtr) -> LLVMType | t.CPtr: ...
|
||||
def Func(ret: LLVMType | t.CPtr, params: LLVMType | t.CPtr, count: t.CInt) -> LLVMType | t.CPtr: ...
|
||||
def Void() -> LLVMType | t.CPtr: ...
|
||||
```
|
||||
|
||||
### 类型打印（match 分派）
|
||||
|
||||
```python
|
||||
def TypePrint(buf: t.CChar | t.CPtr, size: t.CSizeT, ty: LLVMType | t.CPtr):
|
||||
match ty:
|
||||
case LLVMType.Int: # 位置绑定 IntBits
|
||||
viperlib.snprintf(buf, size, "i%d", ty.IntBits)
|
||||
case LLVMType.Ptr: # 位置绑定 PtrPointee
|
||||
TypePrint(inner, size2, ty.PtrPointee)
|
||||
# 拼接 "*"
|
||||
case LLVMType.Func:
|
||||
# 打印 ret (params)
|
||||
case LLVMType.Void:
|
||||
string.strcpy(buf, "void")
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Value / SSA 设计
|
||||
|
||||
```python
|
||||
class Value:
|
||||
Ty: LLVMType | t.CPtr # 值的类型
|
||||
Name: t.CChar | t.CPtr # SSA 名（"%0"/"%result"）或常量文本
|
||||
IsConst: t.CInt # 1=常量字面量，0=SSA 临时值
|
||||
Next: Value | t.CPtr # 链表（函数内的值池）
|
||||
```
|
||||
|
||||
`IRBuilder` 维护一个递增的 `%N` 计数器，每发射一条产生结果的指令就分配一个新名。
|
||||
|
||||
---
|
||||
|
||||
## 7. IRBuilder 设计
|
||||
|
||||
游标式 API，跟踪当前 `BasicBlock`，发射指令文本到块的缓冲区。
|
||||
|
||||
```python
|
||||
class IRBuilder:
|
||||
Func: Function | t.CPtr # 所属函数
|
||||
CurBlock: BasicBlock | t.CPtr # 当前插入点
|
||||
Counter: t.CInt # SSA 名计数器
|
||||
|
||||
def build_add(self, lhs: Value | t.CPtr, rhs: Value | t.CPtr) -> Value | t.CPtr:
|
||||
# 1. 分配 SSA 名 %N
|
||||
# 2. snprintf(buf, size, " %%%d = add %s %s, %s\n", N, ty, lhs, rhs)
|
||||
# 3. 追加到 CurBlock 缓冲
|
||||
# 4. 返回新 Value
|
||||
|
||||
def build_load(self, ty: LLVMType | t.CPtr, ptr: Value | t.CPtr) -> Value | t.CPtr: ...
|
||||
def build_store(self, val: Value | t.CPtr, ptr: Value | t.CPtr): ...
|
||||
def build_br(self, target: BasicBlock | t.CPtr): ...
|
||||
def build_cond_br(self, cond: Value | t.CPtr, then: BasicBlock | t.CPtr, else_: BasicBlock | t.CPtr): ...
|
||||
def build_ret(self, val: Value | t.CPtr): ...
|
||||
def build_alloca(self, ty: LLVMType | t.CPtr) -> Value | t.CPtr: ...
|
||||
def build_gep(self, ptr: Value | t.CPtr, idx: Value | t.CPtr) -> Value | t.CPtr: ...
|
||||
def build_call(self, callee: t.CChar | t.CPtr, args: Value | t.CPtr, ret_ty: LLVMType | t.CPtr) -> Value | t.CPtr: ...
|
||||
```
|
||||
|
||||
### 指令 opcode（CEnum）
|
||||
|
||||
```python
|
||||
class IROp(t.CEnum):
|
||||
# Terminator
|
||||
Ret: t.CEnum = 1
|
||||
Br: t.CEnum = 2
|
||||
CondBr: t.CEnum = 3
|
||||
Switch: t.CEnum = 4
|
||||
# Binary
|
||||
Add: t.CEnum = 10
|
||||
Sub: t.CEnum = 11
|
||||
Mul: t.CEnum = 12
|
||||
SDiv: t.CEnum = 13
|
||||
# Memory
|
||||
Load: t.CEnum = 20
|
||||
Store: t.CEnum = 21
|
||||
Alloca: t.CEnum = 22
|
||||
Gep: t.CEnum = 23
|
||||
# Cast
|
||||
BitCast: t.CEnum = 30
|
||||
SExt: t.CEnum = 31
|
||||
Trunc: t.CEnum = 32
|
||||
# Compare
|
||||
ICmp: t.CEnum = 40
|
||||
# Call
|
||||
Call: t.CEnum = 50
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. IR 文本生成（snprintf 用法）
|
||||
|
||||
每条指令发射用 `viperlib.snprintf` 格式化到块缓冲区。示例：
|
||||
|
||||
```python
|
||||
import viperlib
|
||||
|
||||
def _emit_add(block: BasicBlock | t.CPtr, name: t.CChar | t.CPtr,
|
||||
ty_str: t.CChar | t.CPtr, lhs: t.CChar | t.CPtr, rhs: t.CChar | t.CPtr):
|
||||
line: t.CChar | t.CPtr = mpool.alloc(128) # 行缓冲
|
||||
viperlib.snprintf(line, 128, " %s = add %s %s, %s\n", name, ty_str, lhs, rhs)
|
||||
_block_append(block, line)
|
||||
```
|
||||
|
||||
### Module 输出
|
||||
|
||||
```python
|
||||
def ModulePrint(mod: Module | t.CPtr, out_path: t.CChar | t.CPtr):
|
||||
# 1. 写头部：target triple / datalayout
|
||||
# 2. 遍历函数，写 declare/define
|
||||
# 3. 每函数：签名 + 基本块 + 指令
|
||||
# 用 snprintf 拼接，写到文件（viperio 或 w32/win32file）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 内存管理
|
||||
|
||||
- 库内所有对象从 `mpool.MPool` 分配（像 `ast` 库一样）
|
||||
- `IRBuilder`/`Module`/`Function` 不持有 `mbuddy`，由调用方传入 `mpool`
|
||||
- 文本缓冲区按行分配（每指令一行，128 字节起步），避免频繁 realloc
|
||||
|
||||
---
|
||||
|
||||
## 10. 基础构建范围（第一阶段）
|
||||
|
||||
最小可用集，能生成一个完整的小程序 IR：
|
||||
|
||||
1. **类型**：`IntType`(1/8/16/32/64) + `PointerType` + `FunctionType` + `VoidType` + `StructType`
|
||||
2. **值**：`Value` + 常量整数字面量
|
||||
3. **Module/Function/BasicBlock**：容器与链表
|
||||
4. **IRBuilder** 指令子集：
|
||||
- `alloca` / `load` / `store`
|
||||
- `add` / `sub` / `mul` / `sdiv`
|
||||
- `icmp` (eq/ne/sgt/sge/slt/sle)
|
||||
- `br` / `cond_br` / `ret`
|
||||
- `call`（外部函数）
|
||||
- `bitcast` / `sext` / `trunc`
|
||||
- `getelementptr`
|
||||
5. **ModulePrint**：输出完整 `.ll` 文件
|
||||
|
||||
### 后续扩展路线
|
||||
|
||||
- **第二阶段**：浮点指令、`phi` 节点、`switch`、字符串常量全局、属性（`nounwind`/`nocapture`）
|
||||
- **第三阶段**：内联汇编、`atomic` 指令、`va_arg`、精确的 SSA 验证（支配边界、phi 完整性）
|
||||
- **第四阶段**：对接 TransPyC 的 `LLVMCG`，替换 Python `llvmlite`，完成路径 B 自举
|
||||
|
||||
---
|
||||
|
||||
## 11. 测试计划
|
||||
|
||||
独立测试项目（`Test/LLvmLiteTest/`）：
|
||||
|
||||
1. **类型打印测试**：构造各 `LLVMType`，`TypePrint` 输出，对比预期字符串
|
||||
2. **小函数生成**：用 `IRBuilder` 生成 `i32 add(i32 a, i32 b) { ret i32 %r }`，`ModulePrint` 写 `.ll`，用 `llc` 编译验证语法合法
|
||||
3. **match 分派测试**：构造各变体 `LLVMType`，`match` 正确绑定 payload
|
||||
4. **snprintf 格式测试**：验证 `%d`/`%s`/`%x` 在 IR 文本中的正确性
|
||||
|
||||
---
|
||||
|
||||
## 12. 与现有架构的对接点
|
||||
|
||||
- **`lib/core/Codegen/LLVMCG.py`**：当前用 Python `llvmlite` 生成 IR，自举时改用本库
|
||||
- **`includes/viperlib.py`**：提供 `snprintf` / `sprintf`
|
||||
- **`includes/mpool.py`**：提供 `MPool` 内存池
|
||||
- **`includes/string.py`**：提供 `strcpy`/`strlen`/`memcpy`
|
||||
- **`includes/ast/`**：参考其"胖节点 + mpool + CEnum 常量"的组织方式（但类型系统用 REnum 而非胖节点）
|
||||
Reference in New Issue
Block a user