极客工场

Appearance

共 2,632 字预计阅读约 9 分钟

OpenSTA clock uncertainty 未生效：时钟对象、作用域与顺序五类坑排查 ​

set_clock_uncertainty 0.5 [get_clocks clk] 写完，脚本退出码 0，report_checks 的 slack 却一个字没变——这是 OpenSTA clock uncertainty 未生效最典型的表现。原因和 OpenSTA set_input_delay 时钟引用错误 同源：命令按时钟对象名解析，解析不到只发一条 Warning，约束静默消失；但 uncertainty 还多两层专属坑——-setup/-hold 与 -rise/-fall 的作用域规则、以及同作用域后写覆盖先写。本篇用同一个两级 DFF 设计实跑五类场景，全部数字来自 OpenSTA 2.0.17 真实输出。时钟本身缺失的基础排查先看 OpenSTA no clocks found：create_clock 缺失与端口名写错排查，本篇默认时钟已经建对，专查 uncertainty 为什么没算进 slack。

本文要回答的问题 ​

  • set_clock_uncertainty 报 clock 'clkc' not found 之后，约束是失效还是延后生效？退出码为什么还是 0？
  • 先写 set_clock_uncertainty 再写 create_clock，时钟建出来后约束会自动补挂上吗？
  • -rise/-fall 与 -setup/-hold 各自作用在什么范围？不带任何检查类型旗标时，uncertainty 算进 setup 还是 hold？
  • 同一条时钟上重复设置 uncertainty，两条值是累加还是覆盖？uncertainty 多大才会把路径打成 VIOLATED？
clock uncertainty 未生效五层分诊漏斗

这张漏斗对应全篇排查主线：不要从 slack 倒推玄学，先读告警，再验证时钟对象是否存在，然后核对约束顺序与 -setup/-hold 作用域，最后用路径报告里的 clock uncertainty 行和 slack 数字闭环。漏斗末层是唯一验收点——名字对、顺序对都不算数，数字算进去才算生效。

一、异常现象原文：Warning、Error 与“假 MET”三种命运 ​

实验设计是两级 DFF 流水线 u_a -> u_b，时钟周期 10ns，数据路径只有 DFF 的 CLK→Q 0.20ns，库 setup 0.10ns，所以不设 uncertainty 时 setup slack 基线恒为 9.70ns（10 − 0.2 − 0.1）。任何 uncertainty 生效，max 报告的 slack 都必须小于 9.70。第一种场景把时钟名 clk 拼成 clkc，终端卡摘自真实日志：

时钟名拼错：告警、空对象集合与纹丝不动的 9.70 slack

读图抓住三个证据：第 6 行 set_clock_uncertainty 触发 Warning: ... clock 'clkc' not found.；第 7 行单独执行 get_clocks clkc 又触发一条同文告警，紧接着 GET_CLOCKS_RESULT= 是空串——说明名字拼错时对象集合为空，uncertainty 没有任何挂载点；最后路径报告里完全没有 clock uncertainty 行，slack 仍是基线 9.70 MET，CASE_EXIT bad_name=0。告警而不中止，是这类失效最坑人的地方。

注意这里与 set_input_delay 家族的告警措辞差异：那篇是 clock arg 'clk' clock not found，uncertainty 命令是 clock 'clkc' not found，少了 arg 字样。按告警全文检索排错时不要只搜一种写法，否则会漏掉日志里真正命中的那一行。

第二种场景是顺序颠倒：uncertainty 写在 create_clock 之前。时钟对象当时还没诞生，告警原文几乎一样：

exp-log
Warning: order.tcl, 5 clock 'clk' not found.
...
           9.70   slack (MET)

这里的时钟名拼写完全正确，但 Tcl 是顺序执行的：第 5 行解析 [get_clocks clk] 时集合为空，约束当场丢弃；第 6 行 create_clock 补建出时钟后，不会回溯补挂前一条约束，slack 依旧 9.70。“时钟后来存在”不能挽救“当时为空”的对象集合。

第三种是选项作用域误用，措辞从 Warning 升级为 Error：

