XLXL

XLXL 是用于 VS Code 的 Verilog / SystemVerilog 开发插件，集代码编辑、工程管理、语法检查、仿真和波形查看于一体。

主要功能

• 编辑与补全：语法高亮、代码模板、模块例化、命名端口与参数补全，以及端口方向提示。
• 导航与重命名：模块层次树、Outline、模块定义与引用、模块重命名。支持跳到模块内信号的声明、查找其在同一模块中的引用，以及在父模块、子模块和本模块间跳转信号。Modules 按实例联动显示信号位置数量与方向。
• 语法检查：通过所选的 Vivado、ModelSim、QuestaSim 或 Icarus 在保存时或按需检查 HDL。错误和警告显示在 VS Code 的「问题」面板。
• 代码格式化：文档、选区和保存时格式化，支持缩进、行宽、端口对齐及 kr / ansi / gnu 排版。
• 工程与构建：分类展示源码、IP、仿真、约束和固件，分别选择设计与仿真顶层，支持 Diamond、TD、PDS 工程创建、同步、构建及带来源证据的结果报告。
• 模块工具：生成 Testbench 骨架、预览或导出 Markdown + SVG 接口文档，查看一层 RTL 模块连接图。
• HDL 计算器：精确大整数表达式、进制转换、移位和位运算，显示位宽、Verilog/C 数值形式、负数编码及二进制运算过程。
• 仿真与波形：使用 Icarus 编译和运行 Testbench；VCD 支持精确总线进制、分组排序、布局保存、拖选缩放、双光标和可选 wave-mcp 信号查询。

Windows x64 已内置 Verible 格式化器。其他平台需要配置 Verible，厂商编译器、Icarus 和 FPGA 开发软件按需自行安装。

快速开始

点击 XLXL 侧栏 Project 标题栏的书本图标，即可用默认浏览器打开完整中文教程。也可在 XLXL 设置 中选择「使用教程」，或按 Ctrl+Shift+P 搜索 XLXL：使用教程（xlxl.openTutorial）。该入口无需先打开工程，网站公开访问，无需登录。

1. 在 VS Code 中打开工程文件夹，再打开 .v 或 .sv 文件。
2. 在左侧 XLXL 侧栏查看 Project 和 Modules。代码编辑无需先创建厂商工程。
3. 按 Ctrl+Space 补全，F12 转到定义，Shift+F12 查看引用，F2 重命名模块，Shift+Alt+F 格式化文档。
4. 从 Project 标题栏的「…」菜单选择「打开 XLXL 设置」，再选择「配置工具路径」。也可在命令面板运行 XLXL: Open Settings。在设置菜单中选择「打开 VS Code 设置」，可查看扩展的全部设置项。

工程配置

新建厂商工程时，先配置本机厂商工具，然后点击 Project 标题栏“创建厂商工程”按钮，或执行 XLXL: Initialize Project。按向导选择厂商、器件和工程参数。向导准备以下目录，原生工程创建并验证成功后写入 .xlxl/project.json：

工程根/
├─ .xlxl/
│  ├─ project.json       # 成功创建后保存的工程配置
│  ├─ lint/
│  │  ├─ vivado/
│  │  └─ questa/
│  ├─ toolchain/
│  └─ sim/               # 仿真编译产物和运行记录
├─ doc/                  # 模块接口文档，目录名为单数
├─ prj/                  # 厂商工程及脚本
├─ constraints/          # 引脚和时序约束
├─ rvl/                  # RVL 文件分类
├─ rtl/                  # 设计源码
├─ sim/                  # Testbench 源码
├─ ip/                   # IP 源码
├─ fw/                   # 固件、位流等文件
└─ include/              # HDL 头文件

向导创建目录，不自动生成设计和 Testbench 文件。已有源码按配置范围引用，不会被搬迁或重排；默认扫描 rtl/、ip/ 等目录。厂商主工程分别为 prj/<工程名>.ldf（Diamond）、.al（TD）或 .pds（PDS）。sim/ 与 .xlxl/sim/ 用途不同；示例使用 $dumpfile("wave.vcd") 时，波形写入工程根目录。

