BUAA CO 工具箱

面向北航计算机组成（CO）实验的 VS Code 插件。它把 MIPS 汇编、Verilog、Logisim 和 P3–P7 CPU 对拍测试整合到同一个工作流中：少装工具、少配参数，先让项目跑起来。

在 VS Code Marketplace 安装 · GitHub 仓库 · 发布版本与 VSIX

快速开始

1. 安装并确认运行环境

可在扩展市场搜索 BUAA CO Toolkit 安装；离线安装时，从发布页下载与本机匹配的 VSIX，再在扩展视图的“从 VSIX 安装…”中打开它。

插件需要 VS Code 1.90 或更高版本，并在以下本地扩展宿主上发布：

每个平台包只携带对应平台和架构的 Icarus 运行时。Linux 使用系统标准 glibc、libstdc++ 和 libgcc；其他 glibc 发行版不做白名单拦截，但尚未承诺兼容。WSL、Remote SSH 和 Dev Containers 的完整工作流尚未验收。

2. 打开项目并选择 Profile

新项目：先在 VS Code 中打开一个文件夹或工作区，然后在命令面板（Ctrl+Shift+P）运行 CO: 项目向导。向导可以创建课程目录、模板文件，并写入 Profile。

已有项目：运行 CO: 选择项目 Profile，选择 P0–P7；也可以把 co.project.profile 设为 auto，插件会根据项目文件、顶层接口和 trace 格式推断。不能唯一推断时，插件会提示你选择。

3. 只配置当前工作流需要的外部工具

打开 VS Code 设置，搜索 co.toolchain。P1 和 P4–P7 的常规 Verilog 检查、手动仿真和自动测试都使用插件随包提供的 Icarus，无需安装 ISE、Homebrew 或 MARS。

工具路径是本机配置；不要把个人绝对路径提交到项目的 .vscode/settings.json。配置后运行 CO: 检查工具链，它只检查当前 Profile 和操作实际需要的工具。

4. 开始使用

从左侧活动栏打开 BUAA CO Toolkit，在“操作”区按需要执行：

P3 自动测试需要 Logisim 和 Java；P4–P7 自动测试不需要 MARS 或 ISE。

测试失败后怎么排查

1. 在持续测试页或测试历史点击 定位失败，查看首个差异的 PC、期望值与实际值。
2. 点击 定位差异指令 跳到保存的测试汇编，或 对比写回记录 打开事件对照页：自动聚焦首个差异，并排展示 PC、写入目标和两侧值，忽略时间戳、排版和 WARNING 等非写回日志。可跳转上个 / 下个差异、查看前后记录，点击 PC 定位汇编；原始日志仍可按行打开。P7 定向检查会显示对应场景及范围说明。
3. 修改并保存 CPU 源码，点击 重跑此用例。程序与测试输入保持不变，新结果另存为一条记录，原始失败仍可查看。
4. P4–P7 需要查看内部信号时，点击 重跑并看波形，自动使用该用例的课程测试环境生成 VCD。波形中的写回事件可点击定位时刻；以后从历史页可以再次打开保存的波形。

重跑可在进度通知中取消。测试未完成、未覆盖与 CPU 结果不符分别展示；没有成对写回或源码映射时，页面会说明缺失的证据。流水线冲突分析位于更多排查工具中，只在适用的程序上提供。旧版缺少完整快照的用例仍可查看，重新启动持续测试可生成完整的新记录。

测试、排查、写回对照和波形默认作为当前编辑器组的标签页打开，源码定位优先切回已打开的文件。已有多个分栏时，可在排查页点击 合并编辑器组 收拢成标签页。

交互式 MIPS 调试

打开 ASM 文件后，点击编辑器标题栏的调试图标，或运行 CO: 打开 MARS 调试工作台；也可从 CO: 更多工具 → MARS 调试工作台 进入。工作台默认跟随当前 Profile，可切换到普通 MARS 或 P3–P7 课程模式。点击 汇编 后，可以在指令列表设断点、单步或运行，再查看寄存器、内存、符号、控制台和系统服务参考；汇编后的 text、ktext、data 或 kdata 段也可导出为 HexText。

