RUNBOOK — PDK 与 Calibre↔Virtuoso 集成（pdk_integration_20260927）¶

读者：接手日常使用与运维的人（可能不熟悉本套 PDK/集成）。每条操作都给全命令 + 预期输出 + 异常处置。变更档案：docs/SOP.md；备份台账：backup/README.md。

目录¶

服务概览 / 2. 接入与凭据 / 3. 日常速查表 / 4. 日常操作 / 5. 配置管理 / 6. 备份与恢复 /
监控与告警 / 8. 故障处置 / 9. 安全与权限 / 10. 容量与性能 / 11. 附录

1. 服务概览¶

组成	位置	作用
PDK 数据树	宿主 `/data/nfs/pdk/{ncsu-cdk-1.6.0.beta,FreePDK45,FreePDK15}`（客户端 `/pdk`）	工艺库、技术文件、模型、Calibre 规则
用户模板	`/pdk/templates/{.cdsinit,cds.lib}`	复制到设计目录后，Virtuoso 启动即加载 Calibre Skill 界面 + NCSU CDK
环境变量	`CDK_DIR`（IC617 modulefile 下发）	NCSU CDK 根；`CALIBRE_HOME` 由 calibre 模块下发
部署/巡检工具	本工程 `.venv/bin/python main.py`	`precheck` / `apply` / `drift` / `verify`

依赖谁：共享盘宿主 192.168.31.249（NFS server）、客户端 Lmod（/opt/modulefiles）、Calibre 与 IC617 安装树（/tools）。
异常时的业务影响：用户无法在 Virtuoso 中使用 NCSU 器件库 / Calibre 集成菜单（版图 DRC/LVS/PEX 流程受阻）； 不影响 IC617 本身启动与 Spectre 仿真（PDK 缺失时 .cdsinit 只打印提示，不中断）。
重要性等级：中（教学/设计流程依赖，非集群基础设施单点）。

2. 接入与凭据¶

客户端接入（对用户）：作业脚本或交互 shell 首行 source /etc/profile.d/zzz_site_lmod.sh，然后

module load cadence; module load virtuoso/IC06.17.700
module load siemens; module load calibre/2015.2_36.27
cp /pdk/templates/.cdsinit /pdk/templates/cds.lib ~/<你的设计目录>/
cd ~/<你的设计目录> && virtuoso &

预期：CIW 启动时出现 // [pdk] Loading Calibre Skill Interface: … 与 // [pdk] Loading NCSU CDK: /pdk/ncsu-cdk-1.6.0.beta。注意：module load 不可放进管道（管道是子 shell，父 shell 拿不到环境变量）。

运维接入：工程根 /home/rain/Documents/eda_tools_ins/Cadence/pdk_integration_20260927（rain 用户，.venv/ 已挂共享库）。
凭据：客户端 SSH 用 root + 密钥认证（密码为空，不入配置文件）；宿主写共享盘用本机 sudo 免密。凭据取用：不需要；若密钥失效，按 ${HOME}/.ssh 既有约定恢复。

3. 日常速查表¶

cd /home/rain/Documents/eda_tools_ins/Cadence/pdk_integration_20260927

.venv/bin/python main.py precheck    # 只读门禁（环境契约/介质/sudo/目标/客户端），结论落 reports/
.venv/bin/python main.py drift       # 只读漂移检测（0 无漂移 / 1 有漂移 / 2 探测失败）
.venv/bin/python main.py verify      # 只读功能验证（落点/模板/modulefile/客户端）
.venv/bin/python main.py apply --dry-run   # 预演：打印将做的变更，零改动
.venv/bin/python main.py apply             # 幂等部署（已达期望态则零变更、全跳过）

ls -l /data/nfs/pdk/ ; ls -l /data/nfs/pdk/templates/          # PDK 落点与模板
grep -n CDK_DIR /data/nfs/modulefiles/cadence/virtuoso/IC06.17.700.lua   # modulefile 增量
tail -50 logs/pdk_integration.log                              # 运行日志
ssh root@192.168.31.18 'findmnt -rno TARGET,SOURCE /pdk'       # 客户端可见性（任一台）

4. 日常操作¶

