RUNBOOK — vco5 瞬态标定工具（pll_cal_20261003）¶

面向：要重跑或换点标定的人（换 corner / 温度 / VCTRL / 时长 / 精度档）。变更档案与坑的来由见同目录 SOP.md；环境事实见 docs/BASELINE.md。

1. 概览¶

项	内容
用途	在 .28 上用 Spectre 跑 `pll45/vco5` 的扁平镜像网表瞬态，量取频率/成本
构成	`vco5_cal.sp`（网表）、`cal_run.sh`（跑 + 计时）、`parse_cal.py`（波形解析）、`probe_params.il`（只读参数探针）
依赖	.28 的 `module load cadence && module load virtuoso/IC06.17.700`；模型卡适配副本 `proj1/verif/models/spectre_nom.include`
失败影响	无：纯离线仿真，不改变任何库/cell，不影响用户 GUI
重要性	中（阶段 2 的时长与派发策略依赖其数字）

2. 接入与凭据¶

ssh root@192.168.31.28          # 本机 root 免密已通
runuser -u rain01 -- bash <脚本>  # 涉及 virtuoso/库的必须降权到 rain01

凭据来源：docs/BASELINE.md §3（本机 root 到 18 台免密；rain 用户免密未配）。

3. 日常速查表¶

想干什么	命令
重跑 1µs 标定	`ssh root@192.168.31.28 'runuser -u rain01 -- bash /projects/design/rain01/proj1/verif/cal_0/cal_run.sh'`
看频率/摆幅	`ssh root@192.168.31.28 'cd /projects/design/rain01/proj1/verif/cal_0 && python3 parse_cal.py psf R0 900e-9'`
看耗时	同上 cal_run.sh 输出里的 `WALL= / USER= / SYS=`
看 spectre 结果	`.../cal_0/vco5_cal.log` 的 `completes with` 行
核对 cell 参数	`ssh root@192.168.31.28 "runuser -u rain01 -- bash <G>/run_skill.sh <G>/probe_params.il /tmp/r_params.log"`（`G=/projects/design/rain01/proj1/verif/gen`）
换 corner	改 `vco5_cal.sp` 里 `include` 行 → `spectre_{ss,ff}.include`
换时长/精度	改 `vco5_cal.sp` 里 `tran1 tran stop=.. errpreset=.. maxstep=..`
换控制电压	改 `vco5_cal.sp` 里 `parameters vctlq=..`

4. 日常操作¶

运行前确认 .28 空闲：ssh root@192.168.31.28 'uptime; nproc'（1µs 占 1 核 ≈145 s；60µs 占 1 核 ≈2.4 h）。
产物：cal_0/psf/tran1.tran.tran（psfascii，65 MB/µs，跑长瞬态前先量磁盘）、cal_0/vco5_cal.log、cal_0/time.txt。
幂等：cal_run.sh 每次先 rm -rf psf 再重算，重跑即重算，无状态残留。

5. 配置管理¶

全部配置集中在 vco5_cal.sp 顶部与末尾：parameters vddv/vctlq、器件 l/w（必须与 gen_vco5.il 契约一致，改动前先读该文件头注释）、ic 初值、save 节点、tran1 语句。改完直接重跑，无需重传 GUI 侧。

6. 备份与恢复¶

本工具无状态变更（只新增仿真产物），不需要备份；恢复=删除 cal_0/ 与 probe_params.il 后按 SOP 步骤 1 重传。

7. 监控与告警¶

无服务、无告警。判读靠 spectre 退出码与日志：SPECTRE_EXIT=0 + 0 errors 才算成功。

8. 故障处置¶

场景 A：SPECTRE_EXIT=127 症状：日志里连 vco5_cal.log 都没生成。诊断：command -v spectre（未 load module 时为空）。处置：确认脚本内 module load 两行未被删；此处 127 主要是调用了 .28 上不存在的 GNU /usr/bin/time。

场景 B：SFE-23 ... undefined model or subcircuit 症状：read-in 阶段 4 条错误、0.5 s 即退出。诊断：看报错指向的行号。处置：不要把 HSPICE 风格的 measure 语句写进 spectre 语言网表；测量一律走 parse_cal.py。

场景 C：PARSE_FAIL no samples parsed 症状：parse_cal.py 识别不出波形。处置：看它 dump 的文件头 30 行，确认 psfascii 的字段顺序（"time" <t> / "<node>" <v>）后再改解析口径；期间频率可先用 vco5_cal.log 与手工查看波形代替。

场景 D：不起振（VERDICT NO_OSCILLATION） 症状：窗口内摆幅接近 0。诊断：环形振荡器可能停在对称 DC 解。处置：确认 ic 行的非对称初值未被删（R0=0 R1=vddv R2=0 ...），或改用短脉冲 kick。

9. 安全与权限¶

流程只读 /pdk、/tools；所有落盘文件属主 rain01 design。不得用 root 直跑（会让库文件属主错乱）。

10. 容量与性能¶

基线（2026-10-03，nom/27 °C/conservative/maxstep=10ps）：1µs → 144.3 s 墙钟、141.8 s CPU（单核）、峰值内存 67 MB、波形 65 MB。60µs 单点 ≈2.4 h、≈3.9 GB；200 点 MC 串行 ≈480 核时、≈780 GB——批跑前必须先定输出裁剪策略。

11. 附录¶

术语：psfascii = Spectre 的 ASCII 原始数据格式；conservative = errpreset 最严精度档。
相关文档：pll_cal_20261003/SOP.md（变更档案与坑）、pll_sch_20261003/SOP.md（生成器与器件层契约）、smoke_20261003/SOP.md（模型卡适配）。
修订记录：2026-10-03 首版（首轮 1µs 标定）。

来源：/home/rain/Documents/eda_tools_ins/design/pll_cal_20261003/RUNBOOK.md ｜最后更新：2026-10-03 21:08（由 build/sync.py 同步，请勿在站点侧修改）