amdgpu-asm-tool — VS Code Extension

1. 实现的功能

1.1. 对`.s`、`.S`、`.asm`、`.ASM` 文件语法着色

支持函数跳转（DefinitionProvider + ReferenceProvider）
支持悬停文档（HoverProvider）
支持大纲导航（OutlineTreeProvider）

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

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

alt text

左侧面板：十六进制 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 Header：树形结构展示 ELF 头信息，包含 e_ident、e_flags（AMDGPU 特定位域解析：Mach ID、XNACK、SRAMECC、Target ID 等）
- Segments：表格展示 Program Headers（Type、Flags、Offset、VirtAddr、PhysAddr、FileSz、MemSz、Align）
- Sections：表格展示 Section Headers（Name、Type、Flags、Addr、Offset、Size、Link、Info、Align、EntSize）
- Symbols：表格展示 Symbol Table（Name、Value、Size、Bind、Type、Visibility、Index）

1.3. Code Object (.co) 反汇编为 .asm 文件

生成的 .asm 文件可用 clang -target amdgcn-amdhsa 重新汇编

1.4. 汇编文件编译成 .co 文件

在 .s、.S、.asm、.ASM 文件编辑器中可直接执行 「编译成.co文件」 命令，扩展会自动从汇编里的 amdhsa.target 字段解析 gfxNNNN，调用 /opt/rocm/llvm/bin/clang++ 生成同目录下的 .co 文件。

编译过程中会打开输出通道 「AMDGPU Compile」，打印本次执行的完整编译命令，并同步输出编译器的 stdout / stderr，便于排查参数错误、路径问题或编译失败原因。

1.5. AMDGPU 调试视图（rocgdb / cppdbg 寄存器与变量查看）

alt text

在 VS Code 主编辑器区域打开 AMDGPU 调试视图 面板，自由输入要查看的寄存器（s0、v0、s[0:3]、v[0:7]）、变量名，由扩展通过 正在运行的 cppdbg + rocgdb 调试会话 实时取值并按选定数据类型（hex / uint32 / int32 / fp32 / bf16 / fp16）显示。

并支持静态分析汇编符号别名：自动扫描已打开的 .s/.S/.asm 中的 .set / .equ / NAME = EXPR 定义，把 v[v_a]、s[s_A_base:s_A_base+1] 这类带符号下标的表达式解析成 v16、s[18:19] 后再去取值。

1.6. LDS 布局可视化（静态分析）

alt text

在汇编源中用 print "layout lds" 标记要展示的 LDS 访问：扩展会解析其上一行的 ds_* 指令，通过符号化执行推断各线程的 LDS 字节地址，在 LDS Layout Webview 中以可缩放网格展示（可选显示地址、数据寄存器、Wave/Thread；支持 bank conflict 统计；若地址依赖 kernel 参数可在面板中输入仿真值后重算）。

1.7. Global 布局可视化（静态分析）

alt text

在汇编源中用 print "layout global" 标记要展示的 Global Memory 访问：扩展会解析其上一行的 global_load_* / global_store_* / buffer_load_* / buffer_store_* 指令，通过符号化执行从 kernel 入口一路回溯得到 addr = f(tid_*, bid_*, kargs, consts)，再把 grid 内每个 workgroup 逐 thread 代入得到真实触达的字节。结果在 Global 布局视图 Webview 中以内存映射网格展示：

每一行代表 buff stride 字节（buffer 行跨度），每一格代表 col stride 字节；
每个 group 按真实触达的字节（包括 2D tile 的多行多列 / 非连续 stride）贴到对应格子——一个 group 可以占多行多列，不会再被压缩成一格；
相邻 group 自动以深/浅同色交替渲染，边界一眼可辨；多 group 覆盖同一格 → 黄色 Overlap 色；
支持 下钻到单个 Group 看每 thread 的地址与 tid 映射；
若地址依赖 kernel 参数，可在面板中填仿真值后重算。

1.8. 指令排序时间轴视图

指令排序视图

指令排序视图会按时间轴展示源码或 .co 反汇编中的指令。支持按指令类别区分 Scalar、Vector、LDS、Memory、MFMA/WMMA、Branch 等类别，并选择在色块上显示指令序号、PC 地址和指令名。

支持解析 s_branch 指令，并连线跳转目标；
支持解析 s_waitcnt 指令，并连线等待目标；
支持统计自定义区间内的各类指令数目

1.9. ATT Trace 可视化

trace解释视图

1.10. 常用skill

技能源码位于 vsext/skills/，按 gfx 代际分目录，每个技能是一个含 SKILL.md 的目录。可供 Cursor / Claude / Codex 等 AI agent 加载使用。

