Bb Create Floorplan

---
name: bb-create-floorplan
description: "从 MAS（io_ring/pad_list/clock_plan）+ 综合网表生成 Magic floorplan TCL，交给 bb-invoke-magic 执行。触发场景：(1) bba-guru-pd 综合后做 floorplan；(2) DRC 失败后调整 utilization 重生成；(3) 显式 /bb-create-floorplan。"
user-invocable: true

---

# bb-create-floorplan

## 职责

按 MAS IO ring + clock plan + utilization/aspect_ratio 参数渲染 Magic floorplan TCL。

- 调用者：`bba-guru-pd`
- 上游：`bb-mas`（MAS json）、`bb-invoke-yosys`（netlist）
- 下游：`bb-invoke-magic`(action=place)
- 禁止使用：Task / Agent / Skill

## Input Args

| arg | type | required | 默认 | 说明 |
|-----|------|----------|------|------|
| mas_path | path | true | — | `designs/<name>/mas/mas.json` |
| netlist_v | path | true | — | `designs/<name>/synth/netlist.v` |
| tech_file | path | true | — | ASAP7 Magic tech file |
| design_name | string | true | — | — |
| utilization | float | false | `0.65` | 目标利用率 |
| aspect_ratio | float | false | `1.0` | 宽高比 |
| stamp | string | false | `<auto>` | — |

## Output Contract

| field | 值 |
|-------|----|
| `artifact_path` | `designs/<name>/pd/floorplan_<stamp>.magic.tcl` |
| `script_path` | `designs/<name>/pd/gen_fp_<stamp>.py` |
| `io_count` | int |
| `utilization` | float |
| `valid` | bool |
| `error` | string\|null |

## Floorplan TCL 结构

```tcl
# Auto-generated by bb-create-floorplan
# design: <name>  util: <util>  aspect: <ar>
# Read LEF for technology/cell definitions
readspice <netlist_spice>
# Or if using DEF-based flow:
# def read <design>.def
tech load <tech_file>
floorplan -utilization <util> -aspectratio <ar>

# IO placement (from MAS.pad_list / io_ring)
place_io -side N -pads { vdd vss }
place_io -side E -pads { rx_data[7:0] }
# ...

# Clock buffers (from MAS.clock_plan)
add_clock_buffer -net clk -buffer BUFX4_ASAP7
```

## 4-Phase 执行

### Phase 1 — render_fp_py

`scripts/render_fp_py.py` 渲染 Python：

```python
import json
mas = json.load(open(mas_path))
io_ring   = mas["io_ring"]
pad_list  = mas["pad_list"]
clk_plan  = mas.get("clock_plan", {})
# 按 io_ring side 分组 pads，渲染 TCL
```

### Phase 2 — run_fp_gen

`timeout 120 uv run python <script_path> > <artifact_path> 2> <log>`

### Phase 3 — parse_fp

`scripts/parse_fp.py`：

- 计 TCL 中 `place_io` 行数 → `io_count`
- 与 MAS.pad_list 数量比对一致
- 简单 tokenize check：括号配对、命令名合法

### Phase 4 — return

返回 JSON。`bba-guru-pd` 调 `bb-invoke-magic`(action=place, layout_input=artifact)。

## 收敛 / 失败

| 状态 | 行动 |
|------|------|
| valid=true | 进 Magic place |
| io_count 不匹配 | 修正参数映射重试 |
| DRC fail（下游反馈） | 调 utilization/aspect_ratio 重生成 |

## 资源索引

- `scripts/render_fp_py.py`、`scripts/run_fp_gen.py`、`scripts/parse_fp.py`
- `assets/floorplan.tcl.tmpl`
- `references/asap7_io_pads.md` — ASAP7 可用 pad 单元
- `Gotcha/floorplan_pitfalls.md`