极客工场

Appearance

共 2,179 字预计阅读约 7 分钟

Verilator UNOPTTHREADS 线程分配：多线程仿真告警解读与复验 ​

更新时间：2026-10-31。本文属于 EDA 报错排查系列，讨论多线程模型的调度问题；它不同于组合逻辑成环导致的 UNOPTFLAT 排查。

首屏答案：Verilator UNOPTTHREADS 线程分配告警表示线程调度器在当前设计与参数约束下，无法提供 --threads 请求的并行度。它不是组合环，也不表示仿真结果必然错误。设计很小、关键路径较长或并行任务不足时，可以减少 --threads，甚至接受单线程；确有较多独立逻辑时，可评估提高 --threads-max-mtasks。不要只靠关闭告警或机械拆模块，修复后应保留版本与参数复跑，再用相同激励检查功能。

本文要回答的问题 ​

  • unable to provide requested parallelism 具体指什么？
  • --threads 与 --threads-max-mtasks 分别约束什么？
  • 什么时候该减少线程、放宽任务上限或调整设计？
  • 为什么只增加模块层级可能仍然报警？
  • 复跑通过能够证明什么，又不能证明什么？

线程数不是越大越好。调度器需要把计算组织成可执行任务，同时控制任务间同步；告警说明的是这次分区没有满足目标，而不是给出一个“最佳线程数”。

UNOPTTHREADS 的三条处理路径

三条路径对应不同前提。左侧是在降低不现实的并行目标，中间是在给调度器更多组织空间，右侧才涉及设计改造。选择前先看依赖关系与仿真目标，不必为了保留某个线程数而重写本来清晰的 RTL。

一、读懂告警：问题在线程分区，不在端口或语法 ​

MTask 可以理解为 Verilator 调度执行的一类任务单元。使用 --threads 2 时，是在请求生成支持两个仿真线程的模型；--threads-max-mtasks 则限制调度器保留的任务单元数量。任务太多会增加通信与同步，所以 Verilator 会尝试合并它们。如果合并过程受关键路径和依赖关系限制，仍无法填满请求的线程，就可能出现 UNOPTTHREADS。

这与编译期的并行编译任务数是两回事。--threads 面向生成的仿真模型，不能简单理解成“Verilator 命令用了几个核”。告警末尾出现 %Error 也常令人误判：这里是警告按默认策略使命令失败，并不表示发现了新的 RTL 语法错误。

请求双线程且限制 MTask 数量，调度器报 UNOPTTHREADS

输出直接建议减少线程，但没有要求必须这么做。exit_code: 1 只说明当前调用未通过；真正的处理依据仍是设计是否能提供有意义的并行工作。全局忽略告警虽可能让命令继续，却不会改善分区。

还要检查参数是否从公共构建脚本继承。有时当前工程并未主动启用多线程，公共 Makefile 却统一附加 --threads；只修改手头命令，下一次构建仍会带回旧值。把最终生效参数写进复现命令，能避免“本地已修、回归仍报警”的错觉。

二、用四个计数过程构造最小复现 ​

复现设计包含四个独立的时序过程，每个过程更新一个计数器，组合逻辑再把四个结果异或。逻辑刻意保持短小，便于把现象集中到线程调度。

systemverilog
module top (
    input  logic clk,
    input  logic [31:0] seed,
    output logic [31:0] result
);
    logic [31:0] count0, count1, count2, count3;
    always_ff @(posedge clk) count0 <= count0 + seed;
    always_ff @(posedge clk) count1 <= count1 + seed + 1;
    always_ff @(posedge clk) count2 <= count2 + seed + 2;
    always_ff @(posedge clk) count3 <= count3 + seed + 3;
    always_comb result = count0 ^ count1 ^ count2 ^ count3;
endmodule

运行命令把 MTask 上限设为 2，让这个小例子稳定进入受限合并路径：

bash
verilator -Wall -Wwarn-UNOPTTHREADS --cc \
  --threads 2 --threads-max-mtasks 2 \
  --Mdir obj_bad --top-module top top.sv

这里的上限是为了缩小复现，不是正常工程的推荐配置。实际项目通常不需要显式写这么低的值；遇到告警时，应保留原参数判断，而不是先照搬示例中的 2 或 20。

三、减少线程与放宽任务上限，如何选择 ​

两条常见修复都能让本次复现通过，但适用条件不同。下表给出决策依据，不把“没有告警”误当成“运行更快”。

