SOP — 阶段 2：ADE-XL test 的 SKILL 程序化生成（`test_lock` 首件）¶

日期：2026-10-04 ｜执行机：hpc-submit（192.168.31.28）｜实施：.28:/projects/design/rain01/proj1/verif/gen 方案工作区：/home/rain/Documents/eda_tools_ins/design/adexl_setup_20261004 上游：pll_loop_cal_20261004/SOP.md（环路元件取值）、hpc_slurm_20261003/SOP.md（批处理运行层）协作模式：AI 写 SKILL → .28 无头自测 → 用户 GUI 复核（2026-10-03 用户明确要求）

1. 背景¶

阶段 2 需在 ADE-XL 建 test_lock/test_pnoise/test_mc 三个 test（HANDOFF §2#1）。此前 ADE-XL setup 只有 pll45/vco5/adexl 一个手工建的 test（S3 派发链复验用），没有任何 SKILL 脚本。用户拍板沿用「AI 写 SKILL 脚本生成」路线，但先要验证 ADE-XL 的 SKILL API 能否程序化建 setup。本 SOP 记录该可行性攻关与 test_lock 首件的落库结果。

2. 目标¶

可验证状态： - pll45/pll_top/adexl（新建视图）存在，含一个 spectre test； - 该 test 的 tran 分析可无头读回 stop/errpreset/maxstep； - 生成器幂等（重跑零变更、不报错）； - 不触碰 pll45/vco5/adexl。

3. 前置条件¶

.28 root 免密 ssh；
Virtuoso 必须以 rain01 身份跑（root 跑会让 cell 属主变 root:design → GUI SCH-1217）。固定入口 runuser -u rain01 -- bash proj1/verif/gen/run_skill.sh <abs>.il <log>；
ADE-XL license（Virtuoso_Multi_mode_Simulation）在 .29，已实测在。

4. 影响范围¶

项	内容
主机	仅 `.28`（无头 virtuoso，未起 GUI、未占 Slurm 计算节点）
变更点	新增 `design/pll45/pll_top/adexl/`（新视图）、`cdssetup/.cadence/jobpolicy/pllTopCmd.jp`、`verif/gen/{pll45_top_adexl,probe_pll45_top_adexl,probe*_adexl}.il`
未改动	`pll45/vco5/adexl` 未写入（仅只读打开一次）；未改任何 cell；未跑 Spectre；未动 Slurm
是否停服	否
窗口期	约 21 min（含 API 探针迭代）

5. 分步操作¶

步骤 1：只读探针确认 API 链路（probe_adexl.il / probe2b / probe4 / probe5）¶

先证「无头能不能建/读 ADE-XL setup」，再写生成器。

ssh root@192.168.31.28 'runuser -u rain01 -- bash /projects/design/rain01/proj1/verif/gen/run_skill.sh \
  /projects/design/rain01/proj1/verif/gen/probe_adexl.il /tmp/probe_adexl.log'
grep -a '^\\o ' /tmp/probe_adexl.log

坑（本轮踩到，逐条已排除）： - axlGetToolSession 的签名是 (t_sessionName t_testName) 两个字符串，不是句柄；传句柄一律返回 nil，会让人误判「无头不可用」。 - axlGetTests(x_hsdb) 返回 (testHandle (testName))；axlGetTest(x_hsdb "lib:cell:N") 另返回一个句柄——两者不同，tool session 用的是名字。 - 所有探测/取值调用都要包 errset，否则单点报错会让整段 prog 停止、后续 probe 行全不输出。

预期：U1_TOOLSESSION=(sevSession1)、U3_ANALYSES=(...)。

步骤 2：生成器落库（pll45_top_adexl.il）¶

ssh root@192.168.31.28 'runuser -u rain01 -- bash /projects/design/rain01/proj1/verif/gen/run_skill.sh \
  /projects/design/rain01/proj1/verif/gen/pll45_top_adexl.il /tmp/pll45_top_adexl.log'
grep -a '^\\o ' /tmp/pll45_top_adexl.log | grep -a 'G[0-9]'

关键坑（逐条已排除）： 1. axlPutTest 后必须紧跟 axlSetTestToolArgs 显式设 lib/cell/view/sim=spectre。默认会生成 sim="hspiceD" 与一个不存在的 state/path ⇒ sevEnvironment() 返回 nil，整条 OASIS/asi* 链路全废。 2. 分析字段分两类（用错函数返回 nil）：stop/errpreset 是 field（asiSetAnalysisFieldVal）；maxstep/strobeperiod 是 option（asiSetAnalysisOptionVal）。 3. 无头落库入口：axlSaveSetupToLib 在无头下必然失败（内部 axlGetWindowSession 要 window），须用 axlCommitSetupDB(x_hsdb) + axlMainAppSaveSetup(sessionName)（文档明示 non-GUI 用法）。 4. Job Policy attach 的第 4 参数不能传 nil（报 Non-Job Interface subclass object or name [] provided），须带含 distributionmethod/jobsubmitcommand 的属性表。