技能	路径	用途
`dump-ttrace`	`skills/gfx1250/dump-ttrace/`	用 `rocprofv3 --att` 抓 gfx1250 / MI400 的 ATT ttrace：解码库与环境、`--att-simd-select 0` 等关键开关、让目标 CU 上有 wave 的 grid 配置、单 wave 抓取、判定 dump 是否有效
`parse-ttrace`	`skills/gfx1250/parse-ttrace/`	解析已解码的 ATT dump：`code.json` / `filenames.json` / 逐波 JSON 字段、类别枚举、发射拍 = `time + stall`、补回无 token 指令、stall 热点与循环逐拍；附 `scripts/ttrace_summary.py`
`read-clocks`	`skills/gfx1250/read-clocks/`	获取运行频率：sysfs 采样 gfxclk / mclk / fclk / socclk / 功耗（1 ms），以及从 ATT `realtime.json` 算 dispatch 内的 gfxclk 曲线（约 160 ns）；附 `scripts/clk_sample.py`、`scripts/att_clk.py`
`disasm-co`	`skills/gfx1250/disasm-co/`	把 gfx1250 `.co` 反汇编成可重编的 `.s`：分支改标签、KD 转 `.amdhsa_*` 指令、metadata 转 `.amdgpu_metadata`，自动重编比对，汇编器写不出的指令保留为 `.long`；默认按反汇编等价，`--exact` 要求逐字节相同；附 `scripts/co2s.py`（含 TDM 误解码补丁）
`disasm-tdm`	`skills/gfx1250/disasm-tdm/`	gfx1250 TDM（`tensor_load_to_lds` / `tensor_store_from_lds`）的 LLVM 反汇编补丁说明：识别、原因、`tdm_words.py` 编解码/扫描，与 `disasm-co` / `.co` 查看器中的折叠逻辑对应
`wait-alu`	`skills/gfx1250/wait-alu/`	检查与调整 gfx1250 / gfx1251 在 `SCHED_MODE.DEP_MODE=2` 下的 `s_wait_alu`：VGPR 跨管道 RAW/WAR/WAW、分支/循环、MSB、内存 wait 覆盖及 WMMA 共执行边界；附 `.co` 检查脚本 `scripts/check_wait_alu_co.py` 和返回源码行号的 `.asm` 检查脚本 `scripts/check_wait_alu_asm.py`
`vgpr-bank`	`skills/gfx1250/vgpr-bank/`	分析与优化 gfx1250 / gfx1251 的 VGPR 读 bank 冲突：真实读源、宽操作数与 MSB、广播值复制、缓存/forwarding 对时序的影响，以及 VOPD 专用限制
`lds-bank`	`skills/gfx1250/lds-bank/`	分析与优化 LDS 64-bank 冲突：字节地址、事务分组、宽/转置访问、load 广播与 store/atomic 的区别，以及 padding 和可逆 swizzle
`lds-segment`	`skills/gfx1250/lds-segment/`	分析与优化 LDS 64 KiB segment 争用：物理分配基址、wave/端口映射、逐阶段足迹、跨界访问、TDM/DS 重叠和访问次序置换
`isa-gfx1250`	`skills/gfx1250/isa-gfx1250/`	TDM ISA 与 G0–G3 位域；SCOPE/TH、LU/WB；cluster 拓扑/启动、TTMP 状态、多播请求与 barrier/release/acquire，以及 LLVM 语法与编码核对

1.11 设备信息查看

在编辑区旁打开 设备信息 面板，列出本机全部 AMD GPU。静态信息优先用 rocminfo 读取（找不到时回退 amd-smi static），包括 amdhsa.target、CU、wavefront、LDS、缓存和 PCI 地址。GPU 占用、VRAM、温度和功耗由 rocm-smi 定时刷新（找不到时回退 amd-smi metric）。

可通过命令面板 AMDGPU: 打开设备信息面板 打开，或先点活动栏 AMDGPU 图标，再在侧边栏「设备信息」里点 打开设备信息面板。

2. 使用方式

2.1. 语法着色

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

2.1.1 汇编文件编译成 .co 文件

在已打开的 .s、.S、.asm、.ASM 文件编辑器中右键，选择 「编译成.co文件」。

扩展会先检测 /opt/rocm/llvm/bin/clang++ 是否存在；检测成功后，会从汇编里的 amdhsa.target 字段解析出 gfxNNNN，并执行：

/opt/rocm/llvm/bin/clang++ -x assembler -target amdgcn--amdhsa --offload-arch=gfxNNNN ./xxx.y -o xxx.co

其中 xxx.y 为当前汇编文件完整文件名，输出文件为同目录下的同名 .co 文件。

2.1.2 检查 s_wait_alu

扩展把当前编辑器内容传给内置的 skills/gfx1250/wait-alu/scripts/check_wait_alu_asm.py，包括未保存的修改。检查过程中不保存源码、不生成 .co，可通过进度通知取消。需要 Python 3.10+ 和支持 gfx1250 / gfx1251 的 llvm-mc。

结果显示在 “问题”面板和 “AMDGPU s_wait_alu”输出通道：

未覆盖依赖在消费者行显示警告，附上冲突 VGPR、RAW/WAR/WAW、建议的 wait 字段；关联信息可以跳转到生产者。
CHECKED 表示支持的模型内未发现未覆盖依赖；REVIEW 表示存在待核对依赖；INCOMPLETE 表示有未知指令、非零等待未证明等限制，仍保留已发现的问题。汇编语法或工具错误会单独报告。
主源码修改、关闭或检查设置变化后清除旧诊断；再次检查会替换该文件的结果。同一文件的新检查会取消前一次检查。
宏、重复块和 include 可能定位到展开调用行；须结合显示的展开指令检查内部等待位置。include 从磁盘读取，修改 include 后应保存并重新检查主文件。