普通 MARS 模式按 $v0 执行内置 syscall 服务，等待输入时可在控制台提交文本或 EOF。P3–P6 课程模式不会调用普通 MARS 服务；P7 的 syscall 会产生 ExcCode=8 并跳转到 0x4180，由课程内核处理。工作台显示指令的架构状态，不模拟 Timer 周期或外部中断，也不支持反向单步或直接编辑机器状态。

P1 在模块文件中点击运行时，如果工作区里还没有 <模块>_tb，插件会在 .co/tb/<模块>_tb.v 生成激励模板并打开，本次不仿真；在“在此编写激励”处写好输入后再次点击运行（在模块文件或 testbench 中均可），$monitor 的输出会显示在“输出”面板，并保存到 .co/out/<模块>_tb.sim.out。右键菜单的“生成 Testbench”同样写入 .co/tb；插件不会覆盖 .co/tb 中已有的文件。

内置波形查看器

仿真并查看波形 用随包 Icarus 运行与“运行仿真”相同的 testbench，并自动记录全部信号，无需在 testbench 里手写 $dumpfile。GRF 这类不超过 64 个字的存储器会逐个字记录，寄存器行旁边显示 $sp、$ra 等别名；IM/DM 这类大存储器不记录，写入情况看 trace。

查看器以编辑器页签打开，左侧可搜索信号树（双击、+ 或拖入即可添加，模块和存储器可整组添加），右侧用画布绘制波形：

• 0/1/x/z 四态分开绘制：x 为红色块，z 为黄色中线，部分位未知的总线值显示为 X
• 游标所在时刻的值直接列在信号名旁；单击放置游标会吸附到附近的跳变，按住 Alt 可取消吸附
• Ctrl + 滚轮以指针为中心缩放，拖动框选区间放大，Shift + 滚轮或中键拖动平移，底部缩略条显示全程和当前视窗
• ←/→ 跳到所选信号的上一次/下一次跳变，Shift + ←/→ 按时钟周期步进；标尺上会标出周期序号
• M 添加标记，工具栏和标尺显示游标到标记的 Δt 与周期数，适合核对 MDU busy、握手延迟等
• 显示进制可选十六进制、二进制、无符号/有符号十进制、ASCII 和 MIPS 指令；D_ins、IR_E、i_inst_rdata 等指令信号默认显示为汇编
• testbench 用 $display 打印的 GRF/DM 写入会出现在 Trace 页和标尺上，点击即跳到对应时刻并选中寄存器行
• 双击信号名跳转到 Verilog 声明；信号列表、分组、进制与视图会在重新仿真或重新打开后保留

插件如何工作

插件把“编辑体验”和“课程工具链”分开处理。MIPS、Verilog 与 Logisim 文件先获得高亮、诊断、导航和格式化；涉及课程执行时，再根据 Profile 选择对应的运行流程。

P3–P7 的自动测试链路如下：

内置测试生成器
  → 内置 TypeScript 汇编器
  → 内置课程 oracle
  → Logisim（P3）或随包 Icarus（P4–P7）运行你的 CPU
  → 比较课程可观察写事件，生成报告和可复现用例

默认引擎边界如下：

ASM/MARS 功能统一使用插件内置 TypeScript 引擎，无需任何外部 MARS 或 Java。普通控制台模式使用 MARS 的 Default 或 Compact 内存布局，支持宏、.eqv、有界 .include、数据与 kdata 段、整数与浮点指令、普通 CP0、标准输入输出、堆分配和文件读写；“在终端运行”使用 VS Code 伪终端，支持输入、EOF 和 Ctrl+C。执行在惰性启动的 Worker 中进行，带指令预算、超时、取消和输出大小限制。失败的机器码导出保留已有文件。

课程 CPU 模式与普通控制台模式共享核心，但使用独立的语义策略。P7 的 syscall 只产生 ExcCode=8 异常并从 0x4180 进入内核，不执行任何打印或输入服务，符合 tutorial P7-2-6；普通 MARS 运行命令才按 $v0 分派服务。P3–P7 的 CPU 测试和导出继续采用课程地址布局、延迟槽、CP0、Timer 和外部中断契约。CPU 测试中的数据存储器从全零开始，非零 .data 初值仍会被拒绝，需用 store 初始化。

