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 模板

```tcl
#==============================================================================
# {{ 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 输出

```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

```python
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

```bash
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