OpenSTA 执行 Tcl 报 invalid command name：PrimeTime 方言命令不存在的排查
更新时间：2026-11-12。长尾速查篇，属于 EDA 报错排查系列，汇总入口见 开源 EDA 报错排查导航。
静态时序分析（STA，Static Timing Analysis）的脚本语言都是 Tcl，但 PrimeTime（Synopsys 的商业签核时序工具）与 OpenSTA（开源时序分析器）在 Tcl 之上各自注册了一套命令，两者是方言关系而非同一套接口。把 PrimeTime 手册里的命令原样抄进 OpenSTA 脚本，命令名在解释器里根本不存在，Tcl 会在该行直接抛出 invalid command name 并中止。本篇用一份两级缓冲器的最小工程把这类故障跑透；约束文件本身语法写错的情形另见 OpenSTA SDC 语法报错排查，本篇只讲「工具方言差异导致命令名不存在」。
首屏答案：坏脚本 bad.tcl 第 5 行调用 PrimeTime 方言 report_qor，而 OpenSTA 2.0.17 没有注册这个命令，Tcl 解释器逐行执行到此处命令查表落空，报 Error: e137-bad.tcl, 5 invalid command name "report_qor" 并中止，前四行 read_liberty、read_verilog、link_design、read_sdc 均已成功。修复不是改拼写，而是换成 OpenSTA 等价原语：report_clock_properties [all_clocks] 出时钟属性表，report_checks 出路径 slack，QoR（Quality of Results，结果质量）指标从报告里自行汇总。
这张漏斗对应本文的排查主线：先把报错行号落到具体命令，再用 Tcl 自己的查询接口确认命令是否注册，接着判断它是不是另一套工具的方言，最后找等价原语并加守卫。一见 invalid command name 就按拼写错误处理，是最常见的弯路。
本文要回答的问题
- OpenSTA invalid command 报错的完整原文是什么，脚本中止时前面已经成功的步骤有哪些？
- Tcl 解释器遇到一个命令名时内部怎么查找，为什么查不到就在该行中止而不是跳过？
- PrimeTime 与 OpenSTA 的命令集是什么关系，哪些常见 PrimeTime 命令在 OpenSTA 2.0.17 里不存在，等价信息怎么取？
- 同一份 Tcl 脚本要在两套工具间复用，怎样写命令存在性守卫？
一、完整报错原文：OpenSTA invalid command 在脚本第 5 行中止
最小工程顶层 top 是两级 BUF_X1 组合链：d 经 u_buf1、u_buf2 到 q，clk 端口承载周期 10ns 的时钟约束，库用手写的最小 Liberty 文件 tiny.lib，约束写在 base.sdc 里。坏脚本 bad.tcl 前四步是标准加载流程，第 5 行直接调用从 PrimeTime 脚本里抄来的 report_qor。在容器内执行 sta -exit -no_init -no_splash e137-bad.tcl，完整输出原样摘录如下：
===== [1] 复现原始报错：e137-bad.tcl =====
Error: e137-bad.tcl, 5 invalid command name "report_qor"整个坏例运行只有这一行 Error，没有任何 Warning 铺垫。报错格式是「文件名, 行号 + Tcl 原话」：e137-bad.tcl 第 5 行的命令名 report_qor 无效。注意它与「命令拼错」共用同一句 Tcl 原话，但性质不同——report_qor 在 PrimeTime 里是拼写正确的正式命令，只是 OpenSTA 的命令表里没有它。报错后进程直接结束，第 5 行之后的语句不再执行；前四行加载已经生效，说明网表、库、SDC 都是好的，故障边界就在命令解析层。
二、工具与版本
本次实验在 macOS 上用 Docker 镜像 geek-eda:0.3-sta 运行，容器内 OpenSTA 版本为 2.0.17，统一带 -exit -no_init -no_splash 走批处理模式，不进交互界面。版本先固定，因为 OpenSTA 的命令集随版本增补，本文的「某命令不存在」结论只对 2.0.17 这个构建负责，升级后需要重新查证。
另一个要先交代的边界：OpenSTA 与 PrimeTime 都以 Tcl 为外壳，SDC 约束命令（如 create_clock、set_input_delay）遵循同一套行业标准，这部分脚本大体通用；差异集中在各自扩展的报告、多角管理和内部命名空间命令上。判断命令属于哪一层，要查当前工具的命令表。
三、根本原因：Tcl 命令查表落空，两套工具的命令表不通用
Tcl 是纯解释执行的脚本语言，没有编译期符号检查。解释器每读到一行完整命令，先做词法拆分拿到第一个词作为命令名，再到当前命名空间的命令表里查找：命中内置命令或已注册的过程（proc）就执行命令体，查不到则立刻抛出 invalid command name 错误。默认情况下这个错误会终止整个脚本：前四行逐行命中执行，第 5 行查表落空，后面的语句不再有执行机会。
图中蓝色是脚本入口与查表动作，紫色是 Tcl 求值环节，绿色是命令命中的正常支路，红色是本例实际走到的落空支路。关键认知是：命令表的内容由宿主工具决定。OpenSTA 启动时把自己实现的时序命令注册进 Tcl 解释器，report_qor 是 PrimeTime 注册的扩展命令，OpenSTA 从未注册，查表必然落空。这与 SDC 语法错误有本质区别：SDC 写错（比如 create_clock 漏了 -period）时命令本身存在，错误发生在参数解析或对象语义层；而本例命令名在词法解析后的第一步就不存在，根本走不到参数处理。
在 OpenSTA 2.0.17 上实测查证，PrimeTime 常见的 report_qor、all_corners、current_corner、复数形式的 report_clocks 以及内部命名空间命令 sta::cmd_scene 都不存在；可用的是 report_clock_properties、report_checks、all_clocks、get_name 等 OpenSTA 自己的原语。查证命令是否注册，交互态敲 help 列全量命令，或用内省命令 info commands report_* 按模式过滤；自定义过程则用 info procs 查过程表。
四、排查清单：先查证命令表，再找等价原语，最后加守卫
排查按五步走，核心是让解释器自己回答命令在不在，而不是凭记忆争论。
- 按行号锁定命令名：报错格式固定为「文件名, 行号 invalid command name」，先打开该行确认命令拼写，排除少字母、大小写这类真正的笔误；笔误与方言差异报错文本相同，只能靠「这个命令在目标工具里是否存在」区分。
- 用
info commands查证：在同一容器里执行sta进交互模式，输入info commands report_qor，返回空字符串即命令未注册；带通配符的info commands report_*可以一次列出所有报告类命令，顺手就能发现名字相近的替代者。 - 按语义找等价原语：不要执着于一一对应的同名命令，PrimeTime 与 OpenSTA 的报告组织方式不同。实测可用的映射如下表，QoR 类信息在 OpenSTA 里没有单一出口，需要从路径报告自己汇总。
| PrimeTime 方言命令 | OpenSTA 2.0.17 | 替代做法 |
|---|---|---|
report_qor | 不存在 | 跑 report_checks，从各路径组 slack 自行汇总 WNS/TNS |
report_clocks（复数） | 不存在 | report_clock_properties [all_clocks] 出时钟属性表 |
all_corners / current_corner | 不存在 | 该版本按单角模型组织脚本，不引用 corner 管理命令 |
get_name | 存在 | 直接沿用，取对象名字 |
- 内部命名空间不跨工具：形如
sta::cmd_scene的::命名空间命令是工具内部实现，PrimeTime 的sta::与 OpenSTA 的内部接口没有兼容约定，脚本里一律不引用。 - 跨工具脚本加存在性守卫：同一份 Tcl 需要在两套工具上跑时，用
info commands的返回值分流，让脚本按当前命令表自选支路。
守卫写法如下，info commands report_qor 在命令存在时返回命令名、不存在时返回空串，字符串比较即可完成分流：
if {[info commands report_qor] ne ""} {
# PrimeTime 支路：原生 QoR 报告
report_qor
} else {
# OpenSTA 支路：等价原语组合
report_clock_properties [all_clocks]
report_checks
}方言命令到等价原语的分流路径如下图，蓝色是脚本入口，紫色是存在性判定，红绿分别是两套工具的执行支路，橙色是 OpenSTA 侧的汇总动作：
五、修复代码与复跑确认
修复只动第 5 行：删掉不存在的 report_qor，换成 OpenSTA 原语组合。好坏两份脚本的差异如下：
read_sdc base.sdc
-report_qor
+puts "clocks=[all_clocks]"
+report_clock_properties [all_clocks]
+report_checksputs 先打印 all_clocks 返回值，确认时钟对象存在；report_clock_properties 承接 PrimeTime report_clocks 的职责，report_checks 承接路径时序与 QoR 数据。同一条容器命令复跑修复后的 good.tcl，报错不再出现，终端记录如下：
输出分两段读。第一段是时钟属性表，clk 周期 10.00ns、波形 0.00/5.00，与 base.sdc 里的 create_clock 完全对应；开头那行 clocks= 后面跟的是时钟对象的内部句柄而不是时钟名，想要可读名字要用 get_name 遍历，这是 OpenSTA 对象模型的正常表现。第二段是 report_checks 的路径报告：起点输入端口 d、终点输出端口 q，数据通路经过 u_buf1、u_buf2 两级 BUF_X1，数据到达时间 0.60ns、需求时间 9.70ns，最终 slack 9.10 且 MET。PrimeTime 一张 report_qor 给出的 WNS（最差负裕量）、TNS（总负裕量），在 OpenSTA 里对各路径组报告做同样汇总即可，数据不缺，缺的只是一键命令。
实验环境
- 机器/系统：macOS 本机，Docker 镜像
geek-eda:0.3-sta（容器内 Linux 环境） - 工具版本：OpenSTA 2.0.17，批处理命令
sta -exit -no_init -no_splash <tcl> - 日期：2026-11-12
- 完整命令：在实验目录执行
bash run.sh，脚本先跑sta bad.tcl复现report_qor命令不存在的报错中止，再跑sta good.tcl验证换成report_clock_properties与report_checks后输出时钟属性表和 slack 9.10 MET 的路径报告。
代码获取
完整源码与复现脚本位于公开仓 https://github.com/derekzhuo/geek-doc.cn/tree/main/experiments/ts-opensta-tcl-command-unknown，含 tiny.lib、top.v、base.sdc、好坏两份 Tcl（bad.tcl 与 good.tcl）与 run.sh。本地装好对应 Docker 镜像后，在该目录执行 bash run.sh 即可原样复现「报错中止、等价原语修复」两步运行。
这一篇在知识体系里的位置
本篇属于 开源 EDA 报错排查导航 的静态时序分析分支，回答「别的工具里好好的 Tcl 命令为什么在 OpenSTA 报命令不存在」。最容易混淆的邻居是 OpenSTA SDC 语法报错排查：那篇处理命令存在但拼写、参数、花括号出错，本篇处理命令名在当前工具的命令表里根本没有注册，两者报错文本同为 invalid command name，分界点是 info commands 查不查得到。同批的 OpenSTA read_spef 寄生文件读取失败排查 与 OpenSTA generated clock 源引脚找不到排查 分别覆盖寄生标注与派生时钟阶段的对象失配；SDC 约束的完整编写顺序见 OpenSTA SDC 约束编写流程，全系列入口见 EDA 报错排查系列。
总结
OpenSTA invalid command name 这类报错，本质是 Tcl 解释器逐行求值时命令查表落空：坏例把 PrimeTime 方言 report_qor 写进 OpenSTA 2.0.17 脚本，第 5 行查无此命令，解释器在该行中止，前四步库、网表、链接、SDC 加载均已成功，故障与 SDC 语法无关。排查按「行号锁定命令名、info commands 查证是否注册、按语义找 OpenSTA 等价原语、不引用 sta:: 内部命名空间、跨工具脚本加存在性守卫」五步走；修复用 report_clock_properties [all_clocks] 加 report_checks 替代，复跑得到 clk 10ns 时钟属性表与 d→q 路径 slack 9.10 MET，WNS/TNS 从路径报告自行汇总。分界线一条：命令存在但参数写错归 SDC 语法问题，命令查不到归方言问题，先查证再改代码。