预期：SKILLRC=0，日志 G33/G68/G67 显示 test/corner/model 均为目标值；第二次整跑 G02_SDB_EXIST、G35~G38=(nil)（已是目标值、零改动）。

6. 验证¶

只读探针 probe_pll45_top_adexl.il 的输出（节选，实测）：

项	读回值
test	`pll45:pll_top:1`（唯一）
tool args	`lib=pll45 / cell=pll_top / view=schematic / sim=spectre`
corner	`nom` + model `/projects/design/rain01/proj1/verif/models/spectre_nom.include`
tran	`stop="1u"`、`errpreset="conservative"`、`maxstep="10p"`、`strobeperiod="100p"`、`enabled=t`
save	模式 `selected`（白名单未持久化，见附录 B）
落库	`pll45/pll_top/adexl/data.sdb` 生成

失败判断：SKILLRC≠0 或探针读回值与上表不符 → 按第 7 章回滚后重来。

7. 回滚¶

本次只新增文件、未覆盖任何既有文件，故无 .bak 备份项（见 backup/README.md）。回滚 = 删除新增对象：

# [高危] 先确认路径；vco5/adexl 不在删除范围
ssh root@192.168.31.28 'rm -rf /projects/design/rain01/proj1/design/pll45/pll_top/adexl'
ssh root@192.168.31.28 'rm -f /projects/design/rain01/proj1/verif/gen/pll45_top_adexl.il /projects/design/rain01/proj1/verif/gen/probe_pll45_top_adexl.il /projects/design/rain01/proj1/verif/gen/probe*_adexl.il'

回滚后验证：pll45/pll_top/ 下只剩 schematic/；vco5/adexl 与既有 cell 不受影响。

8. 风险说明¶

风险	缓解
`pll_top` 顶层端子只有 `REF/VDD/GND`（无 `VCTRL` 引脚；`VCTL` 是内部网）⇒ 激励加不到 `VCTRL`	需在 testbench（或顶层加端口）解决，见附录 B
save 白名单、Job Policy attach 无法用 SKILL 持久化	走 GUI 补充（附录 B），这是「脚本 + GUI」的既定分工
生成器由子智能体开发，主智能体只核验了库状态与探针输出	已复核 `vco5/adexl` mtime 未变、`pll_top/adexl` 内容有效

附录 A：ADE-XL SKILL 脚本化契约（关键，已同步 `docs/BASELINE.md` §7.9）¶

两层 API：结构层 axl*（session/test/corner/model/vars/jobPolicy/run）；分析/save 层属 OASIS（asi*/sev*），入口 axlGetToolSession(sessionName testName) → sevSession。
已实现并实测的调用序见第 5 章；函数签名清单见 doc/adexlSKILLref/（sessionIl.html/setupDB.html/testRelated.html/cornersRelated.html/modelRelated.html/varRelated.html/jobPolicy.html）。

附录 B：未做到项（需 GUI 补充或另行解决）¶

项	状态	说明
`psfbin` 输出格式	做不到	IC617 ADE-XL 的 `simOutputFormat` 合法取值只有 `sst2 / psf / psf with floats / psfxl / fsdb`，无 `psfbin`。S2 裁剪策略里的「psfbin」只对扁平 spectre CLI 成立；ADE-XL 侧须改用 `psf`/`psfxl`。
save 节点白名单	未持久化	`asiSetKeepList` 回显但 `asiGetKeepList` 读回 `nil`；只能到「save 模式 = selected」一层。需 GUI 定白名单。
Job Policy attach 到 test	未持久化	`axlAttachJobPolicy(...)` 会话内有效，重开会话读回 `ADE XL Default`（Local）；策略文件 `pllTopCmd.jp` 已写盘（`distributionmethod "Command"`、`jobsubmitcommand` = wrapper 绝对路径）。需 GUI 绑定或在既有 vco5 路径上确认。
`test` 激励 / `VCTRL`	未做	`pll_top` 顶层无 `VCTRL` 引脚。
温度	可脚本化	`axlPutVar(corner "temperature" "85")` 可用（corner vars 读回含 `temperature`）。
corners 全建（nom/ss/ff×27/85）	未做	当前只有 `nom`。

附录 C：交付物清单¶

生成器：pll45_top_adexl.il（方案副本 + .28:proj1/verif/gen/）
只读探针：probe_adexl.il、probe2b/2/3/4/5_adexl.il、probe_pll45_top_adexl.il
策略文件：.28:proj1/cdssetup/.cadence/jobpolicy/pllTopCmd.jp
备份台账：backup/README.md

附录 D：GUI 侧收口实录（2026-10-04 晚）——save 白名单 + 激励¶

D.1 save 白名单：GUI `Save All` 已落盘（用户操作）¶

