Verilator UNUSEDPARAM 参数未使用：Parameter is not used 修复

更新时间：2026-10-29。报错排查短答，属于开源 EDA 工具链报错库系列。UNUSEDPARAM 是 Verilator 的一条 lint 警告：模块头部声明的 parameter 在模块体内一次都没被引用。它不产生逻辑错误——参数只是静静躺在那里——但它通常是重构残留或忘接线的接口占位，是代码变脏的早期信号。-Wall 下该警告会阻断编译，必须处理。同系列的姊妹警告见 Verilator UNUSEDSIGNAL 未使用信号和 Verilator WIDTH 位宽不匹配。

这张流程卡的读法：UNUSEDPARAM 没有复杂机理，核心决策只有一个——这个没人用的参数是「该删的垃圾」还是「该留的占位」。先全局搜引用排除「其实有人在用」的误伤，再定性，最后处置加复跑收尾，整条线五分钟走完。

本文要回答的问题

Parameter is not used: 'XXX' 这条警告在说什么，为什么会触发？
参数明明没人用，警告为什么值得修而不是直接豁免掉？
删除前要做什么检查，防止删掉「别人靠例化覆盖在用」的参数？
修复后怎么确认警告真的消了？

一、报错原文与现象

最小复现：一个参数化寄存器模块，头部声明了三个参数，只有 WIDTH 真正参与端口位宽和逻辑，MAX_DEPTH 是上一轮重构删掉 FIFO 后的残留，DEBUG_LEVEL 是当初预留的调试开关、从没接过线。用 verilator --lint-only -Wall 一跑，两条警告一起出来：

复现代码（unusedparam_bad.v，完整文件见文末「代码获取」）：

verilog

module unusedparam_bad #(
    parameter WIDTH       = 8,     // 在用
    parameter MAX_DEPTH   = 16,    // 重构后残留，没人引用了
    parameter DEBUG_LEVEL = 2      // 调试占位参数，从未接线
)(
    input  wire             clk,
    input  wire [WIDTH-1:0] din,
    output reg  [WIDTH-1:0] dout
);
    always @(posedge clk) begin
        dout <= din;
    end
endmodule

报错文本逐段拆开读：

第一行：Parameter is not used: 'MAX_DEPTH'，行号 4、列 15 精确指到参数名本身——WIDTH 没有上榜，因为它在端口声明 [WIDTH-1:0] 里被引用了，这个对照正好说明判定标准是「模块体内有没有引用」，跟「例化时有没有覆盖」无关。
In instance 注记：警告挂在具体例化实例上。参数化模块被多处例化时，未使用的判定按实例展开，哪一处例化触发的会写清楚。
最后一行：%Error: Exiting due to 2 warning(s)——-Wall 下警告即失败，退出码非零。注意这次是两个参数各报一条，同一模块里多个未使用参数会全部列出，不用改一个跑一轮。

二、工具与版本

本例实测环境为 Verilator 5.020（Debian 打包版，docker 镜像 geek-eda:0.2 内），触发命令为：

bash

verilator --lint-only -Wall unusedparam_bad.v

两点版本相关的注意。其一，UNUSEDPARAM 只在 -Wall（或显式 -Wwarn-UNUSEDPARAM）下开启，裸跑 --lint-only 看不到它——所以 lint 环节务必带 -Wall，否则残留参数会无声无息地越堆越多。其二，报错末尾提示的 /* verilator lint_off UNUSEDPARAM */ / lint_on 是「故意保留占位参数」的正解，但它排在两个更优选项之后：能删就删、该接就接，豁免是第三选择。

三、根本原因

UNUSEDPARAM 的触发条件一句话说清：parameter 声明存在于模块头部，而模块体内的任何表达式、位宽、generate 条件、子模块参数传递都没有引用它。警告背后的工程问题分三类，按出现频率排：

重构残留（最常见）：功能删掉了，参数忘了删。上面的 MAX_DEPTH 就是典型——FIFO 逻辑重构没了，深度参数成了孤儿。这类参数的危害不是功能，是误导：读代码的人会以为这个模块还有深度概念，花时间去找并不存在的逻辑。
接口占位（要小心）：为了「以后扩展」或保持一组模块接口形状一致而预留的参数，比如 DEBUG_LEVEL。当前版本没接线，但删了将来还要加回来、或者删掉会让这组模块的参数列表不再对齐。这类该留，但要用 lint_off 显式标记「我知道它没用，这是设计意图」。
删漏的间接引用（少数但要排查）：参数只通过 localparam 中转或只在被注释掉的代码里出现。直接删之前先确认没有这种情况。

