Ghidra Sleigh 处理器规格编辑器：GhidraSleighEditor 的 XTEXT 架构、编辑功能与构建实战

本文基于 Ghidra 仓库中 GhidraSleighEditor 插件的官方 README 展开，系统讲解这个基于 Eclipse XTEXT DSL 框架的 Sleigh 语法编辑器的定位、安装方式与全部编辑功能（语法高亮、验证、QuickFix、悬停、导航、重命名、格式化），并结合仓库内 Sleigh.xtext 语法定义、验证器、QuickFix 提供者与格式化器等源码，说明每一项功能背后的实现原理，最后给出从 MWE2 代码生成到导出可安装 zip 包的完整构建流程。读完本文，读者既能直接上手使用该编辑器开发 .sinc/.slaspec 处理器模块，也能理解并参与其源码级维护。

1. 插件定位与模块结构

GhidraSleighEditor 是一个 Eclipse 插件，用于把编写和修改 Ghidra Sleigh 处理器规格（processor module）的过程变得现代而高效：它提供上下文敏感的编辑器，具备语法高亮、导航、上下文错误标注、快速修复等能力。该编辑器构建于 Eclipse 内的 XTEXT DSL 框架之上。文档信息以 Ghidra Sleigh Editor 1.0.0 为基准生效，并随后续版本演进——仓库中 feature.xml 声明的当前版本正是 1.0.2.qualifier。

插件按 XTEXT 标准工程拆分，从仓库目录结构可以看到五个子模块（外加测试工程）：

模块	职责
ghidra.xtext.sleigh	运行时：语法文件、生成器、作用域（scoping）、验证（validation）、格式化器（formatting2）
ghidra.xtext.sleigh.ide	IDE 支持（解析、内容辅助等）
ghidra.xtext.sleigh.ui	UI：高亮、悬停、大纲、QuickFix、补全建议
ghidra.xtext.sleigh.tests / ghidra.xtext.sleigh.ui.tests	解析、作用域、宏、交叉引用等测试
ghidra.xtext.sleigh.feature	feature 定义（feature.xml、category.xml），用于打包 p2 仓库

其中 feature.xml 的 <requires> 部分声明了对 org.eclipse.xtext、org.eclipse.xtext.xbase、org.eclipse.xtext.ide、org.eclipse.xtext.ui、org.eclipse.xtext.builder 等插件的依赖，这也解释了为什么目标 Eclipse 必须带 DSL/XTEXT 能力。

2. 版本历史与最低要求

2.1 Change History

• 1.0.2：语法中加入 lzcount；修复 cpool 的非法错误报告，并为 cpool 参数补充了测试。
• 1.0.1：支持 define token 定义上的新 endian 标签；修复 @if "!=" 比较的 bug；语法中加入 popcount。
• 1.0.0：首次发布。

这些改动都能在 Sleigh.xtext 中得到印证：

• exprSingle 规则中列有 pcodeop='popcount' '(' op1=expr ')'、pcodeop='lzcount' '(' op1=expr ')' 以及 pcodeop='cpool' '(' op1=cpoolParams ')'（cpoolParams 语法上强制至少 2 个参数）；
• tokendef 规则写作 'define' 'token' ID '(' size ')' ( 'endian' '=' ( 'big' | 'little' ) )? fields=tokenprop ';'，即可选的 endian 标签正是 1.0.1 新增项；
• 预处理指令 @if 对应的 DefineTest 规则同时接受 OP_EQUAL（== 语义的字符串等值）与 OP_NOTEQUAL（!=），对应 1.0.1 的 bug 修复。

2.2 Minimum Requirements

• Eclipse 2019-3，带 DSL 和 XTEXT 2.17 或更高版本。

官方建议使用 “Eclipse IDE for Java and DSL Developers” 版本；README 明确指出，只有该版本才具备执行后文构建操作的能力。

3. 安装

GhidraSleighEditor 需要手动安装到 Eclipse 中，适合所有需要编写处理器模块 Sleigh 规格的人。README 说明未来它可能会随 GhidraDev Eclipse 插件在配置 Ghidra 脚本/插件开发环境时自动安装。安装步骤（面向已有 Eclipse 安装）：

