ucs_filter_report

从一个或多个 timing report 中按完整 path block、正则表达式和 slack 条件筛选

Program: ucs_filter_report
Version: UCS-1.1.0
Platform: RHEL 7 / RHEL 8；标准输出可直接进入文件或 Unix pipeline
Input: 普通文本或 .gz timing reports
Output: 命中的完整 path blocks 写到 stdout
Support: support@universalchipstudio.com

1. Quick Start

# 所有 path block 中必须出现 CLK
ucs_filter_report -r CLK timing.rpt > clk_paths.rpt

# 排除 scan，只保留负 slack 且小于 -0.2 的 path
ucs_filter_report -e 'scan|SCAN' --slack_less -0.2 \
  timing.rpt.gz > severe_non_scan.rpt

# 同时处理多个报告
ucs_filter_report -r CORE report_a.rpt report_b.rpt.gz \
  > core_paths.rpt

工具按 完整 timing path block 匹配，不是逐行 grep。输出保留原始 block 内容和顺序，便于继续交给其他 timing 工具或人工检查。

2. 筛选模型与组合逻辑

Require · AND每一个 -r 都必须命中。

Exclude · NOT任一个 -e 命中即排除。

Any · OR存在 -o 时，至少一个必须命中。

NAND全部 -n 同时命中才排除。

最终规则可以理解为：

KEEP =
  (all REQUIRE match)
  AND (no EXCLUDE matches)
  AND (ANY is empty OR at least one ANY matches)
  AND (NAND is empty OR not all NAND patterns match)
  AND (all configured slack conditions pass)

2.1 Repeatable options

# path 必须同时包含 Startpoint: 和 Endpoint:
ucs_filter_report -r '^Startpoint:' -r '^Endpoint:' timing.rpt

# CLK 或 DATA 任一出现即可
ucs_filter_report -o CLK -o DATA timing.rpt

# 只有 scan 与 false_path 同时出现时才排除
ucs_filter_report -n scan -n false_path timing.rpt

NAND 不是普通 exclude：-n A -n B 只排除同时含 A 与 B 的 block；只含 A 或只含 B 的 block 仍保留。若要分别排除 A、B，请使用 -e A -e B。

3. Command-Line Options

Option	可重复	说明
`-r REGEX`	是	Require。所有 require pattern 必须命中。
`-e REGEX`	是	Exclude。任一个命中即排除。
`-o REGEX`	是	Any/OR。至少一个 any pattern 命中。
`-n REGEX`	是	NAND。所有 nand pattern 同时命中时排除。
`-f FILE`	否	Mixed filter file；用行首前缀定义模式。
`--anyfile FILE`	否	文件中每个有效行作为一个 Any/OR regex。
`--antifile FILE`	否	文件中每个有效行作为一个 Exclude regex。
`--sep REGEX`	否	自定义每个 path block 的起始 separator regex。
`--slack_less N`	否	只保留 slack 严格小于 N 的 block。
`--slack_more N`	否	只保留 slack 严格大于 N 的 block。
`--slack_between A,B`	否	只保留闭区间 [A, B] 内的 slack；A 必须 ≤ B。
`REPORT...`	是	一个或多个必填报告路径，支持普通文本与 gzip。

兼容旧拼写：-slack_less、-slack_more、-slack_between、-anyfile、-antifile、-sep 会自动转换为对应的双横线选项。

3.1 Slack 语义

命令	保留范围	边界
`--slack_less -0.2`	slack < −0.2	−0.2 不保留
`--slack_more 0`	slack > 0	0 不保留
`--slack_between -1,-0.2`	−1 ≤ slack ≤ −0.2	两端都保留

一个 block 没有可识别的 slack 时，只要配置了任一 slack 条件，该 block 就不会输出。

4. Filter File

4.1 Mixed filter file (`-f`)

# filters.txt
# 无前缀：Require
Path Group:\s+REG2REG

# !：Exclude
!scan_enable

# *：Any / OR
*GC_GFXCLK
*GC_SYSCLK

# @：NAND
@false_path
@test_mode

ucs_filter_report -f filters.txt timing.rpt.gz > selected.rpt

行首	模式	含义
无	Require	该行 regex 必须命中。
`!`	Exclude	该行 regex 命中即排除。
`*`	Any	所有 `*` 行中至少一个命中。
`@`	NAND	所有 `@` 行同时命中时排除。

空行与以 # 开头的注释行忽略。文件模式与 CLI 的 -r/-e/-o/-n 会合并使用。

4.2 anyfile / antifile

# clocks.txt：每行一个 OR pattern
GC_GFXCLK
GC_SYSCLK
GC_AONCLK