可在 VS Code 设置中配置：

设置	默认值	用途
`amdgpu.waitAlu.pythonPath`	`python3`	Python 3.10+ 解释器路径
`amdgpu.waitAlu.llvmBin`	空	`llvm-mc` 所在目录；为空时按 `ROCM_LLVM_BIN`、`/opt/rocm/llvm/bin`、PATH 查找
`amdgpu.waitAlu.mcpu`	`auto`	从源码声明识别架构；没有声明时设为 `gfx1250` 或 `gfx1251`
`amdgpu.waitAlu.entryMode`	`0`	初始 DEP_MODE，随后按执行路径推导；仅在已知入口处于 Mode 2 时设为 `2`
`amdgpu.waitAlu.includeDirectories`	`[]`	额外 include 目录；相对路径基于当前源码所在目录

脚本用法与支持边界见源码检查器文档。开发回归在 vsext/ 下运行 npm run test:wait-alu，测试编辑器诊断、未保存内容、取消与过期结果处理，并调用实际 Python / LLVM 前端。

2.2. .co 文件查看

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

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

2.3. .co 文件反汇编为 .asm 文件

在 .co 文件查看器中，点击 "导出为 .asm 文件" 按钮，可将 Code Object 反汇编为可重新汇编的 AMDGPU 汇编源文件。

2.4. AMDGPU 调试视图

用途：调试 AMDGPU 汇编（.s / .asm）时，在主编辑器区域打开一个面板，输入任意寄存器或表达式查看运行时值。

2.4.1 打开面板

按 Ctrl+Shift+P（macOS：Cmd+Shift+P）打开命令面板。
输入 AMDGPU: 打开rocgdb调试视图（命令 ID：amdgpuDebug.openView），回车。
扩展会在主编辑器区域打开标签页 「AMDGPU 调试视图」。

同样会注册的命令还有：AMDGPU Debug: 启动 rocgdb 会话（amdgpuDebug.start）、AMDGPU Debug: 停止 rocgdb 会话（amdgpuDebug.stop）。

2.4.2 选择调试后端

面板顶部状态栏显示当前后端与状态（已就绪 / 未运行）。由配置 amdgpuDebug.backend 控制：

auto（默认）：若已有 type: cppdbg 调试会话，则复用该会话；否则使用扩展自启的 rocgdb。
activeCppdbg：仅复用当前活动的 cppdbg 会话（推荐：用 C/C++ 扩展 launch.json 启动调试，并把 miDebuggerPath 指向 rocgdb）。
spawnRocgdb：仅使用扩展通过 MI2 启动的独立 rocgdb 子进程。点面板上的 「启动 rocgdb」 按钮启停。

2.4.3 添加 / 编辑监视项

输入框支持的内容：

输入	含义
`s0`、`v15`	单个 SGPR / VGPR
`s[0:3]`、`v[0:7]`	寄存器范围（VGPR 范围只展示每个 VGPR 的 lane 0；如需完整向量请单独添加 `vN`）
`v[v_a]`、`s[s_A_base:s_A_base+1]`	符号别名：根据汇编里的 `.set` 定义解析为 `v16` / `s[18:19]`，然后查询对应 GPR（详见 6.4）
`v_a`、`TILE_Y`、`LOAD_DWORD`、`BLOCK_SIZE`	静态常量：直接显示由汇编 `.set` / `NAME=EXPR` 计算出的常量值（详见 6.4）
`$pc`、`$sp` 等	rocgdb / GDB 内置变量
`(int)0x12340000`、`my_var`	任意 GDB 表达式或 C/C++ 端变量

操作：

按 Enter 或点 「添加」 新增监视项；点行内表达式可编辑，编辑后再次按 Enter 生效。
每行可单独选 数据类型（hex / uint32 / int32 / fp32 / bf16 / fp16），切换后即刻重算。
按钮：「刷新」（单项）/ 「全部刷新」 / 「删除」 / 「全部清空」。
勾选 「断点停下时自动刷新」（默认开）：通过 cppdbg 的 DebugAdapterTracker 监听 stopped 事件，命中断点时自动重算所有监视项。
监视项持久化保存在 workspaceState（amdgpuDebug.watchItems），重开窗口仍在。

2.4.4 符号别名解析（静态分析）

面板顶部「符号表」状态栏会显示当前已加载的别名数量与来源文件，按钮 「重载符号表」 可手动重新扫描。扫描内容来自 当前打开的 .s / .S / .asm 文档：

识别的定义形式：.set NAME, EXPR、.equ NAME, EXPR、NAME = EXPR。
表达式支持：十进制 / 0x... 十六进制 / 0b... 二进制；运算符 + - * / % << >> | & ^ ~ 与括号；可引用其它已定义符号（多遍迭代解析）。
自动重新扫描：保存 / 打开 / 关闭 .s 文档，或切换活动编辑器到 .s 文档时自动触发。
解析效果：监视项命中别名时，面板会在表达式下方以 → 解析后形式 高亮提示（例如 v[v_a] → v16，s[s_A_base:s_A_base+1] → s[18:19]）。
找不到符号时会给出明确报错并提示重载。

