Verilog Assistant — VSCode 全功能 Verilog 开发助手

集成 Verible（格式化 & 风格检查）和 Verilator（语义错误检查），提供语法高亮、代码补全、跳转定义、Hover 文档、CodeLens、注释横幅等全套功能。

1. 安装

准备工作

工具	必需	安装
Verible	✅ 是	下载 `verible-verilog-ls`，解压后加入 PATH
Verilator	❌ 否	Windows: MSYS2 `pacman -S mingw-w64-verilator` 或 WSL `sudo apt install verilator`

验证安装：

verible-verilog-ls --version    # 必须成功
verilator --version              # 可选

安装插件

code --install-extension verilog-forge-1.1.1.vsix

重启 VSCode，打开 .v 文件，右下角出现电路板图标表示激活成功。

2. 功能速览

功能	操作	快捷键
格式化	保存自动格式化，或右键 → Format Document	`Shift+Alt+F`
等长对齐	格式化后自动对齐尾部分隔符（需开启 trailingAlign）	—
实时 Lint	输入时自动检查风格	—
Verilator 检查	保存时自动深度检查	—
精确排除	`.verilator_ignore` 文件指定排除的 IP 核	—
跳转定义	Ctrl+Click 模块名/端口名	`F12`
悬浮提示	鼠标悬停符号，显示注释文档	—
代码补全	输入时自动弹出	`Ctrl+Space`
模块引用	模块行上方显示引用数和文件名	—
横幅注释	选中文字 → 右键 → Wrap Banner	`Ctrl+Shift+/`
@keyword 补全	输入 `//! @` 自动弹出注解关键词	—
端口方向	实例化 `.f(sig)` 自动显示 ←输入 / →输出	—

3. 语法高亮 & 格式化

插件自动为 .v .vh .sv .svh 文件着色。

格式化：保存文件自动调用 Verible：

Shift+Alt+F — 手动格式化
右键 → Format Document

风格检查：输入时实时检查，违规处黄色波浪线 + 💡 快速修复。

关闭风格检查："verilog.verible.lintEnabled": false

4. Verilator 语义检查

保存 .v 文件后自动运行，检查：

检查项	示例
位宽不匹配	`assign [7:0] a = [3:0] b;`
端口未驱动	模块输出端口无连接
信号未使用	声明但从未引用的 wire
Case 不完整	`case (x)` 缺少分支
阻塞/非阻塞混用	always 中用 `=` 而不是 `<=`

手动触发：Ctrl+Shift+P → Verilog: Run Verilator Lint

`.verilator_ignore` 文件

在 workspace 根目录创建，YAML-like 语法，三个可选 section：

# 忽略模块（通配符 * ?）
module:
  - xpm_*
  - clk_*out*

