ucs_sta_viewer

STA Summary、timing-path 浏览、筛选、short-path 聚合与 Path Info 分析的完整用户指南

Program: ucs_sta_viewer
Release: UCS-1.1.2 · 2026-08-02
Platform: macOS / RHEL 7 / RHEL 8，原生单文件 GUI，不依赖浏览器
Input: Run Directory、一个或多个 timing report、report list、glob pattern
License: 启动时检查 UCS license；debug level 受 license 限制
Support: support@universalchipstudio.com

1. Quick Start

STEP 1选择输入类型

STEP 2Choose / 输入路径

STEP 3Generate Summary

STEP 4选择 Corner / Group

STEP 5浏览、筛选或 Path Info

# 从当前目录启动
./ucs_sta_viewer

# 预设一个 run directory
./ucs_sta_viewer --run-dir /proj/chip/run_001

# 不打开 GUI，直接导出 summary
./ucs_sta_viewer --run-dir /proj/chip/run_001 \
  --export-xlsx /tmp/run_001_sta_summary.xlsx

推荐操作：先在左上角确认 Input Mode，再用 Choose 选择输入；路径确定后点击 Generate Summary。只修改输入框不会自动重新扫描。

2. 输入方式

Input Mode	适用场景	输入格式	Scope / Output 默认位置
Run Directory	标准 STA run，已有 QoR 与 full timing report	一个目录	该 run directory
Timing Reports	临时分析独立报告或多个 corner 报告	GUI 多选；或用分号分隔路径 / glob	第一个报告的父目录
Report List	报告很多、需要复用输入集合	`@/path/report.list`；list 每行一个路径或 glob	list 文件所在目录

2.1 Timing Reports 与 glob

# 输入框可接受分号分隔
/proj/run/a.max.rpt.gz;/proj/run/a.min.rpt.gz

# glob 可匹配多个层级
/proj/run/**/report_timing.full.*.rpt.gz

# 多个 pattern
/proj/A/**/*.rpt.gz;/proj/B/**/*.rpt

支持普通文本报告和 gzip 压缩报告。glob 在程序内部展开，不要求 shell 先展开；因此路径包含 * 时也可直接粘贴到 GUI。

2.2 Report List

# reports.list
# 空行和注释可忽略
/proj/run_a/reports/*.report_timing.full.max.rpt.gz
/proj/run_a/reports/*.report_timing.full.min.rpt.gz
../run_b/**/*.rpt.gz

相对路径以 list 文件所在目录为基准。选择 Report List 后，输入框会以 @ 开头显示 list 路径。

2.3 Run Directory 的识别

Run Directory 模式会收集 corner QoR，并关联对应的 setup / hold full timing report。Summary 中若显示 timing report missing，通常表示 QoR 已找到但命名规则下的 full report 不存在，或报告尚未生成。

3. 界面区域

顶部输入栏	Input Mode、路径、Choose、Generate Summary、Export Excel。
Overall Summary	每个 corner / check type 一行，显示最差 WNS、负 slack TNS、NVP、violating group 数量与 comment。
Path Groups	当前 corner 下的 group 排名；支持动态 Group Filter。
Timing Report	显示选中 group 的原始 path block，按 slack 从 worst 到 best 排列。
Report Toolbar	Search Report、Next Path、Generate Short、Slack Histogram。
Filter / Subgroup	预览 path filter，或把命中 path 写成新的 subgroup report。

UCS STA Viewer summary and timing report workspace — Figure 1. Summary 主界面。示例沿用 GFX full timing report 格式，设计对象与 group 名已匿名化。

4. Summary 与 Group Filter

4.1 指标定义

字段	定义	说明
WNS	Worst Negative Slack	group / corner 中最差 slack。
TNS	Total Negative Slack	只累计负 slack；正 slack 不进入 TNS。
NVP	Number of Violating Paths	slack < 0 的 path 数量。
Status	MET / VIOLATED	WNS < 0 显示 VIOLATED，否则 MET。

4.2 Group Filter 语法

输入时结果动态刷新，不需要点击 Search。先用 ||（也接受全角 ｜｜）分成 OR 分支，再在每个分支中用分号连接 AND 条件。名称文本和名称 regex 都不区分大小写；数值比较使用报告中的原始数值。