两种使用方式：

想查 GPR 实际值 → 用方括号包起来：v[v_a] / s[s_A_base:s_A_base+1]，扩展会先静态解析下标再向调试后端取值。
想看符号本身的常量值 → 直接输入符号或纯算术表达式：v_a / TILE_Y / LOAD_DWORD，扩展直接显示由 .set / NAME=EXPR 计算出的整数（标记为「汇编静态常量」），不会发到调试后端。

判定优先级：先匹配寄存器形式 (vN、sN、v[…]、s[…])；之后若表达式含至少一个标识符且能用符号表完全求值 → 视为静态常量；最后才落到 GDB print。

示例（与 test/dbg_view/k_vadd.s 对应）：

输入	类型	显示
`v[v_a]`	VGPR	解析为 `v16`，显示该 VGPR 各 lane 的值
`v[v_A_addr:v_A_addr+1]`	VGPR 范围	解析为 `v[26:27]`，显示 v26 / v27（每个 VGPR 仅 lane 0；完整向量请单独添加 `v26`、`v27`）
`s[s_A_base:s_A_base+1]`	SGPR 范围	解析为 `s[18:19]`，显示 s18、s19
`v_a`	静态常量	`16 (0x10)`
`LOAD_DWORD`	静态常量	`1 (0x1)`
`TILE_Y`	静态常量	`4 (0x4)`（由 `TILE_Y = THREADS_PER_BLOCK_Y` 推得）
`BLOCK_SIZE`	静态常量	`128 (0x80)`
`karg_A_buff_offset`	静态常量	`0 (0x0)`
`my_var`、`(int)0x12340000`、`$pc`	GDB 表达式	不在符号表内，发给调试后端 `print` 求值

提示：若想把同一个符号既当静态常量又查它的 GPR 值，可以同时添加两条：v_a（看 16）和 v[v_a]（看 v16 的运行时值）。

2.5. LDS 布局可视化

打开 .s / .S / .asm / .ASM 文件（语言 ID：amdgpu-asm）。
在目标 LDS 指令的下一行 添加：print "layout lds"。
命令面板执行 AMDGPU: Show LDS Layout（命令 ID：amdgpu.showLdsLayout），在编辑器旁打开 LDS Layout 面板。
匹配规则：从 print "layout lds" 向上查找，跳过空行与行注释；第一条非空行须为 ds_* 内存指令，否则跳过该标记。
面板：标记下拉（多处标记时切换）；粒度 1B / 4B / 8B / 16B；列数；显示项开关；滚轮缩放、拖拽平移；悬停提示；状态栏含 LDS 占用与 bank conflict 摘要。
自动刷新：修改当前汇编且 LDS Layout 已打开时，约 500 ms 防抖后重新分析。
Kernel 参数：分析结果若需要 kernarg 仿真值，面板顶部会出现输入框与计算按钮。

示例：../test/lds_read_write/k_vadd.s。

2.6. Global 布局视图

用途：在一张内存映射网格上可视化一次 global_* / buffer_* 指令被 grid 里所有 workgroup 执行时、各自触达的字节位置。既能展示 1D 连续访问，也能正确还原 2D tile、strided 等非连续访问的真实形状。

2.6.1 打开面板

打开 .s / .S / .asm / .ASM 文件（语言 ID：amdgpu-asm）。
在目标 global 指令的下一行 添加：print "layout global"。
打开方式二选一：

命令面板执行 AMDGPU: 打开Global布局视图（命令 ID：amdgpu.showGlobalLayout），在编辑器旁打开 Global布局视图 面板。
或者直接点击汇编文件编辑器标题栏中的 「打开Global视图」 按钮。

匹配规则：从 print "layout global" 向上查找，跳过空行与行注释；第一条非空行须为 global_* / buffer_* 类内存指令，否则跳过该标记。
自动刷新：修改当前汇编且面板已打开时，约 500 ms 防抖后自动重新分析。
Kernel 参数：地址公式若依赖 kernarg，面板顶部会出现输入框和 「应用并重算」 按钮；若未提供，状态栏会显示「需要 Kernel Args」。

示例：../test/lds_view/k_vadd.s（同一文件里混合了 layout global 与 layout lds 标记，可对比两种视图）。

2.6.2 两种显示模式

面板用 「显示全部 Groups」 / 「显示一个 Group」 切换。

a) 显示全部 Groups（概览：内存映射网格）

每行 = buff stride 字节；每格 = col stride 字节；每行列数 = floor(buffStride / colStride)。
网格基址自动向下对齐到 buffStride 边界，这样任意绝对字节地址稳定映射到 (row, col)。
每个 group 按 group.rows[]（per-thread 访问合并后的连续段）把真实触达的字节贴到对应单元格，不再假设 group 内地址一定连续——2D tile 会跨多行多列、stride 访问会留出空格。
配色规则：同一个 marker 的 group 按 (bidX + bidY + bidZ) & 1 棋盘分档，两档是同色相不同透明度（0.35 / 0.70）。任意沿单维度的相邻 group（bidX±1、bidY±1、bidZ±1）必然换档 → 可轻松分辨边界；≥ 2 个 group 落到同一格 → 黄色 Overlap 色；无任何 group 触达 → 虚线空格。
行头：显示该行的绝对字节地址 @<addr>（baseAddr + row × buffStride）。
列头：显示行内字节偏移 +NB（按 col stride 递增），与行头相加即为该 cell 的绝对地址。
悬停任意单元格：显示该 cell 的绝对字节区间、对应的 row/col 偏移，以及落在其中的所有 group（最多列 8 个，tile 会额外标「2D tile, N 行」）。

