iverilog port is not a port of：例化端口名不存在排查

更新时间：2026-10-30。本文属于 EDA 报错排查系列。iverilog port is not a port of 是模块例化时的硬错误：上层使用 .端口名(信号) 接线，但 Icarus Verilog 在被例化模块的接口里找不到这个端口名。它不是在说信号没有声明，也不是普通的未连接警告；名字无法解析，设计就不能完成详细描述（elaboration），编译随即中止。

首屏答案：先抄下报错文件、行号和反引号中的名字，再打开该实例对应的模块定义逐项核对。rst_n 写成 rest_n 属于拼写问题；定义里确实叫 reset_n 则是模块版本或改名不同步。修复的是例化点左侧的端口名，不是随意改右侧信号。位置连接没有端口名可查，不会以这种形式报错，却可能错位接线，因此也不能靠它绕过问题。

这张漏斗强调排查顺序：先确定是哪一个实例，再处理哪一个名字，最后才决定改哪一端。不要看到 port 就给上层补一根同名 wire；错误发生在模块接口的查名阶段，新增线网不会让子模块凭空多出一个端口。

本文要回答的问题

这条诊断里的文件、行号、端口名和实例名分别指什么？
拼写错误、模块版本不一致和位置连接应该怎样区分？
为什么增加信号声明或忽略警告都不能修复？
怎样用修复前后的真实退出码确认问题已经闭环？

一、iverilog port is not a port of 报错原文

最小设计是一个四位计数器，真实接口包含 clk、rst_n、enable 和 count。错误测试平台把复位口写成了 rest_n，只调换两个字母的位置：

verilog

module tb_bad;
  reg clk;
  reg rst_n;
  reg enable;
  wire [3:0] count;

  counter dut (
      .clk    (clk),
      .rest_n (rst_n),
      .enable (enable),
      .count  (count)
  );
endmodule

下面保留错误版、修复版和修复后仿真的完整命令结果，标准输出与标准错误已经合并：

主诊断 tb_bad.v:7: error: port ``rest_n'' is not a port of dut. 可以拆成四段：tb_bad.v:7 指向命名连接所在行；rest_n 是查不到的端口名；dut 是实例名；error 表明编译不能继续。紧随其后的 1 error(s) during elaboration 说明失败发生在展开实例、连接接口的阶段，紧随其后的退出码是 1。日志后半段则是对照：修复版编译退出码 0，vvp 打印 PASS count=3 并以 0 结束。

二、工具版本与诊断边界

实测使用 Icarus Verilog 13.0 stable，编译参数为 -g2012 -s <顶层模块>。-g2012 选择语言标准，-s 明确顶层；它们都不会放宽端口名检查。即使不运行仿真，只要错误顶层参与编译，详细描述阶段就会报出同一问题。

这条错误只覆盖按名字连接时左侧名称不存在。它不直接判断右侧信号宽度是否合适，也不等于某个真实端口被漏连。其他工具可能使用不同文案，例如 Verilator PINNOTFOUND 端口排查会把同类问题标成 Pin not found，但核对对象仍然是子模块接口。

三、根因分流：拼写、版本与连接方式

拿到诊断后，用同一实例的定义和例化点做三路判断：

场景	定义与例化点的特征	正确修复方向
拼写或大小写错误	两边意图相同，字符、下划线或单复数不同	以当前模块定义为准改例化点
模块版本或改名不同步	当前定义使用另一个完整名字，或旧端口已删除	确认应使用的接口版本，同步全部例化点
位置与命名连接混淆	使用 `counter dut(a, b)`，没有左侧端口名	按声明顺序检查，优先改成命名连接

拼写错误通常一眼可见，但 Verilog 标识符区分大小写，rst_n、rst_N 和 reset_n 是不同名字。模块版本问题则不能靠猜：如果上层基于旧接口，而当前源码已经改名，要决定升级上层还是换回预期版本，不要为了消错把已删除的端口随手加回去。

