极客工场

Appearance

共 2,256 字预计阅读约 8 分钟

Verilator WIDTHTRUNC 位宽截断：用显式位选消除告警 ​

Verilator WIDTHTRUNC 位宽截断 是赋值右值比左值宽时出现的告警：SystemVerilog 会按规则丢弃放不下的高位，仿真可以继续，但丢弃动作没有写在源码里。Verilator 5.x 把它从旧版 Verilator WIDTHTRUNC 位宽截断所属的 WIDTH 总告警 中拆成专码，目的就是让你分清「高位被截掉」和「低位被扩展」这两类不同风险。本篇用 16 位到 8 位的最小赋值复现，并用显式位选完成修复。

本文要回答的问题 ​

  • WIDTHTRUNC 与旧版 WIDTH、反向的 WIDTHEXPAND 有什么区别？
  • 16 位信号直接赋给 8 位信号时，具体丢掉哪些位？
  • 为什么推荐 wide_data[7:0]，而不是关闭告警或简单强转？
  • 显式位选消除了告警，是否也保证了截断策略符合设计意图？
WIDTHTRUNC 排查收敛：先定位丢失位，再写明保留位

读这张漏斗图时，视线要落在最后两步：告警只是指出高位会丢失，真正的修复决策是「哪些位应该留下」。如果协议要求保留高 8 位，机械套用 [7:0] 虽然也能消告警，却会把功能改错。

一、Verilator WIDTHTRUNC 位宽截断到底丢了什么 ​

SystemVerilog 的连续赋值会先求右值，再按左值宽度调整结果。右值更宽时，超出的高位被丢弃，这叫截断（truncation）。例如 16'h12F3 赋给 8 位变量，结果是 8'hF3，高位的 8'h12 不进入左值。它不是越界错误，也不是 Verilator 自行改变语义；告警是在提醒这条隐式规则可能掩盖声明错误或数据处理遗漏。

诊断名赋值形态主要风险推荐处理
WIDTHTRUNC右值宽、左值窄高位被静默丢弃显式位选、切片或实现明确的饱和逻辑
WIDTHEXPAND右值窄、左值宽零扩展或符号扩展不符合预期对齐位宽并检查有符号性
旧版 WIDTH两类问题混在一个告警里升级后名称变化，旧消音配置可能失效按新专码逐项修复，不全局关闭

因此，从 Verilator 4.x 升到 5.x 后看到 WIDTHTRUNC，不一定代表同一份 RTL 突然多出一个硬件错误，也可能只是诊断分类更细。真正需要核对的是赋值两边的声明和丢位方向，而不是把旧配置里的 -Wno-WIDTH 原样扩大成一组新消音项。

二、最小复现：16 位右值直接赋给 8 位左值 ​

下面的 broken 用例只有一条有问题的赋值。wide_data 是 16 位，narrow_data 只有 8 位；额外引出的 high_data 让高 8 位在 -Wall 下也有读者，避免未使用信号告警干扰本次对照。

systemverilog
module widthtrunc_broken (
    input  wire [15:0] wide_data,
    output wire [7:0]  narrow_data,
    output wire [7:0]  high_data
);
    assign high_data   = wide_data[15:8];
    assign narrow_data = wide_data;
endmodule

运行 verilator --lint-only -Wall widthtrunc_broken.sv 即可复现。这里使用 --lint-only，只检查语意和 lint 规则，不生成 C++ 模型；问题发生在位宽分析阶段，无需写测试平台。-Wall 则让这组源码在更接近项目日常检查的严格程度下运行。

告警位置落在最后一条 assign 上是合理的：声明本身可以合法地具有不同位宽，真正触发隐式截断的是这条赋值。排查时也不要只把 narrow_data 改成 16 位了之；输出位宽往往由下游接口约定，随意扩宽只会把不匹配推到模块边界。

三、broken 与 fixed 的真实对照结果 ​

同一目录下的 fixed 用例只把右值改为 wide_data[7:0]，其余声明完全不变。运行脚本依次执行两条 lint 命令，并要求 broken 非零退出、fixed 零退出，防止「命令跑过了」被误当成「修复生效了」。

Verilator 5.x：隐式 16 到 8 位赋值与显式位选对照

这段记录抓三类信息：WIDTHTRUNC 主行确认专码，源码回显确认触发点是 assign narrow_data = wide_data，两个退出状态确认对照方向。broken 末尾的 Exiting due to ... warning(s) 表示告警在默认设置下导致失败，并不表示又出现一个独立语法错误；fixed 没有告警且退出码为 0，才构成修复闭环。

