sv_trace

Verilog / SystemVerilog / UVM 信号与变量追踪 Vim 插件。

sv_trace 用于跨工程追溯 Verilog / SystemVerilog 代码中信号与变量的声明 (Declarations)、驱动源 (Drivers) 与 负载点 (Loads)。支持 RTL 模块与 SystemVerilog / UVM Class 架构。

插件采用 Vimscript 实现，搭配 Universal-Ctags 与 Ripgrep (或 grep)，不需要 Python、LSP 或后台守护进程，支持 Linux 与 Windows。

• 信号与变量追溯：分析过程赋值 (= / <=)、连续赋值 (assign)、端口连接及参数/宏定义 (parameter, localparam, `uvm_field_*)。
• 跨层追溯 (Parent Hop)：若信号为子模块 input 端口，自动向上寻找父模块例化点 (.port(signal)) 的驱动源。
• 模块与 Testbench 层次结构 (:SvTraceHierarchy / <leader>sh)：扫描全工程并生成 RTL 模块及 SV/UVM Class 组件层次树。
• 全路径层次结构解析 (:SvTracePath / <leader>sH)：计算并输出变量自顶层向下的完整层次路径（如 top.tb.xx_agent.my_drv.case_cfg）。
• 非阻塞赋值与比较运算区分：自动区分 always 块内的非阻塞赋值 (<=) 与条件判断语句中的小于等于比较 (<=)。
• 追溯历史栈：按 u / <C-o> 后退，<C-i> 前进。
• 电路拓扑图导出：一键导出为 Mermaid 流程图 (e) 或 ASCII 文本树 (E)。
• 浮动窗口预览：查看匹配行上下文代码（p 键开关）。
• 零 Tags / 纯 Grep 模式：无 Ctags 缓存时自动回退为纯正则模式运行。

• Vim 8.0+ / Neovim 0.5+
• Ripgrep (rg) (推荐，缺失时回退到系统 grep 或内置扫描)
• Universal-Ctags (推荐，缺失时回退到纯 Grep 启发式匹配)

Linux 安装依赖示例：

# Ubuntu / Debian
sudo apt update && sudo apt install ripgrep universal-ctags

# Fedora / RHEL / CentOS
sudo dnf install ripgrep ctags

使用 vim-plug:

Plug 'sqlmap3/sv_trace'

使用 packer.nvim:

use 'sqlmap3/sv_trace'

使用 lazy.nvim:

{ "sqlmap3/sv_trace" }

原生 Vim Package 方式:

# Linux / macOS
mkdir -p ~/.vim/pack/plugins/start
git clone https://github.com/sqlmap3/sv_trace.git ~/.vim/pack/plugins/start/sv_trace

# Windows
mkdir -p $HOME/vimfiles/pack/plugins/start
git clone https://github.com/sqlmap3/sv_trace.git $HOME/vimfiles/pack/plugins/start/sv_trace

• <leader>st → :SvTrace
• <leader>sd → :SvTraceDrivers
• <leader>sl → :SvTraceLoads
• <leader>sh → :SvTraceHierarchy
• <leader>sH → :SvTracePath
• <leader>sL → :SvTraceLocList
• <leader>sp → :SvTracePin
• <leader>sP → :SvTracePins

禁用默认映射：let g:sv_trace_no_default_map = 1

在 _vimrc 或 init.vim 中设置：

" 1. 指定工程根目录 (单目录/多目录)
let g:sv_trace_root = '/path/to/my_chip'
" 或多目录:
" let g:sv_trace_roots = ['/path/to/rtl', '/path/to/tb']

" 2. 文件扫描与检索
let g:sv_trace_search_tool = 'auto'  " 'auto' | 'rg' | 'grep'
let g:sv_trace_filetypes = ['v', 'sv', 'svh', 'vh', 'svi']

" 向上查找模块例化 Heads 的最大行数限制 (防止超大文件逐行搜到 line 0)
let g:sv_trace_inst_window = 50

" ==============================================================================
" 4. 浮动预览窗口配置 (Floating Code Preview)
" ==============================================================================

" 开启/关闭光标移动时的浮动预览窗口 (1=开启, 0=关闭)
let g:sv_trace_preview = 1

" 预览窗口显示的上下文行数
let g:sv_trace_preview_height = 5

" ==============================================================================
" 5. 作用域与高亮配置 (Scope & Highlight)
" ==============================================================================

" 结果项标注 @module 作用域标签 (1=开启)
let g:sv_trace_show_scope = 1

" 优先将当前 Buffer 所在 Module 的匹配项排在前面 (1=开启)
let g:sv_trace_prefer_current_module = 1

" 跳转源码后高亮匹配信号 (1=开启)
let g:sv_trace_highlight = 1

" ==============================================================================
" 6. Tags 策略与纯 Grep 模式配置
" ==============================================================================

" 主开关：使用 Tags 辅助提取声明 (1=开启, 0=禁用 tags 纯靠 RegEx/Grep)
let g:sv_trace_use_tags = 1

" 优先复用已有 Tags (Gutentags 缓存 / &tags / 工程 tags) 避免重复运行 Ctags
let g:sv_trace_use_existing_tags = 1

" 统一 Gutentags 缓存目录 (仅会加载与当前工程匹配的 tags 索引文件)
let g:sv_trace_tags_dir = expand('~/.cache/tags')

" 显式指定额外的固定 Tags (如 UVM 官方库 tags)
" let g:sv_trace_tags = ['/path/to/uvm-1.2/tags']

" 未找到任何已有 Tags 时是否自动运行 Ctags (1=是, 0=否)
let g:sv_trace_auto_ctags = 1
let g:sv_trace_tags_ttl = 300  " 生成的 .sv_trace_tags 缓存有效时间(秒)

💡 纯 Grep / 零 Tags 运行模式：
若工程极大不希望生成或读取任何 tags 文件，只需设置 let g:sv_trace_use_tags = 0。插件将完全基于强化的 Verilog/SV 语法正则启发式匹配提取声明，无需依赖 Ctags。

在结果窗口中按下 e 键，将自动提取当前信号的驱动与负载关系并导出为标准 Mermaid 流程图 格式：

graph TD
  subgraph Drivers
    node_0["example/top.v:21<br/>.dout(internal_data)"]
  end

  node_target(("internal_data"))

  subgraph Loads
    node_1["example/top.v:25<br/>assign data_out = internal_data + 8'h1;"]
  end

  node_0 -->|port-out| node_target
  node_target --> node_1

按下 E 键可导出直观的 ASCII 文本拓扑树：

================================================================================
Topology Diagram for signal: internal_data
================================================================================

[DRIVERS] (who assigns internal_data)
  ├── example/top.v:21  .dout (internal_data), <port-out> @top

[TARGET SIGNAL]
  └── internal_data

[LOADS] (where internal_data is read)
  └── example/top.v:25  assign data_out = internal_data + 8'h1; @top

1. is_comparison_le 非阻塞赋值与比较运算启发式区分：
   • 准确区分 Verilog 中 <= 符号在 always 块内的 非阻塞赋值 (NBA Driver) 与在条件表达式 (if, while, 三元 ?, &&/|| 右侧, ()) 内的 小于等于比较 (Comparison)。
2. 两阶段流水线异步渲染：
   • 阶段 1：瞬间提取同层与子模块匹配，先出屏渲染 Decl / Driver / Load，防止第一屏等待。
   • 阶段 2：后台自动检查信号是否为当前模块 input 端口；若是，则以非阻塞方式向上查找父模块例化点的赋值，完成平滑更新。
3. 高性能 mtime 范围缓存：
   • 全新的 s:file_module_ranges 解析机制，一次解析后缓存文件内部所有 Module/Class 的行号区间，后续标注作用域仅需 $O(1)$ 区间比较，相比传统逐行向上搜算效率提升数十倍。

插件内置完整的 Headless 无界面冒烟测试集，可在 Shell 中直接运行验证环境正确性：

# Windows
vim -Nu NONE -n -es -S c:/sv_trace/test/run.vim

# Linux / macOS
vim -Nu NONE -n -es -S ~/tools/sv_trace/test/run.vim

测试运行完成后，结果将写入 test/out.txt。若输出末尾为 === ALL PASS === 且退出码为 0，说明插件全部功能正常。

MIT License