表达式	含义	例子
`name=TEXT`	名称包含文本	`name=reg2reg`
`name~REGEX`	名称匹配正则表达式	`name~^(REG\|CORE)`
`name!~REGEX`	名称不匹配正则表达式	`name!~clock\|test`
`wns OP N`	按 WNS 比较	`wns<-0.2`
`tns OP N`	按 TNS 比较	`tns<=-10`
`nvp OP N`	按 NVP 比较	`nvp>0`

数值操作符支持 <、>、<=、>=、=。

# 只看 reg2reg 且 WNS 小于 -0.2
name~reg2reg; wns<-0.2

# 看严重违例，或者名字含 clock 的 group
wns<-1.0 || name~clock

# 有 violation，但排除 scan/test
nvp>0; name!~scan|test

常见误解：name~A; name~B 要求同一个 group 同时匹配 A 和 B。若希望 A 或 B，请写 name~A || name~B 或 name~A|B。

4.3 Group Filter 操作流程

先在 Overall Summary 选定一个 corner；Path Groups 会载入该 corner 的全部 group。
从最简单的条件开始，例如 nvp>0。每次输入变化都会立即重算列表。
再加入名称或严重度条件，例如 nvp>0; wns<-0.2; name!~scan。
需要保留另一类 group 时再增加 OR 分支，例如 ... || name~clock。
清空输入框即可恢复全部 group；filter 只改变显示，不修改报告或 QoR 数据。

表达式边界：= 是数值精确比较；名称包含请使用 name=TEXT。错误或无法识别的 clause 不会被当成任意匹配，建议逐段输入以便立即发现问题。

5. Timing Path 浏览与搜索

在 Overall Summary 选择 corner。
在 Path Groups 点击一个 group。右侧加载该 group 的 path，并按 slack 从最差到最好排列。
点击 Next Path，视图直接跳到下一条 path 的开头，并高亮 header；不需要连续滚动长报告。
在搜索框输入文本并点击 Search Report。重复点击会跳到下一处；到末尾后从开头继续。

搜索标题会显示当前匹配序号、总匹配数和行号。更换搜索文本后，搜索位置自动从报告开头重新计算。

5.1 Slack Histogram

Slack Histogram 从当前 group report 提取 slack，使用 outlier-aware 分桶。离群值单独进入边缘 bucket，主分布不会因少量极端 slack 被压缩得不可读。

6. Generate Short

Generate Short 将当前 group 中的 timing path 按 startpoint / endpoint 结构聚合，适合快速判断违例是否集中在同一批 launch/capture 结构。

控件	行为
Group by: Start → End	startpoint 与 endpoint 组合相同的 path 为一组。
Group by: Start Only	只按 startpoint 聚合。
Group by: End Only	只按 endpoint 聚合。
Compact numeric indices	把层级名中的数字序列归一为 `*`，例如 `reg_17/D` 与 `reg_42/D` 可归到同一类。
Sort by WNS	最差 WNS 的组优先。
Sort by TNS	最差 TNS 的组优先。
WNS / TNS / NVP	WNS 为组内最差 slack；TNS 只累加负 slack；NVP 为负 slack path 数量。

展开一个 short group 后，每条 path 显示 Select、Startpoint、Launch Clock、Endpoint、Capture Clock、Slack。Launch Clock 与 Capture Clock 分别来自完整 timing path 中 data arrival time 前后的 clock edge 行；报告没有对应 clock edge 时显示 —。点击 Select 列切换复选状态；点击该行其他列打开完整 path 文本。

选择保持稳定：切换 Group by、Compact 或排序方式时，复选状态按原报告中的 path ID 保留，不会因为重新分组而选错 path。

Generate Short grouped path table — Figure 2. Generate Short：Compact 把数字序列归一为 `*`；中间 Paths 表格同时对齐显示 launch/capture clock、端点、选择状态和 slack。

7. Path Info

打开 Generate Short。
勾选需要比较的 path；也可先展开一个组，再用 Select Group 选中该组全部 path。
点击 Path Info 生成横向信息表。