1. 点击 Help -> Install New Software...
2. 点击 Add...
3. 点击 Archive...
4. 选择 <GhidraInstallDir>/Extensions/Eclipse/GhidraSleighEditor/ 下的 GhidraSleighEditor zip 文件
5. 点击 OK（名称字段可以留空）
6. 勾选 Ghidra 类别（或 Ghidra Sleigh Editor 条目）
7. 点击 Next
8. 点击 Next
9. 接受许可协议
10. 点击 Finish
11. 点击 Install anyway
12. 点击 Restart Now

安装完成后，任何被编辑的 .sinc 或 .slaspec 文件都会自动交给 Sleigh 编辑器打开。这一行为由 MWE2 生成配置决定：GenerateSleigh.mwe2 中 StandardLanguage 设置了 fileExtensions = "slaspec,sinc"，XTEXT 据此把这两种扩展名的文件注册为该 DSL 语言的编辑器。

4. 编辑器功能详解

4.1 语法高亮（Syntax Highlighting）

关键字、Token、子构造器（sub-constructor）名、注释、指令格式（instruction formats）、字符串、变量等都可以着色，以提升 Sleigh 规格的可读性。在 Window -> Preferences -> Sleigh 偏好面板中，可以为任何 Sleigh 文件 token 修改颜色和字体样式。

从源码看，高亮类别在 SleighHighlightingConfiguration.java 中注册，共 8 类默认样式：

高亮类别	默认 RGB	字体样式
Context Field（上下文域）	(50,50,0)	斜体
Token Field（token 域）	(50,50,0)	常规
Symbol	(50,50,50)	默认
Variable	(106,62,63)	粗体
Attached Symbol	(50,50,50)	粗体
Print Piece	(0,0,255)	粗体
Local Symbol	(40,40,40)	斜体
SubTable	(192,82,5)	常规

背景统一为白色（255,255,255）。这些类别与 README 描述的关键字、token、变量、print piece 等对象一一对应，用户可在偏好面板里逐个调整。

4.2 验证（Validation）

Sleigh 文件的结构虽然相对简单，但用纯文本编辑器编写时容易出错。编辑器理解 Sleigh 的语法和全部构造，不必等 Sleigh 编译器报错，即可用红色错误标记捕获（但并非全部）语法错误。

验证器 SleighValidator.xtend 实现了若干 XTEXT @Check 规则：

• 名称唯一性（黄色警告）：对 fielddef（token 域）、contextfielddef（上下文域）与 VARSYM（变量）分别实现 checkDuplicate，用 typeMap 按根容器缓存“名字 → 定义集合”的映射，发现同名定义多于 1 个就发出 warning。这就是 README 中“token 重名会以黄色标记”的实现。
• 比较匹配昂贵性警告：checkWarnExpensiveOperation(constraint) 对 constraint 中除 = 之外的比较运算符（!=、<、<=、>、>=）发出警告：“comparison can be expensive, and should be used sparingly”。源码注释中还保留了 TODO：可对 token 尺寸做判断（2、3 位这类小尺寸其实不贵），目前尚未实现。

README 还强调了三类验证行为，可结合实现理解：

1. 局部变量必须声明。虽然 Sleigh 编译器允许不声明局部变量，但实践中发现不声明会导致 Sleigh 编译器都抓不住的错误。例如把寄存器 r0 误写成 ro 可能不会被发现。因此要求所有局部变量用 local 关键字声明，或至少带一个 :size。这一点由作用域机制支撑：SleighScopeProvider.xtend 的 variablesDeclaredBefore 只收集此前语句中真正以 local 声明过的 LOCALSYM，未声明的局部引用无法链接，从而被标错。
2. 复杂匹配模式警告。'!=' '<' '>' 这类比较匹配同样是警告项：比较匹配会让生成的 .sla 文件不必要地膨胀，因为展开的匹配分支数量很大；对超过几位的 token 尤其应避免，除非别无选择。
3. 对 define 使用位置的人为约束。Sleigh 是一种上下文敏感语法，且带有 define 式的预处理展开，因此编辑器只允许 $(define) 变量出现在“单个 token 应当出现的位置”。最常被标记的错误是在 define 内部嵌入连接符 & 后又在匹配模式中整体引用：:MOV ax, bx is t1=1 $(BadDefine) {} 不被允许，应写作 :MOV ax, bx is t1=1 & $(GoodDefine) {}。从语法结构看，匹配模式的最小单元是 atomic，其分支为 constraint、DefineUsage、或带括号子表达式，这与“define 只能替换单个 token 位置”的约束相吻合。