在 XLXL 设置 → 工程目录与源文件发现 中可调整 xlxl.projectFolders，也可以在 Project 的更多操作菜单选择 配置工程目录。每项填写一个工程根目录下的文件夹名。名称必填，大小写不同的同名目录也视为重复。修改会用于新建工程和后续一键导入。现有目录的迁移以及 .xlxl/project.json 中已保存的路径需按实际工程调整。

只做代码编辑、检查或 Icarus 仿真时，也可手动配置已有 RTL。下面是源码接入示例；它不会创建上述完整目录或厂商工程，请勿用它整段覆盖向导生成的配置：

{
  "name": "demo",
  "topModule": "top",
  "simulationTopModule": "tb",
  "sources": ["rtl/**/*.{v,vh,sv,svh}", "include/**/*.{vh,svh}"],
  "ipSources": ["ip/**/*.{v,vh,sv,svh}"],
  "simulationSources": ["sim/**/*.{v,vh,sv,svh}"],
  "includePaths": ["include", "rtl", "ip"],
  "defines": ["ENABLE_FEATURE", "WIDTH=8"]
}

路径以工作区文件夹为基准，文件范围使用 glob 规则。综合使用设计和 IP 文件，仿真额外使用 simulationSources；头文件通过包含路径参与编译。sources: [] 表示不扫描设计源码，IP 和仿真范围仍独立生效。

按实际文件名填写匹配规则。需要同时匹配大小写后缀时，可用 rtl/**/*.{[vV],[vV][hH],[sS][vV],[sS][vV][hH]}。未配置工程时，模块树扫描设置中的 RTL 和 IP 目录，也可用 xlxl.sourceGlobs 指定扫描范围。

执行 XLXL: Set Top Module 选择设计顶层，XLXL: Set Simulation Top Module 选择 Testbench。转义模块名在配置中填写名称本身，例如 module \tb.x ; 对应 "simulationTopModule": "tb.x"。

创建厂商工程可执行 XLXL: Initialize Project，按向导填写厂商、器件及工程参数。插件生成 .xlxl/project.json，厂商工程保存在 prj/。配置文件使用 UTF-8 编码，可带 BOM；修改配置后先保存，再进行顶层选择、同步或构建。

代码编辑与诊断

在模块或 generate 结构中按 Ctrl+Space 可插入模块例化模板。在连接列表中输入 . 选择端口，在 #(...) 中选择可覆盖参数。导航与补全支持转义模块、端口和参数名称。

.v/.vh 按 Verilog 解析，.sv/.svh 按 SystemVerilog 解析。未保存文档可在编辑器右下角选择语言，使用本地模块补全、大纲和定义跳转。

在 .enable(run_en) 这样的命名端口连接中，把光标放在 enable 上按 F12，可跳到子模块的端口声明。放在括号里的 run_en 上，则跳到当前模块的信号声明。Shift+F12 可查看 run_en 在同一模块中的使用位置，例如赋值和其他端口连接。

信号定义和引用覆盖源码中可确认的模块级端口及 wire、reg、logic 等信号。对模块名使用这两个快捷键时，仍可跳到模块定义或查看工程中的模块引用。

通过 XLXL: Select Syntax Checker 选择 Vivado、ModelSim、QuestaSim 或 Icarus，默认使用 Vivado。配置工程后，保存 HDL 文件会自动检查；可用 xlxl.checkOnSave 关闭，或执行 XLXL: Check Current HDL File、XLXL: Check HDL Project。磁盘编译器检查前请保存相关源码和头文件；检查头文件时通过工程源码编译。完整工具输出位于 XLXL 输出频道。

在模块定义或例化中的模块名上按 F2 可重命名模块。填写新名称本身，插件会生成必要的转义语法，并检查模块名称冲突。

