1. 项目概述为什么我们需要一个Verilog分析工具如果你和我一样在数字电路设计或者FPGA开发的路上摸爬滚打过几年肯定遇到过这样的场景接手一个庞大的、由不同工程师在不同时期编写的Verilog项目模块关系错综复杂信号定义满天飞想要理清一个顶层模块到底调用了哪些子模块或者追踪某个关键信号的来源和去向简直像在迷宫里找路。更别提那些因为拼写错误、位宽不匹配、多驱动冲突而导致的诡异仿真失败排查起来耗时耗力。这时候一个能“读懂”Verilog代码并能帮你进行结构化分析、可视化和静态检查的工具就显得至关重要了。Pyverilog就是这样一个用Python写成的开源Verilog HDL分析工具包。简单来说Pyverilog能帮你做三件核心事情解析、转换和分析。它能将你的Verilog源代码包括复杂的include和define解析成一个结构化的抽象语法树AST然后你可以基于这个AST进行各种操作比如生成网表、提取模块层次结构、进行简单的代码检查甚至作为你自定义EDA工具的后端。对于中小型项目维护、学术研究、教学演示或者想自己动手写点小工具提升效率的工程师来说它是个非常趁手的“瑞士军刀”。今天我就结合自己多次使用的经验带你从零开始深入它的核心功能并分享一些实战中总结出来的技巧和避坑指南。2. Pyverilog的核心架构与设计思路拆解要玩转一个工具先得理解它的“五脏六腑”。Pyverilog的设计非常模块化理解其架构能让你在调用时更加得心应手。2.1 核心组件三件套解析器、代码生成器与数据流分析器Pyverilog的核心可以看作由三个主要部分组成它们共同构成了一个完整的数据处理流水线。1. 解析器Parser这是工具的入口。它的任务是把文本形式的Verilog代码.v文件转换成计算机能理解的、结构化的数据。Pyverilog的解析器是基于PLYPython Lex-Yacc实现的这是一个用纯Python实现的词法分析和语法分析工具。它内部定义了Verilog-2005标准的语法规则。当你把代码喂给它时它首先进行“词法分析”把代码拆解成一个个有意义的“单词”Token比如module、input、wire、标识符、数字等。然后进行“语法分析”根据预定义的语法规则把这些Token组织成一棵抽象语法树AST。这棵AST完整保留了代码的逻辑结构但剥离了空格、注释等无关信息。注意Pyverilog主要支持Verilog-2005标准。对于SystemVerilog中引入的很多新特性如interface、package、always_comb等它的支持是不完整甚至不支持的。这是使用前必须明确的第一条限制。2. 代码生成器Code Generator这是解析的逆过程。它接收一个AST可能是原始解析得到的也可能是你修改过的然后将其“翻译”回Verilog代码文本。这个组件非常有用比如你可以写一个程序自动在所有always块前加上特定的注释标签或者进行简单的代码风格转换然后再通过代码生成器输出修改后的.v文件。3. 数据流分析器Dataflow Analyzer这是Pyverilog的“大脑”也是最能体现其分析价值的部分。它会在AST的基础上进一步分析模块的互联关系生成网表Netlist。这个网表不是一个简单的列表而是一个包含了模块实例、端口连接、信号线、寄存器等元素及其相互关系的图结构。基于这个网表你可以进行依赖分析、扇入扇出计算、甚至简单的时序路径提取。2.2 为什么选择Python优势与妥协Pyverilog选择用Python实现这是一个非常务实且对用户友好的决定。优势显而易见上手门槛极低Python语法简洁库生态丰富。你不需要去啃C的编译原理用几十行Python脚本就能开始进行有趣的电路分析。快速原型利器当你有一个针对Verilog代码的自动化处理想法时比如自动检查某个命名规范、提取特定信号生成文档用Pyverilog可以快速搭建出原型验证想法的可行性。无缝集成数据科学生态分析得到的网表、层次结构可以轻松地用networkx进行图分析用matplotlib画图用pandas做统计为设计空间探索提供了巨大便利。当然也有妥协性能瓶颈对于超大型的、百万行级别的工业级设计纯Python的解析和分析速度可能无法与商业EDA工具如Synopsys VCS、Cadence Xcelium或C/C实现的工具相比。它更适合于项目子模块分析、教学或中等规模设计。功能完整性正如前面提到的对SystemVerilog的有限支持是最大的功能限制。理解了这个设计思路我们就能扬长避短把它用在最合适的场景自动化代码审查、设计可视化、教学辅助、以及作为自定义设计流程工具链中的一环。3. 环境搭建与基础使用实操理论说得再多不如动手跑一遍。我们从最基础的安装开始。3.1 安装与依赖管理Pyverilog可以通过Python的包管理工具pip直接安装这是最推荐的方式。pip install pyverilog这条命令会自动安装Pyverilog及其依赖主要是PLY。为了后续的数据处理和可视化我强烈建议一并安装以下几个库pip install matplotlib networkx安装完成后可以在Python交互环境里简单验证一下import pyverilog print(pyverilog.__version__) # 查看版本例如 1.3.0如果顺利输出版本号说明安装成功。3.2 第一个分析脚本解析与遍历AST让我们从一个最简单的例子开始。假设我们有一个计数器模块counter.v// counter.v module counter ( input clk, input rst_n, input en, output reg [7:0] count ); always (posedge clk or negedge rst_n) begin if (!rst_n) begin count 8‘b0; end else if (en) begin count count 1; end end endmodule我们想用Pyverilog解析它并打印出模块名和端口列表。创建一个parse_demo.py脚本from pyverilog.vparser.parser import parse import sys # 1. 指定Verilog文件列表 filelist [‘counter.v‘] # 2. 指定顶层模块名对于单个文件通常就是文件里的模块名 top ‘counter‘ # 3. 指定include目录如果没有可以为None或空列表 include None # 4. 指定define宏如果没有可以为None或空字典 define None # 执行解析返回AST和解析过程中的指令字典 ast, directives parse(filelist, toptop, includeinclude, definedefine) # 5. 遍历AST。ast是一个Node对象的树形结构。 # 我们先找到顶层的模块定义 from pyverilog.vparser.ast import * def show_module(node, depth0): indent ‘ ‘ * depth # 判断节点类型 if isinstance(node, ModuleDef): print(f“{indent}模块: {node.name}“) # 遍历模块内的声明项 for item in node.items: show_module(item, depth1) elif isinstance(node, Decl): # 这是一个声明节点比如input/output/wire/reg for var in node.list: # var可能是Input/Output/Reg等类型 if isinstance(var, (Input, Output, Reg, Wire)): type_name var.__class__.__name__ name var.name # 获取位宽信息 if var.width is not None: width f“ [{var.width.msb.value}:{var.width.lsb.value}]“ else: width ““ print(f“{indent} {type_name}{width}: {name}“) # 从AST的根节点描述节点开始遍历 for desc in ast.description.definitions: show_module(desc)运行这个脚本你会看到类似输出模块: counter Input: clk Input: rst_n Input: en Output: count [7:0]这个简单的例子展示了Pyverilog工作的核心将代码变成可编程访问的对象树。ModuleDef,Input,Output,Reg这些都是Pyverilog定义好的AST节点类你可以通过判断节点的类型来获取相应的信息。实操心得在编写AST遍历代码时一个非常实用的技巧是使用pyverilog.vparser.ast中的NodeVisitor类。它实现了访问者模式可以帮你自动遍历整棵树你只需要重写对应节点类型的visit_*方法即可比手动写递归函数更清晰、不易出错。我们会在进阶部分看到它的用法。4. 进阶应用模块层次提取与可视化单纯解析一个模块意义不大Pyverilog的威力在于分析多模块构成的完整设计。我们来处理一个更典型的例子一个顶层模块调用了若干子模块。4.1 构建一个多模块设计实例假设我们有一个简单的ALU算术逻辑单元设计包含以下文件alu.v(顶层模块)module alu ( input [31:0] a, b, input [2:0] op, output reg [31:0] out, output reg zero ); wire [31:0] adder_out, logic_out, shift_out; wire cmp_out; adder u_adder (.a(a), .b(b), .out(adder_out)); logic_unit u_logic (.a(a), .b(b), .op(op[1:0]), .out(logic_out)); shifter u_shifter (.a(a), .shamt(b[4:0]), .dir(op[0]), .out(shift_out)); comparator u_cmp (.a(a), .b(b), .equal(cmp_out)); always (*) begin case(op) 3‘b000: out adder_out; 3‘b001: out logic_out; 3‘b010: out shift_out; 3‘b011: out {31‘b0, cmp_out}; default: out 32‘b0; endcase zero (out 32‘b0); end endmoduleadder.v(子模块之一)module adder ( input [31:0] a, b, output [31:0] out ); assign out a b; endmodulelogic_unit.v,shifter.v,comparator.v类似此处省略4.2 使用Dataflow Analyzer提取层次结构现在我们想自动提取出alu这个顶层模块下实例化了哪些子模块以及它们之间的连接关系。这就需要用到DataflowAnalyzer来生成网表。from pyverilog.dataflow.dataflow import * from pyverilog.vparser.parser import parse import os # 1. 准备文件列表 src_files [‘alu.v‘, ‘adder.v‘, ‘logic_unit.v‘, ‘shifter.v‘, ‘comparator.v‘] top ‘alu‘ # 2. 解析生成AST ast, directives parse(src_files, toptop) # 3. 生成数据流分析对象 analyzer DataflowAnalyzer(ast, top) # 执行分析生成网表 analyzer.generate() # 4. 获取网表信息 # 获取顶层模块的实例化信息 top_instances analyzer.getInstances(top) print(f“顶层模块 ‘{top}‘ 中的实例“) for inst_name, module_name in top_instances.items(): print(f“ - 实例名: {inst_name}, 模块类型: {module_name}“) # 5. 获取信号连接关系以 u_adder 的端口为例 print(“\n实例 u_adder 的端口连接“) bindings analyzer.getBindings() # 获取所有绑定关系 # 这是一个复杂的字典结构需要根据实例名和端口名来查找 # 通常我们需要遍历 bindings[top] 来查找 if top in bindings: for scope, bindlist in bindings[top].items(): if ‘u_adder‘ in scope: # 筛选出与u_adder相关的绑定 for bind in bindlist: # bind 包含端口名、信号名等信息 print(f“ 端口 {bind[0]} 连接到信号 {bind[1]}“)运行这个脚本你会得到实例化列表并能初步看到连接关系。但getBindings()返回的数据结构比较原始直接解读有难度。4.3 可视化模块层次图使用networkx和matplotlib将网表信息转换成图形是最直观的分析方式。我们可以利用networkx库来构建一个有向图其中节点是模块/实例边是实例化关系。import networkx as nx import matplotlib.pyplot as plt def build_hierarchy_graph(analyzer, top_module): “““根据分析器构建层次图”“” G nx.DiGraph() G.add_node(top_module, type‘module‘) # 使用一个栈来进行广度优先遍历 to_process [(top_module, top_module ‘ (top)‘)] # (模块名 显示标签) processed_modules set() while to_process: current_module, parent_label to_process.pop(0) if current_module in processed_modules: continue processed_modules.add(current_module) # 获取当前模块的所有实例 try: instances analyzer.getInstances(current_module) except: instances {} for inst_name, submodule_name in instances.items(): # 添加子模块节点和边 child_label f“{inst_name}\n({submodule_name})“ G.add_node(child_label, type‘instance‘) G.add_edge(parent_label, child_label) # 如果这个子模块本身也有实例将其加入待处理队列 # 注意这里需要确保能获取到子模块的定义。我们的文件列表包含了所有子模块文件所以analyzer可以处理。 # 为了避免循环实例化如A例化BB又例化A需要检查submodule_name是否已在processed_modules中 if submodule_name not in processed_modules and submodule_name ! current_module: to_process.append((submodule_name, child_label)) return G # 构建图 G build_hierarchy_graph(analyzer, top) # 绘制图 plt.figure(figsize(10, 8)) # 使用分层布局让图更清晰 pos nx.nx_agraph.graphviz_layout(G, prog‘dot‘) # 需要安装graphviz和pygraphviz # 如果上述方法失败可以使用spring布局 # pos nx.spring_layout(G, k2, iterations50) # 根据节点类型着色 node_colors [] for node in G.nodes(): if ‘(top)‘ in node: node_colors.append(‘lightcoral‘) elif ‘instance‘ in G.nodes[node].get(‘type‘, ‘‘): node_colors.append(‘lightgreen‘) else: node_colors.append(‘lightblue‘) nx.draw(G, pos, with_labelsTrue, node_colornode_colors, node_size3000, font_size10, font_weight‘bold‘, arrowsTrue) plt.title(“模块层次结构图”) plt.tight_layout() plt.savefig(‘module_hierarchy.png‘, dpi150) plt.show()这段代码会生成一张图片清晰地展示出alu顶层模块下实例化了u_adder,u_logic等四个子模块。对于更复杂的设计这种可视化能帮你快速理解系统架构。注意事项graphviz_layout需要系统安装Graphviz软件以及Python的pygraphviz库安装相对麻烦。如果失败回退到spring_layout也能看只是布局可能没那么层次分明。在实际自动化脚本中可以考虑将图数据导出为.dot格式然后用外部工具渲染。5. 静态检查与自定义分析实践除了可视化我们还可以利用AST和网表进行一些静态检查提前发现潜在问题。5.1 示例一查找未连接的输入端口未连接的输入端口在综合中可能被优化掉或连接到不定态是常见的错误来源。我们可以写一个检查器from pyverilog.vparser.ast import * from pyverilog.vparser.parser import parse from pyverilog.dataflow.dataflow import DataflowAnalyzer def check_unconnected_inputs(ast, top_module): “““检查顶层模块中实例的输入端口是否未连接”“” analyzer DataflowAnalyzer(ast, top_module) analyzer.generate() bindings analyzer.getBindings() issues [] if top_module in bindings: # 遍历所有绑定范围scope for scope, bindlist in bindings[top_module].items(): # scope的格式可能是 ‘top_module/instance_name‘ if ‘/‘ in scope: instance_name scope.split(‘/‘)[-1] # 获取该实例对应的模块名 instances analyzer.getInstances(top_module) if instance_name in instances: module_name instances[instance_name] # 这里我们需要知道 module_name 模块有哪些输入端口。 # 我们需要从AST中获取模块定义。这需要遍历AST找到对应模块。 # 为了简化我们假设有一个函数 get_module_inputs(ast, module_name) 能返回端口列表。 # 由于篇幅我们略去其实现它需要遍历AST找到ModuleDef然后收集Input类型的端口。 input_ports get_module_inputs(ast, module_name) # 假设这个函数已实现 # 检查每个输入端口是否在bindlist中有连接 connected_ports {bind[0] for bind in bindlist} for port in input_ports: if port not in connected_ports: issues.append(f“实例 {instance_name} ({module_name}) 的输入端口 ‘{port}‘ 未连接。“) return issues # 使用示例 src_files [‘alu.v‘, ‘adder.v‘, ‘logic_unit.v‘, ‘shifter.v‘, ‘comparator.v‘] top ‘alu‘ ast, _ parse(src_files, toptop) problems check_unconnected_inputs(ast, top) for p in problems: print(“警告: “, p)这个检查器的关键在于结合网表提供的连接信息和AST提供的模块定义信息。实现get_module_inputs函数需要你熟练遍历AST找到目标ModuleDef节点然后筛选出Input节点。5.2 示例二使用NodeVisitor自动生成代码摘要前面提到NodeVisitor能简化AST遍历。假设我们想统计项目中所有always块的数量和类型是时序always (posedge clk)还是组合always (*)。from pyverilog.vparser.ast import * from pyverilog.vparser.parser import parse class AlwaysBlockVisitor(NodeVisitor): def __init__(self): self.always_count 0 self.sync_always 0 # 有时钟事件的 self.comb_always 0 # 组合逻辑的(*) def visit_Always(self, node): self.always_count 1 # 检查敏感列表 sens_list node.sens_list if sens_list is None: return # 遍历敏感列表中的每个元素 for sens in sens_list.list: if isinstance(sens, SensList): for item in sens.list: # 判断是否有 posedge/negedge if isinstance(item, (Posedge, Negedge)): self.sync_always 1 return # 找到一个边沿事件就认为是时序逻辑 # 如果没有找到边沿事件可能是组合逻辑如 always (*) 或 always (a or b) # 检查是否是 always (*) if len(sens_list.list) 1 and isinstance(sens_list.list[0], SensList) and sens_list.list[0].list[0] ‘*‘: self.comb_always 1 else: # 其他类型的敏感列表电平触发这里也归为组合逻辑的一种 self.comb_always 1 # 使用Visitor src_files [‘alu.v‘, ‘counter.v‘] # 分析多个文件 ast, _ parse(src_files) # 不指定top解析所有文件中的所有模块 visitor AlwaysBlockVisitor() visitor.visit(ast) print(f“总共找到 {visitor.always_count} 个 always 块。“) print(f“ - 时序逻辑 (带posedge/negedge): {visitor.sync_always}“) print(f“ - 组合逻辑: {visitor.comb_always}“)NodeVisitor会自动遍历AST每当遇到Always节点时就会调用我们重写的visit_Always方法。这种方式比手动递归遍历要清晰、安全得多是编写复杂AST分析脚本的首选。6. 常见问题、排查技巧与性能优化在实际使用中你肯定会遇到各种问题。这里记录了几个我踩过的坑和解决方案。6.1 解析失败语法支持与预处理问题1代码中包含include 或definePyverilog的parse函数提供了include和define参数来处理这些预处理指令。务必使用它们而不是手动预处理。# 正确做法 ast, directives parse( [‘top.v‘], top‘top‘, include[‘./include‘, ‘../rtl/inc‘], # 指定包含目录列表 define{‘DEBUG‘: ‘1‘, ‘DATA_WIDTH‘: ‘32‘} # 定义宏 )如果include文件嵌套或宏定义复杂解析器可能会出错。对于复杂情况一个务实的做法是先用标准的EDA工具如Verilator或商业仿真器进行预处理生成一个展开了所有宏和include的“纯净”Verilog文件再用Pyverilog分析这个文件。问题2SystemVerilog语法遇到always_comb,logic,interface等语法解析器会直接报语法错误。目前没有完美的解决方案。可以将代码手动或通过脚本降级到Verilog-2005例如将always_comb改为always (*)将logic改为reg/wire。这适用于分析逻辑结构。寻找其他支持SystemVerilog子集的开源解析器如Surelog、slang但它们的Python绑定和易用性可能不如Pyverilog。6.2 分析结果异常理解网表的粒度问题getInstances()返回的列表为空或不全这通常是因为DataflowAnalyzer没有正确找到顶层模块或者顶层模块的实例化不在它分析的范围内。请检查parse和DataflowAnalyzer初始化时使用的top参数是否一致且正确。顶层模块的文件是否在文件列表filelist中。子模块的定义是否都能被找到即对应的.v文件也在filelist中或能被include路径找到。问题信号连接信息getBindings()难以解读getBindings()返回的数据结构是内部表示主要用于工具链其他部分。对于用户来说直接使用可能不友好。更高级的分析建议使用pyverilog.dataflow模块中的其他对象如DataflowGraph或者直接基于AST和getInstances提供的信息自己编写逻辑来追踪信号。对于简单的层次和连接检查可视化第4.3节通常是更有效的方法。6.3 性能瓶颈与优化建议当处理大型设计数百个模块时可能会感觉解析速度较慢。缓存AST如果你的分析脚本需要多次运行且代码没有变化可以将解析后的AST对象用pickle序列化到磁盘下次直接加载避免重复解析。import pickle ast_cache_file ‘design_ast.pkl‘ if os.path.exists(ast_cache_file): with open(ast_cache_file, ‘rb‘) as f: ast pickle.load(f) else: ast, directives parse(filelist, toptop, includeinclude, definedefine) with open(ast_cache_file, ‘wb‘) as f: pickle.dump(ast, f)注意directives对象可能包含文件路径等信息序列化/反序列化时可能有问题通常只缓存ast是安全的。增量分析如果只修改了设计的一部分可以尝试只重新解析修改过的文件但需要处理模块间的依赖这比较复杂。针对性分析不要总是解析整个设计并生成完整网表。如果只想做语法检查或统计always块直接用parse得到的AST就够了无需调用DataflowAnalyzer后者更耗时。并行处理对于独立的多个分析任务如分别统计不同模块的代码度量可以使用Python的multiprocessing库并行处理多个文件或模块。6.4 调试技巧观察AST结构当你的脚本没有按预期工作时最好的方法是查看AST到底长什么样。Pyverilog提供了to_dict()和show()方法。# 将AST节点转换为字典便于用json打印查看 import json node_dict ast.to_dict() print(json.dumps(node_dict, indent2, defaultstr)) # 注意可能需要处理不可序列化的对象 # 或者使用show()方法以文本树形式打印更直观 ast.show()show()方法会打印出整个AST的树形结构帮助你理解节点类型和嵌套关系对于编写正确的遍历代码至关重要。Pyverilog是一个强大的起点它把Verilog分析的门槛降到了最低。虽然它在处理工业级、全特性SystemVerilog时力有不逮但在其擅长的领域——中小型项目分析、自动化脚本编写、教育研究——它表现得非常出色。我个人的体会是不要指望它替代专业的EDA工具而是把它当作一个“设计助手”和“效率倍增器”。当你下次面对一团乱麻的遗留代码时不妨写个几十行的Pyverilog脚本让它帮你画张图、列个表很多问题或许就豁然开朗了。