exp-log
%Warning-WIDTHTRUNC: widthtrunc_broken.sv:7:24: Operator ASSIGNW expects 8 bits on the Assign RHS, but Assign RHS's VARREF 'wide_data' generates 16 bits.
%Error: Exiting due to 1 warning(s)
# broken_exit_code: 1
$ verilator --lint-only -Wall widthtrunc_fixed.sv
# fixed_exit_code: 0
# result: PASS (WIDTHTRUNC reproduced; explicit bit select passed)

四、修复：用显式位选写出保留范围 ​

systemverilog
module widthtrunc_fixed (
    input  wire [15:0] wide_data,
    output wire [7:0]  narrow_data,
    output wire [7:0]  high_data
);
    assign high_data   = wide_data[15:8];
    assign narrow_data = wide_data[7:0];
endmodule

wide_data[7:0] 的位选结果天然是 8 位，与左值等宽，因此不再发生隐式截断。更重要的是，读代码的人不必在脑中重算赋值规则，就能知道这里有意保留低 8 位。这个写法也没有改变本例原本的仿真结果：broken 和 fixed 对同一输入都得到 wide_data 的低 8 位，差别在于后者把意图表达清楚了。

相比 lint_off WIDTHTRUNC，位选修的是源码表达，而不是诊断可见性。相比单纯依赖尺寸强制转换，位选还直接展示了保留区间，评审时更容易发现高低位写反。若项目已经约定统一的尺寸转换风格，也可以使用团队认可的显式转换；关键是让截断成为可见、可审查的设计决定。

五、告警消失后，还要判断截断策略是否正确 ​

[7:0] 是本例的修复，不是所有 WIDTHTRUNC 的万能补丁。消告警之前先问下游需要哪一种数值语义，再选择对应电路。

设计意图合适写法不能忽略的检查
取总线低 8 位wide_data[7:0]字节序与接口位号约定
取总线高 8 位wide_data[15:8]是否误把符号位或有效负载丢掉
超范围时保留最大值比较高位后做饱和选择比较逻辑、位宽与有符号性
除法或缩放后保留低位先明确缩放，再位选舍入、溢出和精度损失

例如把 16 位传感器码值压到 8 位显示，直接取低 8 位会让大数值回绕；这种场景通常需要右移缩放或饱和，而不是只追求 lint 干净。反过来，若 16 位总线本来就由两个独立字节组成，分别取 [15:8] 和 [7:0] 才是合理设计。告警码告诉你发生了截断，协议和数值范围才决定怎样截。

六、团队检查中的处理建议 ​

把 WIDTHTRUNC 当作代码评审的定位线索，而不是需要批量清除的噪音。优先检查新修改的赋值、参数化位宽和模块接口，尤其留意把常量宽度改小后，原本刚刚好的赋值开始丢高位。确实经过设计评审的截断也应优先用显式位选表达；只有无法改源码的第三方模块等特殊情况，才考虑局部、带原因说明的消音。

持续集成里保留 -Wall，同时保存 broken/fixed 这类最小用例，可以在工具升级后快速区分「诊断专码变化」与「RTL 行为变化」。不要使用全局 -Wno-WIDTHTRUNC 换取表面通过，它会让真正的高位丢失与已知无害截断一起消失。

实验环境 ​

  • 机器/系统：Intel x86_64 Mac / macOS 26.5.2，实验在 geek-eda:0.2 容器中运行
  • 工具版本：Verilator 5.020 2024-01-01 rev (Debian 5.020-1)
  • 日期：2026-10-30
  • 完整命令：docker run --rm -v "$PWD":/work -w /work geek-eda:0.2 make run；脚本内部依次执行 verilator --lint-only -Wall widthtrunc_broken.sv 与 verilator --lint-only -Wall widthtrunc_fixed.sv，并核对 broken 非零、fixed 零退出。

代码获取 ​

broken/fixed 源码、Makefile、复现脚本与原始输出均在公开仓 experiments/ts-verilator-warn-widthtrunc。本机装有 Verilator 时进入该目录执行 make run；也可沿用上面的容器命令，脚本会自动核对两次 lint 的退出状态。

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

本篇是 EDA 报错排查系列 中 Verilator 位宽诊断的截断分支：右值过宽看本篇，扩展方向及旧版总告警看 Verilator WIDTHTRUNC 位宽截断相关的 WIDTH 说明。如果告警已经指向同一信号存在多个赋值来源，则不是位宽问题，应转到 %Warning-MULTIDRIVEN 排查。开源工具报错的整体分类见 开源 EDA 报错排查导航。

总结 ​

Verilator WIDTHTRUNC 位宽截断 的本质是右值比左值宽，高位按语言规则被丢弃。16 位到 8 位对照中，broken 用例触发专码并非零退出，把右值改成 wide_data[7:0] 后，fixed 用例零告警、零退出。显式位选的价值不仅是消告警，更是把保留范围写清楚；实际修复仍要结合字节序、缩放、饱和与有符号性确认截断策略，不能用全局消音代替设计判断。