b) 显示一个 Group（细节）

填入 bid_x / bid_y / bid_z 后点击 「显示一个 Group」 切换。
若该 group 是 2D tile（group.rows.length > 1）→ 每条 tile row 作为一个显示行按自然宽度排列，行头 r<idx>@<startAddr>，忽略 列数 numCols（避免把行间 stride 的字节也画上来）。
若是 1D 连续访问 → 按 列数 numCols 把一段长地址折成若干行显示，行头为该行起始绝对地址。
每格显示第一个命中该字节的 tid[x,y,z] 与字节区间；命中多个 thread 时会标注 +N threads。
列头按 粒度 cellSize（1 Byte / 4 Bytes(dword) / 8 / 16 / 64 / 256 / 1KB / 4KB）递增显示 +NB。

2.6.3 工具栏与参数输入

输入 / 控件	仅概览	仅细节	说明
`buff stride`	✅	—	每行内存跨度。count × unit，默认 `1 × 4B(dword) = 4B`。2D 场景建议填 buffer 真实 row pitch（例如 `32 × 4B = 128B`）。
`col stride`	✅	—	每个格子覆盖多少字节。count × unit。count=0 时回退到「所有 group 真实宽度中位数」的 auto 缺省；状态栏会标注 `(auto)`。
`bid_x / bid_y / bid_z`	—	✅	选择要下钻的单个 group。
`粒度 cellSize`	—	✅	细节模式下每个 cell 覆盖多少字节。
`列数 colCount`	—	✅	仅对 1D 连续访问有效；tile 模式忽略。
WG x/y/z, Grid x/y/z	✅	✅	workgroup / grid 尺寸。默认从汇编解析（`.amdhsa_workgroup_*`、常量等），可手动覆盖。
Kernel Args	✅	✅	地址公式中用到的 kernarg；只有需要时会显示输入框。
「应用并重算」			提交当前 WG / Grid / Kernel Args 组合。
「公式」			弹出侧边面板，列出地址公式、需要的 kernarg、前若干 group 的摘要（含 tile rows 信息）。
滚轮缩放 + 左键拖拽平移	✅	✅	大网格也能平滑浏览。

2.6.4 状态栏

概览：| 概览模式(内存映射网格) | col stride: NB [(auto)] | 内存行 R × 每行 C 格 | Groups: G
细节（2D tile）：| 细节模式(显示thread) | Group[x,y,z] | Threads: T | 2D tile N行 | 触达: XB / span [..]=YB
细节（1D 连续）：| 细节模式(显示thread) | Group[x,y,z] | Threads: T | 区间: [..] (XB)

2.6.5 典型用法

1D vadd：保持默认 buff stride = 4B、col stride = 4B，概览每格就是一个 dword；每个 group 占一行连续若干格，相邻 group 深浅交替。
2D tile kernel（如 GEMM 读 A 一行）：把 buff stride 设成矩阵 A 的 row pitch（如 32 × 4B = 128B），col stride 设为单元粒度（如 1 × 4B = 4B），就能在网格里看到 tile 的真实形状——每个 group 占一个矩形区块，相邻 tile 深浅交替。
strided gather / scatter：把 col stride 调细（例如 1B），可以精确看到每个线程访问的字节位置，空余字节以虚线空格体现。

2.7. ATT Trace 可视化

2.7.1 打开 `.att`

在 VS Code 中直接打开 *.att 文件，扩展会使用自定义只读编辑器 AMDGPU ATT Trace 查看器。
也可以在资源管理器右键 *.att，或打开文件后点击标题栏命令 「AMDGPU: 打开ATT Trace可视化视图」（命令 ID：amdgpu.showAttViewer）。
首次打开时会自动调用 Python 解码脚本和 ROCm 解码库，完成后显示 per-wave canvas 时间线和 stall 统计。

2.7.2 Code object 目录

ATT dump 本身能提供 wave / instruction 时间线、category 和 stall 信息；若需要 PC→反汇编文本映射，需要提供对应 kernel 的 code object：

默认扫描 .att 同目录下的 *.out。
支持 testft 风格文件名：*#offset=0x<base>&size=<size>.out，用于恢复 code object load base / size。
普通 *.out 会降级为 load_base=0、load_size=文件大小。
在 ATT Viewer 工具栏点击 「选择 code object 目录」 可手动指定目录。

提供 code object 后，tooltip 中会显示 PC 和反汇编文本，并可把 v_mfma* / v_wmma* / v_smfmac* 从 VALU 中细分为 Tensor 类别。

2.7.3 鼠标操作

