安全点与栈增长机制：仓颉 LLVM Statepoint 与 StackPointerInserter 原理完全指南

安全点与栈增长机制：仓颉 LLVM Statepoint 与 StackPointerInserter 原理完全指南

【免费下载链接】llvm-projectLLVM 项目是一个模块化、可复用的编译器及工具链技术的集合。此fork用于添加仓颉编译器的功能，并支持仓颉编译器项目。项目地址: https://gitcode.com/Cangjie/llvm-project

本文面向新手，完整讲解仓颉编译器（Cangjie LLVM）中的两大核心机制：基于 LLVMStatepoint的GC 安全点标记原理，以及StackPointerInserter栈指针分析与按需栈增长的工作方式。你不需要任何编译器背景，跟着读就能理解：编译器如何在"垃圾回收随时可能介入"的前提下，仍保证程序安全、高效运行。

🧭 什么是安全点？为什么仓颉编译器需要它

仓颉语言采用自动垃圾回收（GC），程序不需要手动释放内存。但 GC 回收器在运行时需要"看清"程序当前持有哪些对象引用，才能判断哪些对象可以回收。

这就引出了**安全点（Safepoint）**的概念：

• 安全点：程序中允许 GC 介入的特殊位置。只有程序停在安全点上，GC 才能扫描栈中的引用；
• Statepoint：LLVM 中的术语，指比"暂停"更进一步的机制——它不仅能暂停执行，还能把现场状态"存档"，让 GC 在任意时刻介入而无需程序等待。

💡 打个比方：安全点就像高速公路的服务区——车（程序）必须开到服务区，加油站（GC）才能为它服务。Statepoint 则更进一步，相当于给车拍了一张"全景快照"，随时可以恢复。

Statepoint 的完整设计文档见官方文档：llvm/docs/Statepoints.rst

🗺️ LLVM Statepoint：从内建函数到 StackMap

LLVM 提供了通用的 Statepoint 基础设施，仓颉编译器在其上做了扩展。核心流程分三步：

1. 标记安全点：前端（Sema/CodeGen）在调用点插入llvm.experimental.gc.statepoint内建函数，把原本的普通调用改写成"状态点 + 重新定位序列"，并记录调用地址、GC 映射等元数据；
2. 生成 StackMap：优化器中的 RewriteStatepointsForGC 一类 pass 会为每个状态点生成StackMap（栈映射表），告诉 GC："此时哪些寄存器、哪些栈槽位里藏着对象指针"；
3. 后端发射：机器代码中每个状态点会生成一条"伪指令"，最终由 AsmPrinter 发射出真实的栈溢出检查代码。

StackMap 的解析工具类 StackMaps.h 中可以看到状态点操作数结构的完整定义，包括 GC 指针列表、栈指针数量（getNumStackPtrsIdx）、栈检查判断（isCJStackCheck）等字段——这正是下一节 pass 要填写的"空格"。

🔍 StackPointerInserter：栈指针存活的自动分析

普通 GC 只关心对象指针，而仓颉编译器还需要追踪栈指针（指向栈上数据的裸指针）。难点在于：一个状态点执行时，哪些栈指针还"活着"（之后还会被用到）？如果 GC 需要搬移或增长栈，它必须知道这些指针的存在并更新它们。

这就是CJStackPointerInserterpass 的使命，其完整实现在 llvm/lib/CodeGen/CJStackPointerInserter.cpp（pass 名称为cangjie-stack-pointer-inserter），头部接口见 llvm/include/llvm/CodeGen/CJStackPointerInserter.h。它的分析过程可以概括为 5 步：

几个值得新手注意的设计细节：

• 只关心 64 位指针宽度的寄存器与 8 字节栈槽（MemBytes == 8判断），避免误报；
• 区分 x86 与 AArch64：两种架构的内存操作数编码不同（如MOV64rm与LDRXui），pass 内部按目标平台分别解析偏移量（见StackOperand类）；
• GC 指针去重：filterGCPointer会把已列入 GC 映射的指针从栈指针集合中剔除，避免 GC 重复处理。

IR 层面还配套了 GC 存活分析 pass：llvm/include/llvm/Transforms/Scalar/CJGCLiveAnalysis.h。

🛡️ 栈增长机制：CJStackCheck 与按需扩展