位置连接按端口声明顺序绑定，不存在“查不到端口名”这一步，所以顺序错误可能变成错误电路而非这条诊断。命名连接多写一个名字，却换来可检查的接口关系；用位置连接规避报错，只是把显式错误变成隐蔽错误。

图中红色是原始错误，蓝色是定位动作，灰色表示两类根因分支，橙色是修复，绿色是复验。两条分支在“修复连接”汇合，但修改依据不同：拼写问题以现定义为准，版本问题先确认整个设计约定，不能只追求当前文件编过。

四、可执行排查清单

保留第一条完整诊断。记录文件、行号、实例名和不存在端口名；不要只看最后的错误计数。
打开实例真正的模块定义。确认没有编进另一目录的同名模块，直接核对当前接口列表。
逐字符比较左侧名字。检查大小写、下划线、单复数和相似拼写；右侧信号名不必与端口名相同。
判断是不是接口演进。若名字曾经存在，检查模块版本和全部例化点，避免只修一个实例。
拒绝无效绕行。给上层新增 rest_n wire、降低警告级别或换成位置连接，都不能正确创造子模块端口。
同命令复跑。先要求编译退出码 0，再运行自检仿真；只有不再报错还不够，功能结果也应符合预期。

五、修复代码与复跑 PASS

本例模块定义没有变化，只把错误例化点的 .rest_n(rst_n) 改成 .rst_n(rst_n)。左侧现在对应真实端口，右侧仍连接测试平台原来的 rst_n 信号：

verilog

counter dut (
    .clk    (clk),
    .rst_n  (rst_n),
    .enable (enable),
    .count  (count)
);

修复测试平台还会实际运行计数器：复位释放后让 enable 保持有效，观察三个上升沿，要求 count 恰好为 3。真实输出如下：

exp-log

$ iverilog -g2012 -s tb_good -o build/tb_good.vvp counter.v tb_good.v
[exit] 0

$ vvp build/tb_good.vvp
PASS count=3
[exit] 0

这里的两个 0 分别证明编译和仿真成功，PASS count=3 则证明修复没有停留在“错误文本消失”。对照实验只改了一个端口名，因此结果可以直接归因于这次修复。

实验环境

机器/系统：macOS，Darwin x86_64
工具版本：Icarus Verilog 13.0 stable（v13_0）
日期：2026-10-30
完整命令：bash run.sh，依次执行 iverilog -g2012 -s tb_bad -o build/tb_bad.vvp counter.v tb_bad.v（退出码 1）、iverilog -g2012 -s tb_good -o build/tb_good.vvp counter.v tb_good.v（退出码 0）和 vvp build/tb_good.vvp（退出码 0）

代码获取

最小复现源码、运行脚本和真实日志位于公开仓 https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/ts-iverilog-cannot-find-port。安装 Icarus Verilog 后，在该目录执行 bash run.sh，即可得到本文的错误编译与修复仿真对照。

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

本篇处理的是 Icarus Verilog 的例化接口查名错误。若名字问题发生在隐式线网声明，应看 iverilog 隐式线网定义排查；若要比较另一套工具对同类端口错误的表述，可看 iverilog port is not a port of 与 Verilator PINNOTFOUND 对照。更多编译、仿真错误可从开源 EDA 报错排错中心按诊断文本分流。

总结

iverilog port is not a port of 的判断很直接：命名端口连接左侧的名字不在当前子模块接口里。先用行号定位实例，再逐字符核对拼写；若名字来自旧接口，就统一模块版本和全部例化点，而不是补线网或换位置连接掩盖问题。本例将 rest_n 改回 rst_n 后，编译与仿真退出码都从失败路径转为 0，并得到 PASS count=3，这才是完整修复闭环。

入门

进阶

专家

iverilog port is not a port of：例化端口名不存在排查 ​

本文要回答的问题 ​

一、iverilog port is not a port of 报错原文 ​

二、工具版本与诊断边界 ​

三、根因分流：拼写、版本与连接方式 ​

四、可执行排查清单 ​

五、修复代码与复跑 PASS ​

实验环境 ​

代码获取 ​

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

总结 ​