4.3 快速修复（QuickFix）

部分简单语法错误可以借助 QuickFix 建议快速修复：在错误上按 Ctrl-1 即可弹出可用的快速修复。

• 未定义局部变量（Undefined local variable）：插入 local，或若能推断出尺寸则插入 :size 形式；
• 未定义用户 pcodeop（Undefined user pcodeop）：为未知标识符插入用户 pcodeop 定义；
• 未定义宏（Undefined macro）：为未知标识符插入宏定义；
• 添加 token 域定义（Add token field definition）：为匹配模式中的未知 token 创建 fielddef。

未来可能还会增加更多 QuickFix；官方提醒在大文件（如 AARCH64）上 QuickFix 可能较慢。

源码层面，SleighQuickfixProvider.xtend 以 @Fix(Diagnostic::LINKING_DIAGNOSTIC) 注解注册统一入口 createMissingVariable，通过解析链接失败消息（reference to ...）判断目标符号类型，再分派到四个修复动作：

• missingPseudoOp：在模型中当前构造器之前插入 pcodeopdef（用 SleighFactory 创建 USEROPSYM，名字取自光标处文本）；
• createLocalVarnode：把未定义的左值替换为 localDefine；findElementSize/findSize 会沿着右侧表达式树回溯 exprSym，尝试从 varnodedef.size、localDefine.size 或 varattach 推导尺寸，能推导出就生成带 :size 的形式，否则退化为纯 local；
• missingConstraint：在第一个 tokendef 的 fields 末尾追加 fielddef（start/end 暂填 0，源码留有 TODO 尝试自动推断）；
• missingSubConstructor：生成一个带空 print piece、epsilon 匹配与 unimpl 子构造器模板，插入到当前构造器之前。

4.4 悬停（Hover）

Sleigh 文件中的许多构造在鼠标悬停时会显示附加信息。对 token 尤其有用：不必跳转到 token 域定义就能看到它的尺寸。README 列出的悬停能力：

• 子构造器：显示所有同名的已定义子构造器；
• token 域定义：显示尺寸，若已 attach 则显示对应寄存器集合；
• 寄存器：显示尺寸；
• 数值：同时以十六进制、二进制、十进制显示；
• $(Defines)：显示该名字的所有可能 define，因为实际使用哪一个是无法静态确定的。

实现位于 SleighEObjectHoverProvider.xtend：getIntegerFormats 把 integerValue（支持 0x、0b 前缀，用 BigInteger 解析）渲染为 0b…/0x…/十进制 三行 HTML 文本；getDefineSymText 遍历模型中所有 @define 收集同名定义；SUBTABLESYM 与 aliasSym 则通过 getSubTableText 列出同名子构造器。后续版本还会继续增加悬停项。

4.5 导航（Navigation）

如果你曾在普通文本编辑器里改过 Sleigh 处理器规格，会立刻体会到按变量“定义/使用”进行前后导航的价值。导航支持：子构造器名、域 token 名、寄存器、宏名、局部变量、define 名、用户定义 pcodeop。

操作方式：

• 在变量上按 F3 跳转定义/使用；
• 使用编辑器的前向/后向导航箭头；
• 作者最推荐 Ctrl-*，可直接跳回上一个编辑位置。

其基础是 SleighScopeProvider.xtend 为各符号引用（assignSym.symref、exprSym.vnode、exportedSym.symref、constraint.sym、aliasSym.symref、contextentry.lhs、globalLoc.tsym）实现的自定义作用域：局部作用域来自构造器 print piece 中的 aliasSym 与按语句顺序收集到的局部变量，全局作用域则先过滤掉 LOCALSYM 与 aliasSym 再合并（createFilteredLocalScope），从而让跳转落在正确的定义上。

