极客工场

Appearance

共 2,262 字预计阅读约 8 分钟

OpenSTA read_liberty 找不到库：路径错误与库文件格式错误的排查 ​

在 OpenSTA 流程里，read_liberty 是时序分析的第一步：库读不进来，后面的 link_design、时序报告全都无从谈起。这个报错看似直白，实际混着两批完全不同的故障——文件确实不在路径上，和文件在、但内容不是当前 OpenSTA 能解析的 Liberty。本篇用 OpenSTA 2.0.17 做六个探针，把两类报错的原文、根因和定位命令一次摊开。库文件本身的结构（时序弧、阈值、NLDM 表）在 Liberty 时序库视图 里展开，这里只谈「读不进」这一步。

本文要回答的问题 ​

  • Error: cannot read file xxx.lib 一定是文件不存在吗？相对路径是相对于谁解析的？
  • 为什么文件在磁盘上，OpenSTA 却报 line 1 syntax error？
  • .lib.gz 要不要先解压？把 Verilog、LEF 喂给 read_liberty 会看到什么？
  • ff is not the name of process corner 是库坏了吗？
  • 为什么库读取失败了，脚本退出码仍然是 0？
read_liberty 报错分诊：从一句话报错收敛到六个具体故障点

读这张漏斗只抓一个要点：分诊的钥匙是报错原文的措辞。cannot read file 说明 OpenSTA 根本没打开文件，排查全部在文件系统一侧；line N syntax error 说明文件打开了、解析器在第 N 行读不下去，排查全部在内容一侧。两边的命令互不通用，混着查只会浪费时间。

一、完整报错原文：两类措辞，六个故障点 ​

实验脚本 run.sh 依次跑三组 Tcl，全部输出合并记录。第一组 missing.tcl 制造两个路径事故：引用不存在的相对路径 ./lib/not_here.lib，以及用未设置的环境变量拼路径。

路径类报错原文：文件打不开与环境变量未设置

第一条 Error: cannot read file ./lib/not_here.lib. 是 OpenSTA 自己的文件诊断；第二条 Tcl 结果 can't read "::env(STA_LIB)": no such variable 发生在命令执行之前——Tcl 解释器在替换 $::env(STA_LIB) 时就失败了，read_liberty 压根没有被调用。注意组末的 CASE_EXIT missing=0：本组探针用 catch 包住了错误以便跑完所有用例，但即便不 catch，OpenSTA 2.0.17 在 -exit 批处理模式下对这类报错给出的进程退出码仍可能是 0。用退出码判断库是否加载成功不可靠，必须在脚本里检查后续命令的真实输出。

第二组 broken.tcl 制造四个格式事故：第 7 行被截断的库、把 Verilog 网表当库读、直接读 gzip 压缩库、以及引用未定义的 corner 名。

格式类报错原文：截断库、喂错文件、gz 与 corner 名

前三条都收敛成同一句话 line N syntax error：截断库报在损坏处（line 7），Verilog 和 gzip 都报在 line 1——解析器打开文件后读到的第一批 token 就不是合法的 Liberty 文法。第四条措辞不同：ff is not the name of process corner，库本身没有问题，失败在多 corner 的对象引用上。

二、工具与版本行为 ​

  • OpenSTA 2.0.17，Debian 官方独立包，运行于 Ubuntu 24.04 容器；
  • 该版本的 read_liberty 不会自动解压 gzip：直接读 .lib.gz 得到的是 line 1 syntax error，需要先 gunzip 或用 zcat 管道落盘；
  • -corner 参数不做静默匹配：名字必须事先由 define_corners 声明，拼写不一致（ff 对 tt）直接报错，不会回退到默认 corner；
  • 路径解析基于 Tcl 进程的当前工作目录（[pwd]），与脚本文件所在目录、启动 sta 时的 shell 目录都可能不同——容器 -w /work、Makefile 多层 cd 是常见的踩坑场景。

关于「喂错文件」再多说一句：LEF 和 Liberty 都是 ASCII 文本、都以大写字段开头，肉眼容易混淆，但 LEF 首行通常是 VERSION 或 BUSBITCHARS，喂给 read_liberty 一样是 line 1 syntax error，判据就是步 5 的 head。容器环境还要排除一类假「找不到」：-v 挂载路径写错时，Docker 会把宿主不存在的路径当成空目录挂进去，ls 能进目录但里面没有库——此时在宿主机和容器内各跑一次 ls -l 库路径 对拍，比在 Tcl 里反复猜路径更快。

三、根本原因：打不开与读不懂是两层失败 ​

read_liberty 内部分两步：先由 Tcl 文件 I/O 打开路径，再交给 Liberty 语法解析器。两类故障正好落在这两层上。

eda/ts-opensta-liberty-not-found.md D2 示意图

红色是入口与两列根因，蓝色是定位动作，橙色是修复，绿色是验收。环境变量那条支路容易被误判成「OpenSTA 找不到库」，其实是 Tcl 替换阶段就失败了，报错里没有 read_liberty 字样，这也是它要和 cannot read file 分开看的原因。