Lattice / Diamond 工程会根据 device，从检测到的 Diamond 安装目录加载对应器件及 PMI 的原语声明，用于补全、端口提示和定义跳转。可通过 xlxl.diamondPath 指定安装路径。仿真需相应的行为模型。

行尾提示默认只显示错误，警告保留波浪线和悬停详情。编辑 HDL 内容时清除过期的基础检查结果，保存后按设置重新检查。xlxl.inlineDiagnostics.mode 默认 auto，Error Lens 可用时自动让出显示；也可设为 on 或 off。

模块工具

三向信号导航与工程树联动

将光标放在 HDL 信号上，再点击编辑器右上角「整理格式」左侧的 XLXL 工具 图标，或从命令面板运行以下命令。

父模块和子模块跳转按实例层级判断，适用于输入和输出端口。多个目标会列出实例路径；跨层后保留所选实例及已确认位范围。快捷键只在 HDL 编辑器获得文本焦点时生效，可在 VS Code 键盘快捷方式中修改。保留宿主原有 Ctrl+点击定义及 Alt+点击多光标手势。

打开 XLXL → Modules，在编辑器中点一下信号名。树会只显示与该信号有已确认连接的模块实例，自动展开相关层级。例如，ip 和 mac 接 I_uclk，spare 接另一根时钟，点 I_uclk 就只看到 ip、mac 及这根时钟实际经过的上下层。信号只在某个子树中使用时，直接从该子树显示。点击编辑器空白处可恢复完整层级。如果同一模块有多条可能的实例路径，按树中的提示运行“选择信号实例”。

行首箭头表示信号相对于该行模块的方向。← 流入表示该模块接收信号，→ 流出表示该模块输出信号，↔ 双向表示两个方向，• 内部信号表示模块内的连线。例如，节点旁的 流入 data [3] 表示本实例通过输入端口 data 接收信号，模块中有 3 处已确认位置，包含声明。树标记沿端口及非 ANSI 别名连接传播，区分不相交的已确认位范围。计数排除注释、字符串、显式子端口标签和未确认的局部作用域。

点击有标记的节点可定位该实例的关联信号。模块多次例化时，可先点击具体 Modules 节点，再选信号；也可用“选择信号实例”切换路径。自动联动不弹实例选择框。横向跳转在当前模块的已确认位置间循环，不需要选择实例。修改相关源码、头文件或工程配置后旧目标失效，需要重新选取。导航使用能确认的端口连接及位对应。

HDL 计算器

在编辑器右上角的 XLXL 工具 或 XLXL 设置 中选择「HDL 计算器」。也可从命令面板运行 xlxl.openHdlCalculator。选中的有效表达式会带入计算器。重复执行复用现有面板。

支持括号、+ - * / % << >> & | ^ ~；裸数字可选 DEC、HEX、BIN、OCT。明确前缀如 12'h123、8'shff、0xFF、0b1010、0o77 使用自身进制。结果保留大于 53 位的整数精度，同时显示四种进制、Verilog/C 形式、最少位宽、原码/反码/补码及二进制步骤。默认显示 32 位，可设为 1–4096 位；超出所选位宽时提示溢出，并分开显示精确数学结果与截取后的低位模式。

HDL 字面量先按自身位宽截断、按 s 标记解释符号，后续使用数学整数运算；显示位宽不参与完整 SystemVerilog 表达式位宽推导。>> 为算术右移，~ 使用无限符号扩展，除法向零取整。不支持 >>>、X/Z、标识符、拼接或函数。输入最多 2048 字符、512 个标记、64 层嵌套；移位量最多 4096，中间整数最多 8192 位。较长计算只展示前 64 步，最终结果完整计算。

Testbench、接口文档与 RTL 连接图

在编辑器右上角点开 XLXL 工具，或从命令面板运行以下命令。选择模块时可按源文件区分同名模块。右键点击 Modules 中已解析的节点可直接使用该模块。