操作	效果
鼠标移动	泳道区或频率带上显示贯穿全部泳道的十字准星，时间轴上标出当前 cycle（已知频率时附时间）
滚轮	横向时间轴：以光标处为锚点缩放；纵向：上下滚动时间轴
右键拖拽	平移时间轴
左键拖拽	选取拖过的时间范围内全部泳道的指令，在任意泳道（包括空泳道）上拖都可以；拖动时显示范围带和跨度
左键单击	选中单条指令；点在空白处清空选择
按住 Ctrl/⌘/Shift	单击或拖拽时追加到已有选择，不清空

2.7.4 gfxclk 频率曲线

trace 里带有 REALTIME 样本时（compute-viewer dump 的 realtime.json，或 .att 解码出的 REALTIME 记录），面板会画出这次 dispatch 内的 gfxclk 曲线，并与指令时间线对齐：

工具栏 「频率曲线」 选择差分窗口：关 / 1 / 5 / 10 / 20 / 50 个样本，默认 10。每个样本约 256 cycle，窗口越大越平滑；窗口 1 只能看到 1600 / 2133 MHz 这类量化台阶。
横向时间轴时，曲线位于时间轴下方；纵向时，位于时间轴右侧。曲线随缩放、滚动同步，虚线为全程平均频率。
十字准星的竖线贯穿时间轴、频率带和全部泳道，可直接对照指令与频率；鼠标在频率带上时会提示该处的 gfxclk。
指令 tooltip 附带发射时刻的 gfxclk；左键拖选的时间范围不少于约 4 个样本间隔时，选区信息会显示「平均 gfxclk」。
时间轴切到「时间」时，cycle 按实测平均频率换算（概要信息里标为「REALTIME 实测平均」），不再用峰值 sclk。realtime.json 的 metadata.frequency 为 0 时，realtime 计数器按 100 MHz 计算。
trace 中没有 REALTIME 样本时，「频率曲线」下拉框显示「无 REALTIME 样本」并禁用。

2.8. 安装 skill

技能（见 1.10）随插件打包在扩展目录的 skills/ 下。Cursor、Claude、Codex 不会去扫描插件目录，需要把每个技能目录（含 SKILL.md 的那一层）放进它们的发现目录：

工具	当前用户	当前仓库
Cursor	`~/.agents/skills/` 或 `~/.cursor/skills/`	`.agents/skills/` 或 `.cursor/skills/`
Claude	`~/.claude/skills/`	`.claude/skills/`
Codex	`~/.agents/skills/`	`.agents/skills/`

插件提供三个命令完成这件事。按 Ctrl+Shift+P 打开命令面板，输入 amdgpu asm skills：

命令	命令 ID	作用
AMDGPU: 安装 amdgpu asm skills	`amdgpu.installAiSkills`	选择范围、目录、技能和方式后安装
AMDGPU: 更新 amdgpu asm skills	`amdgpu.updateAiSkills`	升级插件后，把已安装的技能刷新到新版本
AMDGPU: 移除 amdgpu asm skills	`amdgpu.removeAiSkills`	只删除本插件安装的条目

执行过程写入输出通道 「AMDGPU Skills」。插件激活时不会自动写入任何目录，必须手动执行这些命令。

2.8.1 安装

执行 「AMDGPU: 安装 amdgpu asm skills」，依次选择：

安装范围
- 当前用户：写到 ~/ 下，所有项目都能用。
- 当前工作区：写到当前打开的第一个工作区根目录下，只在这个仓库可用。Cloud Agent 只读仓库里的技能，要在云端用就选这个。
发现目录（可多选）：.agents/skills（默认勾选，三个工具都读）、.claude/skills（默认勾选）、.cursor/skills。
技能（可多选）：默认勾选正式技能。标了「占位」的技能只有被点名时才会加载，需要的话可以手动勾上。
安装方式
- 符号链接：插件先把 skills/ 同步到固定目录 ~/.amdgpu-asm-tool/skills/，发现目录里放的是指向它的链接。升级插件后执行一次「更新」即可。当前用户范围默认用这个。
- 复制：每个发现目录放一份独立副本，可以随仓库提交到 git。当前工作区范围默认用这个，因为链接指向本机路径，到别的机器上会失效。

补充说明：

无法建立符号链接时（例如 Windows 未开启开发者模式），会自动改为复制，并在完成提示里注明。
目标位置已有同名目录、且不是本插件安装的，会先弹窗确认再替换。
安装记录保存在 ~/.amdgpu-asm-tool/manifest.json，更新和移除都只操作其中记录的条目。

完成后新开一个 Agent 会话才会生效。验证方法：提到 "dump ttrace"、"解析 ATT"、"gfxclk 频率" 等关键词，对应技能应自动加载；也可以直接点名技能名，例如 dump-ttrace。

2.8.2 更新

升级插件（安装新的 .vsix）后，执行 「AMDGPU: 更新 amdgpu asm skills」：

重新同步 ~/.amdgpu-asm-tool/skills/，链接条目随之生效，复制条目重新复制。
新版本里已经删除的技能，会一并删掉对应条目。
新版本里新增的技能不会自动安装，完成提示会列出名字，需要时再执行一次「安装」。
「复制」方式的副本如果被手动改过 SKILL.md，会先弹窗：选「全部覆盖」或「跳过被修改的」。

