bb-invoke-yosys

name: bb-invoke-yosys description: "调用 Yosys 0.35 对 RTL 进行逻辑综合并技术映射到 ASAP7 标准单元，产出门级网表 + QoR 报告。支持并行综合（基于空闲CPU数量）。Workflow: (1)生成综合脚本;(2)并行执行综合;(3)LLM检查结果并迭代优化。触发场景：(1) bba-guru-synthesis 已完成 SDC 与 CDC 检查、需要生成 netlist；(2) PD 反馈 area/path 超标需要重综合；(3) 显式 /bb-invoke-yosys。"

职责

把 RTL 综合 → 技术映射 → ASAP7 标准单元网表，并产出供下游（OpenSTA、PD）使用的 QoR JSON。

核心 Workflow（LLM驱动）:

生成综合脚本: 调用 generate_synthesis_config.py + render_yosys_tcl.py
并行执行综合: 调用 run_parallel_synthesis.py（并行数=空闲CPU数）
LLM检查迭代: 分析 synthesis_summary.json，修复问题并重试

调用者：bba-guru-synthesis。被调用方：bb-invoke-abc（间接，由 yosys 内部 abc 命令触发）。禁止使用：Task / Agent / Skill（本 skill 是叶子 skill，不递归调用其他 agent）。

Input Args

arg	type	required	默认	说明
file_list	path	true	—	`file_list.f`，每行一个 RTL 源文件路径
sdc_path	path	true	—	`constraints/<name>.sdc`（yosys 仅做时序参考）
tech_lib	path	true	—	ASAP7 Liberty
top_module	string	true	—	顶层模块名
design_name	string	true	—	用于路径 `designs/<name>/synth_parallel/`
abc_options	string	false	`-g AND,OR,NAND,NOR,XOR`	ABC 优化参数
mapping_effort	enum	false	`medium`	`low` / `medium` / `high`
enable_retiming	bool	false	`false`	是否启用 retiming pass
mode	enum	false	`single`	`single`（单模块）/ `hierarchical`（分层多模块）
modules	path	false	—	JSON文件列出子模块（hierarchical模式）

Output Contract

写入 designs/<name>/synth_parallel/，返回 summary JSON：

field	值
`synthesis_summary.json`	综合结果汇总
`results[].artifact_path`	`designs/<name>/synth_parallel/<module>/netlist_<stamp>.v`
`results[].qor_path`	`designs/<name>/synth_parallel/<module>/qor_<stamp>.json`
`results[].valid`	bool（综合成功 true）
`results[].cell_count`	int
`results[].chip_area_um2`	float
`results[].wire_count`	int
`results[].error`	string\|null
`max_parallel`	int（并行执行数=空闲CPU数）

5-Phase 执行（LLM驱动）

Phase 1 — generate_config

调用 scripts/generate_synthesis_config.py，生成 synthesis_config.json：

python3 scripts/generate_synthesis_config.py \
    --file-list designs/<name>/rtl/file_list.f \
    --sdc designs/<name>/constraints/<name>.sdc \
    --top <top_module> \
    --design-name <name> \
    --tech-lib libs/asap7/.../asap7sc7p5t.lib \
    --out designs/<name>/synth_parallel/synthesis_config.json \
    --mode single|hierarchical

LLM职责: 根据MAS/RTL结构决定 mode，准备输入参数。

Phase 2 — render_scripts

run_parallel_synthesis.py 内部调用 scripts/render_yosys_tcl.py，为每个模块生成TCL脚本：

read_verilog -sv 逐行展开 file_list.f
hierarchy -check -top <top_module> 检查顶层
synth -top <top_module> 通用综合
dfflibmap -liberty <tech_lib> DFF 映射
abc -liberty <tech_lib> <abc_options> 技术映射
可选：abc -liberty <tech_lib> -script +retime （若 enable_retiming）
opt_clean -purge
write_verilog -noattr <netlist>
stat -liberty <tech_lib> 输出统计

并行准备: 所有模块的TCL脚本同时生成，不阻塞。

Phase 3 — parallel_synthesis

调用 scripts/run_parallel_synthesis.py：

python3 scripts/run_parallel_synthesis.py \
    --config designs/<name>/synth_parallel/synthesis_config.json \
    --timeout 600

并行执行:

自动检测空闲CPU数量 (get_idle_cpu_count())
使用 ProcessPoolExecutor 并行运行综合
max_workers = min(idle_cpus, module_count)

每个模块执行:

source ~/wrk/eda_opensources/eda_env.sh
校验 yosys -V 输出含 Yosys 0.35
以 600s 超时执行 yosys -c <tcl_path> > <log_path> 2>&1
把退出码追加到 log 末尾：exit:<rc>

Phase 4 — parse_results

run_parallel_synthesis.py 内部调用 scripts/parse_qor.py，从 log 提取：

Chip area for module <top>: <float> → chip_area_um2
Number of cells: <int> → cell_count
Number of wires: <int> → wire_count
任何 ERROR: / Error: 行 → error

生成 synthesis_summary.json：

{
  "stamp": "20260519_120000",
  "total_elapsed": 45.3,
  "max_parallel": 4,
  "modules_total": 3,
  "modules_passed": 2,
  "modules_failed": 1,
  "results": [...]
}

Phase 5 — llm_analysis_and_iteration

LLM职责:

读取 synthesis_summary.json
分析失败模块（valid=false）
根据错误类型决定修复策略：
- MULTIDRIVEN / latch inferred → rtl-needs-fix
- WIDTHEXPAND (≥5次) → rtl-needs-fix
- YOSYS_TIMEOUT → 降低复杂度、增加 opt -fast
- VERSION_MISMATCH → 修复EDA环境
调整参数重试（最多6次）
成功后返回给 bba-guru-synthesis

命令行用法

# Step 1: Generate config
python3 scripts/generate_synthesis_config.py \
    --file-list designs/uart16550/rtl/file_list.f \
    --sdc designs/uart16550/constraints/uart16550.sdc \
    --top uart16550 \
    --design-name uart16550 \
    --out designs/uart16550/synth_parallel/synthesis_config.json

# Step 2: Run parallel synthesis
python3 scripts/run_parallel_synthesis.py \
    --config designs/uart16550/synth_parallel/synthesis_config.json \
    --timeout 600

# Step 3: LLM analyzes synthesis_summary.json and iterates

并行执行策略

空闲CPU	模块数	max_parallel
1	N	1（串行）
4	3	3（全并行）
4	10	4（分批并行）
8	10	8（分批并行）

检测方法：读取 /proc/loadavg 计算 idle_cpus = total_cpus - load_avg

收敛 / 失败

状态	处理
`modules_failed == 0`	调用 `bb-invoke-opensta` 做 STA
`modules_failed > 0`（RTL错误）	返回错误，调整后重试
Phase 3 timeout（600s）	返回 `{valid:false, error:"YOSYS_TIMEOUT"}`
`VERSION_MISMATCH`	返回 `{valid:false, error:"VERSION_MISMATCH"}`

资源索引

scripts/generate_synthesis_config.py — Phase 1（配置生成）
scripts/render_yosys_tcl.py — Phase 2（TCL渲染）
scripts/run_parallel_synthesis.py — Phase 3（并行执行）
scripts/run_yosys.py — 单模块执行器
scripts/parse_qor.py — Phase 4（QoR解析）
references/yosys_tcl_template.md — TCL 模板
references/asap7_libs.md — ASAP7 库位置
Gotcha/yosys_errors.md — 常见错误与修复