bb-create-sdc

name	bb-create-sdc
description	从 MAS（clock_domains / io_timing / path_exceptions）派生 Synopsys SDC 时序约束文件，OpenSTA 语法校验。触发场景：(1) bba-guru-synthesis 综合前；(2) post-PD timing fail 修订约束；(3) 显式 /bb-create-sdc。
user-invocable	true

bb-create-sdc

职责

按 MAS clock_domains / io_timing / path_exceptions + target_freq 生成 SDC，OpenSTA 解析校验。ADR-016：SDC 来源是 MAS，不从 RTL 推断。

• 调用者：bba-guru-synthesis
• 上游：bb-mas
• 下游：bb-check-cdc、bb-invoke-yosys、bb-invoke-opensta
• 禁止使用：Task / Agent / Skill

Global Paths

# Skill-local scripts (this skill's own scripts/ dir), consistent with all other bb-* skills.
PROJECT_SCRIPTS   = .claude/skills/bb-create-sdc/scripts

Input Args

arg	type	required	默认	说明
mas_path	path	true	—	designs/<name>/mas/mas.json
target_freq_mhz	int	true	—	目标频率（MHz）
design_name	string	true	—	—
process_corner	string	false	tt_0p77v_25c	ASAP7 corner
io_delay_pct	float	false	0.3	IO delay 占周期比
stamp	string	false	<auto>	—

Output Contract

field	值
artifact_path	designs/<name>/constraints/<design>.sdc
script_path	designs/<name>/synth/gen_sdc_<stamp>.py
clocks	int
io_constraints	int
exceptions	int
valid	bool
error	string|null

SDC 模板

#==============================================================================
# {{ DESIGN_NAME }} Timing Constraints
# Source: spec/MAS/{{ MODULE_NAME }}/MAS.md §7
# Spec Hash: {{ sha256:xxxxxxxxxxxx }}
# Generated by bb-create-sdc @ {{ TIMESTAMP }}
# REQ Coverage: REQ-NFR-01, REQ-ARCH-01, REQ-M##-F##
#==============================================================================

# ── REQ-NFR-01: 主时钟频率 ──────────────────────────────────────────────────
# @requirement REQ-NFR-01
# @spec_ref MAS/{{ MODULE_NAME }}/MAS.md §7.1
create_clock -name clk -period <period> [get_ports clk]

# ── REQ-ARCH-01: CDC 策略 ───────────────────────────────────────────────────
# @requirement REQ-ARCH-01
# @spec_ref ARCH/clock_reset_spec.md §3
set_false_path -from [get_ports rst_n]

# ── REQ-M##-F##: IO 时序 ────────────────────────────────────────────────────
# @requirement REQ-M##-F##
# @spec_ref MAS/{{ MODULE_NAME }}/MAS.md §7.2
set_input_delay  -clock clk -max <io_max> [get_ports {<in_ports>}]
set_output_delay -clock clk -max <io_max> [get_ports {<out_ports>}]

# ── REQ-M##-F##: 多周期路径 ─────────────────────────────────────────────────
# @requirement REQ-M##-F##
# @spec_ref MAS/{{ MODULE_NAME }}/MAS.md §7.3
set_multicycle_path 2 -setup -from [...]  ;# from MAS.path_exceptions

Traceability 规则

SDC → REQ 关联

SDC 命令	关联 REQ 类型	来源
create_clock	REQ-NFR-## (频率)	PRD.md §3 PPA
set_input_delay / set_output_delay	REQ-M##-F## (IO 时序)	MAS.md §7.2
set_false_path	REQ-ARCH-## (CDC/复位)	ARCH/clock_reset_spec.md
set_multicycle_path	REQ-M##-F## (多周期路径)	MAS.md §7.3
set_clock_groups	REQ-ARCH-## (时钟域)	ARCH/clock_reset_spec.md

生成流程

1. 读取 MAS.md §7 时序约束
2. 从 traceability/requirements_matrix.arch.csv 查找关联 REQ_ID
3. 生成 SDC 文件，每个约束前添加 @requirement + @spec_ref 注释
4. 计算 @spec_hash（使用 .claude/skills/bb-rtl-coder/scripts/compute_spec_hash.py，该 helper 归 bb-rtl-coder 所有）
5. 生成 traceability/requirements_matrix.sdc.csv

CSV 输出

req_id,req_desc,module,sdc_command,sdc_file,line_number,status
REQ-NFR-01,主时钟频率 ≥ 500MHz,SYS,create_clock,constraints/{{ DESIGN }}.sdc,12,implemented
REQ-ARCH-01,CDC 策略,SYS,set_false_path,constraints/{{ DESIGN }}.sdc,18,implemented

4-Phase 执行

Phase 1 — render_sdc_py

import json
mas = json.load(open(mas_path))
period = 1000.0 / target_freq_mhz   # ns
io_max = period * io_delay_pct
# 渲染 create_clock / set_input_delay / set_output_delay / set_false_path / set_multicycle_path

Phase 2 — run_sdc_gen

timeout 120 uv run python <script_path> > <artifact_path>

Phase 3 — sdc_syntax_check

sta -exit "read_sdc <artifact_path>; exit" 2>&1

$PROJECT_SCRIPTS/parse_sdc.py：

• log 含 Error: → valid=false
• 否则计 clocks / io_constraints / exceptions 数

Phase 4 — return

返回 JSON。

收敛 / 失败

状态	行动
valid=true	进 bb-check-cdc → bb-invoke-yosys
valid=false	重试 1 次，仍失败 error="sdc invalid"
post-PD timing fail	bba-guru-pd 触发本 skill 加 false_path / multicycle

资源索引

• $PROJECT_SCRIPTS/render_sdc_py.py、$PROJECT_SCRIPTS/run_sdc_gen.py、$PROJECT_SCRIPTS/parse_sdc.py
• assets/sdc.tcl.tmpl
• references/asap7_corner_period.md — 各 corner 推荐 margin
• Gotcha/sdc_pitfalls.md — virtual clock / clock group / generated clock