旧 co.toolchain.mars、marsP7 和 co.mips.extraArgs 已停用；旧 mars、verify-both 引擎设置自动使用内置引擎。Java 只用于 Logisim。历史测试记录仍保留原引擎标识；重新运行需作为内置引擎的新记录，不能冒充旧引擎的精确复现。桌面 MARS 的工具窗口和 MIDI 服务不在插件控制台接口中；不支持的服务会返回明确诊断。

“启动持续测试”固定采用当前 Profile 的强测试策略，而不是让用户选择生成器、批量大小或对拍后端。co.test.instructions 是唯一的测试侧重点设置：留空会覆盖该阶段完整课程指令集，填写真实指令可让生成器优先覆盖它们。P7 还会覆盖 CP0、异常、外部中断和 Timer；对拍关注课程定义的可观察行为，不把某一种流水线周期数当作正确性的唯一标准。

co.test.concurrency 控制同时执行的测试点上限，默认 4，可设 1–8；设为 1 即串行模式，修改后下次启动测试生效。并发可让多个 CPU 仿真进程重叠执行，也会增加 CPU 和内存占用；资源紧张时调低。每点测试强度保持不变，基础 GPR 检查完成后才执行常规测试，P7 特殊压力点等待全部常规点通过后再开始。发现首个失败或错误立即停止派发并取消其余运行中的测试，待进程退出后清理未完成用例；已完成的结果仍保存。报告显示并发上限及当前运行点数，测试点编号不受完成顺序影响。

串行/并发的资源复用策略、实测结果和复现命令见 自动测试并发设计与实测。

功能一览

Verilog 格式化

打开已保存的 .v / .vh 文件，在命令面板运行 格式化文档；只整理局部代码时选中内容并运行 格式化选定内容。有多个格式化扩展时，通过“格式化文档的方式…”选择 BUAA CO Toolkit。无需安装外部格式化工具。

格式化采用统一 Verilog 风格：模块与实例列表缩进一级，闭括号对齐声明，范围写作 [31:0]，实例名和端口括号之间留空格；赋值续行对齐右值，并对参数、模块端口与多行三元链进行分组对齐。保留已有换行和空行，缩进继承编辑器的 editor.tabSize / editor.insertSpaces。旧 co.verilog.format.* 配置已移除，不再影响结果，可从工作区设置中删除。

需要保存时自动格式化，可在自己的 VS Code 设置中添加：

{
  "[verilog]": {
    "editor.defaultFormatter": "stone926.buaa-co-toolkit",
    "editor.formatOnSave": true
  }
}

字符串、数字、注释正文及宏续行保持原样；不会为了整理排版修改表达式或增删 begin/end。需要保留手工排版的真值表等代码时，使用独占行标记：

// co-format: off
assign y = sel ? a : b;
// co-format: on

关闭区域连同标记行保持原样，缺少 on 时保护到文件末尾。选区按相交的完整行处理，结束位置在下一行行首时不包含该行；不会顺带重排整个模块或清理选区外的文件末尾。未完成的语法或无法确定的宏结构会保守保留，不尝试修复源码。不提供 SystemVerilog 或按键触发格式化，也不强制将长行折行。

流水线冲突分析

在 P5–P7 项目的侧边栏点击 分析流水线冲突，通过系统文件对话框选择汇编或机器码；也可运行 CO: 分析流水线冲突 或从 CO: 更多工具 进入。支持 .asm / .s / .mips、逐行十六进制机器码、Logisim v2 raw 和 COE。汇编由插件内置引擎处理，无需安装 Hazard-Calculator、Java 或 Python；汇编失败会直接提示原因。

报告展示转发与阻塞覆盖率、转发有效率、课程参考分和类别缺口，可按类型、有效性、指令、寄存器或 PC 筛选事件。页面上可以重新分析、打开输入或查看 JSON；历史报告用 CO: 打开冲突报告 重开。报告保存在 .co/hazard/，不同输入分别保留，同一输入重新分析会更新其报告。

分析默认最多执行 100000 步，可以在进度通知中取消。达到上限或遇到未定义行为时，报告明确标出部分结果。P7 使用 P6 的覆盖表；周期数是课程参考流水线模型的估算，不是实际 CPU 的测量结果。旧外部工具的 JSON 请使用原始程序重新生成。