列	来源 / 计算	用途
Startpoint / Endpoint	Timing path header	定位 launch / capture 对象。
Launch Edge	launch clock rise/fall edge	launch reference edge。
Launch Clock Latency	launch clock arrival − launch edge	launch side insertion/latency。
Data Path Delay	forward data arrival − launch edge − launch latency	数据路径自身延迟。对于在 slack equation 中再次显示负号 `data arrival time` 的报告，只使用正向数据路径的第一个 arrival 值。
Capture Edge	capture clock rise/fall edge	capture reference edge。
Capture Clock Latency	capture clock arrival − capture edge	capture side insertion/latency。
Skew	capture latency − launch latency	未扣除 CRPR 的 clock skew。
CRPR	clock reconvergence/common-path pessimism line	报告中的 pessimism removal。
Real Skew	Skew − CRPR	按 UCS 定义显示扣除 CRPR 后的 skew。
Path Margin	报告中的 path margin	报告无该行时显示 `—`。
Requirement Time	data required time	数据到达要求时间。
Slack	timing path slack	最终 timing 裕量。

单位：Path Info 不猜测或换算单位，数值沿用报告的 time unit。报告缺失的字段显示 —，避免把缺失数据误当作 0。

Path Info launch data capture and skew columns — Figure 3. Path Info：所选 path 横向对齐比较。表格可水平滚动查看 Path Margin、Requirement Time 与 Slack；对象名已匿名化。

8. Timing-path Filter 与 Subgroup

该 filter 针对当前选中 group 的每一个完整 path block。分号连接的 clause 同时生效；正则表达式区分大小写。

Clause	逻辑	行为
`require=REGEX`	AND	每个 require 都必须命中 path block。
`exclude=REGEX`	NOT	任一 exclude 命中即排除。
`any=REGEX`	OR group	存在 any 时，至少一个 any 必须命中。
`nand=A&B`	NAND	A 与 B 全部同时命中时排除；只命中其中一个仍保留。
`slack<N`	数值条件	只保留 slack 严格小于 N 的 path。
`slack>N`	数值条件	只保留 slack 严格大于 N 的 path。

# 包含 KEEP，排除 BUF，只看 slack < -0.1
require=KEEP; exclude=BUF; slack<-0.1

# CLK 或 DATA 至少一个出现，同时排除同时包含 scan 和 false_path 的 block
any=CLK|DATA; nand=scan&false_path

# 只取一个 slack 区间：-1.0 < slack < -0.1
slack>-1.0; slack<-0.1

8.1 Preview Filter

必须先在 Path Groups 选中一个 group；filter 的对象就是该 group 对应的完整 timing report。
在 Expression 输入一个或多个 clause。表达式中的正则区分大小写；例如 require=CLK 不匹配小写 clk。
点击 Preview Filter。新窗口显示完整命中 path block，并报告匹配数量。
检查 Startpoint、Endpoint、slack 及排除条件是否符合预期。Preview 不创建目录、不写 report，也不修改原文件。

多个 require 是 AND；多个 exclude 任意一个命中就排除；多个 any 组成一个 OR group。nand=A&B&C 只有 A/B/C 全部命中同一 path block 时才排除。

8.2 Create Subgroup Report

在 Path Groups 选中 source group，并用 Preview Filter 验证 Expression。
用 Explore 选择 Output；默认建议使用输入范围下的 sta_viewer_output。
可填写 New group。留空时按当前目录内容自动选择未占用的 group_1、group_2……
点击 Create Subgroup Report。只有这一步会写文件。

输出目录固定为 <Output>/<YYYYMMDD>/<corner>/。原始压缩报告只在首次创建时保存一份解压文本 <source>.rpt；subgroup 写成 <source>.<group>.rpt。日期、corner 或 group 中不能用于路径的字符会安全替换为下划线。

状态栏返回完整输出路径、WNS、TNS、NVP。WNS 只报告负 violation 中的最差值；没有负 slack 或没有命中 path 时 WNS 显示 —、TNS 为 0、NVP 为 0。空结果仍然是可追溯的有效 subgroup report。

New group 命名：不要依赖同名文件被覆盖。需要重复生成不同条件时使用不同 group 名，或留空让程序自动选择新名称。

9. Output、Comment 与 Excel

Artifact	位置	说明
Comment	`<Output>/<YYYYMMDD>/.ucs_sta_viewer_comments.json`	按 run、corner、check type、group 保存。
Original report copy	`<Output>/<date>/<corner>/<source>.rpt`	首次创建 subgroup 时保存解压后的原文。
Subgroup report	`<source>.<group>.rpt`	只包含命中的完整 path block。
Excel summary	用户选择的 `.xlsx`	汇总 corner、group、WNS/TNS/NVP 和 comment。

9.1 Add / Edit Comment

