amdgpu-asm-tool — VS Code Extension

对 AMDGPU HSA 汇编文件 (.s) 进行语法着色、函数跳转、悬停文档和大纲导航的 VS Code 插件。基于编程式语言特性 (Semantic Tokens / Language Provider API) 开发。

项目结构

vsext/
├── package.json                    # 扩展清单：语言注册、语义令牌类型/修饰符/作用域
├── tsconfig.json                   # TypeScript 编译配置
├── language-configuration.json     # 语言基础配置：注释、括号、折叠标记
├── .vscodeignore                   # 打包忽略文件
└── src/
    ├── extension.ts                # 入口点：注册所有 Provider
    ├── tokenizer.ts                # 核心词法分析器（~500 行）
    ├── semanticTokensProvider.ts   # 语义令牌 Provider（语法着色）
    ├── definitionProvider.ts       # 跳转到定义 + 查找引用
    ├── symbolProvider.ts           # 文档符号（大纲视图）
    ├── hoverProvider.ts            # 悬停文档
    └── instructions.ts             # 指令数据库（~300 条指令文档）

实现的功能

1. 语法着色（编程式 SemanticTokensProvider）

• AMDGPU 指令：区分标量 (s_*)、向量 (v_*)、内存 (global_* / flat_* / ds_* / buffer_*) 等类别，使用不同语义修饰符
• 寄存器：SGPR (s0~s105, s[n:m])、VGPR (v0~v255, v[n:m])、特殊寄存器 (vcc, exec, scc, null, off 等)
• GAS 伪指令：.text, .data, .section, .global, .set, .p2align 等完整覆盖
• AMDHSA 指令：.amdhsa_kernel / .end_amdhsa_kernel 块内所有 .amdhsa_* 子指令
• Metadata 块：.amdgpu_metadata / .end_amdgpu_metadata 内的 YAML 键值对
• 指令修饰符：glc, slc, dlc, offset, s_delay_alu 的 instid0 / instskip 等
• 注释：;、//、# 行注释和 /* */ 块注释
• 数字 / 字符串：十六进制、十进制、八进制和字符串字面量

2. 函数跳转（DefinitionProvider + ReferenceProvider）

• 支持跳转到标签定义（函数标签如 vadd_kernel:、局部标签如 .LBB0_2:）
• 支持 .amdhsa_kernel 中的 kernel 名称跳转
• 支持 .kd 后缀的 kernel descriptor 符号关联
• 支持查找所有引用

3. 文档符号（DocumentSymbolProvider）

• 大纲视图中显示：函数标签、Kernel Descriptor 块（含所有字段作为子项）、Metadata 块、.set 常量定义、.section 段

4. 悬停文档（HoverProvider）

• 指令悬停：显示分类（SMEM / SOP1 / VOP2 等）、中文说明、语法示例
• AMDHSA 指令悬停：显示说明和对应 Kernel Descriptor 字段名
• GAS 伪指令悬停：功能说明
• 寄存器悬停：SGPR / VGPR 范围显示位宽计算，特殊寄存器显示用途说明
• 修饰符悬停：glc / slc 等修饰符的含义

5. Code Object (.co) ELF 解析查看器

打开 .co 文件时自动启用可视化解析界面：

• 左侧面板：十六进制 Hex Dump（地址 + 十六进制字节 + ASCII）
• 右侧面板：四个 Tab 页切换
  • 反汇编：通过 llvm-objdump 输出 AMDGPU 指令级反汇编
  • Kernel Descriptor：每个 kernel 的 64 字节描述符字段解析（COMPUTE_PGM_RSRC1/2/3 各位域、SGPR/VGPR 配置、enable 位等）
  • Metadata：Code Object Metadata (YAML) 完整内容（amdhsa.kernels、参数列表等），通过内置 MessagePack 解码器从 ELF .note 段直接提取
  • ELF Info：ELF 头信息、GPU 架构、Section 列表、符号表

ELF 解析、Kernel Descriptor 解码和 Metadata 提取均为纯 TypeScript 实现，无需 Python 依赖。仅反汇编功能需要 llvm-objdump（安装 ROCm 后自带）。

使用方式

开发调试

cd vsext
npm install
npm run compile
# 按 F5 在 VS Code Extension Host 中启动调试

打包安装

cd vsext
npx @vscode/vsce package
# 生成 amdgpu-asm-tool-0.1.0.vsix

完整命令

cd vsext && npm run compile && npx @vscode/vsce package

命令行安装

code --install-extension amdgpu-asm-tool-0.1.0.vsix

也可以在 VS Code 中通过 Extensions → ⋯ → Install from VSIX... 手动选择 .vsix 文件安装。

监听模式（开发时自动重编译）

npm run watch

打开任何 .s、.S、.asm、.ASM 文件即可自动激活汇编语法着色，语言 ID 为 amdgpu-asm。

.co 文件查看

直接在 VS Code 中打开 .co 文件即可自动启用 ELF 解析查看器。

配置项（File → Preferences → Settings 中搜索 amdgpuCoViewer）：

前置依赖：仅反汇编功能需要 llvm-objdump（安装 ROCm 后自带）。ELF 解析、Kernel Descriptor 和 Metadata 提取为纯 TypeScript 实现，无额外依赖。

发布到 VS Code 扩展市场

以下步骤可将扩展发布到市场，供其他人在 VS Code 扩展窗口中搜索并安装。

1. 创建 Azure DevOps 组织

VS Code 扩展市场基于 Azure DevOps 账号体系。

1. 打开 https://dev.azure.com
2. 用 Microsoft 账号登录（没有的话先注册一个）
3. 创建一个组织（Organization），例如 feifei-dev

2. 创建 Personal Access Token (PAT)

1. 在 Azure DevOps 右上角点击头像 → Personal access tokens
2. 点击 New Token，填写：
   • Name：随意，例如 vsce-publish
   • Organization：选 All accessible organizations
   • Scopes：选 Custom defined，展开 Marketplace，勾选 Manage
   • Expiration：按需选择
3. 点击 Create，复制生成的 Token（只显示一次，务必保存好）

3. 创建发布者 (Publisher)

1. 打开 https://marketplace.visualstudio.com/manage
2. 用同一个 Microsoft 账号登录
3. 点击 Create publisher，填写：
   • ID：例如 feifei14119（需与 package.json 中的 publisher 字段一致）
   • Display Name：显示名称
4. 创建完成后，确保 package.json 中的 publisher 与此 ID 一致

4. 登录 vsce 并发布

cd vsext

# 登录（会提示输入上面的 PAT）
npx @vscode/vsce login <你的publisher-id>

# 发布
npx @vscode/vsce publish

或者用 PAT 直接发布：

npx @vscode/vsce publish -p <your-personal-access-token>

5. 版本更新

后续更新版本时：

# 自动递增版本号并发布
npx @vscode/vsce publish patch   # 0.1.0 → 0.1.1
npx @vscode/vsce publish minor   # 0.1.0 → 0.2.0
npx @vscode/vsce publish major   # 0.1.0 → 1.0.0

发布前检查清单

发布后大约几分钟内即可在 VS Code 扩展市场搜索到。