soc-integrate 从 Verilog 子模块文件生成并维护芯片或子系统顶层。其原则是不要手工编辑生成的实例,把连接意图保存在 port-map JSON 中;优先使用其内置的 MCP 服务器,CLI 可用于本地使用和测试。
MCP 工具包括:soc_extract 解析 ANSI 模块端口;soc_instantiate 生成 .port(signal) 实例;soc_wrap 生成直通包装;soc_csv 生成端口 CSV;soc_snapshot/soc_diff 快照与增量;soc_integrate 拼接模块为生成的顶层与 .integrate.json;soc_extract_map 从已有顶层恢复映射;soc_update 在列出的子模块端口变化后刷新顶层;soc_remove 从配置移除模块并刷新。注册 stdio 需 pip install mcp,配置 command 为 python3,args 指向 mcp_server.py 路径。
当 .integrate.json 中命名模块的端口增删、改名或改宽后,用 soc_update 刷新已生成的顶层;子模块端口未变时不要运行,快照/CSV 证据足够。生成顶层的负责人运行 soc_update,叶子 IP 工作区不更新芯片顶层。若跳过 soc_update 要说明原因:端口未变,或点名被推迟的端口变化。
连接规则:同名且方向兼容的端口可自动共享,简单情况才自动共享;多驱动、位宽、时钟域、复位域和协议连接需显式审查,并通过 --map / port-map JSON 指定意图,如 {"mappings": {"uart.clk_i": "clk_sys_i", "gpio.clk_i": "clk_sys_i"}}。解析器接受 ANSI Verilog/SystemVerilog 端口,对非 ANSI 端口列表和包类型端口(pkg::word_t)会失败关闭,需先包装这些模块。非端口的内部网络(门控时钟、同步复位、层次化 IRQ 抽头)无法由本技能拼接,应先在胶合模块中导出再集成。
复位归属:CRG 拥有时钟树和组合复位源合并;集成方为每个域在门控域时钟上拥有一个 rst_synchronizer(STAGES=2,rst_<dom>_sync_ni),不要把同步释放触发器放进生成的 CRG 或各叶子 IP。CLI 用法:python3 soc-integrate/scripts/soc_integrate.py extract path/to/mod.v;integrate a.v b.v -n chip_top -o chip_top.v --map port_map.json;update chip_top.integrate.json。测试可运行 python3 soc-integrate/tests/test_parser.py -v。