Testbench 生成可运行骨架：保留参数和位宽表达式，初始化普通输入，输出用于观察，inout 保持无驱动；仅明确选中的标量输入产生时钟或复位激励，并加入 VCD 导出和有限时长结束。保存只创建新文件，可随后加入 simulationSources 并设为仿真顶层；设计顶层保持原值。它不会自动产生协议激励或结果断言。

TB 不支持 interface/modport、ref、非打包数组、匿名位置端口、type 参数、无法恢复的类型及依赖 TB 作用域外符号（宏、包、局部符号等）的声明。打包位宽表达式只在依赖可恢复参数时保留，不计算数值。模块位于条件编译分支中或内部含条件编译时，当前索引不能证明活动接口，向导保守拒绝并给出原因；可改用接口文档查看原始声明。源码、头文件、依赖模块或配置在向导中变化时会拒绝过期保存。

接口文档保留声明和表达式；没有可靠描述的项显示“待补充”，不从端口名推测功能。有限制的接口仍可导出原始声明与说明，其例化样例会标明所需调用作用域。两个导出目标均不得已存在；发布任一文件失败会尝试仅清理本次创建且未被用户改动的文件。这是有保护的双文件导出，不是跨文件原子事务；不支持硬链接的文件系统会安全失败。

连接图显示一层直接 RTL 连接，不执行综合、generate/参数展开、宏分支选择、位宽求值或协议推断。复杂表达式作为完整节点显示，未知/同名定义、通配和未解析连接有明确标记。双击实例或在实例上按 Enter 进入子模块；用实例内的“↗ 源码”按钮跳转声明；其他节点和连线可点击定位，返回按钮回到上层。源码在旁侧打开并保留图形焦点。预览所依赖的源码或工程改变后需重新打开图。

模块工具支持 UTF-8 BOM 源码；连接图按同一份捕获源码解析模块和定位位置。切换工作区后，旧报告与图形操作需重新打开，返回原目录也不会恢复旧操作的有效性。

格式化

点击编辑器右上角的整理按钮，或使用右键菜单中的 XLXL 格式化命令：没有选中内容时整理整个文件；选中部分代码后点击同一按钮，只整理选区覆盖的代码行，选区外保持不变。反向选区同样适用，选区结束在下一行开头时不会整理该行。一次 Ctrl+Z 可撤销本次整理。

也可使用 VS Code 格式化命令。选区格式化快捷键为 Ctrl+K，再按 Ctrl+F。安装多个格式化插件时，在“使用…格式化文档”中选择 XLXL。

启用端口对齐时，模块例化以第一条端口连接为参照，保留其括号相对缩进的间距，后续行的左右括号分别对齐。对齐间距统一使用空格；遇到更长的端口名或表达式时，整组列位置会适当扩展。选中部分端口整理时，选区外的内容保持不变。已知方向的空连接也显示方向提示，避免连接行因提示宽度不同而错位。

整理连续的单行端口时，input、output、inout 等方向从同一列开始。最长的方向关键字后留四个空格，较短的补齐。类型和位宽也按这个规则分列，包括 wire signed、pkg::类型名 和多维位宽。沿用上一端口方向的名称排在同一列。端口逗号紧跟名称，转义名称保留语法必需的分隔空格。

独立注释和条件编译分支共用端口列宽，空行和格式化禁用区域分隔不同组。模块内部的信号声明按四列制表位排列，数字位宽的方括号与冒号各自同列，两侧数字分别右对齐。

module ddr3 (
    inout     [15:0]    ddr3_dq,
    output    [ 2:0]    ddr3_ba,
    output              ddr3_reset_n
);
wire            cmos_frame_vsync    ;
wire    [127:0] app_addr_rd_min     ;
wire    [  7:0] wr_bust_len         ;
endmodule

内部信号的分号列与最长一行的内容之间至少留四个空格。如果整组都是等长的简单信号名，分号直接跟在名称后面就能对齐。参数表达式和多维范围保留 Verible 给出的内部排版，名称后的数组维度保留在名称后面。只选中组中的几行时，也会参考整组列宽。

