bb-check-cdc

name	bb-check-cdc
description	基于 AST 检查 CDC/RDC 违例：对比 MAS clock_domains 找跨域信号，检查是否被 2ff-sync CBB 保护。触发场景：(1) bba-guru-synthesis 综合前；(2) 显式 /bb-check-cdc。
user-invocable	true

bb-check-cdc

职责

读 bb-parse-ast 的 AST + MAS.clock_domains，识别跨时钟域 register-to-register 路径，检查是否通过 2ff 同步器，输出 violation 报告。

• 调用者：bba-guru-synthesis
• 上游：bb-parse-ast（backend=auto 自动降级到 verible/slang）
• 禁止使用：Task / Agent / Skill

Input Args

arg	type	required	默认	说明
file_list	path	true	—	file_list.f
ast_path	path	true	—	bb-parse-ast 产出
mas_path	path	true	—	designs/<name>/mas/mas.json
design_name	string	true	—	—
stamp	string	false	<auto>	—

Output Contract

field	值
artifact_path	designs/<name>/cdc/cdc_report.json
script_path	designs/<name>/cdc/check_cdc_<stamp>.py
log_path	designs/<name>/cdc/cdc_<stamp>.log
violations	[{type,from_clk,to_clk,signal,line,waived:bool}]
clean	bool（unwaived violations==[]）
valid	bool

4-Phase 执行

Phase 1 — render_cdc_py

scripts/render_cdc_py.py 渲染：

import json
ast = json.load(open(ast_path))
mas = json.load(open(mas_path))
domains = mas["clock_domains"]
# 1. 抽取所有 always_ff (@posedge clk) blocks
# 2. 对每条赋值，标注其 clock domain (信号→sensitivity clock)
# 3. R-to-R 路径：from_clk != to_clk → 候选 violation
# 4. 检查 sink 之前是否经过 wiki/cbb/2ff-sync 实例
violations = analyze(ast, domains)
json.dump({"violations": violations}, open(out, "w"))

Phase 2 — run_cdc

timeout 600 uv run python <script_path> > <log> 2>&1，追加 exit:<rc>。

Phase 3 — parse_cdc

scripts/parse_cdc.py：

• 解析输出 JSON
• clean = all(not v.waived for v in violations)
• 写 cdc_report.json

Phase 4 — return

返回 JSON。clean=false → bba-guru-synthesis 开 rtl-needs-fix（CDC 不允许 waive）。

收敛 / 失败

状态	行动
clean=true	进 yosys
clean=false（unwaived）	开 rtl-needs-fix 退出
pyverilog 解析失败	重试 bb-parse-ast --backend verible（或 slang）
Phase 2 timeout（600s）	error="CDC_TIMEOUT"

资源索引

• scripts/render_cdc_py.py、scripts/run_cdc.py、scripts/parse_cdc.py
• references/2ff_sync_pattern.md — 同步器识别规则
• Gotcha/cdc_false_positives.md — handshake / gray code 等不视为 violation