和 UNUSEDSIGNAL（信号未使用）相比，UNUSEDPARAM 的特殊性在于参数是对外接口的一部分：例化方可以写 u_mod #(.MAX_DEPTH(32)) (...) 覆盖它。Verilator 的判定不看这个——它只看模块体内有没有引用——所以「有例化覆盖」不等于「在用」，覆盖一个没人引用的参数本身就是死代码。但删除前仍要全局搜一遍例化点，把 .MAX_DEPTH(...) 这类覆盖一并清掉，否则删完参数例化处立刻报 PINNOTFOUND 式的参数不存在错误（参数版对应报错见 Verilator PINNOTFOUND 引脚不存在同族处理思路）。

还有一类批量场景：从外部 IP 或老库拷进来的模块，头部长串参数里有一半在你的用法下用不到。这时不要逐个 lint_off 压掉外部库文件——改第三方代码会给升级埋雷——正确做法是把豁免写在自己这侧的包装层，或者用 -Wno-UNUSEDPARAM 只对第三方目录的文件级豁免，自己的代码保持全量 -Wall。

顺带说一个容易误判的边角：参数只出现在 generate 条件里（如 generate if (USE_ECC) ... endgenerate）算「被引用」，不会触发 UNUSEDPARAM；但如果这个条件恒为假、generate 体永远不进 elaboration，参数虽然「语法上被用了」语义上仍是死配置。UNUSEDPARAM 抓不到这类，它只查引用存在性——这类更深一层的死参数要靠代码评审或覆盖率侧的习惯性清点来兜，别指望 lint 一次抓全。

四、排查清单

步骤	动作	判据
1	按行号定位参数声明	确认参数名与默认值
2	模块内全局搜参数名	有无 localparam 中转/注释残留引用
3	全工程搜例化覆盖 `.PARAM(`	有覆盖先清例化点
4	定性：重构残留 / 接口占位	九成是残留，删
5	残留：删参数；占位：lint_off 最小豁免加注释	豁免写明原因
6	复跑 `--lint-only -Wall`	零警告、退出码 0

第 3 步是删参数和删信号最大的不同：参数可能被例化处显式覆盖，直接删会把错误从「警告」升级成「错误」。搜干净再动手。

五、修复代码与复跑确认

本例两个未使用参数都是死代码：MAX_DEPTH 对应的 FIFO 早已删光，DEBUG_LEVEL 从未接线且没有例化覆盖。修复就是删掉它们，接口只留真实在用的 WIDTH：

verilog

module unusedparam_fixed #(
    parameter WIDTH = 8
)(
    input  wire             clk,
    input  wire [WIDTH-1:0] din,
    output reg  [WIDTH-1:0] dout
);
    always @(posedge clk) begin
        dout <= din;
    end
endmodule

复跑确认（log 末尾三行，退出码 0）：

同一命令换成 unusedparam_fixed.v 后没有任何输出、echo $? 返回 0——警告消除，lint 通过。如果保留的是占位参数，豁免写法是 /* verilator lint_off UNUSEDPARAM */ 框住参数声明那一行再加 lint_on，并在注释里写清「预留给 XX 功能」，豁免范围压到单行，将来谁读到都知道为什么。

实验环境

机器/系统：Mac mini M4 / macOS 15（docker 容器内为 Debian 12）
工具版本：Verilator 5.020 2024-01-01 rev (Debian 5.020-1)，geek-eda:0.2 docker 镜像
日期：2026-10-29
完整命令：

bash

docker run --rm -v $PWD:/work -w /work geek-eda:0.2 verilator --lint-only -Wall unusedparam_bad.v
docker run --rm -v $PWD:/work -w /work geek-eda:0.2 verilator --lint-only -Wall unusedparam_fixed.v

代码获取

本文完整复现与修复代码已同步公开仓库：experiments/verilator-warn-unusedparam，含 unusedparam_bad.v、unusedparam_fixed.v 与完整实测记录 run1.log。本地装有 Verilator 时直接 verilator --lint-only -Wall unusedparam_bad.v 即可复现，无需 docker。

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

本篇是 Verilator lint 报错簇的一员，同簇还有 Verilator UNUSEDSIGNAL 未使用信号、Verilator WIDTH 位宽不匹配、Verilator MULTIDRIVEN 多驱动。更宏观的开源 EDA 报错导航见开源 EDA 报错库总览。

总结

Verilator UNUSEDPARAM 参数未使用警告的根因固定为「parameter 声明了但模块体内零引用」，最典型来源是重构残留，其次是未接线的接口占位；处置前先做两步检查——模块内搜间接引用、全工程搜例化覆盖——确认是死代码就直接删参数（连例化覆盖一起清），确属占位才用 lint_off 单行豁免并注明原因；修复后用同一条 verilator --lint-only -Wall 复跑到零警告、退出码 0 才算闭环，CI 里务必带 -Wall 让残留参数在本地就现形。

入门

进阶

专家

Verilator UNUSEDPARAM 参数未使用：Parameter is not used 修复 ​

本文要回答的问题 ​

一、报错原文与现象 ​

二、工具与版本 ​

三、根本原因 ​

四、排查清单 ​

五、修复代码与复跑确认 ​

实验环境 ​

代码获取 ​

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

总结 ​