连续的单行赋值也以组内第一行为参照，对齐 = 或 <=。空行、独立注释和控制语句分隔不同组；条件表达式中的比较运算符不参与赋值对齐。只选中后几行时，仍参考选区外的第一行，且不会修改它。

启用保存时格式化，可在 VS Code settings.json 中添加：

{
  "[verilog]": {
    "editor.defaultFormatter": "zhaiyl.xlxl",
    "editor.formatOnSave": true
  },
  "[systemverilog]": {
    "editor.defaultFormatter": "zhaiyl.xlxl",
    "editor.formatOnSave": true
  }
}

格式化使用当前编辑内容，可通过 Ctrl+Z 撤销。用 // verilog_format: off 和 // verilog_format: on 保留指定区域的手工排版。语法不完整的片段可能无法单独格式化，详情见 XLXL Formatter 输出频道。

仿真与波形

1. 安装 Icarus Verilog，配置 xlxl.iverilogPath，通过 XLXL: Set Simulation Top Module 选择 Testbench。

2. 在 Testbench 中添加波形导出，将示例中的 tb 替换为实际模块名：

   initial begin
     $dumpfile("wave.vcd");
     $dumpvars(0, tb);
   end
   

3. 执行 XLXL: Simulate Project with Icarus，在 XLXL Simulation 查看日志；成功后自动打开本次生成或更新的 VCD。

仿真支持取消和超时停止，超时由 xlxl.simulationTimeout 设置。xlxl.openWaveformAfterSimulation 控制自动打开波形，也可执行 XLXL: Open VCD Waveform（xlxl.openWaveform）手动选择文件。

内置查看器支持数字、实数和事件信号，适合小型 VCD：文件上限 16 MB（16 MiB）、4096 个信号、20 万个变化点，同时显示最多 64 路。总线可切换二进制、十六进制、无符号和有符号十进制，宽总线使用精确整数，X/Z 保留未知态。信号可拖动或用上下按钮排序、加入可折叠分组。

在画布拖选区间缩放，滚轮围绕指针缩放，Shift 拖动、中键拖动或平移滚轮移动视区；可适配全图或输入范围。A/B 双光标显示物理时间及绝对时间差。通过查看器的保存/加载布局按钮保存显示顺序、进制、分组、视区和光标；布局 JSON 上限 1 MiB，按完整名称、位宽和类型匹配信号，不按旧数组下标套用。缺失、重名歧义和超出显示上限有提示；timescale 改变时重置视区与光标。

所选信号可查询驱动源和 X 态，结果以可展开树及原始 JSON 显示。此功能需要另行安装、配置 wave-mcp 后端并为同一波形建立会话；源文件、头文件、宏和配置改变后需重新分析。无法唯一映射信号或验证源码位置时会说明原因，可转到手动查询；可验证的源码位置提供跳转。设置与检查使用 xlxl.configureWaveMcp、xlxl.checkWaveMcp，接入说明为 xlxl.waveMcpHelp（XLXL: Wave MCP Setup Guide）。FST 和更大波形继续使用外部后端/查看器。本次开发环境缺少实际 wave-mcp 后端，已验证协议与生命周期，尚未完成真实后端端到端验收。

FPGA 工程流程

支持 Lattice Diamond、安路 TD、紫光同创 PDS。创建后执行 XLXL: Sync Vendor Project 预览并应用文件与配置变更；同步前关闭对应厂商工程的 GUI。已有 PDS 工程可通过 XLXL: Attach PDS Project 关联。

在 VS Code 打开工程根目录，点击 XLXL → Project → 一键导入工程文件。每次点击都会按 xlxl.projectFolders 递归扫描 RTL、IP 和约束目录，默认是 rtl/、ip/ 和 constraints/，并将新增引用写入现有工程。已有 XLXL 配置时优先使用关联的厂商工程。工作区只有一个厂商工程时可直接导入。导入前请关闭对应厂商 GUI，导入后重新打开工程即可看到新增文件。