exp-log
Error: scope.tcl, 7 -rise, -fall options not allowed for single clock uncertainty.
Error: scope.tcl, 8 -rise, -fall options not allowed for single clock uncertainty.

-rise/-fall 只在两个时钟之间的 uncertainty（跨时钟、带 -from/-to 对象）才允许使用；单时钟上指定沿类型直接报错，两行约束全部拒绝。同文件里改用 -setup 0.5 与 -hold 0.3 分设后，max 报告出现 -0.50 clock uncertainty、setup slack 变为 9.20，min 报告出现 0.30 clock uncertainty——hold 的要求时间从 0 被抬高到 0.30，而本设计数据到达只有 0.20，hold slack 直接 −0.10 VIOLATED。这顺带说明一个反直觉点：hold uncertainty 是加到要求时间上让 hold 更严，小设计里 0.3ns 就足以违规。

二、版本与复现环境 ​

全部实验在 Docker 镜像 geek-eda:0.3-sta 内完成：容器为 Ubuntu 24.04，OpenSTA 是 Debian 官方独立包 2.0.17。七个用例各自独立启动一次 sta -no_init -exit 进程，互不污染。另有两个与版本相关的真实行为必须说明：其一，2.0.17 没有 report_clock_uncertainty 命令，fixed.tcl 用 catch 实测得到 invalid command name "report_clock_uncertainty"，所以 uncertainty 是否生效只能从路径报告数字反推；其二，网上教程常见的 report_checks -setup/-hold 在本版本是非法旗标，工具告警 is not a known keyword or flag 后仍按默认 max 出报告——想看 hold 必须写 report_checks -path_delay min，否则你以为查了 hold，实际看的还是 setup。

三、根因分层：对象、顺序、作用域、覆盖与数值边界 ​

set_clock_uncertainty 的执行语义分两步：先把对象参数解析成时钟集合，再把数值记到集合内每个时钟的对应检查类型上。五类坑正好落在这条链路上。

eda/ts-opensta-clock-uncertainty.md D2 示意图

读图按颜色走：红色是入口现象，两个蓝色节点是分诊动作（先读告警、再验对象），两个橙色节点按告警措辞分叉修复，绿色是唯一验收点。漏设检查类型旗标还有个隐藏陷阱：default_unc.tcl 实测，不带 -setup/-hold 的裸命令会把同一值同时挂到两类检查上——max 报告减 0.5、setup slack 9.20，min 报告加 0.5、hold slack 变成 −0.30 VIOLATED。只想收紧 setup 却意外把 hold 打穿，是裸值写法的典型事故。第四类坑是覆盖：override.tcl 连续写 -setup 0.5 再 -setup 0.8，报告里只有 -0.80 clock uncertainty、slack 8.90，证明同作用域是后值覆盖而非累加。第五类是数值边界：uncertainty 9.9 时要求时间被压到 0.00，slack −0.20 VIOLATED——功能上完全正确的约束组合，也可能只因为不确定度填大一个数量级而全面违规。

四、排查命令序列 ​

步命令看什么异常含义
1通读加载期输出clock not found / options not allowed对象为空或旗标非法，约束已丢弃
2get_clocks clk / all_clocks返回对象句柄而非空串空集合=名字拼错或时钟尚未建
3report_clock_properties时钟名、周期、波形核对引用名与定义名逐字一致
4report_checks -path_delay max捕获路径 clock uncertainty 行无此行=setup uncertainty 未生效
5report_checks -path_delay min要求时间是否被抬高hold 用 min 报告，勿用 -hold 旗标

数字判读公式可以直接套：本设计 max 要求时间 = 周期 10 − uncertainty − setup 0.10，setup slack = 要求时间 − 到达 0.20；uncertainty 0.5 时要求 9.40、slack 9.20，与日志逐行对得上。min 报告方向相反：hold 要求时间 = hold 0 + uncertainty，hold slack = 到达 0.20 − 要求时间，所以 hold uncertainty 0.2 时恰好 0.00，0.3 就违规。