# 排除文件夹（glob 模式），不索引不 lint
exclude:
  - **/ip_cores/**
  - **/extra_submodule/**

# 外部库路径，Verilator 搜模块定义
library:
  - D:\App\Xilinx\Vivado\2022.1\data\verilog\src

文件可随 git 共享给团队
也可在设置 verilog.verilator.ignoreModuleList 中配置（仅 module 部分）
library 优先级最高，Verilator 会去这些路径找模块定义

5. 跳转 & 悬浮提示

Ctrl+Click 或 F12 → 跳转到定义
Shift+F12 → 查看所有引用
鼠标悬停 → 显示类型、位宽、文件位置、注释文档

跨文件跳转：自动索引全部 workspace 文件，无需手动配置。

6. 代码补全

输入时自动弹出补全列表。补全来源：

关键词：wire reg assign always（范围由 verilog.language.standard 控制）
模块名：选择后自动插入例化模板（含端口连接）
端口名：在 ( 内输入 . 触发 .port(signal) 补全
代码片段：always → 时序逻辑模板，case → case 模板

7. Hover 注释系统

`//! @keyword` 注解

在声明上方写 //! @keyword，悬停时格式化展示：

关键词	说明	示例
`@brief`	主描述	`//! @brief 计数器模块`
`@author`	作者	`//! @author Lixin`
`@date`	日期	`//! @date 2026-07-05`
`@param`	参数说明	`//! @param WIDTH 数据位宽`
`@port`	端口说明	`//! @port clk 系统时钟`
`@warning`	注意事项	`//! @warning 不可修改`
`@deprecated`	废弃标记	`//! @deprecated 请用 v2`
`@todo`	待办事项	`//! @todo 加流水线`
`@note`	补充说明	`//! @note 已通过 CDC`
`@see`	交叉引用	`//! @see a.v`
`@return`	返回值	`//! @return 计算结果`
`@arg`	函数参数	`//! @arg data 输入`

输入 //! @ 自动弹出补全。@author 值从设置读取，@date 自动填当前日期。

注释就近归属

空行是注释块分界线。hover 时只显示紧邻上方的注释，不会跨空行收集。

横幅注释

选中文字 → Ctrl+Shift+/ 生成 lowRISC 风格居中等宽横幅：

////////////////////////////////////////////
//                                        //
//            Counter Module              //
//                                        //
////////////////////////////////////////////

8. CodeLens

模块 CodeLens：行上方显示引用计数和文件名，点击跳转。

2 refs  b.v:5  top.v:24
module a (...);

变量 CodeLens：行上方显示 2 refs，点击弹出引用位置列表。

9. 端口方向提示

实例化模块时，端口连接自动显示方向箭头：

a inst_name (
    .f(←clk),    // ← 橙色 = 输入
    .h(→j),      // → 蓝色 = 输出
);

10. 配置项参考

Verible

配置项	默认值	说明
`verilog.verible.path`	`""`	二进制路径，空则自动查找 PATH
`verilog.verible.lintEnabled`	`true`	启用实时风格 Lint
`verilog.verible.formatOnSave`	`true`	保存时自动格式化
`verilog.verible.formatStyle`	`align`	对齐风格：`align` / `flush-left` / `infer`
`verilog.verible.trailingAlign`	`false`	等长对齐：格式化后对齐尾部分隔符（`;` `,` `)`）
`verilog.verible.formatArguments`	`""`	Verible 格式化额外参数，覆盖 formatStyle

Verilator

配置项	默认值	说明
`verilog.verilator.enabled`	`true`	启用语义检查
`verilog.verilator.path`	`""`	二进制路径
`verilog.verilator.onSave`	`true`	保存时自动运行
`verilog.verilator.useWsl`	`false`	Windows 通过 WSL 调用
`verilog.verilator.ignoreMissingModules`	`false`	忽略所有找不到的模块
`verilog.verilator.ignoreModuleList`	`[]`	精确排除（支持 `*` 通配符），推荐替代上面的开关

语言 & 注解

配置项	默认值	说明
`verilog.language.standard`	`verilog-2001`	语言标准：`verilog-2001` / `verilog-2005` / `systemverilog`
`verilog.annotation.author`	`""`	@author 默认值
`verilog.annotation.dateFormat`	`YYYY-MM-DD`	@date 格式

CodeLens & 补全

配置项	默认值	说明
`verilog.codelens.moduleEnabled`	`true`	模块 CodeLens
`verilog.codelens.variableEnabled`	`true`	变量 CodeLens
`verilog.completion.enabled`	`true`	代码补全
`verilog.completion.snippetsEnabled`	`true`	补全含片段

11. 命令列表

Ctrl+Shift+P 搜索：

命令	快捷键
Verilog: Format Document	`Shift+Alt+F`
Verilog: Run Verilator Lint	—
Verilog: Wrap with Banner Comment	`Ctrl+Shift+/`
Verilog: Generate verible.filelist	—
Verilog: Toggle Module CodeLens	—
Verilog: Toggle Variable CodeLens	—

12. 常见问题

Q: 格式化不生效？ → 确认 verible-verilog-ls --version 有输出，或设置 verilog.verible.path。

Q: Verilator 报 "not found"？ → Windows 推荐 MSYS2 安装，或设置 verilog.verilator.useWsl: true。

Q: 代码补全出现 logic/always_ff 干扰？ → 设置 verilog.language.standard 为 verilog-2001。

Q: Hover 显示太多注释？ → 用空行分隔注释块，每个符号只显示紧邻上方的注释。

Q: Ubuntu 上 Verilator 报 VERILATOR_ROOT 错误？ → 不要手动设置 VERILATOR_ROOT 环境变量，插件已在 1.0.1 修复此问题。

Q: 如何修改快捷键？ → Ctrl+K Ctrl+S 搜索命令名。

13. 更新日志

v1.1.1

修复 "Exiting due to" 汇总行被计入错误总数（解析时直接丢弃）
修复 filteredCount 计数包含已丢弃的汇总行

v1.1.0

重构 .verilator_ignore 为 YAML-like 三段格式：module / exclude / library
新增 exclude 文件夹排除（glob 模式），不索引不 lint
新增 library 外部库路径（替代旧 libraryFiles 设置）
移除 verilog.verilator.libraryFiles 和 includePaths 配置项

v1.0.1

新增 Verible 格式化风格 formatStyle + 等长对齐 trailingAlign
新增 .verilator_ignore 文件 + ignoreModuleList 精确模块排除
新增 Verilator 输出日志重定向（.verilator_lint.log）
修复 Linux VERILATOR_ROOT 误设
修复 LSP 格式设置即时生效

v1.0.0

初始发布

14. 联系方式

提交 BUG 或需求

发送邮件时请包含以下信息：

**标题：** [BUG/需求] 简短描述

**环境：**
- 操作系统：Windows 11
- VSCode 版本：1.95.0
- 插件版本：0.1.1

**问题描述：**
- 预期行为：
- 实际行为：
- 复现步骤：

**附件（可选）：**
- 截图
- 最小可复现的 Verilog 代码片段

VeriForge

LiXintao

Verilog Assistant — VSCode 全功能 Verilog 开发助手

1. 安装

准备工作

安装插件

2. 功能速览

3. 语法高亮 & 格式化

4. Verilator 语义检查

`.verilator_ignore` 文件

5. 跳转 & 悬浮提示

6. 代码补全

7. Hover 注释系统

`//! @keyword` 注解

注释就近归属

横幅注释

8. CodeLens

9. 端口方向提示

10. 配置项参考

Verible

Verilator

语言 & 注解

CodeLens & 补全

11. 命令列表

12. 常见问题

13. 更新日志

v1.1.1

v1.1.0

v1.0.1

v1.0.0

14. 联系方式

提交 BUG 或需求

VeriForge

LiXintao

Verilog Assistant — VSCode 全功能 Verilog 开发助手

1. 安装

准备工作

安装插件

2. 功能速览

3. 语法高亮 & 格式化

4. Verilator 语义检查

.verilator_ignore 文件

5. 跳转 & 悬浮提示

6. 代码补全

7. Hover 注释系统

//! @keyword 注解

注释就近归属

横幅注释

8. CodeLens

9. 端口方向提示

10. 配置项参考

Verible

Verilator

语言 & 注解

CodeLens & 补全

11. 命令列表

12. 常见问题

13. 更新日志

v1.1.1

v1.1.0

v1.0.1

v1.0.0

14. 联系方式

提交 BUG 或需求

`.verilator_ignore` 文件

`//! @keyword` 注解