4.6 查找引用（Find References）

编辑器提供“查找全部使用”而不是关键字搜索：每个找到的使用点都列在一个搜索窗口中，并显示其所在行的文本；双击即可跳转到该引用位置。使用方式：编辑器弹出菜单中的 Find References 动作。

4.7 重命名（Renaming）

变量命名往往很重要。相比对字符串做查找替换，编辑器可以做重命名重构：一次改名，所有其他使用该名字的位置都会同步更新——甚至包括其他 .sinc 与 .slaspec 文件。使用方式：编辑器弹出菜单中的 Rename Element 动作。

该能力由 MWE2 配置中的 ui.refactoring.RefactorElementNameFragment2 片段启用（见 GenerateSleigh.mwe2），配合 scoping/linking 机制实现跨文件重命名。

4.8 代码格式化（Code Formatting）

Sleigh 文件在开发过程中可能变得庞大而凌乱。与其刻意关注格式或手工排版，不如直接使用 Source -> Format 动作（README 原文即：编辑器弹出菜单 Source -> Format）。格式化器的规则：

• 常见构造自动对齐：例如 token 定义会找到最长的 token，把所有 token 及其定义对齐；
• 同名子构造器在 is 关键字、匹配模式、语义定义三处对齐；
• 所有构造器的 is 关键字按各自最长 print piece 大致对齐；
• 语句以一致方式缩进；
• 多行 attach 定义的每一项都对齐；
• 格式化可以限定在选中的行范围内，避免把精心排好的文件整体重排。

未来可能加入更多格式化规则，格式化器也可能变得更可配置。