• Lattice Diamond .ldf 导入 RTL .v、IP .ipx 和约束 .ldc / .lpf。已有启用的约束保持原状态。Synplify 工程中的新 .ldc 以禁用状态导入。
• 安路 TD .al 导入 RTL .v、IP .ipc 和约束 .adc / .sdc。
• 紫光同创 PDS/PDS Lite .pds 导入 RTL .v / .sv / .vhd / .vhdl、IP .idf 和约束 .fdc / .sdc。IP 的生成源码通过 .idf 引用，需保留在原位置。

执行 XLXL: Build FPGA Bitstream 构建关联工程，日志位于 XLXL FPGA Build。Diamond 和 PDS 可使用原生工程入口；TD 需配置从厂商软件导出的 Tcl 构建流程，并将 xlxl.anlogicPath 设置为 td_commands_prompt.exe（Linux 为 td_commands_prompt）。新建 Diamond 工程的 .bit/.jed 自动归集到 fw/。

Diamond 设计源码包含 SystemVerilog 时需选择 Synplify Pro 并准备相应许可证；LSE 不支持 SystemVerilog。TD 的宏定义值不能包含空白字符，含空格的宏值请写入头文件。器件、封装和许可证按本机软件及实际硬件配置。

仿真与构建前会保存工程中的修改，保存未完成时停止本次操作。配置发生变化或有未保存编辑时，先处理配置，再重新同步或创建。

构建结果报告

在 XLXL 设置 中选择「查看最近构建报告」（xlxl.showBuildReport）可打开最近报告或查看历史。「分析已有厂商报告」（xlxl.analyzeBuildReport）可手动选择已有报告。xlxl.buildReport.openAfterBuild 默认开启，构建结束后自动打开报告。面板提供构建状态、消息筛选与去重次数、资源/容量/利用率、阶段耗时、独立的时序判断、来源快照和兼容历史的指标差值。

构建是否成功沿用进程与产物结果，时序判断另行显示。旧报告或只更新时间戳的相同内容不计为本次指标；手选来源明确标为无法证明所属构建。0 条约束路径、未约束提示、哨兵 slack、缺失时序值均不会产生“时序通过”的假象。自动收集只限可确认的本次输出范围；Diamond 未指定实现时仅分析本次日志，TD 未确认输出目录时也仅分析本次构建日志。历史差值要求工作区、厂商、工程、器件和实现一致，且指标名称/单位匹配。

工具设置与常见问题

在 XLXL 设置 中选择「配置工具路径」，可将程序或安装目录写入用户或工作区设置，工作区设置优先。选择「检测工具链」可查看本机工具的检测状态、版本与路径。

• 工具未检测到：检查路径，或将安装目录加入 xlxl.toolSearchPaths。迁移电脑后清除失效的显式路径，可恢复自动检测。Windows 下 Icarus 支持 .exe 及 .cmd/.bat 启动器，使用启动器时建议同时配置实际 vvp 路径。
• 找不到头文件或宏：检查 includePaths、defines 和源码匹配范围。defines 每项填写一个宏，例如 "WIDTH=8"。
• 工程配置无效或模块树为空：检查 .xlxl/project.json 的 JSON 和字段类型，文件范围、包含路径、宏应为字符串数组；确认 sources 包含实际源码目录。
• 仿真后没有波形：确认 Testbench 执行了 $dumpfile、$dumpvars，并正常结束。
• TD 提示中文路径不存在：将工程及引用文件移至英文目录后重试；创建和同步错误会显示实际路径，同步日志位于 .xlxl/sync。

多文件夹工作区目前使用第一个文件夹作为工程根目录。语言服务面向 Verilog / SystemVerilog；加密 IP 或缺失的厂商库需补充可解析模型及相应宏。

许可

XLXL 使用 MIT 许可。第三方组件许可随插件附带在 THIRD_PARTY_NOTICES.md 中。