处理方式更适合的情况需要接受的取舍
减少 --threads模型较小、串行依赖多、并行工作不足放弃部分目标并行度
接受 --threads 1仿真不是当前瓶颈，或单线程已满足使用需求不生成多线程并行收益
提高 --threads-max-mtasks有较多独立计算，当前上限过紧更多任务可能增加同步开销
调整设计结构依赖边界不清，确能拆出独立计算有改造成本，需完整功能回归

本次实验分别验证单线程和放宽 MTask 上限。除线程相关参数外，源码与检查选项保持一致：

exp-log
=== fix: accept a single-threaded model ===
$ verilator -Wall -Wwarn-UNOPTTHREADS --cc --threads 1 --threads-max-mtasks 2 --Mdir obj_single --top-module top top.sv
# exit_code: 0
PASS: single-threaded model accepted

=== fix: allow more MTasks with 2 threads ===
$ verilator -Wall -Wwarn-UNOPTTHREADS --cc --threads 2 --threads-max-mtasks 20 --Mdir obj_mtasks --top-module top top.sv
# exit_code: 0
PASS: two-thread partition accepted

两个 PASS 只证明模型生成阶段接受了相应分区，没有给出任何速度结论。若调整目的是性能，还应使用相同输入、相同仿真时长和相同运行环境测量；否则，选择单线程以减少复杂度，或保留双线程以利用独立逻辑，都可以是合理结果。

四、为什么只拆模块层级不一定有效 ​

把每个计数器放进 counter 子模块，再由 hierarchical 顶层例化四次，代码结构更整齐，但计算与依赖并未改变。Verilator 还会进行模块展开与调度分析，所以“源码里多了几层”不等于“运行时自然多了可并行任务”。

对照实验沿用双线程和 MTask 上限 2：

exp-log
=== control: hierarchy alone, still at most 2 MTasks ===
$ verilator -Wall -Wwarn-UNOPTTHREADS --cc --threads 2 --threads-max-mtasks 2 --Mdir obj_hier --top-module hierarchical counter.sv hierarchical.sv
%Warning-UNOPTTHREADS: Thread scheduler is unable to provide requested parallelism; suggest asking for fewer threads.
%Error: Exiting due to 1 warning(s)
# exit_code: 1
PASS: hierarchy alone did not change the constrained partition

因此，划分层级应服务于真实独立性与可维护性，例如把彼此独立、内部联系紧密的计算组织成清楚边界；不要仅为消除告警随意拆包。若共享状态、长依赖链和同步关系不变，分区难题通常也不会凭模块名消失。

五、复跑与收尾清单 ​

  • 固定 Verilator 版本、源码和其余选项，每次只改变一个线程相关变量。
  • 先尝试减少线程，确认这是模型需求与并行目标不匹配，而非其他告警的连带结果。
  • 只有在独立工作足够时才考虑提高 MTask 上限，并评估额外同步成本。
  • 调整设计后运行原有功能测试，不能只用模型生成成功替代仿真回归。
  • 若目标是提速，用同口径实测决定是否保留多线程；本文不据此宣称某个配置更快。
  • 不建议全局关闭 UNOPTTHREADS 来掩盖问题，忽略分区告警不会自动改善仿真效率。

实验环境 ​

  • 机器/系统：macOS 主机，Docker geek-eda:0.2 容器。
  • 工具版本：Verilator 5.020 2024-01-01 rev (Debian 5.020-1)。
  • 日期：2026-10-31。
  • 完整命令：docker run --rm -v "$PWD:/work" -w /work geek-eda:0.2 bash run.sh。脚本依次执行受限双线程复现、单线程复验、双线程加宽 MTask 上限复验，以及仅调整层级的对照，并检查各自退出码。

代码获取 ​

完整源码、层级化对照与运行脚本位于公开仓 https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/ts-verilator-warn-unoptthreads。进入该目录后，用上述 Docker 命令执行 bash run.sh；两处预期告警与两处修复结果全部符合预期时，脚本整体返回 0。

这一篇在知识体系里的位置 ​

本篇处理运行时模型的线程分区；如果告警是 UNOPTFLAT 且涉及信号环，应转到 Verilator UNOPTFLAT 组合环排查。若当前问题只是例化连接不完整，则参考 Verilator PINNOCONNECT 排查，不要把接口告警与线程调度混为一谈。

总结 ​

Verilator UNOPTTHREADS 线程分配的核心是请求的并行度与当前任务分区不匹配。小模型或串行依赖较重时，减少 --threads、接受单线程往往更直接；独立计算充足时，可评估放宽 --threads-max-mtasks。模块层级本身不保证改善调度，实测对照也确认了这一点。保留参数复跑只能确认分区被接受，功能回归与同口径性能测量仍需分别完成。