OpenCode Review Verilog/SystemVerilog RTL 评审规则深度解析时序赋值、推断锁存器与跨时钟域缺陷审查指南【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibabas scale. Hybrid architecture code review tool: deterministic pipelines LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review本篇文章围绕 open-code-review 内置的 Verilog/SystemVerilog 评审规则文档internal/config/rules/rule_docs/verilog.md展开系统讲解这套规则在 RTL 代码评审中关注的核心缺陷类别阻塞/非阻塞赋值混用、推断锁存器、位宽与符号性、时钟与复位、跨时钟域以及仿真与综合差异。读者读完可以掌握 open-code-review 对.v/.sv/.vh文件的评审判定标准理解宁可精确、不求召回的 HDL 审查哲学并学会用ocr rules check验证与按层定制 RTL 评审规则。一、这条规则何时生效.v/.sv/.vh的识别与路由1.1 路径到规则的映射open-code-review 的内置规则集中在一个随二进制发布的system_rules.json中其中一行把三类硬件描述语言文件映射到本文档**/*.{v,sv,vh}: verilog.md见 internal/config/rules/system_rules.json。这意味着仓库中任意路径下的 Verilog.v、Verilog 头文件.vh、SystemVerilog.sv文件只要 diff 进入评审范围就会命中这条映射其规则正文随后被注入评审 prompt 的{{system_rule}}占位符见 pages/src/content/docs/zh/review-rules.md 中每文件的规则解析一节。1.2 扩展名白名单在进入规则解析之前文件还要先通过扩展名白名单过滤。[internal/config/allowlist/supported_file_types.json](https://link.gitcode.com/i/81b3673e821918af4aa715cfbcb3e36f)中明确收录了.v、.sv、.vh三个扩展名由 internal/config/allowlist/allowed_ext.go 中的IsAllowedExt做大小写不敏感的判定对应测试覆盖见 internal/config/allowlist/allowed_ext_test.go.v/.sv/.vh均被断言为允许。1.3 测试平台testbench自动排除默认排除规则中有一条专门针对硬件验证代码的全局模式**/tb_*.{v,sv,vhd,vhdl}, **/*_tb.{v,sv,vhd,vhdl}见 internal/config/allowlist/default_exclude_patterns.json。以tb_前缀或_tb后缀命名的 Verilog/SystemVerilog testbench 文件会被默认排除在评审之外除非你在项目规则的include中显式绕过避免把纯验证代码混入设计代码评审。测试覆盖见 internal/config/allowlist/allowed_ext_test.go。1.4.v扩展名的歧义处理.v并非 Verilog 独占Coq 证明脚本与 V 语言源码也使用.v扩展名。规则文档要求模型在这种情况下不输出任何 HDL 专属结论直接回退到通用评审原则正确性、安全性、性能、可维护性、测试覆盖见 internal/config/rules/rule_docs/default.md。这是 open-code-review 处理扩展名共享问题的通用思路——与sniffer.go中针对.mMATLAB / Objective-C 共用做首行内容嗅探的做法同源internal/config/rules/sniffer.go只不过 Verilog 规则把内容判定交给了评审模型本身。二、总原则宁可精确不求召回Precision over Recall规则文档开篇即明确了整套 Verilog 评审的最高优先级原则只报告真正可能改变综合后硬件行为、导致仿真/综合不一致、或在被改动的 RTL 中引入时序风险的缺陷。区分设计与仿真模型上报前先判断文件是可综合的设计代码还是仅用于仿真的模型两者适用不同的判定标准不报风格问题凡是 linter 或 formatter 已能处理的风格类问题一律不报把模型注意力集中在语义级硬件缺陷上宁缺毋滥拿不准的疑似问题优先不报避免噪声淹没真正的缺陷。这条原则贯穿后面所有类别也是后续各节中反复出现的Do not…不要误报条款的总纲。三、阻塞赋值与非阻塞赋值Blocking vs Non-Blocking Assignments这是 Verilog 评审中最经典、也最容易被机械误报的一类。规则从产生真实硬件后果的角度定义了需要上报的情形3.1 时序/组合语义错配组合逻辑中使用非阻塞赋值在组合always/always_comb块中会把赋值延迟到过程块结束模拟时的执行顺序与推断出的硬件可能多出一级寄存器不一致// 错误组合逻辑中使用非阻塞赋值 always_comb begin next_state current_state 1; // 在组合块中隐式引入寄存器/时序问题 end时序逻辑中使用阻塞赋值在时钟驱动的always/always_ff块中阻塞赋值使后续语句立即读到新值改变模拟时序并可能推断出非预期硬件// 错误时序逻辑中使用阻塞赋值 always_ff (posedge clk) begin if (rst) q 0; // 阻塞赋值在时序块中改变赋值顺序语义 else q d; end3.2 同一变量混用两种赋值同一变量在相邻语句中混合使用与由于非阻塞赋值是延迟更新的后续语句可能观察到与意图不同的值always_ff (posedge clk) begin a b; // 阻塞立即取 b 的当前值 b a; // 非阻塞取 a 的旧值——a 的新值要等块结束时才生效 end这类混用在模拟与综合之间可能产生完全不同的行为属于必须上报的缺陷。3.3 多条不要误报条款规则明确划定了误报边界体现精确优先不要断言过程块内的语句顺序天然是非确定的——Verilog 的块内语句顺序是有定义语义的这是常见的机械误报点不要标记 net 类型上合理的有意多驱动如tri线网上的多源驱动除非能证明存在实际冲突不要把写法正确的always (*)仅当作风格问题上报——只要语义正确(*)不是缺陷。3.4 单驱动规则与 always_ff / always_comb / always_latch一个寄存器或变量只应由一个过程块驱动。多过程块写同一变量尤其是违反always_ff/always_comb/always_latch单写者语义会导致综合结果不定// 错误两个时序块驱动同一个 reg always_ff (posedge clk) count count 1; always_ff (posedge clk) count 0; // 多驱动最终值不定同时误用always_ff/always_comb/always_latch导致违反其事件控制、赋值方式或单写者语义的写法例如在always_comb中写时序逻辑、在always_ff中漏掉复位分支都需要上报。四、推断锁存器Inferred Latches透明锁存器是 RTL 综合中最常见的意外产物规则聚焦三种典型成因4.1 组合块中未全覆盖赋值组合always/always_comb块中若某个信号并非在所有路径上都被赋值缺少else、case分支不完整、case没有default综合器会推断出一个透明的锁存器// 错误缺少 elseen0 时 q 保持旧值 → 推断锁存器 always_comb begin if (en) q d; end4.2 组合块顶部缺少默认赋值在组合块开头给所有输出赋一个默认值default赋值是业界惯例。缺少它时新加的分支会悄悄重新引入锁存器且往往不被代码评审注意到// 推荐块顶部先给全部输出赋默认值 always_comb begin q 0; if (en) q d; end4.3 译码器 / 多路选择器 / FSM 次态逻辑输出悬空对于 decoder、mux、FSM 次态逻辑某些输入组合下输出未被赋值同样是锁存器来源always_comb begin case (state) 2b00: out 1b0; 2b01: out 1b1; // 缺少 2b10、2b11 分支与 default → 推断锁存器 endcase end五、位宽与符号性Signal Width and Signedness位宽与符号处理不当是 Verilog 中静默出错最集中的来源规则列出四类必查项5.1 隐式截断与零扩展不同位宽操作数之间的赋值或比较会静默截断或零扩展可能丢弃高位或改变比较结果wire [7:0] a, b; wire [3:0] c; assign c a b; // 8 位运算结果被截断为 4 位 if (a c) ... // 不同位宽比较隐式扩展可能改变语义5.2 算术溢出与中间表达式收窄运算结果超出声明位宽发生溢出或中间表达式在加宽之前先被收窄先窄后宽信息已丢失wire [3:0] x, y; wire [7:0] sum; assign sum (x y); // 中间结果先按 4 位计算再零扩展到 8 位——进位已丢失 assign sum x y; // 直接写才让上下文把加法提升到 8 位5.3 有符号/无符号混用Verilog 的上下文决定符号性context-determined signedness规则常让比较或移位表现出意外行为。规则要求显式使用$signed/$unsigned消除歧义wire [7:0] a; // 无符号 wire signed [7:0] b; // 有符号 if (a b) ... // 混用时按上下文规则扩展结果可能反直觉 // 明确意图 if ($signed(a) b) ...5.4 部分选择、拼接与复制计数不匹配part-select、拼接{}、复制{n{}}的位宽与目标不匹配以及依赖未声明 net 的隐式reg/wire位宽隐式 net 默认 1 位极易截断都属于上报范围wire [7:0] a; wire [3:0] b; assign b a[7:4]; // 位宽匹配OK assign b {2{a[3:0]}}; // 8 位拼接到 4 位目标——宽度不匹配六、时钟与复位处理Clock and Reset Handling6.1 复位极性、同步方式与复位释放复位既不同步也不异步实现与声明意图不符、复位极性不匹配高有效写成低有效、或复位非同步释放异步释放未做同步撤除存在复位恢复时序风险 reset-recovery hazard都需要上报。6.2 异步复位未进灵敏度列表异步复位必须出现在always的灵敏度列表中否则复位事件不会触发过程块// 错误异步复位 rst_n 未出现在灵敏度列表 always_ff (posedge clk) begin if (!rst_n) q 0; // rst_n 变化不会触发该块 else q d; end // 正确negedge rst_n 显式列入 always_ff (posedge clk, negedge rst_n) begin if (!rst_n) q 0; else q d; end规则同时要求检查需要在复位后保持的值被错误地放在复位分支上复位分支应只处理需要清零/置位的信号需要保持状态的信号不应写在复位分支里。6.3 门控时钟与多时钟驱动在应当使用时钟使能clock enable的地方使用门控、派生或组合生成的时钟gated/derived/combinational clock以及多个时钟驱动同一寄存器会引入毛刺、占空比失真与跨时钟竞争属于上报范围// 应使用时钟使能而非门控时钟 // 错误assign gclk clk en; always_ff (posedge gclk) ... // 推荐always_ff (posedge clk) if (en) q d;6.4 无复位寄存器设计假设上电时寄存器处于已知状态但寄存器没有任何复位无论同步还是异步导致上电/复位后状态未知应上报。七、跨时钟域与竞争Clock-Domain Crossings and Races7.1 缺少同步器单比特一个时钟域采样的信号由另一时钟域驱动且没有同步器会带来亚稳态metastability风险。单比特控制信号的标准做法是两级触发器two-flop// clkA 域信号 async_sig 进入 clkB 域需两级同步 always_ff (posedge clkB) begin sync1 async_sig; sync2 sync1; end总线级信号则应使用握手handshake或异步 FIFO。7.2 多比特总线逐位同步多比特总线逐位各自打两拍同步位间到达时刻会错开skew产生瞬时无效值。规则要求改用格雷码gray coding或握手方案// 错误bus[3:0] 从 clkA 域进入 clkB 域时逐位打拍 // 各比特 sync 到 clkB 的时间不同组合出的值可能是无效瞬时值7.3 组合反馈环与读-写竞争组合逻辑反馈环combinational feedback loop会使电路成为非组合振荡源推断出的存储器inferred memory若没有定义的冲突策略则存在读-写竞争read-during-write race即同一周期读写同一地址时结果未定义——均需上报。八、仿真与综合差异及不安全构造Simulation vs. Synthesis8.1 仿真专用构造出现在设计路径#delay延迟控制、fork/join、force/release以及行为被设计所依赖但目标综合流程不支持的initial块都属于仿真专用构造// 仿真专用不可综合且行为被测试依赖 initial begin #10 clk 0; forever #5 clk ~clk; end但规则特别强调一条不要误报不要仅凭语法就标记初始化——当目标 FPGA 或综合工具文档明确支持initial初始化时如 FPGA 的寄存器上电初值不应视为缺陷。8.2 灵敏度列表不完整或重叠裸always (...)中灵敏度列表不完整或存在重叠会使仿真行为与综合出的组合逻辑不一致// 错误缺少 b 的灵敏度b 变化时仿真不重新计算 always (a) begin y a b; end // 正确优先使用 (*) 或 always_comb always (*) begin y a b; end规则建议优先使用(*)或always_comb从根本上消除该问题。8.3 casex / casez 与 x/z 匹配casex/casez的 dont-care 匹配容易掩盖优先级缺陷依赖x/z匹配的case同理。规则建议在意图为互斥或带优先级时使用带unique/priority修饰的case// casez 的通配匹配可能掩盖优先级问题 casez (sel) 4b1???: y a; // 匹配优先级最高 4b?1??: y b; // 若 sel1_1??实际走的是上一支 endcase // 意图互斥时 unique case (sel) 4b0001: y a; 4b0010: y b; endcase8.4 系统任务与断言守卫真实行为$display、$finish、断言assertions守卫着真实行为例如用$display分支决定逻辑、用$finish终止仿真被设计路径依赖以及不可综合的系统任务残留在设计路径中都属于上报范围。8.5 full-case / parallel-case 编译指示full_case/parallel_case编译指示pragmas宣称的性质全覆盖、无并行冲突必须与实际逻辑真正吻合如果逻辑并没有保证这些性质仅靠 pragma 断言会误导综合器属于必须上报的不安全构造。九、实战验证与定制这条规则9.1 用ocr rules check验证路由如果怀疑某个 RTL 文件没有按预期命中 Verilog 规则可以直接用ocr rules check命令查看生效的层与匹配模式命令实现见 cmd/opencodereview/rules_cmd.go$ ocr rules check rtl/axi_lite.v File: rtl/axi_lite.v Source: System built-in Pattern: **/*.{v,sv,vh} Rule: ──────────────────────────────────────── …verilog.md 的规则正文… ────────────────────────────────────────输出中的Source与Pattern会明确告诉你命中规则来自内置系统层、匹配的是**/*.{v,sv,vh}模式。详见 pages/src/content/docs/zh/review-rules.md 的查看哪条规则生效一节。9.2 规则的四层优先级链Verilog 规则位于最低优先级的系统层其上还有三层用户可配置规则第一个匹配的模式生效first match wins实现见 internal/config/rules/system_rules.go 的LoadDefault与composedResolver优先级来源位置1最高--rule参数用户指定文件CLI 覆盖2项目规则repo/.opencodereview/rule.json3全局规则~/.opencodereview/rule.json4最低系统内置内嵌system_rules.json系统层始终存在随二进制内嵌见 internal/config/rules/system_rules.go 的go:embed因此任何文件总能解析出某个规则。9.3 为 RTL 团队定制评审规则如果内置 Verilog 规则之外团队还有自己的硬件编码规范例如强制unique case、禁止门控时钟、异步复位必须negedge同步释放可以在项目根目录.opencodereview/rule.json中添加更具体的路径规则{ rules: [ { path: rtl/**/*.{v,sv,vh}, rule: Check Verilog/SystemVerilog RTL for: (1) combinational logic using non-blocking assignments; (2) clock gating where clock enable is intended; (3) FSM outputs not assigned on every path; (4) cross-clock-domain signals lacking two-flop synchronizers or handshake. Do not report style issues. } ] }用户层的规则默认替换系统规则若希望与内置 Verilog 规则叠加生效可将条目标记为merge_system_rule: true解析器会把系统规则与用户规则合并为System-Specific Rules User-Specific Rules两段见 internal/config/rules/system_rules.go。总结open-code-review 的 Verilog/SystemVerilog 评审规则internal/config/rules/rule_docs/verilog.md以宁可精确、不求召回为核心围绕阻塞/非阻塞赋值、推断锁存器、位宽与符号性、时钟与复位、跨时钟域竞争、仿真与综合差异六大缺陷类别为 RTL 评审划定了明确的上报边界与误报禁区。它通过 internal/config/rules/system_rules.json 的**/*.{v,sv,vh}模式自动生效配合扩展名白名单与 testbench 排除规则让评审模型把注意力集中在真正改变硬件行为、引发仿真/综合不一致或引入时序风险的改动上——这正是 RTL 代码评审区别于普通软件评审的关键所在。【免费下载链接】open-code-reviewFast, efficient, battle-tested at Alibabas scale. Hybrid architecture code review tool: deterministic pipelines LLM Agent, precise line-level comments, built-in multi-language ruleset (NPE, thread-safety, XSS, SQL injection), OpenAI Anthropic compatible.项目地址: https://gitcode.com/GitHub_Trending/op/open-code-review创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考