现场排查还有个快速二分法：报告里完全没有 clock uncertainty 行，是“没挂上”（对象空、顺序错、选项被拒），回到第 1–3 步；有这行但 slack 数字不符合预期，是“挂了但作用域或数值不对”（裸值双挂、被后写覆盖、值过大），直接查第 4–5 步。两类问题的修法完全不同，混在一起调参数只会越调越偏。约束写完后的系统化 lint 流程见 SDC 约束 lint：从警告到签核前检查，负 slack 的含义与分级见 OpenSTA slack (VIOLATED) 负裕量解读。

五、修复与复跑：fixed.tcl 的数字对照 ​

修复只有三条纪律：先建时钟再设 uncertainty；时钟名逐字复制；setup 与 hold 显式分开，不用裸值赌默认作用域。

tcl
create_clock -name clk -period 10.0 [get_ports clk]
set_clock_uncertainty -setup 0.5 [get_clocks clk]
set_clock_uncertainty -hold  0.2 [get_clocks clk]

复跑后 get_clocks clk 返回对象句柄，report_clock_properties 给出 clk 10.00 0.00 5.00，加载期零告警。两类报告的关键数字：

exp-log
=== setup (path_delay max) ===
  -0.50    9.50   clock uncertainty
  -0.10    9.40   library setup time
           9.20   slack (MET)
=== hold (path_delay min) ===
   0.20    0.20   clock uncertainty
   0.00    0.20   library hold time
           0.00   slack (MET)

验收看三个位置同时成立：报告里出现与设定值逐字相等的 clock uncertainty 行（max 0.50、min 0.20）；setup slack 相对基线 9.70 恰好减少 0.5；hold slack 相对无 uncertainty 时的 0.20 恰好减少 0.2 到 0.00。三个数字互相对得上，uncertainty 才算真正进入了时序计算。

代码获取：完整设计、教学库、七个 Tcl 用例与运行脚本位于 geek-doc.cn/experiments/ts-opensta-clock-uncertainty，安装 OpenSTA 2.0.17 后执行 bash run.sh，或用 docker run --rm -v "$PWD":/work -w /work geek-eda:0.3-sta bash -lc 'bash run.sh' 一次复现全部故障与修复对照。

实验环境 ​

  • 机器/系统：本地 Docker 容器，Ubuntu 24.04；宿主为 macOS。
  • 工具版本：OpenSTA 2.0.17，Debian 官方独立二进制包（镜像 geek-eda:0.3-sta）。
  • 日期：2026-11-02。
  • 完整命令：在实验目录执行 bash run.sh，依次运行 bad_name、order、scope、default_unc、override、big_unc、fixed 七个用例，合并 stdout/stderr 并记录各组退出码。
  • 实验边界：experiment.lib 仅含一个 DFF 的最小时序弧，数值用于演示约束解析，不能外推为任何工艺的签核结论。

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

本篇属于 SDC 约束故障层，与 OpenSTA set_input_delay 时钟引用错误：clock not found 三种触发排查 共用“按名解析时钟对象”的底层机制，区别在于那篇讲 IO 约束引用、本篇专讲时钟不确定度的作用域与覆盖语义；时钟压根没建出来的场景先走 OpenSTA no clocks found：create_clock 缺失与端口名写错排查，约束写完仍报未约束端点再看 OpenSTA report_checks 全 unconstrained 排查。

总结 ​

OpenSTA clock uncertainty 未生效的根因都在“解析—挂载”链路上：时钟名拼错或先设值后建时钟，对象集合为空，得到 clock not found 告警后约束静默丢弃、退出码仍为 0；-rise/-fall 对单时钟直接报 Error，裸值则同时作用 setup 与 hold 可能意外击穿 hold；同作用域重复设置是后值覆盖而非累加，值过大则会把路径真实打成负 slack。排查按“读告警 → get_clocks 验对象 → report_clock_properties 对名字 → report_checks -path_delay max/min 核对 uncertainty 行与 slack 数字”推进，2.0.17 没有 report_clock_uncertainty 命令，数字闭环就是唯一验收依据。