相对路径的坑则来自「三个目录」：Tcl 脚本放在 flow/ 下，库里写的是 ../lib/tt.lib，人以为相对脚本解析，OpenSTA 却相对 [pwd] 解析；Makefile 里先 cd build 再调 sta、CI 步骤之间换了工作目录，都会让同一条命令在交互式终端能过、进流程就挂。可靠的写法只有两种：要么在 Tcl 里用脚本自身位置拼绝对路径（[file dirname [info script]]），要么在调 sta 前显式 cd 到约定目录。容器场景再加一条：宿主演示时 export STA_LIB=/data/lib 能跑，docker run 没带 -e STA_LIB 进容器，变量就在容器里消失，报的同样是 no such variable。

四、排查清单 ​

按顺序执行，命中即停：

步命令 / 动作判据
1读报错第一行cannot read file 走步 2；syntax error 走步 5；process corner 走步 8
2Tcl 里 puts [pwd]相对路径是相对这个目录，不是相对 .tcl 所在目录
3file exists ./lib/tt.lib（Tcl）或 ls -l返回 0/文件不存在即路径写错或未挂载
4echo $STA_LIB；容器加 printenv STA_LIB变量未设置或没传进容器，先 export / 加 -e
5head -5 tt.lib第一行应是 library(...) {；出现 module 是 Verilog，出现 LAYER/MACRO 多半是 LEF
6file tt.lib；gunzip -t tt.lib报 gzip data 就是压缩库，先 gunzip 再读
7报错行号附近查括号配平库被手工截断/拼接时，line N syntax error 指向失配处
8define_corners 处逐字对名字-corner 参数必须在已声明名单中，先声明再读库

多工艺角的正确顺序是「先声明、再按角读入」：

tcl
define_corners tt ff ss
read_liberty -corner tt lib/tt.lib
read_liberty -corner ff lib/ff.lib
read_liberty -corner ss lib/ss.lib

如果流程只有单一工况，直接 read_liberty lib/tt.lib 即可，不要带 -corner——带了就必须先 define_corners。库与 SDC 在流程中的先后关系可对照 SDC 数据格式与生命周期。

五、修复代码与复跑确认 ​

通过组 valid.tcl 用一份括号完整、阈值齐全的最小库跑完整链路：

tcl
read_liberty minimal.lib
read_verilog top.v
link_design top
create_clock -name clk -period 10.0 [get_ports clk]
set_input_delay 1.0 -clock clk [get_ports d]
set_output_delay 1.0 -clock clk [get_ports q]
report_checks

修复是否成功，不看退出码，看报告里是否出现了来自库的真实单元延迟与 MET slack：

exp-log
VALID_CASE: read_liberty minimal.lib then read_verilog and link
LINK_OK: minimal.lib accepted and top linked
   0.20    0.20 ^ u_stage/Q (DFF_P)
   0.30    0.50 ^ u_buf/Y (BUF_X1)
           8.50   slack (MET)
CASE_EXIT valid=0

u_stage/Q (DFF_P) 的 0.20ns 和 u_buf/Y (BUF_X1) 的 0.30ns 都来自 minimal.lib 的时序弧，说明库不仅被打开，而且真正参与了时序计算；这是与「读库命令没报错但库没生效」的本质区别。若 link_design 阶段报 Module DFF_P not found in link，说明库压根没加载成功，应回到第一节按报错措辞重新分诊；链接通过但后续没有时钟路径，则是另一个话题，见 OpenSTA no clocks found 排查。

代码获取：六份探针 Tcl、最小库、截断库、网表与运行脚本位于 geek-doc.cn/experiments/ts-opensta-liberty-not-found，用 OpenSTA 2.0.17 执行 bash run.sh 可一次复现全部报错与通过组。

实验环境 ​

  • 机器/系统：本地 Docker 容器（镜像 geek-eda:0.3-sta），Ubuntu 24.04；宿主为 macOS。
  • 工具版本：OpenSTA 2.0.17（Debian 官方独立包）。
  • 日期：2026-11-02。
  • 完整命令：在实验目录执行 docker run --rm -v "$PWD":/work -w /work geek-eda:0.3-sta bash -lc 'bash run.sh'，脚本合并 stdout/stderr，顺序运行 missing、broken、valid 三组并记录各组退出码。
  • 实验边界：minimal.lib 是只含 DFF/BUF 两条时序弧与阈值定义的教学库，数值不对应任何真实工艺，不能外推为签核结论。

这一篇在知识体系里的位置 ​

本篇位于 EDA 流程的最入口：库读入失败时，后续一切 STA 讨论都不成立。库文件内部该写什么，向上接 Liberty 时序库视图；库通过之后约束从哪里来，接 SDC 数据格式与生命周期；库和时钟都在但仍无时序路径，转 OpenSTA no clocks found 排查 与 unconstrained endpoint 排查。

总结 ​

OpenSTA read_liberty 找不到库要先按报错措辞分诊：cannot read file 是文件没打开，查相对路径的 cwd 与环境变量；line N syntax error 是文件打开了但内容不对，查文件类型、是否 gzip 未解压、括号是否截断；not the name of process corner 则是 corner 名没经 define_corners 声明。2.0.17 不自动解压 gzip、读取失败退出码仍可能为 0，验收必须看到 link_design 通过且报告中出现库内单元的真实延迟与 slack (MET)。