先确定 comment target：点击 Overall Summary 的一行表示整个 corner；点击 Path Groups 的一行表示当前具体 group。
Comment 输入框会自动载入该 target 已保存的文本。切换 target 前先保存当前修改。
确认 Output。comment 以 Output root 和日期为作用域；切换 Output 后会载入该位置对应日期的 comment 集合。
输入 owner/leader 说明，点击 Save Comment。状态和 summary 立即刷新。
需要清除显示内容时把输入框清空并再次 Save Comment。

# Overall comment 示例
Owner: PD
RouteOpt rerun after clock ECO; signoff extraction pending.

# Path Group comment 示例
Owner: STA
Violations concentrated on cross-block endpoints; ECO list issued.

comment 保存到 <Output>/<YYYYMMDD>/.ucs_sta_viewer_comments.json，内部 key 包含 run、corner、setup/hold 类型和 group（Overall 使用专用标记），因此不同 run/corner/group 不会互相覆盖。父目录不存在时会自动创建。

9.2 Export Excel

Export Excel 使用当前已载入数据和 comment。Overall Summary worksheet 包含 corner-level comment；各 corner worksheet 保留相应 group comment。保存 comment 后再导出，确保交付表格包含最新 owner/leader 说明。

10. GFX timing report 实测用例

以下验证使用 GC_GFXCLK_min.rpt 详尽 GFX min timing report；文档只记录统计结果，不公开设计对象名称。

检查项	实测结果
Report size	31,722 行，约 11 MB
Timing paths	168
Startpoint / Endpoint	168 / 168
Launch Clock / Capture Clock	168 / 168
Launch edge / latency / data delay	168 / 168 / 168
Capture edge / latency	168 / 168
Skew / CRPR / Real Skew	168 / 168 / 168
Requirement / Slack	168 / 168，slack 范围 −13.6200 到 7.9870
Data Path Delay range	20.8020 到 144.5820；168 条 path 均为非负值
Path Margin	报告不包含该字段，正确显示 `—`

# GUI：选择 Timing Reports 后输入
/path/to/GC_GFXCLK_min.rpt

# 建议验证流程
Generate Summary → 选择 group → Next Path → Generate Short
→ 勾选若干 path → Path Info → 对照原报告字段

11. Command Line Reference

Usage: ucs_sta_viewer [OPTIONS]

Options:
      --run-dir <DIRECTORY>  Initial run directory [default: .]
      --export-xlsx <XLSX>   Export and exit without opening GUI
      --debug <DEBUG>        Requested debug level [default: 0]
  -h, --help                 Print help
  -V, --version              Print version

--debug 只控制诊断详细程度，不写死 user ID。若申请的 level 高于 license 的 max_debug_level，程序会降级到获准级别并给出提示。

12. Troubleshooting

现象	原因与处理
No timing report paths	确认报告包含 Startpoint / Endpoint / slack；确认选择的是 full timing report，不是只有 QoR summary 的文件。
Summary 为空	检查 Input Mode 是否正确；修改路径后点击 Generate Summary；glob 是否匹配到文件。
Group 有 QoR 但 report missing	full report 未生成、命名不匹配或路径已移动。用 Timing Reports 模式可直接验证具体报告。
Filter 没有结果	先逐条删除 clause；检查大小写和 regex；注意多个 require 是 AND。
Path Info 为 `—`	字段在原报告中不存在或该工具格式未提供对应行。程序不会用 0 填充缺失值。
Launch/Capture Clock 为 `—`	检查完整 path 中是否有 `clock NAME (rise edge)` 或 `clock NAME (fall edge)` 行；summary-only 报告通常不包含该信息。
Select 后切换分组	选择按原 path ID 保留；若看不到已选 path，切回包含它的组或点击 Clear 清空。
License error	确认 UCS license 文件位于发布约定位置、host/date/product 有效；不要修改可执行文件或 license 内容。

13. 本版本验证范围

已验证：168-path GFX 报告字段完整度，包括每条 path 同时含正向 arrival 与 slack equation 负号 arrival 的格式；Generate Short 的 Launch/Capture Clock 显示、三种分组、Compact、WNS/TNS 排序；跨重分组稳定选择；Select Group / Clear；Path Info 列与 Real Skew 公式；report search / Next Path；filter 逻辑；完整自动化测试。

RHEL 7 与 RHEL 8 发布文件在对应目标环境编译并做 license、启动、依赖和功能 smoke test；客户使用时请选择与系统对应的 compiled version。