2.8.3 移除

执行 「AMDGPU: 移除 amdgpu asm skills」，勾选要移除的条目（默认全选）：

链接条目只在它仍然指向 ~/.amdgpu-asm-tool/skills/ 时才删除；复制条目被手动改过时，会先确认。
全部链接都移除后，同时删除 ~/.amdgpu-asm-tool/skills/。
不会删除 .agents/skills 等目录本身，也不会动其他来源的技能。

2.8.4 常见问题

「插件目录中没有 skills/」：安装的 .vsix 是在加入技能之前打包的，需要升级插件。也可以按 2.8.5 从源码仓库手动安装。
装了但 Agent 没加载：确认是在新会话里试的；确认目标工具读取你选的目录（Claude 不读 .cursor/skills）；用「AMDGPU Skills」输出通道核对实际写入的路径。
不要把技能放进 ~/.cursor/skills-cursor/，那是 Cursor 内置技能的目录。

2.8.5 手动安装（没有插件，或需要脚本化时）

直接使用源码仓库的 vsext/skills/，效果与「当前用户 + 符号链接」相同：

SRC=/path/to/amdgpu-asm-tool/vsext/skills
mkdir -p ~/.amdgpu-asm-tool && rm -rf ~/.amdgpu-asm-tool/skills && cp -r "$SRC" ~/.amdgpu-asm-tool/skills
for dest in ~/.agents/skills ~/.claude/skills; do
  mkdir -p "$dest"
  for s in ~/.amdgpu-asm-tool/skills/*/*/; do
    [ -f "$s/SKILL.md" ] && ln -sfn "${s%/}" "$dest/$(basename "$s")"
  done
done

手动建的链接没有写入 manifest.json，所以插件的「更新」「移除」命令不会处理它们。重新执行上面的 cp -r 那一行即可更新；移除时手动删掉这些链接。

3. 安装与配置

3.1. 安装

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

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

3.2. 反汇编配置项

alt text

在 File → Preferences → Settings 中搜索 amdgpu：

设置项	默认值	说明
`amdgpuCoViewer.llvmObjdumpPath`	`/opt/rocm/llvm/bin/llvm-objdump`	llvm-objdump 可执行文件路径，用于反汇编

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

3.3. dbg视图配置项

在 File → Preferences → Settings 中搜索 amdgpuDebug：

设置项	默认值	说明
`amdgpuDebug.backend`	`auto`	后端选择：`auto` / `activeCppdbg` / `spawnRocgdb`
`amdgpuDebug.rocgdbPath`	`rocgdb`	自启 rocgdb 的可执行文件路径
`amdgpuDebug.rocgdbArgs`	`[]`	传给 rocgdb 的额外参数
`amdgpuDebug.startupCommands`	`[]`	rocgdb 启动后顺序执行的命令列表
`amdgpuDebug.defaultDataType`	`hex`	新增监视项的默认数据类型
`amdgpuDebug.laneCount`	`64`	VGPR 向量展示的最大 lane 数量
`amdgpuDebug.queryTimeoutMs`	`1500`	查询命令的超时时间（毫秒）
`amdgpuDebug.logFile`	`""`	文件日志路径（为空禁用）
`amdgpuDebug.logLevel`	`info`	日志级别：`error` / `info` / `debug`

后端运行日志同时写入输出通道 「AMDGPU Debug」。

3.4. ATT Viewer 依赖与配置项

ATT Viewer 依赖 ROCm 官方解码库解析二进制 *.att，扩展本身不直接解析 SQTT 字节流。

3.4.1 系统依赖

依赖	默认 / 示例路径	用途
Python 3	`python3`	运行扩展内置的 `python/att_decode.py`；脚本仅使用 Python 标准库，包括 `ctypes`、`json`、`subprocess` 等
ROCm SDK 入口库	`/opt/rocm/lib/librocprofiler-sdk.so`	ATT 二进制解码入口
ATT 解码后端	`librocprof-trace-decoder.so` 所在目录	ROCm trace decoder 后端；可能不在 `/opt/rocm/lib`，需配置目录
llvm-objdump	`/opt/rocm/llvm/bin/llvm-objdump`	选择 code object 后用于 PC→反汇编文本映射
code object `*.out`	`.att` 同目录或手动选择目录	可选；用于恢复 PC、反汇编文本和 MFMA / WMMA 分类

若找不到 librocprof-trace-decoder.so，可设置 AMDGPU_ATT_DECODER_DIR 环境变量，或在 VS Code 设置中填写 amdgpu.att.decoderDir。

3.4.2 VS Code 配置项

在 File → Preferences → Settings 中搜索 amdgpu.att：