路径：ADE XL → Outputs 面板 → Outputs Setup 标签页 → 右键 test 行 → Save All... → 弹出表单点 OK。
坑（重要）：ADE XL 必须退出程序才把 setup 落盘。进程开着时 data.sdb 不变且存在 data.sdb.cdslck（锁）；退出时对「原理图」选 不保存（标题 * 是打开时带的），对「ADE XL」选保存。
判据：pll_top/adexl/data.sdb 由 1629 → 1863 B（mtime 19:11:15）；test state 下生成 outputs（5810 B）、outputsScripts。
outputs 里 _envSaveOptions 已被 Save All 填充；另有用户误点产生的 /GND 行（save='t，无害）。短试跑足够；精确白名单留到 200 点批跑前。

D.2 激励：可直接写 `graphicalStimuli` 文件，无需 GUI（本轮实测通过）¶

ADE-XL 每个 test 的 ADE 状态落在 design/<lib>/<cell>/adexl/test_states/<lib>/<cell>/spectre/<test>_active/，全部是纯文本 SKILL（analyses / outputs / graphicalStimuli / variables / modelSetup / simulatorOptions …）。
激励写在 graphicalStimuli："#INPUTS" + 每条 ((name "…")(nodes ("…" "/gnd!"))(enabled t)(tranType "dc|pulse")(srcType "Voltage")(instParameters …)) + 结尾 "#GLOBALS"。模板取自跑通的 vco5 test 同名文件。
本轮为 pll_top 写入三条（pll_top 顶层端子 REF/VDD/GND，无 VCTRL 引脚，环内 VCTL 由 CP 驱动）：
REF：pulse，val0=0 val1=1.1、period=1.2903n（fref=775 MHz）、width=645p、rise/fall=10p；
VDD：pulse 软启动（取自 vco5），val0=0 val1=1.1、period=2、rise/fall=1n、width=1；
GND：dc 0。
验证（无头）：asiGetStimulusInputs(env) 原样读回这三条（探针 probe_stim.il，SKILLRC=0）⇒ 该文件即权威来源，ADE-L 会话会读它。设计变量 variables 为 nil（pll_top 无 ADE 变量，正常）。
模板文件：adexl_setup_20261004/graphicalStimuli_pll_top.txt；探针：adexl_setup_20261004/probe_stim.il。
备份：.28:/tmp/pll_top_adexl_bak_20261004-191335.tgz。

D.3 仍未收口¶

Job Policy 绑定：axlAttachJobPolicy 不落库（BASELINE §7.9），只能 GUI Job Setup...（策略文件 pllTopCmd.jp 已写盘）。
之后：清 Slurm 残骸（hpc_slurm_20261003/SOP.md §9.7）→ test_lock 短试跑。

D.4 经验（写进 BASELINE §7.9 的候选）¶

ADE-XL 的 setup 改动要退出 Virtuoso 才落盘；否则文件锁住且不写。
激励等 ADE state 可用文本改写并经 asiGetStimulusInputs 无头验证——为后续 test_pnoise/test_mc 省掉大量 GUI。

附录 E：10 µs × 6 角跑通与 `test_lock` 时长定案（2026-10-13）¶

E.1 前序（2026-10-05 → 10-12）¶

--mpi=none 后派发通（Interactive.12，6 角）；ADEXL-1788/9038 用 Check and Save 解。
2026-10-12：4 路保存白名单落盘（outputs 四项 save='t；网表 save VCTL REF VCOCK FB + saveOptions options save=selected）；存储落层（结果落 Lustre）。
体积实测：单点 1 µs 由 8.5 MB（全存）降至 0.27 MB（4 路白名单）；10 µs 单点 4.4 MB。

E.2 本次（`Interactive.16`，tran `stop=10u`，6 角）¶

参数：tran stop=10u errpreset=conservative maxstep=10p strobeperiod=100p；srun -p long -N1 -n1 -c1 --mpi=none 一点一作业。
结果：6 角全过（Number of simulation errors: 0），墙钟 76 分钟（22:42:45→23:58:52），落 Lustre 共 32 MB（每点约 5.2 MB）。
measurement：新增 dVCTL_lock（Outputs Setup → Add Expression；落盘后 outputs 第 5 项 type=nil）。

角	值	角	值
nom_27	147.6 µV	ss_85	267.5 µV
nom_85	5.44 mV	ff_27	4.328 mV
ss_27	106.1 µV	ff_85	120.7 µV

结果落点：<adexl>/results/data/Interactive.16.log（不在波形目录）；读取 grep -n "" <该文件>。

E.3 定案与判据¶

test_lock 时长 = 10 µs：9~10 µs 窗口 VCTL 峰峰值最差 5.44 mV（nom_85）≈ VCTRL(0.55 V) 的 1% ⇒ 进入稳态。
局限：峰峰值含稳态纹波，不能单独区分"未锁定的大摆动"；如需更硬可补早期窗口同法对照。
机制与读数已同步 docs/BASELINE.md §7.12；教学版见 docs/kb/howto-adexl.md。

E.4 待办¶

t4 test_mc：FreePDK45 无统计模型 ⇒ 200 点只能是 corner×温度×参数扫描矩阵；扫什么/范围/步数待定。

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

SOP — 阶段 2：ADE-XL test 的 SKILL 程序化生成（test_lock 首件）¶