集成 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. 代码补全
输入时自动弹出补全列表。补全来源：
- 关键词：
wireregassignalways（范围由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 代码片段