4.1 状态检查¶

.venv/bin/python main.py drift

预期：9 行 OK（3 kit + 2 模板 + 1 modulefile 标记 + 3 客户端挂载）+ 结论：无漂移。异常：出现 DRIFT → 见场景 F。

4.2 新增一个 kit（例如启用 FreePDK3D45）¶

编辑 config/pdk_integration.yaml，在 kits 追加一项（name/zip/outer/inner/top_dir/markers）。坑：介质是套娃包，outer 是 zip 内的外层包名、inner 是外层包里的真实压缩包名，两者都要填对。
先预演：.venv/bin/python main.py apply --dry-run（预期只列出该 kit 一项待变更）。
执行：.venv/bin/python main.py apply；随后 drift 应无漂移。

4.3 更新站点模板¶

模板由实现体渲染（deployer.py::_render_templates），不要手改 /pdk/templates/*——改渲染函数后跑 apply 即增量重写（按 sha256 判定）。改模板时务必遵守 SOP 第 5 章步骤 3 的三个坑（-- 注释符、行尾不留 -、英文注释）。

4.4 新节点接入 `/pdk`¶

在 config/pdk_integration.yaml 的 client_mount.nodes 追加节点地址。
precheck（新节点应 SSH 可达；/pdk 未挂载只记 WARN，属预期）。
apply → verify。fstab 变更前实现体会自动备份该节点 fstab 到 backup/<hostname>/etc/ 并登记台账。红线：fstab 属高危动作，改前须用户确认。

4.5 重新部署（灾难恢复）¶

.venv/bin/python main.py apply      # 幂等：缺失项自动补齐（重解介质），已有项跳过
.venv/bin/python main.py verify

5. 配置管理¶

配置唯一真源：config/pdk_integration.yaml（样例 .example 同步维护）。
关键字段：

字段	含义	易错点
`contract.{os_family,arch,clients_os_major}`	环境契约	操作机 Ubuntu、客户端 Rocky 9；不符即门禁 BLOCK
`pdk.root` / `owner` / `group` / `strip_write_bits`	PDK 根与权限	权限收敛为 `u=rwX,go=rX`（PDK 只读使用）
`templates.dir`	模板目录	用户从此处复制，不要就地改
`modulefile.{path,marker_key,cdk_dir_client,anchor}`	模块增量	`anchor` 必须真实存在于目标 modulefile，否则实现体拒绝改写
`kits[].{zip,outer,inner,top_dir,markers}`	kit 定义	套娃包三层命名；`markers` 是幂等判据（落点关键文件）
`client_mount.{source,target,fstab_fs,fstab_options,nodes}`	客户端挂载	参数须与 `/tools` 一致（`ro,hard,timeo=600,…`）
`ssh.username`	客户端 SSH 用户	仅用户名；认证走密钥，密码不入配置

生效方式：改配置 → apply --dry-run 复核 → apply。配置校验（必填/取值域/唯一性/零引用）已接入门禁，字段写错会在 precheck 阶段报出并定位到字段路径。

6. 备份与恢复¶

备份策略：每次写共享盘文件或改远端 fstab 前自动备份，落 backup/，命名 <原名>.bak.<YYYYmmdd-HHmmss>，并写入 backup/README.md 台账（文件、原路径、时间、因由、回滚什么、何时可删）。
当前台账内容：1 个 modulefile + 3 个远端 /etc/fstab（lsf 三台）。
恢复步骤：见 docs/SOP.md 第 7 章（modulefile 恢复 / fstab 恢复 + umount / 删除新增 PDK 树）。
恢复后验证：module load 后 echo $CDK_DIR 为空；drift 显示 kit/template/modulefile 全 pending。
演练记录：本次变更中已于 2026-09-27 实际执行过「模板增量重写 → 复跑零变更 → verify 通过」的闭环（见 SOP 第 6 章实测表）。

7. 监控与告警¶

本交付物无常驻服务，无需进程级监控；替代手段是定期只读巡检：

.venv/bin/python main.py drift      # 退出码：0 无漂移 / 1 有漂移 / 2 探测失败

判据：drift 返回 0 视为健康；返回 1 表示落点/模板/modulefile/挂载偏离期望态（见场景 F）。
日志：logs/pdk_integration.log（含时间戳/级别/模块/主机/命令，关键动作留痕）。
门禁报告：reports/precheck-<时间戳>.md（每次 precheck 落盘，结论可复现）。
建议巡检频率：变更后立即；之后随集群整体巡检一并执行。

8. 故障处置¶

场景 A：Virtuoso 启动无 `[pdk] Loading …` 输出（`.cdsinit` 未加载）¶

症状：CIW 无 Calibre/NCSU 加载提示，用户看不到 Calibre 菜单。

诊断

# 1) 当前目录是否有模板（CDS_LOAD_ENV=CWD 只从工作目录读）
ssh root@192.168.31.18 'ls -l ~/设计目录/.cdsinit' ; echo "CDS_LOAD_ENV=$CDS_LOAD_ENV"
# 2) 手动复核模板可加载性（临时目录自清理）
ssh root@192.168.31.18 'bash -s' < scratch/verify_cdsinit.sh

预期：verify_cdsinit.sh 输出含两行 // [pdk] Loading… 与 Done loading NCSU_CDK customizations.，且 Skipping/redefines/NOT loaded 均为 0。处置：① 用户目录缺模板 → cp /pdk/templates/{.cdsinit,cds.lib} <设计目录>/；② CDS_LOAD_ENV 非 CWD → 检查 modulefile 是否被改； ③ 脚本报 NOT loaded → 见场景 B。

场景 B：`CDK_DIR` 或 `CALIBRE_HOME` 未设置¶

症状：.cdsinit 打印 NCSU CDK NOT loaded (CDK_DIR unset) 或 Calibre Skill Interface NOT loaded。

诊断

ssh root@192.168.31.18 'bash -lc "source /etc/profile.d/zzz_site_lmod.sh
  module load cadence; module load virtuoso/IC06.17.700; module load siemens; module load calibre/2015.2_36.27
  echo CDK_DIR=\$CDK_DIR; echo CALIBRE_HOME=\$CALIBRE_HOME"'
grep -n CDK_DIR /data/nfs/modulefiles/cadence/virtuoso/IC06.17.700.lua

预期：CDK_DIR=/pdk/ncsu-cdk-1.6.0.beta、CALIBRE_HOME=/tools/mentor/calibre/aoi_cal_2015.2_36.27/aoi_cal_2015.2_36.27。处置：CDK_DIR 缺失 → modulefile 增量行丢失（可能被覆盖），跑 apply 恢复（实现体按 marker_key 判幂等）； CALIBRE_HOME 缺失 → 用户漏 load calibre 模块，按第 2 章模块序列纠正。

场景 C：客户端 `/pdk` 不可见¶

症状：ls /pdk 报 No such file or directory 或目录为空。

诊断

ssh root@192.168.31.25 'findmnt -rno TARGET,SOURCE,OPTIONS /pdk; grep pdk /etc/fstab'

预期：/pdk 192.168.31.249:/data/nfs/pdk ro,… 且 fstab 有条目。处置：

cd /home/rain/Documents/eda_tools_ins/Cadence/pdk_integration_20260927
.venv/bin/python main.py apply     # 幂等补齐：目录 + fstab 条目 + mount
.venv/bin/python main.py verify

验证：drift 中该节点 mount:<host> 为 OK。

场景 D：Calibre 菜单缺失但 `CALIBRE_HOME` 正常¶

症状：CIW 有 NCSU CDK 加载行，但无 Calibre 集成菜单。

诊断

ssh root@192.168.31.18 'bash -lc "module load siemens; module load calibre/2015.2_36.27
  ls -l \$CALIBRE_HOME/lib/calibre.skl"'

预期：文件存在（约数十 KB）。处置：文件缺失 → Calibre 安装树被改，按 ic617_install_20260926 工程重新 patch/安装；文件存在但菜单仍缺 → 检查 .cdsinit 中 Calibre 段是否被用户本地 .cdsinit 覆盖（Cadence 只加载一个 .cdsinit，用户自有内容应合并进去）。

场景 E：CIW 刷屏 `Skipping` 或库 `redefines` 警告¶

症状：启动输出大量 *WARNING* '…/cds.lib', Line N: Skipping: … 或 LIB … redefines。

诊断

grep -c Skipping /tmp/virt_out.txt ; grep -B1 redefines /tmp/virt_out.txt | head

处置：① 若来源是用户自己的 cds.lib → 注释符必须是 --（不是 ;;，否则被注释语句仍执行），且注释行尾不留 -、注释用英文； ② 若来自 /pdk/templates/cds.lib → 说明模板被改坏，rm 后 apply 重新生成； ③ basic 库冲突 → 说明 FreePDK45 与 NCSU CDK 的 INCLUDE 同时启用，按模板注释二选一。

场景 F：`drift` 报有漂移¶

症状：drift 输出含 DRIFT 行、退出码 1。

诊断/处置：按 DRIFT 前缀定位对象类型：

对象	含义	处置
`kit:*`	落点标记文件缺失（树被删/未挂）	`apply` 重新解包；宿主未写权限先查 `sudo -n true`
`template:*`	模板内容与渲染结果不一致	`apply` 增量重写；若刚改过渲染函数属预期
`modulefile:CDK_DIR`	增量行丢失（modulefile 被覆盖）	`apply` 恢复；若整个 modulefile 被还原，先按 `backup/README.md` 恢复再 `apply`
`mount:*`	客户端挂载或 fstab 条目缺失	`apply`；fstab 变更前须用户确认

验证：处置后 drift 返回 0、verify 通过。

9. 安全与权限¶

/pdk 在客户端为 ro 挂载（与 /tools 一致），用户不能改动 PDK 树；宿主侧 /data/nfs/pdk 属 root:root、go-w。
模板目录同样只读；用户按需复制到自己的设计目录。
工程内不含凭据：SSH 走密钥认证，配置只写用户名。
备份目录 backup/ 含 modulefile 与远端 fstab 副本（无凭据）；仅在本机工程目录内，不外传。
权限模型：宿主写操作经本机 sudo -n；客户端操作以 root 免密 SSH 执行。

10. 容量与性能¶

当前水位：/data/nfs/pdk 约 269M（FreePDK15 194M / CDK 52M / FreePDK45 23M / 模板 12K）；/data/nfs 剩余空间充足。
扩容触发条件：新增 kit（如 LithoSim/3D45，各数十～数百 MB）前确认 /data/nfs 剩余 > 1G。
已知瓶颈：chown -R/chmod -R 对整棵树递归，属一次性开销（本次 3 个 kit 全程约 5 秒）；解包在工程 scratch/ 完成，不占共享盘。
模板与 modulefile 原地更新（按 sha256/标记判幂等），不影响已运行会话。

11. 附录¶

术语¶

项	说明
NCSU CDK	NC State 大学免费工艺设计套件（含器件库、技术文件、Skill 定制）
FreePDK45 / FreePDK15	NCSU 附带的 45nm / 15nm 预测性 PDK（OA 库 / Calibre 规则）
Calibre Skill Interface	Calibre 与 Virtuoso 通信的 Skill 文件（`$CALIBRE_HOME/lib/calibre.skl`）
`CDS_LOAD_ENV=CWD`	Cadence 从当前工作目录读 `.cdsinit`/`.cdsenv`（IC617 modulefile 设定）

交付物与相关文档¶

路径	内容
`docs/SOP.md`	本次变更档案（八章 + 实测数据）
`docs/RUNBOOK.md`	本文件
`backup/README.md`	备份台账
`scratch/verify_cdsinit.sh`	集成生效性验证脚本
`../ic617_install_20260926/docs/`	IC617 工具链安装档案与运维手册
`../docs/HANDOFF.md`	项目根交接快照

修订记录¶

日期	修改人	内容
2026-09-27	Agent	首版：PDK 部署 + Calibre↔Virtuoso 集成、lsf 三台 `/pdk` 接入

来源：/home/rain/Documents/eda_tools_ins/Cadence/pdk_integration_20260927/docs/RUNBOOK.md ｜最后更新：2026-09-27 18:55（由 build/sync.py 同步，请勿在站点侧修改）