常用设置与生成文件

除工具路径外，大多数项目只需要下面几项设置：

插件会在工作区的 .co/ 下保存生成物：

Testbench 只有三种来源：自动测试在 .co/iverilog/ 使用私有内部 TB；插件面向用户生成的 TB 统一放在 .co/tb/，需要你编写输入和激励；你自己创建的 *_tb.v、*_testbench.v、tb.v 或 testbench.v 文件也可直接运行，插件不会管理或改写它们。普通模块手动仿真缺少 TB 时会创建并打开激励模板，填写后再次运行。

P4–P7 的 CPU 顶层模板保留课程时钟、复位和存储器接线。点击运行或“仿真并查看波形”后直接选择 ASM，由内置汇编器自动准备并加载机器码；若缺少 CPU TB，会在选择后生成并继续仿真，无需再次点击。取消选择会停止本次操作。P6/P7 的 $readmemh 已包含在模板中，P4/P5 则沿用课程 CPU 内部 IM 读取 code.txt 的约定。已有用户 TB 保持原样，普通模块和自建 TB 不会询问 ASM。

除 .co/tb/ 外，这些文件都是本地工作产物，不是学生源代码；建议在自己的课程项目的 .gitignore 中写入 .co/* 和 !.co/tb/，忽略生成物但保留 testbench。

兼容性与边界

• Verilog 语法检查、手动仿真、自动测试和波形统一使用随包 Icarus。
• Linux 内置 Icarus 保留文本 trace、$readmemh 和基础 VCD，不提供 FST / LXT / LXT2 压缩波形或 readline 行编辑。
• 插件不覆盖 Xilinx vendor IP、综合、实现、时序仿真或 bitstream 工作流；这些请在相应 Xilinx 工具中完成。
• P3 trace 对拍要求课程标准的单个 32 位 ROM 和 trace 接口；无法可靠识别时，插件会给出缺失或冲突端口的诊断。
• 随机和定向测试能有效发现很多问题，但“通过”不等于所有场景都正确；课程最终结果仍以课程测评环境为准。

开发与维护

维护者可从仓库根目录运行：

npm ci
npm run compile
npm test
npm run check:generated
npm run package:vsix

npm run package:vsix 默认生成 Windows x64 包。其他平台在对应系统上运行 node scripts/package-vsix.mjs --target <target> --out dist/<name>.vsix；支持上表的五个 target，统一按目标裁剪运行时，macOS / Linux 在原生系统打包以保留可执行权限。

Extension platforms CI 在 PR、主分支提交和手动触发时验证五个平台的最终 VSIX：检查包内容与 Icarus，再启动真实 VS Code 稳定版，验证扩展激活、LSP 保存诊断与修复、仿真命令和一个固定 P4 课程用例的 Worker / 对拍报告。发布复用同一验证步骤；全量单元测试仍由原有 CI 执行。维护者无需准备其他系统的电脑。

本地可在对应平台解包 VSIX 后运行 npm run verify:extension-host -- <解包后的 extension 目录>；无显示器的 Linux 使用 xvfb-run -a npm run verify:extension-host -- <目录>。VS Code 自动下载至 .vscode-test/，测试工作区和日志保留在 .vscode-test/extension-host-smoke/；排查指定版本时可设置 CO_VSCODE_VERSION。

Linux 二进制由手动触发的 Build bundled Linux Icarus workflow 在两个原生架构的 Ubuntu 22.04 容器中生成；下载 tar artifact 后，将完整安装目录放入 vendor/iverilog/<target>/ 并提交。构建配方 vendor/iverilog/build-linux.sh 随 VSIX 分发；日常发布使用仓库内固定产物，无需重新编译 Icarus。

发布使用 npm run publish -- patch（也可替换为 minor、major 或显式版本号），release matrix 从五个平台的最终 VSIX 解包运行 smoke。完整架构、模块边界和验证说明见架构索引；变更记录见 CHANGELOG。随包 Icarus 的许可证、校验信息和对应源码说明见 Windows x64、macOS Apple Silicon、macOS Intel、Linux x64 和 Linux ARM64。

遇到问题或希望补充课程场景，请到 GitHub Issues 反馈。