源码 SleighFormatter.xtend 印证了这些策略：format(tokenprop) 采用两遍处理——第一遍统计 maxTokenNameLen/maxStartLen/maxEndLen，第二遍按最长名对齐 =、补齐 start/end 列宽；format(Model) 中用三个长度表（constructorPrintLenMap/constructorPatternLenMap/constructorContextLenMap）按去掉尾部数字后的子表名分组，对齐子构造器的 is 与 {（对齐目标宽度超过 120 列时放弃对齐）；format(vardeflist) 处理多行 attach 变量列表的逐行对齐（最长名截断在 20 列）；format(rtlbody)/format(statement) 负责语句换行与缩进。

5. 语法文件与代码生成机制

5.1 Sleigh.xtext 的结构

全部编辑能力最终都建立在 Sleigh.xtext（约 1150 行）这一 XTEXT 语法上。其要点：

• 语法头声明 grammar ghidra.xtext.sleigh.Sleigh hidden(WS, ML_COMMENT, SL_COMMENT)，即空白、块注释 /* */、以 # 开头的单行注释均为隐式 token；
• 顶层 Model: elements+=spec*;，spec 分支覆盖 Sleigh 的主要语句类型：with 子表引入、@include 导入、@define/@if/@ifdef/@ifndef/@elif/@else/@endif 预处理（macroDefine）、define endian/alignment、各种 define token/context/space/offset/bitrange/pcodeop、attach values/names/variables、macro 定义以及 constructor（base/sub 构造器）；
• 表达式体系分三层：匹配模式约束 constraint（支持 =、!=、<、<=、>、>= 六种比较）、匹配模式算术 pexpr*、以及语义体表达式 expr*（后者覆盖完整优先级链：算术、位、比较、布尔、浮点 f+/f-/f*/f/ 等运算符，以及 abs/sqrt/sext/zext/carry/scarry/sborrow/float2float/int2float/nan/trunc/ceil/floor/round/popcount/lzcount/cpool/newobject 等 pcode 操作）；
• 数值字面量 intvalue 支持十进制 NUMVAL、十六进制 HEXVAL（0x 前缀）、二进制 BINVAL（0b 前缀），并以 ecore::EBigInteger 承载，保证大数值不溢出；
• 符号系统按语义分族：VARSYM、LOCALSYM、CONTEXTSYM、TOKENSYM、OPERANDSYM、SUBTABLESYM、MACROPARAMSYM、SPACESYM、SECTIONSYM、USEROPSYM、MACROSYM 等，ID 终端允许字母、数字、.、_。

5.2 MWE2 生成配置

GenerateSleigh.mwe2 是 XTEXT 的工作流描述，关键配置：

language = StandardLanguage {
    name = "ghidra.xtext.sleigh.Sleigh"
    fileExtensions = "slaspec,sinc"
    ...
    fragment = ui.labeling.LabelProviderFragment2 {}
    fragment = formatting.Formatter2Fragment2 {}
    fragment = ui.quickfix.QuickfixProviderFragment2 {}
    // enable rename refactoring
    fragment = ui.refactoring.RefactorElementNameFragment2 {}
    junitSupport { junitVersion = "5" }
}

fileExtensions = "slaspec,sinc" 决定了编辑器接管哪两类文件；四个 UI 片段分别对应标签/悬停、格式化、QuickFix、重命名重构——正好覆盖 README 的功能清单；StandardProjectConfig 中启用了 runtime 测试工程与 Eclipse 插件工程及元数据生成。

5.3 测试工程

ghidra.xtext.sleigh.tests 模块包含四个 Xtext 测试：SleighParsingTest.xtend、SleighScopeTest.xtend、SleighMacroTest.xtend、CrossReferenceTest.xtend，分别验证解析、作用域解析、@define 宏展开与跨引用行为——Change History 中“为 cpool 参数添加测试”一类改进正是依托这套 JUnit 5 测试体系。

6. 构建 GhidraSleighEditor

README 说明：GhidraSleighEditor 目前从 Eclipse 中构建，并随 Ghidra 手工分发；理想情况是某天改用 Gradle，但目前尚未做到。不过确实依赖 gradle prepDev 来生成 Eclipse 工程并构建其依赖项，这正是仓库中存在 build.gradle 的原因。

注意：只有 “Eclipse IDE for Java and DSL Developers” 才能执行以下操作，且官方建议使用该版本 Eclipse。还可以构建出携带 XTEXT runtime 的安装包——默认分发构建未包含 XTEXT runtime，因为那会增加 80MB 体积。

6.1 导入 Eclipse 工程（默认处于停用状态）

1. 取消 settings.gradle 中包含 GhidraSleighEditor 项目的行注释（includeProjects('GhidraBuild/EclipsePlugins/GhidraSleighEditor') // requires Eclipse DSL）；
2. 运行 gradle eclipse -PeclipseDSL 生成 GhidraSleighEditor 的 Eclipse 工程；
3. 在 Eclipse 中 File -> Import -> General -> Existing Projects into Workspace；
4. 从 ghidra 仓库导入所有 “Eclipse GhidraSleighEditor *” 工程。

6.2 生成 Sleigh XTEXT 生成文件

1. 打开 “Eclipse SleighEditor” 工程；
2. 定位到文件 src -> ghidra.xtext.sleigh -> GenerateSleigh.mwe2；
3. 注意：下列步骤会从互联网（不是 NSA）下载一个 jar 文件，除非你预先下载：
   1. 下载 http://download.itemis.com/antlr-generator-3.2.0-patch.jar；
   2. 把文件放到 ghidra/GhidraBuild/EclipsePlugins/SleighEditor/ghidra.xtext.sleigh（README 原文路径，实际仓库中对应 GhidraBuild/EclipsePlugins/GhidraSleighEditor/ghidra.xtext.sleigh）；
   3. 将文件重命名为 .antlr-generator-3.2.0-patch.jar（点开头文件，供 XTEXT 自动发现）；
4. 从弹出菜单执行 RunAs -> MWE2 Workflow；
   • xtend-gen 与 src-gen 中的文件将被创建；
5. 如果任何 “Eclipse Sleigh*” 工程出现红色书签：
   • 全选这些工程，从弹出菜单刷新（refresh）；
   • 工程应当重新构建，且不应再有红色 Problem 错误。

6.3 试用 Sleigh 编辑器

1. 打开 “Eclipse SleighEditor” 工程，选择 RunAs -> Eclipse Runtime；
2. 添加一个 Sleigh 处理器模块，两种方式二选一：
   1. File -> New Java Project...：取消默认位置勾选，导航到 Ghidra/Processors/<X> 下某个处理器目录；工程会被自动命名为 <X>；点击 Finish；取消 Module 创建弹窗；然后导航到 <X>/data/languages/<file>.sinc 或 <file>.slaspec；在询问是否转换为 XTEXT 工程的弹窗中选择 “Yes”；
   2. 或者，直接把 .slaspec 或 .sinc 文件从文件浏览器拖进 Eclipse。这种方式适合快速查看，但跨文件导航可能不工作。

6.4 可选：修改版本号（GhidraSleighEditor 的版本独立于 Ghidra）

1. 打开 GhidraSleighEditor Feature 工程中的 feature.xml（即 feature.xml）；
2. 在 “Overview” 页把 “Version” 字段更新为 x.y.z.qualifier 并保存；
3. 打开该 Feature 工程中的 category.xml；
4. 选中 ghidra.xtext.sleigh.editor (x.y.z.qualifier)，点击 “Remove”；
5. 选中 ghidra.xtext.sleigh.editor，点击 “Add Feature”；
6. 选择 ghidra.ghidradev (x.y.z.qualifier)，点击 “OK” 并保存；
7. 如有必要，更新本文档（README）中的 “Change History” 部分。

6.5 可选：打包 XTEXT runtime

可以把 XTEXT runtime（redist 模块）打进 zip，这样目标 Eclipse 就无需自带 DSL/XTEXT 即可运行该编辑器：

1. 进入 ghidra.xtext.sleigh.feature 工程；
2. 双击 feature.xml，用 Feature Manager Editor 打开；
3. 进入 “Included Features” 页；
4. 点击 Add...；
5. 以 redist 过滤，添加 org.eclipse.xtext.redist。

6.6 创建可安装 zip

1. 执行 gradle prepDev，确保 GhidraSleighEditor 的依赖是最新的；
2. File -> Export -> Plug-in Development -> Deployable plugins and fragments；
3. 选择 Archive file，指定保存目录，命名为 GhidraSleighEditor-x.y.z.zip；
4. 在 “Options” 页确认选项：
   • Export source：不勾选
   • Package as individual JAR archives：勾选
   • Generate p2 repository：勾选
   • Categorize repository：勾选
   • Qualifier replacement：勾选，并清空输入框使用默认值
   • Save as Ant script：不勾选
   • Allow for binary cycles in target platform：勾选
   • Use class files compiled in the workspace：不勾选
5. 点击 Finish。

7. 卸载与升级

7.1 卸载

1. 点击 Help -> About Eclipse（macOS 下为 Eclipse -> About Eclipse）
2. 点击 Installation Details
3. 选中 Ghidra Sleigh Editor
4. 点击 Uninstall...
5. 选中 Ghidra Sleigh Editor
6. 点击 Finish
7. 点击 Restart Now

7.2 升级

升级方式与首次安装完全相同：用新版本的 zip 重复第 3 节的 Install New Software 流程即可。

8. 小结

GhidraSleighEditor 展示了 XTEXT 框架把一个领域特定语言（Sleigh）做成现代 IDE 体验的完整链路：Sleigh.xtext 定义语法与模型 → MWE2 生成解析/补全/验证骨架 → 自定义 SleighScopeProvider 解决上下文敏感的作用域与局部变量声明约束 → 自定义 SleighValidator 发出重名与昂贵匹配的黄色警告 → SleighQuickfixProvider 提供四类一键修复 → SleighFormatter 实现两遍统计式的列对齐与缩进 → feature 工程打包成带 p2 仓库与类别的 zip。对于要新增或修改 Ghidra/Processors/<X> 下处理器模块的开发者，这套“解析即诊断、跳转即导航、格式化即对齐”的工具链，配合 Processors 目录下的真实 .sinc/.slaspec 样例，就是日常开发 Sleigh 规格的完整工作方式。