设置项	默认值	说明
`amdgpu.att.pythonPath`	`python3`	运行 ATT 解码脚本的 Python 解释器路径
`amdgpu.att.sdkPath`	`/opt/rocm/lib/librocprofiler-sdk.so`	`librocprofiler-sdk.so` 路径
`amdgpu.att.decoderDir`	`""`	包含 `librocprof-trace-decoder.so` 的目录；为空时自动探测 `/opt/rocm/lib`、`/opt/rocm/lib/rocprofiler-sdk` 等候选目录或 `$AMDGPU_ATT_DECODER_DIR`
`amdgpu.att.llvmObjdumpPath`	`/opt/rocm/llvm/bin/llvm-objdump`	code object 反汇编所用 `llvm-objdump` 路径
`amdgpu.att.defaultMcpu`	`""`	架构兜底值，例如 `gfx942`；解码结果能提供 gfxip 时优先使用解码结果

3.4.3 常见问题

decoder_create failed：通常是 librocprof-trace-decoder.so 未找到，设置 amdgpu.att.decoderDir 或 AMDGPU_ATT_DECODER_DIR。
ATT 解码无输出：检查 python3、librocprofiler-sdk.so 路径和动态库搜索路径是否正确。
n_inst == 0：多见于 trace 采集为空或抓错 kernel，通常不是 Viewer 渲染问题。
没有 PC / 反汇编文本：需要提供对应的 code object *.out，并确保 llvm-objdump 可用。

4. 项目结构

vsext/
├── package.json                    # 扩展清单：语言注册、语义令牌类型/修饰符/作用域
├── tsconfig.json                   # TypeScript 编译配置
├── .vscodeignore                   # 打包忽略文件
└── src/
    ├── extension.ts                # 入口点：注册所有 Provider
    ├── langAssist/language-configuration.json  # 语言基础配置：注释、括号、折叠标记
    ├── tokenizer.ts                # 核心词法分析器（~500 行）
    ├── semanticTokensProvider.ts   # 语义令牌 Provider（语法着色）
    ├── definitionProvider.ts       # 跳转到定义 + 查找引用
    ├── symbolProvider.ts           # 文档符号（大纲视图）
    ├── hoverProvider.ts            # 悬停文档
    ├── instructions.ts             # 指令数据库（~300 条指令文档）
    ├── coEditor.ts                 # .co 文件自定义编辑器
    ├── codissClient.ts             # Code Object 解析与反汇编核心逻辑
    ├── elfParser.ts                # ELF 文件解析器
    ├── ldsLayoutPanel.ts           # LDS 布局 Webview 面板
    ├── ldsAnalyzer.ts              # print "layout lds" 扫描与内核配置解析
    ├── ldsSymbolicEval.ts          # 符号化执行（寄存器 → 地址表达式）
    ├── ldsLayoutComputer.ts        # 逐线程布局计算与 bank conflict 检测
    ├── globalLayoutPanel.ts        # Global 布局 Webview 面板（内存映射网格渲染 / 细节下钻）
    ├── globalAnalyzer.ts           # print "layout global" 扫描 + workgroup/grid/kernarg 解析
    ├── globalSymbolicEval.ts       # 符号化执行：为 global_* / buffer_* 指令回溯地址公式
    ├── globalLayoutComputer.ts     # 逐 group 访问计算；合并 per-thread 区间为 tile rows
    └── rocgdbDebugView.ts          # AMDGPU 调试视图：rocgdb / cppdbg 后端 + Webview 监视面板

amdgpu-asm-tool

feifei_14119

amdgpu-asm-tool — VS Code Extension

1. 实现的功能

1.1. 对.s、.S、.asm、.ASM 文件语法着色

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

1.3. Code Object (.co) 反汇编为 .asm 文件

1.4. 汇编文件编译成 .co 文件

1.5. AMDGPU 调试视图（rocgdb / cppdbg 寄存器与变量查看）

1.6. LDS 布局可视化（静态分析）

1.7. Global 布局可视化（静态分析）

1.8. 指令排序时间轴视图

1.9. ATT Trace 可视化

1.10. 常用skill

1.11 设备信息查看

2. 使用方式

2.1. 语法着色

2.1.1 汇编文件编译成 .co 文件

2.1.2 检查 s_wait_alu

2.2. .co 文件查看

2.3. .co 文件反汇编为 .asm 文件

2.4. AMDGPU 调试视图

2.4.1 打开面板

2.4.2 选择调试后端

2.4.3 添加 / 编辑监视项

2.4.4 符号别名解析（静态分析）

2.5. LDS 布局可视化

2.6. Global 布局视图

2.6.1 打开面板

2.6.2 两种显示模式

a) 显示全部 Groups（概览：内存映射网格）

b) 显示一个 Group（细节）

2.6.3 工具栏与参数输入

2.6.4 状态栏

2.6.5 典型用法

2.7. ATT Trace 可视化

2.7.1 打开 .att

2.7.2 Code object 目录

2.7.3 鼠标操作

2.7.4 gfxclk 频率曲线

2.8. 安装 skill

2.8.1 安装

2.8.2 更新

2.8.3 移除

2.8.4 常见问题

2.8.5 手动安装（没有插件，或需要脚本化时）

3. 安装与配置

3.1. 安装

3.2. 反汇编配置项

3.3. dbg视图配置项

3.4. ATT Viewer 依赖与配置项

3.4.1 系统依赖

3.4.2 VS Code 配置项

3.4.3 常见问题

4. 项目结构

1.1. 对`.s`、`.S`、`.asm`、`.ASM` 文件语法着色

2.7.1 打开 `.att`