C 语言习惯一次性给函数分配固定大小的栈帧，但现代语言（如仓颉、Kotlin）更倾向于按需栈增长：先给少量栈空间，不够时再向操作系统要。这需要编译器在调用前插入栈检查（Stack Check）：

// x86-64 上生成的栈检查序列（示意） movq 40(%r15), %rax # 从线程局部存储读取"保护地址" cmpq %rax, %rsp jbe .Lstack.overflow # 越界则跳转栈溢出处理

在仓颉 LLVM 中，这条序列由emitCJStackCheck在汇编输出阶段发射，两个平台的实现分别是：

• x86-64：llvm/lib/Target/X86/X86MCInstLower.cpp
• AArch64：llvm/lib/Target/AArch64/AArch64AsmPrinter.cpp（AArch64 版本使用subs sp+ 条件跳转，只需 2 条指令，非常紧凑）

原理拆解：

1. 每个线程在自己的TLS（线程局部存储）中维护一个"保护地址"（protect address），表示"sp 不得低于这条线"；
2. 每次可能分配栈空间之前，程序将当前栈指针与保护地址比较；
3. 若越界，跳转到栈溢出处理入口：恢复部分栈空间后，调用CJ_MCC_ThrowStackOverflowError报错，或调用CJ_MCC_StackGrowStub向运行时申请更大的栈并原地续跑——这就是"按需增长"的落点；
4. 栈增长完成后程序从原检查点继续，对上层代码完全透明。

与 Statepoint 的联动也很巧妙：CJStackCheck本身就是一种特殊状态点（isCJStackCheck判定），StackPointerInserter 会在栈增长点上回填所有仍存活的栈指针参数，让运行时在搬移栈之后能够统一修正它们。通用发射入口位于 llvm/lib/CodeGen/AsmPrinter/AsmPrinter.cpp，目标无关的钩子声明见 llvm/include/llvm/CodeGen/AsmPrinter.h 中的emitCJStackCheck虚函数。

⚡ 好处：函数不必预留"以防万一"的大栈帧，内存占用更省，深递归也不会轻易爆栈。

🐞 与调试器的协作：CJDB 架构

安全点信息不止服务于 GC——调试器同样依赖它。当 GC 搬移对象或增长栈后，调试器看到的寄存器值可能已经过期，必须借助状态点的 StackMap 来"刷新"现场。仓颉调试器 CJDB 的整体架构如下图所示（源自 lldb 模块的仓颉扩展文档）：

调试器在断点命中时，会读取函数中最近的安全点描述，恢复出准确的指针现场，从而实现"在任意时刻停下来看变量"的能力。

📚 延伸阅读：源码与文档索引

想动手深入的同学，可以从以下入口读源码（均在 Cangjie/llvm-project 仓库中，克隆地址：https://gitcode.com/Cangjie/llvm-project）：

• 栈指针分析与状态点重写：llvm/lib/CodeGen/CJStackPointerInserter.cpp
• StackMap 操作数定义：llvm/include/llvm/CodeGen/StackMaps.h
• Statepoint 设计文档（英文原版）：llvm/docs/Statepoints.rst
• IR 层 GC 存活分析：llvm/include/llvm/Transforms/Scalar/CJGCLiveAnalysis.h
• x86-64 栈检查发射：llvm/lib/Target/X86/X86MCInstLower.cpp
• AArch64 栈检查发射：llvm/lib/Target/AArch64/AArch64AsmPrinter.cpp
• 栈增长支持（AArch64 指令尺寸计算）：llvm/lib/Target/AArch64/AArch64InstrInfo.cpp
• 仓颉 GC 调用约定相关定义：llvm/include/llvm/IR/Function.h

✅ 一句话总结

仓颉编译器在 LLVM 通用 Statepoint 设施上，用CJStackPointerInserter做精确的栈指针存活分析、用CJStackCheck + StackGrowStub实现线程级的按需栈增长——两者配合，让 GC 能随时安全介入、让深调用链不再畏惧栈溢出，是仓颉语言"托管内存 + 高性能"体验的重要基石。🚀

【免费下载链接】llvm-projectLLVM 项目是一个模块化、可复用的编译器及工具链技术的集合。此fork用于添加仓颉编译器的功能，并支持仓颉编译器项目。项目地址: https://gitcode.com/Cangjie/llvm-project