# ignored.txt：每行一个 exclude pattern
scan
test_mode

ucs_filter_report --anyfile clocks.txt --antifile ignored.txt timing.rpt

5. Timing Path 分块与自定义 Separator

默认按顺序检测以下常见 report header，第一个能匹配报告的模式会被采用：

Startpoint:
Path N:
Path #: N
Possibility N:
### Path / ### This path
Timing Path to

若报告格式不在此列表中，使用 --sep 指定每个 block 起始行的正则表达式：

ucs_filter_report --sep '(?m)^BEGIN_TIMING_PATH\b' custom_report.rpt

正则提示：--sep 要匹配每个 block 的开头，不是 block 之间的分隔线。建议使用 (?m)^... 锚定行首，避免正文误匹配。

6. 完整示例

6.1 GFX clock 严重违例

ucs_filter_report \
  -r 'GC_GFXCLK' \
  -e 'scan|test' \
  --slack_less -1.0 \
  GC_GFXCLK_min.rpt \
  > GC_GFXCLK_min.severe.rpt

每个输出 block 必须包含 GFX clock，不含 scan/test，且 slack 严格小于 −1.0。

6.2 指定 startpoint / endpoint 类别

ucs_filter_report \
  -r '^Startpoint:\s+CORE/' \
  -r '^Endpoint:\s+MEM/' \
  timing.rpt.gz > core_to_mem.rpt

因为两个 -r 是 AND，只有 CORE launch 到 MEM capture 的 path 被保留。

6.3 Slack window

ucs_filter_report --slack_between=-0.5,-0.1 timing.rpt > review_window.rpt

负数参数建议使用 = 形式，或按当前 shell 正确引用，避免参数解析器把负号当作新 option。

6.4 多报告合并筛选

ucs_filter_report -o REG2REG -o CLK2REG \
  corner_ss.max.rpt.gz corner_ff.max.rpt.gz \
  > selected_corners.rpt

输出按命令行中的报告顺序拼接；每个报告内部保留原 path block 顺序。

6.5 只统计命中 path 数量

ucs_filter_report --slack_less 0 timing.rpt.gz \
  | grep -c '^Startpoint:'

7. Pipeline 与输出约定

正常结果只写 stdout，错误信息写 stderr，因此适合重定向与 pipeline：

# 输出报告，错误另存
ucs_filter_report -f filters.txt timing.rpt.gz \
  > filtered.rpt 2> filter.err

# 先筛选再压缩
ucs_filter_report --slack_less -0.2 timing.rpt \
  | gzip -c > filtered.rpt.gz

# 检查退出状态
if ucs_filter_report -r CLK timing.rpt > out.rpt; then
  echo "filter completed"
else
  echo "filter failed" >&2
fi

Exit code	含义
0	命令成功完成；即使没有 block 命中也属于成功。
1	License 检查失败。
2	报告读取、gzip、regex、range 或其他运行错误。

8. Troubleshooting

现象	处理
输出为空	先只运行一个最简单条件；确认 path block 内确实有 slack；检查多个 require 是否错误地当成 OR。
整份报告像一个 block	默认 separator 未识别该格式；用 `--sep` 指定真正的 path header。
Invalid regex	命令行 regex 用单引号保护；检查未配对的括号、方括号或反斜线。
负数被识别为 option	使用 `--slack_less=-0.2`、`--slack_between=-1,-0.2`。
Gzip 读取失败	用 `gzip -t report.rpt.gz` 验证文件完整性；扩展名为 `.gz` 时工具会按 gzip 解码。
NAND 结果与预期不同	NAND 只在全部 nand pattern 同时命中时排除；逐项排除应使用多个 `-e`。
没有命中也返回 0	这是正常行为。需要强制检查时，对输出文件计数或检测是否为空。

9. Command Synopsis

Usage: ucs_filter_report [OPTIONS] <REPORT>...

Options:
  -e <EXCLUDE>                       Exclude regex; repeatable
  -r <REQUIRE>                       Require regex; repeatable
  -o <ANY>                           Any/OR regex; repeatable
  -n <NAND>                          NAND regex; repeatable
  -f <FILTER_FILE>                   Mixed filter file
      --anyfile <ANY_FILE>           One Any regex per line
      --antifile <ANTI_FILE>         One Exclude regex per line
      --sep <SEPARATOR>              Path-start separator regex
      --slack_less <SLACK_LESS>
      --slack_more <SLACK_MORE>
      --slack_between <MIN,MAX>
  -h, --help
  -V, --version

文档与实现一致性：本页按 UCS-1.1.0 最新源码、CLI help 和 GFX full timing report 验证编写，替代旧页面中的过期元数据与空白 option 描述。