rergession-system documentation
rergession-system 是一个配套于 Thor 仓库和众多 case 仓库的命令行工具, 用于推进 Thor 的迭代开发, 其功能包括但不限于如下举例:
支持执行 regressioncase 和 PPA_testcases 等众多 case 仓库.
执行 case 执行数据分析展示与执行结果的汇总.
支持 tcl flow 的自定义生成与自动生成.
支持与其他服务器进行交互, rpc 调用 dc / genus 等工具.
支持 PPA 数据分析与可视化, 支持远程调用 lec 工具.
…
maat 使用手册
概述
maat 是⽤于Thor进⾏回归测试的⼆进制⼯具, 其集成了指定规则对比、lec检查、输出数据解析、特异性tcl脚本⽣ 成等⼀系列功能。本⽂旨在列举 maat 的简易使⽤⽅法及对应 case 的添加流程.
maat 基础使用教程
1. 环境配置与 case 准备
maat 的启动依赖于两个对象
* 综合工具 RainaSynth
一般来说, maat 将在 thor_submodule 或 thor_submodule 下的 regressioncases 目录中执行, 此时 maat 将尝试查找 thor_submodule 编译 出的 RainaSynth, 若查找失败, 则将使用系统默认的 raina（即 Thor 仓库历史最近版本）。
用户也可以使用环境变量 RAINA_PATH 来指定综合工具 RainaSynth.
# 使用 export 导入环境变量, 建议将其写入 bashrc 文件, 便于在 cmd 中快速启动 maat export RAINA_PATH={my_thor_path}/bin/RainaSynth
* 将要执行的 case 或 cases 目录
在一般情况下, maat 将在 thor_submodule 目录下执行或在 thor_submodule/regressioncases 目录下执行。 当处于 thor_submodule 时, maat 会尝试查找 regressioncases 目录.
2. maat 执行 case 示例
默认以当前路径为 cases 路径, maat 会尝试查找 regressioncases 目录并递归地执行该目录下所有 case, 若未找到任何 case, 则检查当前目录是否在一个 case 内部.
# thor_submodule 目录下应当存在一个 regressioncases 目录, 其下有数个 case: case1, case2, case3 ...
# 默认执行当前目录下所有 case, 此时将会执行 repo 下所有 case 并汇总输出
maat
# 推荐进入 regressioncases 目录下执行
cd regressioncases
maat
# 仅执行 Sdc/.../case1, Eco/.../case3, Power/.../case5 这三个 case, /.../ 表示中间的数个目录层级
maat Sdc/.../case1 Eco/.../case3 Power/.../case5
# 仅执行 Sdc 这个模块下所有的 case
maat Sdc
# 仅执行 Sdc/mod1 这个子模块下所有的 case
maat Sdc/mod1
# 若当前用户位于某个 case 目录中
cd regressioncases/case1
# 尝试执行所有 case, 未发现 case, 检查自身是否为 case
maat
# 未发现其他 case, 检测出 pwd 为 case, 执行当前 case (case1)
# 可指定要执行的 case
cd regressioncases
# 支持通配符, 执行所有以 test 开头的所有 case
maat test*
# 支持排除指定 case, 滤除 case3 和 以 test 开头的所有 case
maat !case3 !test* # sh 脚本中
maat \!case3 \!test* # 命令行中, ! 需要进行转义
# 支持 file_list 文件, 如 cases.txt 中写有三个 case,
maat cases.txt
3. 关于 golden 的更新和 case 更改
一般情况, golden 无需用户手动更改, 当用户在 gitlab 中提交了一个 merge 请求时, 若测试通过, 则 gitlab 的 CI/CD 流将自动完成 golden 的更新操作。
若 CI/CD 流中报错, 将会导致此次执行不通过, 此时用户需要根据 regression 测试结果查看未通过的原因（一般来说, 用户在提交一个 commit 之前, 也应当在本地执行一次测试, 以确保新增代码正确）, 若确定本次 regression 测试结果 中错误的 case 符合预期,则用户应当修改 regressioncases 中对应的 tcl / golden 等文件并随代码一起提交。流程图如下：
4. 搭配 tools update-golden 工具
maat 工具可搭配 tools update-golden 工具, 该工具用于快速更新 regressioncases 仓库中的 golden 文件. 其用法如下:
# 进入 regressioncases 目录, 执行 case.
# case 执行后可能会出现 FAIL 的情况, 并且此时这个 FAIL 是符合预期的.
cd regressioncases
maat
# 假设 Mod/case1 错误, 且其改变是符合预期的, 可以使用 tools update-golden 更新 golden
tools update-golden Mod/case1
# 也可以不加 case 名, 此时 tools update-golden 将更新所有 case 的 golden.
tools update-golden
tools update-golden 的详细使用可以参考 tools update-golden 工具说明
maat 参数一览
maat 有许多额外的参数可以供配置, 其 --help 输出如下:
[root@dev]$ maat --help
Usage: maat [OPTIONS] [CASES]...
Options:
--repeat INTEGER Specify the number of repeated executions of the case,
the default is 1
--timeout TEXT Specifies the timeout of the case. Support unit s
(default)/m/h/d. The default is 0s.
--config TEXT Configure backend custom parameters
--log TEXT Specified logger level: TRACE/DEBUG/INFO/WARNING/ERROR
--compare Enable differential text echo in the command console
-c, --continue Enable to continue running with the last execution result
--debug Enable debug mode for maat
--commit_id TEXT Specify the commit id for test case running
--tag TEXT Specify the tag for test case running
--cpu_num INTEGER Specify the cpu number for test case running
--version Show maat version
--help Show this message and exit.
这些参数均可以组合使用, 一些常用的参数如下:
--compare
指定执行 case 时是否输出 error case 的详细信息.
maat --compare效果如图:
--cpu_num
指定 maat 多进程数量, 默认为当前机器最大核心数的一半以防止过多的占用资源.
maat --cpu_num 8
--version
输出当前 maat 版本.
maat --version
--continue/-c
在执行 case 过程中, 用户可使用 ctrl+c 停止执行 case, 此时可使用 --continue 参数继续上次执行任务
# 执行一些 case maat some_cases # 键盘按下 ctrl+c, maat停止执行 case 并输出当前 case 执行结果汇总 # 继续上次任务执行, 此时需要保证 --dir 输入一致 maat some_cases # 也可用于中途修改 case 参数, 如接下来的 case 均停止 lec 检查 maat some_cases --config case.ENABLE_LEC=false
--config
更改 maat 功能模块参数的指令, 其使用较为多变复杂, 并可搭配 配置文件 使用, 进阶使用请参考 --config 配置表.
--config 是一个可重复使用的参数, 用于更改多个配置, 输入格式为.
maat --config [mod.attr=value] # eg: 打开 lec 检查并指定 lec rpc 调用的端口为 12345 maat --config case.ENABLE_LEC=on --config lec.PORT=12345
--yaml
指定本次 case 执行使用的配置文件, 例如, 用户编辑了一份 custom.yaml 文件, 其内容如下:
case.ENABLE_LEC: false case.timeout: 10m此时 maat –yaml ./custom.yaml 执行的所有 case 均将关闭 lec 检查并且设置超时时间为 10 min.
maat 的配置文件内容可参考 配置文件 部分.
--tag
使用 tag 去更改此次 maat 执行的 tcl 脚本.
对于任意 case 来说, maat 执行此 case 时, 会先生成一个 temp_xxxx.tcl 文件, 其是 case 本身的 tcl 文件的一个 副本, 并对这个 tcl 文件做一系列的处理, 包括但不限于处理相对路径 / 更改 cmd 参数 / 增删 cmd 等功能, 其实现就是 依托于 tag 完成, 如:
# 为 synth 命令增加 --timing_level3 参数 maat --tag timing_level3 # 清除所有的 opt 指令(netlist_opt / resynth) maat --tag non_opt更加详细的使用请参考 tag 使用详解.
--debug
指定以 debug 模式执行 maat, 一般用于调试.
maat --debug
--mock
指定当前仅输出 temp tcl 文件, 不进行实际执行.
# 此时仅在 thor 目录下生成 temp_xxx.tcl 文件 maat --mock
--repeat
指定 cases 重复执行次数, 以预防 RainaSynth 输出偶现 bug 问题.
# 指定 case 重复执行 5 次 maat --repeat 5
--commit_id
指定 golden 的 commit id 以实现历史比较功能.
# 指定与 3940b60ca78706f1e17220e48afb5345602d3763 的 golden 进行比较 maat --commit 3940b60ca78706f1e17220e48afb5345602d3763
--timeout
指定 cases 执行的超时时间, 指定后, 单个 case 执行超时则直接结束运行并给出报错. 该参数可以指定单位, 目前 支持以下四个单位:
秒(s), 当输入不带单位时, 默认为秒
分(m)
时(h)
天(d)
# 指定超时时间为 1000 秒 maat --timeout 1000 maat --timeout 1000s # 指定超时时间为 90 分钟 maat --timeout 90m # 指定超时时间为 2 小时 maat --timeout 2h
case 的编写
1. case 的目录结构
对于一个 case 来说, 其应当满足以下三个要求:
case 是一个 directory.
case 中包含 golden 目录, 其下存放用于对比的 golden 文件.
case 中包含一个 tcl 文件, 其描述了本 case 的执行流程.
ps: 对于一个 case 来说, src 不是必需的, 其 src 可以存放于 case 目录中, 也可以存放于其他位置与其他 case 共享 同一个 src 文件, 目前可以在 RegressionCases 仓库的 TestFile 目录中找到公共使用的 src
另外, 对于一个 dir 中 case 的判定是递归的, 这意味着 maat case 的存放是可以按功能模块进行划分的, 因此, 目前 maat 对应的 case 仓库 RegressionCases 中的 case 是按模块等级进行划分的, 目前已划分为 Sdc / Eco / Database 等 子模块, 每个子模块中可能又按功能的模块继续进行划分, 直到这颗目录树的叶子节点才是真正的 case.
2. 创建一个 case
创建一个 case 时，本质上是创建一个目录，且这个目录必需满足一个 case 的 目录结构。 用户在确定好本 case 的位置后，创建一个目录，目录名即为 case 名，并在 case 目录下按照 case 的 目录结构 去创建对应的 tcl 文件和 golden 文件， 注意，golden 目录是必需的，但其可以是一个空目录 。
# 创建一个名为 “test_case” 的 case，其是 Sdc 模块下的一个 case
cd regressioncases/Sdc
mkdir test_case
# 创建对应的目录结构
cd test_case
mkdir golden # 必需
mkdir src # 非必需
touch run.tcl # 必需
# case 支持多层级
# 创建一个名为 “test_case” 的 case，其是 Sdc 模块下 SdcTest 子模块的一个 case
cd regressioncases/Sdc/SdcTest
mkdir test_case
# 创建对应的目录结构
cd test_case
mkdir golden # 必需
mkdir src # 非必需
touch run.tcl # 必需
3. 用于 --compare 参数的 rule
case 的 tcl 文件不仅指定了本 case 的执行 flow，还指定了本 case 的执行 rule，其由 tcl 注释的形式给出。
1read_verilog src/gcd.v
2read_liberty /share1/platform/nangate45/NangateOpenCellLibrary_typical.lib
3synth -top gcd
4
5# @rule: verilog @result: synth.v @golden: synth_golden.v
6write_file -netlist report/synth.v
7
8# @rule: ppa
9report_area > report/area.rpt
10report_power > report/power.rpt
11report_timing > report/timing.rpt
12report_qor > report/qor.rpt
13
14exit
如上是一个 case 的 tcl 内容, 其中第 5 行的 # @rule: verilog @result: synth.v @golden: synth_golden.v 和
第 8 行的 # @rule: ppa` 即为两个 rule.
rule 是用于指定本 case 是否执行通过的标准。对于一个 regression case 来说，其执行结果是否 PASS，是由 rule 中指定的 golden 文件和 report 生成的文件按照 rule 去进行对比来决定的。不同的 rule 有不同的效果， 可在 rule 一览 中查看。rule 的指定在 tcl 文件中由固定的注释形式给出，其形式如下：
# 其必需是 tcl 文件中的注释，由 ‘#’ 开头
# @rule: {rule_name} @result: {result_name} @golden: {golden_name}
- rule
指定要使用的比对规则，对于不同的规则，其作用不一致，且某些规则可能不需要 golden 或 result。
- result
result 文件路径，作为 rule 的输入，其默认从 case 目录下的 report 目录中寻找，也可以使用相对路径将其定位到其他目录中。
- golden
golden 文件路径，作为 rule 的输入，其默认从 case 目录下的 golden 目录中寻找，也可以使用相对路径将其定位到其他目录中。
rule 一览
1. diff
# @rule: diff @result: result_file @golden: golden_name
用于 golden 文件和 result 文件做之间的文本对比，使用经典的 diff 算法并渲染至命令行。
key |
description |
|---|---|
rule |
diff |
golden |
用于做 diff 比较的 golden 文件路径 |
result |
用于做 diff 比较的 result 文件路径 |
2. report
# @rule: report @result: result_file @golden: golden_name
用于 golden 文件和 result 文件做之间的文本对比，和 diff 规则类似，使用经典的 diff 算法并渲染至命令行但
会忽略文件中的 head 信息，适用于 area / power / sdc 等多种报告，使用该 rule 后将忽略这些报告的 head 信息，
若用户有新类型的文件需要该 rule 支持，可以联系文档编写者 tanlinfeng@raina.tech。
key |
description |
|---|---|
rule |
report |
golden |
用于做 report 比较的 golden 文件路径 |
result |
用于做 report 比较的 result 文件路径 |
3. only_generated
# @rule: only_generated @result: result_file
检查 result 文件是否生成，若未生成，将给出报错提示。
key |
description |
|---|---|
rule |
only_generated |
golden |
无需使用 |
result |
指定需要检测是否存在的文件路径 |
4. lec
# @rule: lec @result: result_file @golden: golden_name
用于检测 golden 文件和 result 文件的逻辑等价性，和 tools lec 工具 使用方式类似。
key |
description |
|---|---|
rule |
lec |
golden |
用于 lec 检查的 GOLDEN 文件 |
result |
用于 lec 检查的 REVISED 文件 |
5. verilog
# @rule: diff @result: result_file @golden: golden_name
用于检测 golden 文件和 result 文件的逻辑等价性，和 lec rule 类似，但相较于 lec rule 会多上 verilog 文件
的其他功能检查。
key |
description |
|---|---|
rule |
verilog |
golden |
用于 lec 检查的 GOLDEN 文件，并进行 verilog 检查 |
result |
用于 lec 检查的 REVISED 文件，并进行 verilog 检查 |
6. ppa
# @rule: ppa
report_area > report/area.rpt
report_power > report/power.rpt
report_timing > report/timing.rpt
report_qor > report/qor.rpt
检查 case 输出的 area、power、timing、qor 报告是否变化过大，若其性能降低到原性能的 90%，则命令台将提示报错 并渲染出对应变差的数据。 注意，使用该 rule 时，要求其必需跟随四种 ppa 报告的输出。
key |
description |
|---|---|
rule |
diff |
golden |
无，但默认需要 golden 目录中有 area.rpt timing.rpt power.rpt qor.rpt 文件 |
result |
无，但默认需要 report 目录中会生成 area.rpt timing.rpt power.rpt qor.rpt 文件 |
maat 的配置文件
maat 使用 yaml 文件作为配置文件, “.maatCfg.yaml” 文件作为其默认的配置文件名, 且用户可以使用 --yaml 参数指定自定义的配置文件.
maat 每次启动时均会按照如下顺序去读取本次执行过程使用的配置(从低到高).
/usr/local/etc/.maatCfg.yaml
/etc/.maatCfg.yaml
~/.maatCfg.yaml
用户使用 --yaml 指定的路径
case 目录下的 .maatCfg.yaml 文件
使用 --config 更改的配置
maat 拥有数个不同层级的模块, 每个模块拥有各自不同的配置, 对于最顶层的配置, 可以直接写配置名即可. 如:
# 指定用户自定义配置文件路径
CONFIG_PATH : ./my_config.yaml
# 指定 case 在执行完成后清除输出文件
CLEAN_WHEN_FINISH : True
# 指定 case 执行等级为 3
LEVEL : 3
对于 maat 中的子模块配置, 则使用 mod.attr 的方式去指定配置, 可有效防止同名配置冲突的问题. 如:
# 指定 case 超时时间为 10 秒
case.TIMEOUT : 10
# 指定 case 输出文件路径, 用于单个 case
case.WORK_DIR : ~/test_dir/case
# 指定 case 输出文件路径, 用于多个 case
case.WORK_DIR_PARENT : ~/test_dir
# 指定 thor 输出目录为 log
thor.RPT_DIR : log
# 开启 rpt 解析为 json 文件的功能
thor.JSON_PARSE_EN : True
# 指定 lec rpc 请求的 IP 和 端口
lec.HOST : 192.168.15.189
lec.PORT : 12300
config 配置一览表
与 maat 的配置文件 类似, 因为 maat 拥有数个不同层级的模块, 每个模块拥有各自不同的 配置, 对于最顶层的配置, 可以直接写配置名即可, 对于 maat 中的子模块配置, 则使用 mod.attr 的方式去指定配置.
# 开启 fake run, 同时将 case 模块的 lec 检查关闭
maat --config FAKE_RUN=true --config case.ENABLE_LEC=false
1. 顶层配置
name |
default |
description |
|---|---|---|
CONFIG_FILE |
“.maatCfg.yaml” |
指定默认 config 文件名 |
CONFIG_PATH |
None |
指定用户自定义的 config 文件路径 |
REPORT_NAME |
“report” |
指定默认的输出文件路径 |
PLATFORM_DIR |
r”/share1/platforms” |
指定库文件存放的路径 |
GIT_URL |
指定远程 case 仓库的 url |
|
GIT_BRANCH |
“main” |
指定远程 case 仓库的分支 |
CMDS_PATH |
None |
指定用户的 tag 文件 |
REPO |
None |
指定远程 case 仓库本地存放的 dir 名 |
IGNORE_CASES_FIEL |
“.cases_ignore” |
指定用于忽略 case 的 block 文件 |
FAKE_RUN |
False |
指定是否启用假执行 |
CLEAN_WHEN_FINISH |
False |
指定是否在执行完成后立即清理输出防止磁盘占用过多 |
2. case 配置
name |
default |
description |
|---|---|---|
MULTI_TCL |
True |
指定是否启用多 tcl 功能 |
ENABLE_LEC |
True |
指定是否启用 lec 检查 |
REPEAT_EN |
False |
指定是否启用 repeat 功能 |
REPEAT_TIMES |
1 |
指定 repeat 次数 |
LEVEL |
1 |
指定本 case 的执行等级 |
TIMEOUT |
0 |
指定本 case 的超时时间 |
FILE_LIST |
“file_list.txt” |
指定默认的 file_list 名 |
ERROR_IFNO_FILE |
“.error_info.txt” |
指定缓存执行差异的默认文件名 |
RESULT_FILE |
“.result.json” |
指定缓存执行结果的默认文件名 |
WORK_DIR_PARENT |
None |
指定 case 执行目录的父目录, 输出将存放于此目录下的 case 同名目录 |
WORK_DIR |
None |
指定 case 执行目录, 输出将存放于此 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 文件 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 文件 |
QOR_FILE |
“qor.rpt” |
指定默认的 qor report 文件 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 文件 |
SOURCE_DIR |
“src” |
指定默认的 RTL 存放目录 |
REPORT_DIR |
“log” |
指定默认的 case 输出目录 |
HISTORY_DOLDEN_DIR |
“.history” |
指定用于 history commit 文件路径 |
NOT_A_CASE |
[“__pycache__”, “Raina_db”] |
指定不进行迭代查找 case 的目录名 |
PROCESS_BY_TAG |
True |
指定是否启用 tag 处理 |
TCL_FILE |
“run.tcl” |
指定单 tcl 模式下 case 默认的 tcl 名 |
RESULT_BACKEND |
“thor” |
指定默认的 result 工具 |
GOLDEN_BACKEND |
“dc” |
指定默认的 golden 工具 |
PLATFORM |
“nangate45” |
指定默认的 lib 名 |
PLATFORM_DIR |
“/share1/platforms” |
指定默认的 lib 存放路径 |
ENABLE_STA |
False |
指定是否启用 sta 功能 |
ENABLE_PHYSICAL |
False |
指定是否启用 physical 功能 |
3. lec 配置
name |
default |
description |
|---|---|---|
HOST |
“192.168.15.189” |
指定用于 rpc 调用的 ip |
PORT |
12300 |
指定用于 rpc 调用的 端口 |
SCRIPT |
None |
指定用户自定义的 lec 脚本 |
DEFAUTL_SCRIPT |
“lec_script.do” |
指定默认的 lec 脚本 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
4. thor 配置
name |
default |
description |
|---|---|---|
debug_en |
False |
指定是否启用 debug 默认 |
environment |
“RAINA_PATH” |
指定用于配置 RainaSynth 路径的环境变量名 |
path |
“/homecloud/public/Nightly_Raina/latest/release/bin/RainaSynth” |
指定默认的 RainaSynth 文件路径 |
prompt |
“Raina>> “ |
指定用于 RainaSynth 的输出提示符 |
BACKEND_NAME |
“thor” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FILE |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
PERFORMANCE_FILE |
“performance.rpt” |
指定默认的 performance report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
PERF_EN |
False |
指定是否使用 perf 工具生成火焰图 |
5. perf 配置
name |
default |
description |
|---|---|---|
FlameGraph_PATH |
“/share1/software/FlameGraph” |
指定 FlameGraph 工具路径 |
PERF_OUT_FILE |
“perf.perf” |
指定生成的 perf 文件名 |
PERF_DATA_FILE |
“perf.data” |
指定生成的 data 文件名 |
FlameGraph_FOLDED_FILE |
“perf.folded” |
指定生成的 folded 文件名 |
FlameGraph_SVG_FILE |
“perf.svg” |
指定生成的 svg 文件名 |
CALL_GRAPH_MODES |
[“dwarf”, “fp”, “lbr”, “no”] |
采集图模式合集 |
CALL_GRAPH_MODE |
“dwarf” |
采集图模式 |
SYSTEM_EN |
False |
全系统采样使能 |
SAMPLING_FREQUENCY |
100 |
采样频率 |
6. dc 配置
name |
default |
description |
|---|---|---|
DEBUG_EN |
False |
指定是否启用 debug 模式 |
RPT_DIR |
“log” |
指定存放输出文件的目录 |
BACKEND_NAME |
“dc” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FIEL |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
HOST |
“192.168.15.189” |
指定 rpc 调用的 ip |
PORT |
12300 |
指定 rpc 调用的 端口 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
7. genus 配置
name |
default |
description |
|---|---|---|
DEBUG_EN |
False |
指定是否启用 debug 模式 |
RPT_DIR |
“log” |
指定存放输出文件的目录 |
BACKEND_NAME |
“genus” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FIEL |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
HOST |
“192.168.15.189” |
指定 rpc 调用的 ip |
PORT |
12300 |
指定 rpc 调用的 端口 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
8. sta 配置
name |
default |
description |
|---|---|---|
TIMING_RPT |
“golden_timing.rpt” |
指定 golden 工具的 timing report 名 |
AREA_RPT |
“golden_area.rpt” |
指定 golden 工具的 area report 名 |
POWER_RPT |
“golden_power.rpt” |
指定 golden 工具的 power report 名 |
QOR_RPT |
“golden_qor.rpt” |
指定 golden 工具的 qor report 名 |
THOR_STA_TCL |
“temp_thor_sta_correlation.tcl” |
指定 thor sta 脚本路径 |
THPR_STA_TIMING_TCL |
“temp_thor_sta_timing.tcl” |
只当 thor sta 输出脚本文件名 |
DC_STA_TCL |
“temp_dc_sta_correlation.tcl” |
指定 dc sta 输出脚本文件名 |
STA_RPT |
“sta_correlation.rpt” |
指定 sta 数据存放名 |
THOR_DIFF_RPT |
“sta_thor_diff_paths.rpt” |
指定仅 thor 拥有路径存放文件名 |
GOLDEN_DIFF_RPT |
“sta_golden_diff_paths.rpt” |
指定仅 golden 拥有路径存放文件名 |
NEQ_PATH_RPT |
“sta_neq_paths.rpt” |
指定 diff 路径存放文件名 |
STA_SUMMARY_RPT |
“sta_summary.rpt” |
指定 sta 报告汇总文件名 |
ACCURACY |
2 |
指定 timing 输出精度 |
NET_PROPS |
[] |
指定必需包含的 port / net 名 |
NON_NET_PROPS |
[] |
指定不参与的 port / net 名 |
GOLDEN |
“DC” |
指定用作 golden 的工具名 |
TIMING_THREADS |
1 |
指定 timing 执行的线程数 |
VERSION |
“v200” |
指定执行的 sta 版本(v100 / v200) |
tag 使用详解
1. tag 概述
tag 是用于更改 case 执行 tcl 脚本的工具, 当用户指定 --tag tag_name 后, maat 会查找指定 tag 对应的 func, 并 使用该 func 对 tcl 脚本进行修改.
需要注意的是, 不同的 tag 可能存在冲突, 如 timing_level1 和 timing_level3, 此时timing_level1 的修改结果 将被 timing_level3 的修改结果覆盖, 最终 synth 指令输出将是 timing_level3 这个 tag 的修改结果.
# 同时使用两个 tag
maat --tag timing_level1 --tag timing_level3
# 此时 temp_xxx.tcl 中, synth 指令为
synth top --timing_level3
2. tag 一览表
使用如下指令可以快捷的查看 maat 的所有 tag:
tools tags maat
3. 用户自定义 tag
当用户需要使用自定义 tag 时, 需要使用 --config 指定 CMDS_PATH 参数导入用户的 tag 文件.
maat --tag user_tag --config CMDS_PATH=user_tags.py
nabu 使用手册
概述
nabu是⽤于Thor进⾏PPA性能测试的⼆进制⼯具,其集成了lec检查、输出数据解析、特异性tcl脚本⽣ 成等⼀系列功能，并作为case-manager后端执⾏⼯具。本⽂旨在列举nabu的简易使⽤⽅法及对应 case 的添加流程.
nabu 基础使用教程
1. 环境配置与 case 准备
nabu的启动依赖于两个对象
* 综合工具 RainaSynth
nabu 使用环境变量 RAINA_PATH 来寻找综合工具 RainaSynth.
# 使用 export 导入环境变量, 建议将其写入 bashrc 文件, 便于在 cmd 中快速启动 nabu export RAINA_PATH={my_thor_path}/bin/RainaSynth
* 将要执行的 case 或 cases 目录
nabu 的支持执行本地 cases 和远程仓库 cases.
本地执行时, 在一般情况下, nabu 在 case 所在目录指定 case 执行, 也可以通过 --dir 指定 本地 cases 存放的目录.
远程执行时, 使用 --remote 则默认拉取远程 cases 仓库执行 case, 执行完成后汇总输出结果, 若 需要保存 case 执行结果, 则可以加上 --record, 此时将在 nabu 执行目录下生成一个名为 Regression_temp_xxxx 带时间戳 的目录(xxxx即为时间戳).
2. nabu 执行 case 示例
默认以当前路径为 cases 路径, 此时会执行该 dir 下所有 case, 若无 case, 则检查当前目录是否在一个 case 内部.
# 假设存在一个目录 repo, 其下有数个 case: case1, case2, case3 ...
mkdir ~/repo
# 进入 case 所在的目录 repo
cd ~/repo
# 默认执行当前目录下所有 case, 此时将会执行 repo 下所有 case 并汇总输出
nabu
# 仅执行 case1, case3, case5 这三个 case
nabu case1 case3 case5
# 若当前用户位于某个 case 目录中
cd ~/repo/case1
# 尝试执行所有 case, 未发现 case, 检查自身是否为 case
nabu
# 未发现其他 case, 检测出 pwd 为 case, 执行当前 case (case1)
# 可指定要执行的 case
cd ~/repo
# 支持通配符, 执行所有以 test 开头的所有 case
nabu test*
# 支持排除指定 case, 滤除 case3 和 以 test 开头的所有 case
nabu !case3 !test* # sh 脚本中
nabu \!case3 \!test* # 命令行中, ! 需要进行转义
# 支持 file_list 文件, 如 cases.txt 中写有三个 case, case_name 可以使用换行或者空格分离
nabu cases.txt
使用 --dir 指定 cases 目录, 此时将在指定的目录下寻找 case 并执行, 其他参数与 默认启动路径 一致.
# 假设存在一个目录 repo, 其下有数个 case: case1, case2, case3 ...
mkdir ~/repo
# 进入其他目录中, 使用 --dir 执行指定路径的 case
cd ~/another_dir
# 尝试使用指定的 dir 执行 repo 下的所有 case 并汇总输出
nabu --dir ~/repo
# 其他用法如通配符, 指定 case 与上述示例一致
nabu --dir ~/repo case1 case3 case5 test*
nabu 参数一览
nabu 有许多额外的参数可以供配置, 其 --help 输出如下:
[root@dev]$ nabu --help
Usage: nabu [OPTIONS] [CASES]...
Options:
--flow TEXT Specify the process to be performed.
--dir TEXT Specifies the directory where the given cases to find
--repeat INTEGER Specify the number of repeated executions of the case,
the default is 1
--level INTEGER Specify the case level(range[1, 5]) to be executed, the
default is 1
--timeout TEXT Specifies the timeout of the case. Support unit s
(default)/m/h/d. The default is 0s.
--config TEXT Configure backend custom parameters
--log TEXT Specified logger level: TRACE/DEBUG/INFO/WARNING/ERROR
--yaml TEXT Specified case config file
--branch TEXT Specify the pulled branch when using a Git pull case
--compare Enable differential text echo in the command console
--record Keep test case execution results
--remote Keep test case execution results
-c, --continue Enable to continue running with the last execution result
--mock Only generated tcl but not run
--debug Enable debug mode for nabu
--tag TEXT Specify the tag for test case running
--cpu_num INTEGER Specify the cpu number for test case running
--version Show nabu version
--help Show this message and exit.
这些参数均可以组合使用, 一些常用的参数如下:
--flow
指定 RainaSynth 执行的流程, 目前有 thor / resynth / lec, 默认执行 thor 流程.
nabu --flow [flow_name]
--dir
指定 cases 存放目录, 默认为当前目录.
nabu --dir [dir_path]
--remote
指定执行远程仓库的 case, 此时 --dir 参数即使输入也会被忽略, 常与 --record 参数使用.
nabu --remote
--record
当执行远程 case 仓库时, 执行完成后 case 数据将被保存到带有时间戳的 “Regression_temp_xxxx” 目录下, 仅在 --remote 参数存在时生效.
nabu --remote --record用户也可以自行指定保存 case 的 dir 名字
# 将 case 保存到 my_cases 目录下 nabu --remote --record --config REPO=my_cases
--branch
搭配 --remote 参数使用, 执行远程 case 仓库时, 可执行要执行的分支.
# 执行 dev 分支的 case nabu --remote --branch dev
--compare
指定执行 case 时是否输出 error case 的详细信息.
nabu --compare效果如图:
--cpu_num
指定 nabu 多进程数量, 默认为当前机器最大核心数的一半以防止过多的占用资源.
nabu --cpu_num 8
--version
输出当前 nabu 版本.
nabu --version
--continue/-c
在执行 case 过程中, 用户可使用 ctrl+c 停止执行 case, 此时可使用 --continue 参数继续上次执行任务
# 执行一些 case nabu some_cases # 键盘按下 ctrl+c, nabu停止执行 case 并输出当前 case 执行结果汇总 # 继续上次任务执行, 此时需要保证 --dir 输入一致 nabu some_cases # 也可用于中途修改 case 参数, 如接下来的 case 均停止 lec 检查 nabu some_cases --config case.ENABLE_LEC=false
--config
更改 nabu 功能模块参数的指令, 其使用较为多变复杂, 并可搭配 配置文件 使用, 进阶使用请参考 --config 配置表.
--config 是一个可重复使用的参数, 用于更改多个配置, 输入格式为.
nabu --config [mod.attr=value] # eg: 打开 lec 检查并指定 lec rpc 调用的端口为 12345 nabu --config case.ENABLE_LEC=on --config lec.PORT=12345
--yaml
指定本次 case 执行使用的配置文件, 例如, 用户编辑了一份 custom.yaml 文件, 其内容如下:
case.ENABLE_LEC: false case.timeout: 10m此时 nabu –yaml ./custom.yaml 执行的所有 case 均将关闭 lec 检查并且设置超时时间为 10 min.
nabu 的配置文件内容可参考 配置文件 部分.
--tag
使用 tag 去更改此次 nabu 执行的 tcl 脚本.
对于任意 case 来说, nabu 执行此 case 时, 会先生成一个 temp_xxxx.tcl 文件, 其是 case 本身的 tcl 文件的一个 副本, 并对这个 tcl 文件做一系列的处理, 包括但不限于处理相对路径 / 更改 cmd 参数 / 增删 cmd 等功能, 其实现就是 依托于 tag 完成, 如:
# 为 synth 命令增加 --timing_level3 参数 nabu --tag timing_level3 # 清除所有的 opt 指令(netlist_opt / resynth) nabu --tag non_opt更加详细的使用请参考 tag 使用详解.
--debug
指定以 debug 模式执行 nabu, 一般用于调试.
nabu --debug
--mock
指定当前仅输出 temp tcl 文件, 不进行实际执行.
# 此时仅在 thor 目录下生成 temp_xxx.tcl 文件 nabu --mock
--repeat
指定 cases 重复执行次数, 以预防 RainaSynth 输出偶现 bug 问题.
# 指定 case 重复执行 5 次 nabu --repeat 5
--level
指定 cases 执行等级, 其取值为 1-5, level 值 1 则执行轻量级 case, level 为 2-3 时则执行中量级 case, level 为 4-5 时则执行重量级 case. 一般来说 level 值越大耗时越高，
# 指定执行所有等级不超过 3 的 case nabu --level 1-3 # 指定执行所有等级不超过 3 的 case，等同于 nabu --level 1-3 nabu --level 3 # 指定执行等级为 3 的 case nabu --level 3-3 # 指定执行等级为 2-3 的 case nabu --level 2-3
--timeout
指定 cases 执行的超时时间, 指定后, 单个 case 执行超时则直接结束运行并给出报错. 该参数可以指定单位, 目前 支持以下四个单位:
秒(s), 当输入不带单位时, 默认为秒
分(m)
时(h)
天(d)
# 指定超时时间为 1000 秒 nabu --timeout 1000 nabu --timeout 1000s # 指定超时时间为 90 分钟 nabu --timeout 90m # 指定超时时间为 2 小时 nabu --timeout 2h
--log
指定 log 日志输出等级, 默认为 INFO 级别, 可选 TRACE/DEBUG/INFO/WARNING/ERROR 以提供不同的日志输出级别.
# 指定以 TRACE 级别的日志输出, 此时将详细追踪 nabu 执行的每个操作 nabu --log TRACE # 指定以 ERROR 级别的日志输出, 此时将忽略 ERROR 以下的输出, INFO / WARNING 等均会被忽略 nabu --log ERROR
NabuCase 的目录结构
对于一个 NabuCase 来说, 其判定应当满足以下四个要求:
NabuCase 是一个 directory.
NabuCase 中包含 golden 目录, 其下存放用于对比的 golden 文件.
NabuCase 中包含一个 tcl 文件, 其描述了本 case 的执行流程.
NabuCase 中包含一个 src 目录, 其下存放了本 case 使用的 RTL 文件(支持 file_list).
nabu 工具使用的 case 仓库是 PPA_testcases 仓库. 由于 NabuCase 的判定是非递归的, 这意味着 nabu case 的存放 是展平的, 对于任意指定的 dir, nabu 仅仅会查找当前目录的所有 nabu case, 若未找到, 则检查自身是否是一个 nabu case.
nabu 的配置文件
nabu 使用 yaml 文件作为配置文件, “.maatCfg.yaml” 文件作为其默认的配置文件名, 且用户可以使用 --yaml 参数指定自定义的配置文件.
nabu 每次启动时均会按照如下顺序去读取本次执行过程使用的配置(从低到高).
/usr/local/etc/.maatCfg.yaml
/etc/.maatCfg.yaml
~/.maatCfg.yaml
用户使用 --yaml 指定的路径
case 目录下的 .maatCfg.yaml 文件
使用 --config 更改的配置
nabu 拥有数个不同层级的模块, 每个模块拥有各自不同的配置, 对于最顶层的配置, 可以直接写配置名即可. 如:
# 指定用户自定义配置文件路径
CONFIG_PATH : ./my_config.yaml
# 指定 case 在执行完成后清除输出文件
CLEAN_WHEN_FINISH : True
# 指定 case 执行等级为 3
LEVEL : 3
对于 nabu 中的子模块配置, 则使用 mod.attr 的方式去指定配置, 可有效防止同名配置冲突的问题. 如:
# 指定 case 超时时间为 10 秒
case.TIMEOUT : 10
# 指定 case 输出文件路径, 用于单个 case
case.WORK_DIR : ~/test_dir/case
# 指定 case 输出文件路径, 用于多个 case
case.WORK_DIR_PARENT : ~/test_dir
# 指定 thor 输出目录为 log
thor.RPT_DIR : log
# 开启 rpt 解析为 json 文件的功能
thor.JSON_PARSE_EN : True
# 指定 lec rpc 请求的 IP 和 端口
lec.HOST : 192.168.15.189
lec.PORT : 12300
config 配置一览表
与 nabu 的配置文件 类似, 因为 nabu 拥有数个不同层级的模块, 每个模块拥有各自不同的 配置, 对于最顶层的配置, 可以直接写配置名即可, 对于 nabu 中的子模块配置, 则使用 mod.attr 的方式去指定配置.
# 开启 fake run, 同时将 case 模块的 lec 检查关闭
nabu --config FAKE_RUN=true --config case.ENABLE_LEC=false
1. 顶层配置
name |
default |
description |
|---|---|---|
CONFIG_FILE |
“.maatCfg.yaml” |
指定默认 config 文件名 |
CONFIG_PATH |
None |
指定用户自定义的 config 文件路径 |
REPORT_NAME |
“report” |
指定默认的输出文件路径 |
PLATFORM_DIR |
r”/share1/platforms” |
指定库文件存放的路径 |
GIT_URL |
指定远程 case 仓库的 url |
|
GIT_BRANCH |
“main” |
指定远程 case 仓库的分支 |
CMDS_PATH |
None |
指定用户的 tag 文件 |
REPO |
None |
指定远程 case 仓库本地存放的 dir 名 |
IGNORE_CASES_FIEL |
“.cases_ignore” |
指定用于忽略 case 的 block 文件 |
FAKE_RUN |
False |
指定是否启用假执行 |
CLEAN_WHEN_FINISH |
False |
指定是否在执行完成后立即清理输出防止磁盘占用过多 |
2. case 配置
name |
default |
description |
|---|---|---|
MULTI_TCL |
True |
指定是否启用多 tcl 功能 |
ENABLE_LEC |
True |
指定是否启用 lec 检查 |
REPEAT_EN |
False |
指定是否启用 repeat 功能 |
REPEAT_TIMES |
1 |
指定 repeat 次数 |
LEVEL |
1 |
指定本 case 的执行等级 |
TIMEOUT |
0 |
指定本 case 的超时时间 |
FILE_LIST |
“file_list.txt” |
指定默认的 file_list 名 |
ERROR_IFNO_FILE |
“.error_info.txt” |
指定缓存执行差异的默认文件名 |
RESULT_FILE |
“.result.json” |
指定缓存执行结果的默认文件名 |
WORK_DIR_PARENT |
None |
指定 case 执行目录的父目录, 输出将存放于此目录下的 case 同名目录 |
WORK_DIR |
None |
指定 case 执行目录, 输出将存放于此 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 文件 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 文件 |
QOR_FILE |
“qor.rpt” |
指定默认的 qor report 文件 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 文件 |
SOURCE_DIR |
“src” |
指定默认的 RTL 存放目录 |
REPORT_DIR |
“log” |
指定默认的 case 输出目录 |
HISTORY_DOLDEN_DIR |
“.history” |
指定用于 history commit 文件路径 |
NOT_A_CASE |
[“__pycache__”, “Raina_db”] |
指定不进行迭代查找 case 的目录名 |
PROCESS_BY_TAG |
True |
指定是否启用 tag 处理 |
TCL_FILE |
“run.tcl” |
指定单 tcl 模式下 case 默认的 tcl 名 |
RESULT_BACKEND |
“thor” |
指定默认的 result 工具 |
GOLDEN_BACKEND |
“dc” |
指定默认的 golden 工具 |
PLATFORM |
“nangate45” |
指定默认的 lib 名 |
PLATFORM_DIR |
“/share1/platforms” |
指定默认的 lib 存放路径 |
ENABLE_STA |
False |
指定是否启用 sta 功能 |
ENABLE_PHYSICAL |
False |
指定是否启用 physical 功能 |
3. lec 配置
name |
default |
description |
|---|---|---|
HOST |
“192.168.15.189” |
指定用于 rpc 调用的 ip |
PORT |
12300 |
指定用于 rpc 调用的 端口 |
SCRIPT |
None |
指定用户自定义的 lec 脚本 |
DEFAUTL_SCRIPT |
“lec_script.do” |
指定默认的 lec 脚本 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
4. thor 配置
name |
default |
description |
|---|---|---|
debug_en |
False |
指定是否启用 debug 默认 |
environment |
“RAINA_PATH” |
指定用于配置 RainaSynth 路径的环境变量名 |
path |
“/homecloud/public/Nightly_Raina/latest/release/bin/RainaSynth” |
指定默认的 RainaSynth 文件路径 |
prompt |
“Raina>> “ |
指定用于 RainaSynth 的输出提示符 |
BACKEND_NAME |
“thor” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FILE |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
PERFORMANCE_FILE |
“performance.rpt” |
指定默认的 performance report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
PERF_EN |
False |
指定是否使用 perf 工具生成火焰图 |
5. perf 配置
name |
default |
description |
|---|---|---|
FlameGraph_PATH |
“/share1/software/FlameGraph” |
指定 FlameGraph 工具路径 |
PERF_OUT_FILE |
“perf.perf” |
指定生成的 perf 文件名 |
PERF_DATA_FILE |
“perf.data” |
指定生成的 data 文件名 |
FlameGraph_FOLDED_FILE |
“perf.folded” |
指定生成的 folded 文件名 |
FlameGraph_SVG_FILE |
“perf.svg” |
指定生成的 svg 文件名 |
CALL_GRAPH_MODES |
[“dwarf”, “fp”, “lbr”, “no”] |
采集图模式合集 |
CALL_GRAPH_MODE |
“dwarf” |
采集图模式 |
SYSTEM_EN |
False |
全系统采样使能 |
SAMPLING_FREQUENCY |
100 |
采样频率 |
6. dc 配置
name |
default |
description |
|---|---|---|
DEBUG_EN |
False |
指定是否启用 debug 模式 |
RPT_DIR |
“log” |
指定存放输出文件的目录 |
BACKEND_NAME |
“dc” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FIEL |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
HOST |
“192.168.15.189” |
指定 rpc 调用的 ip |
PORT |
12300 |
指定 rpc 调用的 端口 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
7. genus 配置
name |
default |
description |
|---|---|---|
DEBUG_EN |
False |
指定是否启用 debug 模式 |
RPT_DIR |
“log” |
指定存放输出文件的目录 |
BACKEND_NAME |
“genus” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FIEL |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
HOST |
“192.168.15.189” |
指定 rpc 调用的 ip |
PORT |
12300 |
指定 rpc 调用的 端口 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
8. sta 配置
name |
default |
description |
|---|---|---|
TIMING_RPT |
“golden_timing.rpt” |
指定 golden 工具的 timing report 名 |
AREA_RPT |
“golden_area.rpt” |
指定 golden 工具的 area report 名 |
POWER_RPT |
“golden_power.rpt” |
指定 golden 工具的 power report 名 |
QOR_RPT |
“golden_qor.rpt” |
指定 golden 工具的 qor report 名 |
THOR_STA_TCL |
“temp_thor_sta_correlation.tcl” |
指定 thor sta 脚本路径 |
THPR_STA_TIMING_TCL |
“temp_thor_sta_timing.tcl” |
只当 thor sta 输出脚本文件名 |
DC_STA_TCL |
“temp_dc_sta_correlation.tcl” |
指定 dc sta 输出脚本文件名 |
STA_RPT |
“sta_correlation.rpt” |
指定 sta 数据存放名 |
THOR_DIFF_RPT |
“sta_thor_diff_paths.rpt” |
指定仅 thor 拥有路径存放文件名 |
GOLDEN_DIFF_RPT |
“sta_golden_diff_paths.rpt” |
指定仅 golden 拥有路径存放文件名 |
NEQ_PATH_RPT |
“sta_neq_paths.rpt” |
指定 diff 路径存放文件名 |
STA_SUMMARY_RPT |
“sta_summary.rpt” |
指定 sta 报告汇总文件名 |
ACCURACY |
2 |
指定 timing 输出精度 |
NET_PROPS |
[] |
指定必需包含的 port / net 名 |
NON_NET_PROPS |
[] |
指定不参与的 port / net 名 |
GOLDEN |
“DC” |
指定用作 golden 的工具名 |
TIMING_THREADS |
1 |
指定 timing 执行的线程数 |
VERSION |
“v200” |
指定执行的 sta 版本(v100 / v200) |
tag 使用详解
1. tag 概述
tag 是用于更改 case 执行 tcl 脚本的工具, 当用户指定 --tag tag_name 后, nabu 会查找指定 tag 对应的 func, 并 使用该 func 对 tcl 脚本进行修改.
需要注意的是, 不同的 tag 可能存在冲突, 如 timing_level1 和 timing_level3, 此时timing_level1 的修改结果 将被 timing_level3 的修改结果覆盖, 最终 synth 指令输出将是 timing_level3 这个 tag 的修改结果.
# 同时使用两个 tag
nabu --tag timing_level1 --tag timing_level3
# 此时 temp_xxx.tcl 中, synth 指令为
synth top --timing_level3
2. tag 一览表
使用如下指令可以快捷的查看 nabu 的所有 tag:
tools tags nabu
3. 用户自定义 tag
当用户需要使用自定义 tag 时, 需要使用 --config 指定 CMDS_PATH 参数导入用户的 tag 文件.
nabu --tag user_tag --config CMDS_PATH=user_tags.py
zeus 使用手册
概述
zeus 是⽤于Thor进⾏回归测试的⼆进制⼯具, 其集成了指定规则对比、lec检查、输出数据解析、特异性tcl脚本⽣ 成等⼀系列功能, 其本质上和 maat 功能相同, 但其控制权限更大, 不推荐普通用户使用, 目前仅提供给 pipeline 使用.
本⽂旨在列举 zeus 的简易使⽤⽅法及对应 case 的添加流程.
zeus 基础使用教程
1. 环境配置与 case 准备
zeus 的启动依赖于两个对象
* 综合工具 RainaSynth
zeus 使用环境变量 RAINA_PATH 来寻找综合工具 RainaSynth.
# 使用 export 导入环境变量, 建议将其写入 bashrc 文件, 便于在 cmd 中快速启动 zeus export RAINA_PATH={my_thor_path}/bin/RainaSynth
* 将要执行的 case 或 cases 目录
zeus 的支持执行本地 cases 和远程仓库 cases.
本地执行时, 在一般情况下, zeus 在 case 所在目录指定 case 执行, 也可以通过 --dir 指定 本地 cases 存放的目录.
远程执行时, 使用 --remote 则默认拉取远程 cases 仓库执行 case, 执行完成后汇总输出结果, 若 需要保存 case 执行结果, 则可以加上 --record, 此时将在 zeus 执行目录下生成一个名为 Regression_temp_xxxx 带时间戳 的目录(xxxx即为时间戳).
2. zeus 执行 case 示例
默认以当前路径为 cases 路径, 此时会递归地执行该 dir 下所有 case, 若无 case, 则检查当前目录是否在一个 case 内部.
对于 zeus 所使用的 case 仓库来说, 其按 Thor 功能划分为了 Sdc / Eco / Power / Sta 等数个功能模块.
# 假设存在一个目录 repo, 其下有数个 case: case1, case2, case3 ...
mkdir ~/repo
# 进入 case 所在的目录 repo
cd ~/repo
# 默认执行当前目录下所有 case, 此时将会执行 repo 下所有 case 并汇总输出
zeus
# 仅执行 Sdc/../case1, Eco/../case3, Power/../case5 这三个 case, /../ 表示中间的数个子模块
zeus Sdc/../case1 Eco/../case3 Power/../case5
# 仅执行 Sdc 这个模块下所有的 case
zeus Sdc
# 仅执行 Sdc/mod1 这个子模块下所有的 case
zeus Sdc/mod1
# 若当前用户位于某个 case 目录中
cd ~/repo/case1
# 尝试执行所有 case, 未发现 case, 检查自身是否为 case
zeus
# 未发现其他 case, 检测出 pwd 为 case, 执行当前 case (case1)
# 可指定要执行的 case
cd ~/repo
# 支持通配符, 执行所有以 test 开头的所有 case
zeus test*
# 支持排除指定 case, 滤除 case3 和 以 test 开头的所有 case
zeus !case3 !test* # sh 脚本中
zeus \!case3 \!test* # 命令行中, ! 需要进行转义
# 支持 file_list 文件, 如 cases.txt 中写有三个 case,
zeus cases.txt
使用 --dir 指定 cases 目录, 此时将在指定的目录下寻找 case 并执行, 其他参数与 默认启动路径 一致.
# 假设存在一个目录 repo, 其下有数个 case: case1, case2, case3 ...
mkdir ~/repo
# 进入其他目录中, 使用 --dir 执行指定路径的 case
cd ~/another_dir
# 尝试使用指定的 dir 执行 repo 下的所有 case 并汇总输出
zeus --dir ~/repo
# 其他用法如通配符, 指定 case 与上述示例一致
zeus --dir ~/repo case1 case3 case5 test*
zeus 参数一览
zeus 有许多额外的参数可以供配置, 其 --help 输出如下:
[root@dev]$ zeus --help
Usage: zeus [OPTIONS] [CASES]...
Options:
--dir TEXT Specifies the directory where the given cases to find
--repeat INTEGER Specify the number of repeated executions of the case,
the default is 1
--timeout TEXT Specifies the timeout of the case. Support unit s
(default)/m/h/d. The default is 0s.
--config TEXT Configure backend custom parameters
--log TEXT Specified logger level: TRACE/DEBUG/INFO/WARNING/ERROR
--branch TEXT Specify the pulled branch when using a Git pull case
--compare Enable differential text echo in the command console
--record Keep test case execution results
--remote Keep test case execution results
-c, --continue Enable to continue running with the last execution result
--debug Enable debug mode for zeus
--commit_id TEXT Specify the commit id for test case running
--tag TEXT Specify the tag for test case running
--cpu_num INTEGER Specify the cpu number for test case running
--version Show zeus version
--help Show this message and exit.
这些参数均可以组合使用, 一些常用的参数如下:
--dir
指定 cases 存放目录, 默认为当前目录.
zeus --dir [dir_path]
--remote
指定执行远程仓库的 case, 此时 --dir 参数即使输入也会被忽略, 常与 --record 参数使用.
zeus --remote
--record
当执行远程 case 仓库时, 执行完成后 case 数据将被保存到带有时间戳的 “Regression_temp_xxxx” 目录下, 仅在 --remote 参数存在时生效.
zeus --remote --record用户也可以自行指定保存 case 的 dir 名字
# 将 case 保存到 my_cases 目录下 zeus --remote --record --config REPO=my_cases
--branch
搭配 --remote 参数使用, 执行远程 case 仓库时, 可执行要执行的分支.
# 执行 dev 分支的 case zeus --remote --branch dev
--compare
指定执行 case 时是否输出 error case 的详细信息.
zeus --compare效果如图:
--cpu_num
指定 zeus 多进程数量, 默认为当前机器最大核心数的一半以防止过多的占用资源.
zeus --cpu_num 8
--version
输出当前 zeus 版本.
zeus --version
--continue/-c
在执行 case 过程中, 用户可使用 ctrl+c 停止执行 case, 此时可使用 --continue 参数继续上次执行任务
# 执行一些 case zeus some_cases # 键盘按下 ctrl+c, zeus停止执行 case 并输出当前 case 执行结果汇总 # 继续上次任务执行, 此时需要保证 --dir 输入一致 zeus some_cases # 也可用于中途修改 case 参数, 如接下来的 case 均停止 lec 检查 zeus some_cases --config case.ENABLE_LEC=false
--config
更改 zeus 功能模块参数的指令, 其使用较为多变复杂, 并可搭配 配置文件 使用, 进阶使用请参考 –config 配置表.
--config 是一个可重复使用的参数, 用于更改多个配置, 输入格式为.
zeus --config [mod.attr=value] # eg: 打开 lec 检查并指定 lec rpc 调用的端口为 12345 zeus --config case.ENABLE_LEC=on --config lec.PORT=12345
--yaml
指定本次 case 执行使用的配置文件, 例如, 用户编辑了一份 custom.yaml 文件, 其内容如下:
case.ENABLE_LEC: false case.timeout: 10m此时 zeus –yaml ./custom.yaml 执行的所有 case 均将关闭 lec 检查并且设置超时时间为 10 min.
zeus 的配置文件内容可参考 配置文件 部分.
--tag
使用 tag 去更改此次 zeus 执行的 tcl 脚本.
对于任意 case 来说, zeus 执行此 case 时, 会先生成一个 temp_xxxx.tcl 文件, 其是 case 本身的 tcl 文件的一个 副本, 并对这个 tcl 文件做一系列的处理, 包括但不限于处理相对路径 / 更改 cmd 参数 / 增删 cmd 等功能, 其实现就是 依托于 tag 完成, 如:
# 为 synth 命令增加 --timing_level3 参数 zeus --tag timing_level3 # 清除所有的 opt 指令(netlist_opt / resynth) zeus --tag non_opt更加详细的使用请参考 tag 使用详解.
--debug
指定以 debug 模式执行 zeus, 一般用于调试.
zeus --debug
--mock
指定当前仅输出 temp tcl 文件, 不进行实际执行.
# 此时仅在 thor 目录下生成 temp_xxx.tcl 文件 zeus --mock
--repeat
指定 cases 重复执行次数, 以预防 RainaSynth 输出偶现 bug 问题.
# 指定 case 重复执行 5 次 zeus --repeat 5
--commit_id
指定 golden 的 commit id 以实现历史比较功能.
# 指定与 3940b60ca78706f1e17220e48afb5345602d3763 的 golden 进行比较 zeus --commit 3940b60ca78706f1e17220e48afb5345602d3763
--timeout
指定 cases 执行的超时时间, 指定后, 单个 case 执行超时则直接结束运行并给出报错. 该参数可以指定单位, 目前 支持以下四个单位:
秒(s), 当输入不带单位时, 默认为秒
分(m)
时(h)
天(d)
# 指定超时时间为 1000 秒 zeus --timeout 1000 zeus --timeout 1000s # 指定超时时间为 90 分钟 zeus --timeout 90m # 指定超时时间为 2 小时 zeus --timeout 2h
ZeusCase 的目录结构
zeus 本质上是更高权限的 maat, 因此, 一个 ZeusCase 本质上是一个 MaatCase, 其判定应当满足以下三个要求:
ZeusCase 是一个 directory.
ZeusCase 中包含 golden 目录, 其下存放用于对比的 golden 文件.
ZeusCase 中包含一个 tcl 文件, 其描述了本 case 的执行流程.
ps: 对于一个 ZeusCase 来说, src 不是必需的, 其 src 可以存放于 case 目录中, 也可以存放于其他位置与其他 case 共享 同一个 src 文件, 目前可以在 RegressionCases 仓库的 TestFile 目录中找到公共使用的 src
另外, 对于一个 dir 中 ZeusCase 的判定是递归的, 这意味着 maat case 的存放是可以按功能模块进行划分的, 因此, 目前 maat 对应的 case 仓库 RegressionCases 中的 case 是按模块等级进行划分的, 目前已划分为 Sdc / Eco / Database 等 子模块, 每个子模块中可能又按功能的模块继续进行划分, 直到这颗目录树的叶子节点才是真正的 case.
zeus 的配置文件
zeus 使用 yaml 文件作为配置文件, “.zeusCfg.yaml” 文件作为其默认的配置文件名, 且用户可以使用 –yaml 参数指定自定义的配置文件.
zeus 每次启动时均会按照如下顺序去读取本次执行过程使用的配置(从低到高).
/usr/local/etc/.zeusCfg.yaml
/etc/.zeusCfg.yaml
~/.zeusCfg.yaml
用户使用 --yaml 指定的路径
case 目录下的 .zeusCfg.yaml 文件
使用 --config 更改的配置
zeus 拥有数个不同层级的模块, 每个模块拥有各自不同的配置, 对于最顶层的配置, 可以直接写配置名即可. 如:
# 指定用户自定义配置文件路径
CONFIG_PATH : ./my_config.yaml
# 指定 case 在执行完成后清除输出文件
CLEAN_WHEN_FINISH : True
# 指定 case 执行等级为 3
LEVEL : 3
对于 zeus 中的子模块配置, 则使用 mod.attr 的方式去指定配置, 可有效防止同名配置冲突的问题. 如:
# 指定 case 超时时间为 10 秒
case.TIMEOUT : 10
# 指定 case 输出文件路径, 用于单个 case
case.WORK_DIR : ~/test_dir/case
# 指定 case 输出文件路径, 用于多个 case
case.WORK_DIR_PARENT : ~/test_dir
# 指定 thor 输出目录为 log
thor.RPT_DIR : log
# 开启 rpt 解析为 json 文件的功能
thor.JSON_PARSE_EN : True
# 指定 lec rpc 请求的 IP 和 端口
lec.HOST : 192.168.15.189
lec.PORT : 12300
config 配置一览表
与 zeus 的配置文件 类似, 因为 zeus 拥有数个不同层级的模块, 每个模块拥有各自不同的 配置, 对于最顶层的配置, 可以直接写配置名即可, 对于 zeus 中的子模块配置, 则使用 mod.attr 的方式去指定配置.
# 开启 fake run, 同时将 case 模块的 lec 检查关闭
zeus --config FAKE_RUN=true --config case.ENABLE_LEC=false
1. 顶层配置
name |
default |
description |
|---|---|---|
CONFIG_FILE |
“.maatCfg.yaml” |
指定默认 config 文件名 |
CONFIG_PATH |
None |
指定用户自定义的 config 文件路径 |
REPORT_NAME |
“report” |
指定默认的输出文件路径 |
PLATFORM_DIR |
r”/share1/platforms” |
指定库文件存放的路径 |
GIT_URL |
指定远程 case 仓库的 url |
|
GIT_BRANCH |
“main” |
指定远程 case 仓库的分支 |
CMDS_PATH |
None |
指定用户的 tag 文件 |
REPO |
None |
指定远程 case 仓库本地存放的 dir 名 |
IGNORE_CASES_FIEL |
“.cases_ignore” |
指定用于忽略 case 的 block 文件 |
FAKE_RUN |
False |
指定是否启用假执行 |
CLEAN_WHEN_FINISH |
False |
指定是否在执行完成后立即清理输出防止磁盘占用过多 |
2. case 配置
name |
default |
description |
|---|---|---|
MULTI_TCL |
True |
指定是否启用多 tcl 功能 |
ENABLE_LEC |
True |
指定是否启用 lec 检查 |
REPEAT_EN |
False |
指定是否启用 repeat 功能 |
REPEAT_TIMES |
1 |
指定 repeat 次数 |
LEVEL |
1 |
指定本 case 的执行等级 |
TIMEOUT |
0 |
指定本 case 的超时时间 |
FILE_LIST |
“file_list.txt” |
指定默认的 file_list 名 |
ERROR_IFNO_FILE |
“.error_info.txt” |
指定缓存执行差异的默认文件名 |
RESULT_FILE |
“.result.json” |
指定缓存执行结果的默认文件名 |
WORK_DIR_PARENT |
None |
指定 case 执行目录的父目录, 输出将存放于此目录下的 case 同名目录 |
WORK_DIR |
None |
指定 case 执行目录, 输出将存放于此 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 文件 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 文件 |
QOR_FILE |
“qor.rpt” |
指定默认的 qor report 文件 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 文件 |
SOURCE_DIR |
“src” |
指定默认的 RTL 存放目录 |
REPORT_DIR |
“log” |
指定默认的 case 输出目录 |
HISTORY_DOLDEN_DIR |
“.history” |
指定用于 history commit 文件路径 |
NOT_A_CASE |
[“__pycache__”, “Raina_db”] |
指定不进行迭代查找 case 的目录名 |
PROCESS_BY_TAG |
True |
指定是否启用 tag 处理 |
TCL_FILE |
“run.tcl” |
指定单 tcl 模式下 case 默认的 tcl 名 |
RESULT_BACKEND |
“thor” |
指定默认的 result 工具 |
GOLDEN_BACKEND |
“dc” |
指定默认的 golden 工具 |
PLATFORM |
“nangate45” |
指定默认的 lib 名 |
PLATFORM_DIR |
“/share1/platforms” |
指定默认的 lib 存放路径 |
ENABLE_STA |
False |
指定是否启用 sta 功能 |
ENABLE_PHYSICAL |
False |
指定是否启用 physical 功能 |
3. lec 配置
name |
default |
description |
|---|---|---|
HOST |
“192.168.15.189” |
指定用于 rpc 调用的 ip |
PORT |
12300 |
指定用于 rpc 调用的 端口 |
SCRIPT |
None |
指定用户自定义的 lec 脚本 |
DEFAUTL_SCRIPT |
“lec_script.do” |
指定默认的 lec 脚本 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
4. thor 配置
name |
default |
description |
|---|---|---|
debug_en |
False |
指定是否启用 debug 默认 |
environment |
“RAINA_PATH” |
指定用于配置 RainaSynth 路径的环境变量名 |
path |
“/homecloud/public/Nightly_Raina/latest/release/bin/RainaSynth” |
指定默认的 RainaSynth 文件路径 |
prompt |
“Raina>> “ |
指定用于 RainaSynth 的输出提示符 |
BACKEND_NAME |
“thor” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FILE |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
PERFORMANCE_FILE |
“performance.rpt” |
指定默认的 performance report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
PERF_EN |
False |
指定是否使用 perf 工具生成火焰图 |
5. perf 配置
name |
default |
description |
|---|---|---|
FlameGraph_PATH |
“/share1/software/FlameGraph” |
指定 FlameGraph 工具路径 |
PERF_OUT_FILE |
“perf.perf” |
指定生成的 perf 文件名 |
PERF_DATA_FILE |
“perf.data” |
指定生成的 data 文件名 |
FlameGraph_FOLDED_FILE |
“perf.folded” |
指定生成的 folded 文件名 |
FlameGraph_SVG_FILE |
“perf.svg” |
指定生成的 svg 文件名 |
CALL_GRAPH_MODES |
[“dwarf”, “fp”, “lbr”, “no”] |
采集图模式合集 |
CALL_GRAPH_MODE |
“dwarf” |
采集图模式 |
SYSTEM_EN |
False |
全系统采样使能 |
SAMPLING_FREQUENCY |
100 |
采样频率 |
6. dc 配置
name |
default |
description |
|---|---|---|
DEBUG_EN |
False |
指定是否启用 debug 模式 |
RPT_DIR |
“log” |
指定存放输出文件的目录 |
BACKEND_NAME |
“dc” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FIEL |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
HOST |
“192.168.15.189” |
指定 rpc 调用的 ip |
PORT |
12300 |
指定 rpc 调用的 端口 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
7. genus 配置
name |
default |
description |
|---|---|---|
DEBUG_EN |
False |
指定是否启用 debug 模式 |
RPT_DIR |
“log” |
指定存放输出文件的目录 |
BACKEND_NAME |
“genus” |
指定本工具在 case 中的目录名 |
AREA_FILE |
“area.rpt” |
指定默认的 area report 名 |
POWER_FILE |
“power.rpt” |
指定默认的 power report 名 |
QOR_FIEL |
“qor.rpt” |
指定默认的 qor report 名 |
TIMING_FILE |
“timing.rpt” |
指定默认的 timing report 名 |
JSON_PARSE_EN |
False |
指定是否将 rpt 解析为 json |
HOST |
“192.168.15.189” |
指定 rpc 调用的 ip |
PORT |
12300 |
指定 rpc 调用的 端口 |
CLEAN_EN |
True |
指定是否在执行完成后清除数据(防止 rpc 主机占用磁盘) |
8. sta 配置
name |
default |
description |
|---|---|---|
TIMING_RPT |
“golden_timing.rpt” |
指定 golden 工具的 timing report 名 |
AREA_RPT |
“golden_area.rpt” |
指定 golden 工具的 area report 名 |
POWER_RPT |
“golden_power.rpt” |
指定 golden 工具的 power report 名 |
QOR_RPT |
“golden_qor.rpt” |
指定 golden 工具的 qor report 名 |
THOR_STA_TCL |
“temp_thor_sta_correlation.tcl” |
指定 thor sta 脚本路径 |
THPR_STA_TIMING_TCL |
“temp_thor_sta_timing.tcl” |
只当 thor sta 输出脚本文件名 |
DC_STA_TCL |
“temp_dc_sta_correlation.tcl” |
指定 dc sta 输出脚本文件名 |
STA_RPT |
“sta_correlation.rpt” |
指定 sta 数据存放名 |
THOR_DIFF_RPT |
“sta_thor_diff_paths.rpt” |
指定仅 thor 拥有路径存放文件名 |
GOLDEN_DIFF_RPT |
“sta_golden_diff_paths.rpt” |
指定仅 golden 拥有路径存放文件名 |
NEQ_PATH_RPT |
“sta_neq_paths.rpt” |
指定 diff 路径存放文件名 |
STA_SUMMARY_RPT |
“sta_summary.rpt” |
指定 sta 报告汇总文件名 |
ACCURACY |
2 |
指定 timing 输出精度 |
NET_PROPS |
[] |
指定必需包含的 port / net 名 |
NON_NET_PROPS |
[] |
指定不参与的 port / net 名 |
GOLDEN |
“DC” |
指定用作 golden 的工具名 |
TIMING_THREADS |
1 |
指定 timing 执行的线程数 |
VERSION |
“v200” |
指定执行的 sta 版本(v100 / v200) |
tag 使用详解
1. tag 概述
tag 是用于更改 case 执行 tcl 脚本的工具, 当用户指定 --tag tag_name 后, zeus 会查找指定 tag 对应的 func, 并 使用该 func 对 tcl 脚本进行修改.
需要注意的是, 不同的 tag 可能存在冲突, 如 timing_level1 和 timing_level3, 此时timing_level1 的修改结果 将被 timing_level3 的修改结果覆盖, 最终 synth 指令输出将是 timing_level3 这个 tag 的修改结果.
# 同时使用两个 tag
zeus --tag timing_level1 --tag timing_level3
# 此时 temp_xxx.tcl 中, synth 指令为
synth top --timing_level3
2. tag 一览表
使用如下指令可以快捷的查看 zeus 的所有 tag:
# zeus 使用的是 maat 的 tag.
tools tags maat
3. 用户自定义 tag
当用户需要使用自定义 tag 时, 需要使用 --config 指定 CMDS_PATH 参数导入用户的 tag 文件.
zeus --tag user_tag --config CMDS_PATH=user_tags.py
tools 工具包
tools 是一个工具包的合集, 里面集成了诸多小工具, 这些小工具的使用方法为:
tools [sub_tool name] [sub_tool args]
其完整的工具列表可以在 help 文档中查看, 如下示例:
[root@dev02 Thor]$ tools --help
Usage: tools [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
clean Clean all temp git repository.
cm call lec check by RPC
cm_ppa call lec check by RPC
create-case create a case
find-top find the top moulde in verilog files
init-regression Generate regressioncases dir and some config file
lec call lec check by RPC
perf run execution perf
ppa Perform ppa data analysis based on the case data...
ppa-gen Generate weights files for ppa data analysis
rpc-server setup lec server
rpt2json Update the JSON file separately according to the RPT file
rules Show all rules.
set-level Set the level based on the runtime of the case
tags show all tag
update-golden update golden files
tools 工具合集
tools lec 工具
lec 工具概述
tools lec 工具用于判断两个输入的 verilog 文件或项目是否逻辑等价. 这两个输入文件或项目被称作 REVISED 和 GODLEN. 此外, tools 工具还支持指定 file_list 文件, 以满足特殊的 src 可能会指定 file 的情况. 若未指定 file_list 文件时, 若 GOLDEN 或 REVISED 输入是目录, 则尝试在输入目录下寻找默认的 file_list 文件 “file_list.txt”
lec 工具基础使用教程
tools lec 工具最简单的用法是直接提供 REVISED 和 GOLDEN 文件(或目录), lec 工具将其上传到 rpc 服务主机并返回 一个 lec 脚本和一个 lec report 文件, 并在命令行中回显此次 lec 检查结果. 其示例如下:
# 存在一个放有 Verilog 文件的目录, 该文件(或目录)作为 golden
ls golden
# golden_file.v
# 存在一个放有 verilog 文件的目录, 该文件(或目录)作为 revised
ls revised
# revised_file.v
# 调用 lec 工具
tools lec golden/golden_file.v revised/revised_file.v
# 当输入是 dir 时, 会读入该目录下所有 verilog 文件, 当存在 file_list 时, 按 file_list 读入.
tools lec golden revised
tools lec golden/golden_file.v revised
tools lec golden revised/revised_file.v
效果图如下:
lec 工具进阶使用教程
tools lec 工具的 help 文档如下:
[root@dev02 Thor]$ tools lec --help
Usage: tools lec [OPTIONS] REVISED GOLDEN
call lec check by RPC
Options:
--platform TEXT specify the platform for lec
--revised_file_list TEXT specify the file_list for revised
--golden_file_list TEXT specify the file_list for golden
--record Keep case file and lec info in server
--script TEXT specify the script for lec.
--help Show this message and exit.
--platform 参数
用于指定此次 lec 校验使用的 lib 库, 默认为 nangate45, 当输入中存在网表时, 一般需要指定为该网表对应的 lib 库.
# eg: 使用 tsmc65 的 lib 库
tools lec src netlist.v --platform tsmc65
--revised_file_list 参数
revised_file_list 参数用于指定 revised 使用的 file_list 文件, 一般用于用户调试 Thor 代码时需要使用自己编写 的 file_list 文件. 当不使用该参数时, 若 REVISED 输入是 dir, 则默认尝试在 REVISED 下寻找 file_list.txt 文件.
--golden_file_list 参数
golden_file_list 参数用于指定 golden 使用的 file_list 文件, 一般用于用户调试 Thor 代码时需要使用自己编写 的 file_list 文件. 当不使用该参数时, 若 GODLEN 输入是 dir, 则默认尝试在 GOLDEN 下寻找 file_list.txt 文件.
--record 参数
指定服务器是否保存本次 lec rpc 调用的相关数据, 否则服务器将在本次 lec 执行完成并返回结果后删除本次 case 等 数据, 一般仅用于调试, 用户使用时不需要开启.
--script 参数
指定本次 lec 使用的脚本, 一般来说无需指定, lec 会自动生成相关的脚本, 若有更改的需求, 建议用户在生成的脚本上进行 修改以满足自己的需求.
--help 参数
查看 help 文档, 其指令如下:
tools lec --help
自定义 lec server IP & port
tools lec 是一个 RPC 接口, 该接口的调用需要一个可提供 lec rpc server 的服务器. rpc server 也是 tools 工具 包中的一个工具, 由 tools rpc-server 可以启动. 启动后, 使用该 rpc server 需要在配置文件中或使用 --config更 改 lec rpc 调用本次 rpc-server 启动时指定的 IP 和端口. 其具体流程如下:
启动一个 rpc-server.
调用 lec rpc 时, 指定 rpc-server 的 IP 和端口.
有多种方式可以指定 lec rpc 的 IP 和端口, 详情可参考如下链接:
# 使用 --config 指定 lec rpc 调用的 IP 和端口
tools rpc revised.v golden.v --config lec.IP=192.168.15.200 --config lec.PORT=12345
tools perf 工具
perf 工具概述
tools perf 工具用于快速生成指定可执行文件的火焰图输出。
perf 工具基础使用教程
tools perf 基础使用方式与 gdb 类似, 需要输入一个可执行文件及其该可执行文件的参数, 该工具将在当前目录下生成一个 perf.svg 文件(即火焰图, 可在浏览器中查看)
svg 文件生成指令如下:
# 在当前目录下生成 perf.svg 文件
tools perf RainaSynth -f demo.tcl
传输 svg 文件到 vdi 中进行查看
# 在 vdi(windows 系统) 的 cmd 中使用如下指令传输 svg 文件, 注意将 user@192.168.15.xx 替换为用户自己的 user@host
scp user@192.168.15.85:~/git/thor_core/Example/perf.svg C:\Users\vdiuser\Desktop
perf 工具基础使用示例
示例如下（以 echo 指令为例）
[root@edacoder85 Example]$ tools perf echo
2025-07-21 15:35:13.465 | INFO | autotest.scripts.tools_scripts.perf:perf:27 - run perf: perf record --call-graph=dwarf --freq 100 -o perf.data echo.
[ perf record: Woken up 1 times to write data ]
[ perf record: Captured and wrote 0.004 MB perf.data ]
2025-07-21 15:35:13.582 | INFO | autotest.scripts.tools_scripts.perf:perf:29 - generate perf file.
2025-07-21 15:35:13.603 | INFO | autotest.backend.perf:run_perf_script:98 - run perf script finish.
2025-07-21 15:35:13.604 | INFO | autotest.scripts.tools_scripts.perf:perf:31 - generate svg file.
2025-07-21 15:35:13.604 | DEBUG | autotest.backend.perf:run_FlameGraph:108 - run perf cmd: /share1/software/FlameGraph/stackcollapse-perf.pl perf.perf
2025-07-21 15:35:13.623 | DEBUG | autotest.backend.perf:run_FlameGraph:127 - run perf cmd: /share1/software/FlameGraph/flamegraph.pl perf.folded
同样的, tools perf 可用于监测 RainaSynth 工具的性能并输出火焰图
# 在 thor_core/Example 目录下执行 tools perf 工具
[root@edacoder85 Example]$ tools perf ../bin/RainaSynth -f demo.tcl
# 输出较多, 不予展示
...
[ perf record: Woken up 18 times to write data ]
[ perf record: Captured and wrote 4.541 MB perf.data (555 samples) ]
2025-07-21 15:10:14.667 | INFO | autotest.backend.perf:run_perf_script:98 - run perf script finish.
2025-07-21 15:10:14.668 | DEBUG | autotest.backend.perf:run_FlameGraph:108 - run perf cmd: /share1/software/FlameGraph/stackcollapse-perf.pl perf.perf
2025-07-21 15:10:14.727 | DEBUG | autotest.backend.perf:run_FlameGraph:127 - run perf cmd: /share1/software/FlameGraph/flamegraph.pl perf.folded
2025-07-21 15:10:14.830 | INFO | autotest.backend.perf:run_FlameGraph:139 - run FlameGraph finish.
# 生成一个 svg 文件, 可使用 scp 将其传输到 vdi 中, 在浏览器上进行查看
[root@edacoder85 Example]$ ll perf.svg
-rw-rw-r-- 1 tanlinfeng tanlinfeng 579 Jul 21 15:35 perf.svg
tools perf 工具的 help 文档
[root@edacoder85 test]$ tools perf --help
Usage: tools perf [OPTIONS] EXECUTION [ARGS]...
run execution perf
Options:
--help Show this message and exit.
--EXECUTION 参数
用于指定生成火焰图的可执行文件, 如 ls / echo / RainaSynth 等, 一般建议使用带调试信息的可执行文件(如 debug 版本的 RainaSynth)
# eg: 生成 echo 指令的火焰图
tools perf echo "xxx"
# eg: 生成 ls 指令的火焰图
tools perf ls
# eg: 生成 RainaSynth 工具的火焰图
tools perf RainaSynth -f test.tcl
--ARGS 参数
用于 EXECUTION 的参数, 如 RainaSynth 的 -f xxx.tcl 参数, python 要执行的脚本名等.
# eg: 生成 RainaSynth 工具的火焰图
tools perf RainaSynth -f test.tcl
# eg: 生成 python 执行脚本 script.py 的火焰图
tools perf python3 script.py
tools ppa 工具
ppa 工具概述
tools ppa 是 tools 工具包中用于解析 ppa 数据以分析两个不同 case PPA 数据集的性能变化趋势的工具.
其输入是两组 case 数据, 这两组数据是由用户指定的 RainaSynth 在指定 tag 下执行 case 后的输出. 用户可能 使用的是同一个 RainaSynth, 也可能使用的是两个不同的 RainaSynth, 故该工具可用于如下两种情况.
- 测试同一个版本的 RainaSynth 在不同优化指令下的性能差异
使用 同一版本 commit 的 RainaSynth, 指定两组不同的 tag(synth level + opt level), 执行后将输出两组 不同的 case 数据, 这两组数据之间的差异显示了 该版本的 RainaSynth 在不同的综合等级和优化等级下 PPA 的差异情况.
- 测试不同版本的 RainaSynth 在相同优化指令下的性能差异
使用 不同版本的 commit, 此时将编译出 两个版本的 RainaSynth 并指定相同的 tag, 执行后将输出两组 不同的 case 数据, 这两组数据之间的差异即两个 版本的 RainaSynth 之间的性能差异情况.
ppa 工具基础使用教程
Tools ppa 工具的要求输入两个版本 RainaSynth 的 ppa 数据, 因此, 在执行 tools ppa 工具之前, 需要先准备两个版本 RainaSynth 的 ppa 数据.
获取新版本 RainaSynth 输出的 ppa 数据
# 以 2023-12-20 的 Nightly RainaSynth 为例
export RAINA_PATH=/homecloud/public/Nightly_Raina/2023-12-20/release/bin/RainaSynth
# 此时将生成一个带有时间戳的 case 目录文件 RegressionSystem_TempGit_xxxx
nabu --remote --record
# 可更名为 golden
mv ./RegressionSystem_TempGit_xxxx golden
获取新版本 RainaSynth 输出的 ppa 数据
# 假定此处使用的是用户自行编译的最新版本的 RainaSynth
export RAINA_PATH={HOME}/Thor/bin/RainaSynth
# 此时将生成一个带有时间戳的 case 目录文件 RegressionSystem_TempGit_xxxx
nabu --remote --record
# 可更名为 target
mv ./RegressionSystem_TempGit_xxxx target
执行 tools ppa 工具进行解析.
tools ppa golden target
tools ppa 工具输出效果图如下所示, 其输出分为两部分, 上部分为单个 case 的 PPA 数据的变化趋势和数值变化, 下部分 为总体 case 的 PPA 数据的变化趋势并按从坏到好的程度进行排序.
ppa 工具进阶使用教程
tools ppa 工具的 help 文档如下:
[root@dev02 Thor]$ tools ppa --help
Usage: tools ppa [OPTIONS] GOLDEN TARGET
Perform ppa data analysis based on the case data generated by nabu, and the
weight can be specified.
Options:
--no_detail Whether to disalble display the details of a single case.
Defaults to True
--weight TEXT Custom weight file path
--save_file TEXT Specify the file to save the data of ppa tool.
--help Show this message and exit.
--no_detail
指定 tools ppa 分析工具不显示单个 case 的详细数据, 仅显示 case 数据汇总图. 效果图如下:
--weight
指定 ppa 分析工具使用自定义的 weight 文件, 可参考 PPA weight 文件的使用.
# 使用用户自定义的权重文件 my_weight.json
tools ppa golden target --weight my_weight.json
--save_file
指定用于保存 ppa 分析过程产生的中间数据的文件名, 一般用户不需要使用, 这些数据可用于 case-manager 或加速 现有的 case 的 ppa 数据分析.
--help
查看 help 文档, 其指令如下:
tools ppa --help
PPA weight 文件使用
weight 文件是一个 json 文件, 用户可以通过 tools ppa-gen 指令先生成一个默认的 weight 文件, 在此基础上 进行修改. 未指定时, ppa 工具将使用默认的权重数据, 此时 ppa 工具将仅关注 PPA 数据中的 WNS / TNS 数据.
# 生成默认的 weight 数据, 生成 weight.json 文件
tools ppa-gen
# 也可以指定生成文件的名字
tools ppa-gen --output my_weight.json
# 更改 my_weight.json 文件中的权重.
在权重文件中, 可按用户需求自定义修改权重, 当权重为 0 时, 该数据将不进行 ppa 数据分析.
当某个数据越大表示性能越好时, 权重应该为正数, 如 WNS, TNS.
当某个数据越小表示性能越好时, 权重应该为负数, 如 area, power 相关指标.
权重文件预览如下:
tools update-golden 工具
update-golden 工具概述
update-golden 是一个用于即时更新指定 maat case 仓库 golden 文件的小工具. 和 maat / nabu 的使用方式类似, 其支持 不定个数的 case, 并可以通过 --dir 指定要更新 golden 的 case.
update-golden 工具一般有两个作用, 但本质上都是通过自动更新 golden 文件来完成的, update-golden 工具会自动读取 tcl 文件 中用户指定的 rule 和 result / target 两个对比文件, 并尝试在 report 目录中寻找 result 文件覆盖 golden 中的 target 文件. 其适用的场景如下:
当用户的 Thor 代码有更新并需要手动更新 golden 时.
当用户需要查看以最新 RainaSynth 数据为 golden 时 maat 执行 case 的结果.
# 假设存在一个目录 repo, 其下有数个 case: case1, case2, case3 ...
mkdir ~/repo
# 用户编译了改动后的 RainaSynth, 在 maat 中使用并获取了最新的输出.
# 使用 tools update-golden 更新 Sdc/../case1, Eco/../case3, Power/../case5 这三个 case, /../ 表示中间的数个子模块
tools update-golden Sdc/../case1 Eco/../case3 Power/../case5
# 仅更新 Sdc 这个模块下所有的 case
tools update-golden Sdc
# 仅更新 Sdc/mod1 这个子模块下所有的 case
tools update-golden Sdc/mod1
# 若当前用户位于某个 case 目录中
cd ~/repo/case1
# 尝试更新所有 case, 未发现 case, 检查自身是否为 case
tools update-golden
# 未发现其他 case, 检测出 pwd 为 case, 更新当前 case (case1)
使用 --dir 指定 cases 目录, 此时将在指定的目录下寻找 case 并更新.
# 假设存在一个目录 repo, 其下有数个 case: case1, case2, case3 ...
mkdir ~/repo
# 进入其他目录中, 使用 --dir 执行指定路径的 case
cd ~/another_dir
# 尝试使用指定的 dir 执行 repo 下的所有 case 并汇总输出
tools update-golden --dir ~/repo
# 其他用法如通配符, 指定 case 与上述示例一致
tools update-golden --dir ~/repo case1 case3 case5 test*
update-golden 工具使用教程
update-golden 的 help 文档如下:
[root@dev02 Thor]$ tools update-golden --help
Usage: tools update-golden [OPTIONS] [CASE_NAMES]...
update golden files
Options:
--debug
--dir TEXT the case dir
--help Show this message and exit.
–debug
指定 tools update-golden 执行模式为 debug 模式, 在此模式下, update-golden 工具将输出详细的 result 覆盖 golden 的情况.
–dir
指定要更新的 case 路径.
–help
输出 update-golden 的 help 文档.
tools clean 工具
clean 工具概述
clean 工具用于清理任意由 regression-system 输出的文件.
示例:
# 使用 nabu 远程拉取并记录了一个 case 仓库
nabu --remote --record
# 调用 tools clean 工具进行清除
tools clean
cm 工具包(待开发)
cm 是 case-manager 2.0 平台与命令行工具联动的一个的工具合集, 里面集成远程创建 case-manager task 的数个小工具， 使得用户无需登录 case-manager web 页面即可创建 regression task 或 custom task，cm help 文档如下：
cm [sub_tool name] [sub_tool args]
其完整的工具列表可以在 help 文档中查看, 如下示例:
# todo: Added cm --help output
[root@dev02 Thor]$ cm --help
cm 工具合集
cm maat 工具
cm maat 工具概述
cm maat 工具是用于研发服务器远程创建 case-manager regression task 的命令行工具，该工具使得用户可以在研发服务器 上远程调用 case-manager 的机器资源来执行 regressioncases，从而减少研发服务器的负载并减少了 cases 执行等待时间（理论上 case-manager 服务器性能更加强大，可以更快的执行完所有 cases）。在创建完成后，用户可以选择在 cmd 中阻塞等待 cases 的执行结果，也可以关闭终端，等待 cases 执行，case-manager 执行完 cases 后，将以邮件的形式通知使用者，此时用户可以 登录 case-manager 网站 regression 模块查看本次执行结果。
cm maat 工具基础使用教程
cm maat 工具最简单的使用方式就是进入 regressioncases 目录下并执行 cm maat 触发 regression task 的创建。
# 用户在使用 cm maat 创建 regression task 时，一般位于 thor 子模块中
cd thor_sub_module
# 进入 regressioncases 目录，准备执行 case
cd regressioncases
# 使用 cm maat 创建一个 regression task
cm maat
此时，终端将给出 cm maat 执行状态输出，并阻塞等待结果返回，效果图如下:
和 maat 一样，cm maat 也可以指定 case 执行
# 进入 regressioncases 目录中
cd thor_sub_module/regressioncases
# 仅执行 case1，case_set/sub_case2
cm maat case1 case_set/sub_case2
cm maat 进阶使用教程
cm maat 工具的 help 文档如下:
# todo：added cm maat --help output
[root@dev02 Thor]$ tools lec --help
Usage: tools lec [OPTIONS] REVISED GOLDEN
--compare
指定执行 case 时是否输出 error case 的详细信息.
maat --compare效果如图:
--config
更改 maat 功能模块参数的指令, 其使用较为多变复杂, 并可搭配 配置文件 使用, 进阶使用请参考 --config 配置表.
--config 是一个可重复使用的参数, 用于更改多个配置, 输入格式为.
maat --config [mod.attr=value] # eg: 打开 lec 检查并指定 lec rpc 调用的端口为 12345 maat --config case.ENABLE_LEC=on --config lec.PORT=12345
--tag
使用 tag 去更改此次 maat 执行的 tcl 脚本.
对于任意 case 来说, maat 执行此 case 时, 会先生成一个 temp_xxxx.tcl 文件, 其是 case 本身的 tcl 文件的一个 副本, 并对这个 tcl 文件做一系列的处理, 包括但不限于处理相对路径 / 更改 cmd 参数 / 增删 cmd 等功能, 其实现就是 依托于 tag 完成, 如:
# 为 synth 命令增加 --timing_level3 参数 maat --tag timing_level3 # 清除所有的 opt 指令(netlist_opt / resynth) maat --tag non_opt更加详细的使用请参考 tag 使用详解.
--debug
指定以 debug 模式执行 maat, 一般用于调试.
maat --debug
--repeat
指定 cases 重复执行次数, 以预防 RainaSynth 输出偶现 bug 问题.
# 指定 case 重复执行 5 次 maat --repeat 5
--timeout
指定 cases 执行的超时时间, 指定后, 单个 case 执行超时则直接结束运行并给出报错. 该参数可以指定单位, 目前 支持以下四个单位:
秒(s), 当输入不带单位时, 默认为秒
分(m)
时(h)
天(d)
# 指定超时时间为 1000 秒 maat --timeout 1000 maat --timeout 1000s # 指定超时时间为 90 分钟 maat --timeout 90m # 指定超时时间为 2 小时 maat --timeout 2h
cm nabu 工具
cm nabu 工具概述
cm nabu 工具是用于研发服务器远程创建 case-manager regression task 的命令行工具，该工具使得用户可以在研发服务器 上远程调用 case-manager 的机器资源来执行 regressioncases，从而减少研发服务器的负载并减少了 cases 执行等待时间（理论上 case-manager 服务器性能更加强大，可以更快的执行完所有 cases）。在创建完成后，用户可以选择在 cmd 中阻塞等待 cases 的执行结果，也可以关闭终端，等待 cases 执行，case-manager 执行完 cases 后，将以邮件的形式通知使用者，此时用户可以 登录 case-manager 网站 regression 模块查看本次执行结果。
cm nabu 工具基础使用教程
cm nabu 工具最简单的使用方式就是执行 cm nabu 触发 PPA cases task 的创建。
# 在任意目录下，调用 cm nabu 创建一个 PPA_testcase task
cm nabu
此时，终端将给出 cm nabu 执行状态输出，并阻塞等待结果返回，效果图如下:
和 nabu 一样，cm nabu 也可以指定 case 执行，但相对于 cm nabu 来说，由于 cm nabu 不一定在用户本地的 PPA_testcase 目录中执行， 故其无法使用目录补全来补全 case，且由于 PPA_testcase 可能位于用户本地也可能位于 PPA_testcase 仓库，即对于 cm nabu 来说，case 的来源不固定，可能用户会上传当前目录的 path，也可能使用的是 PPA_testcase 仓库的 case， 因此 cm nabu 提供一个 –local 参数指定 case 的来源。
# 进入用户本地的 PPA_testcases 目录中
cd PPA_testcases
# 执行所有 case
cm nabu
# 仅执行 case1，case2
cm nabu case1 case2
cm nabu 进阶使用教程
cm nabu 工具的 help 文档如下:
# todo：added cm nabu --help output
[root@dev02 Thor]$ tools lec --help
Usage: tools lec [OPTIONS] REVISED GOLDEN
--compare
指定执行 case 时是否输出 error case 的详细信息.
nabu --compare效果如图:
--config
更改 nabu 功能模块参数的指令, 其使用较为多变复杂, 并可搭配 配置文件 使用, 进阶使用请参考 --config 配置表.
--config 是一个可重复使用的参数, 用于更改多个配置, 输入格式为.
nabu --config [mod.attr=value] # eg: 打开 lec 检查并指定 lec rpc 调用的端口为 12345 nabu --config case.ENABLE_LEC=on --config lec.PORT=12345
--tag
使用 tag 去更改此次 nabu 执行的 tcl 脚本.
对于任意 case 来说, nabu 执行此 case 时, 会先生成一个 temp_xxxx.tcl 文件, 其是 case 本身的 tcl 文件的一个 副本, 并对这个 tcl 文件做一系列的处理, 包括但不限于处理相对路径 / 更改 cmd 参数 / 增删 cmd 等功能, 其实现就是 依托于 tag 完成, 如:
# 为 synth 命令增加 --timing_level3 参数 nabu --tag timing_level3 # 清除所有的 opt 指令(netlist_opt / resynth) nabu --tag non_opt更加详细的使用请参考 tag 使用详解.
--debug
指定以 debug 模式执行 nabu, 一般用于调试.
nabu --debug
--repeat
指定 cases 重复执行次数, 以预防 RainaSynth 输出偶现 bug 问题.
# 指定 case 重复执行 5 次 nabu --repeat 5
--timeout
指定 cases 执行的超时时间, 指定后, 单个 case 执行超时则直接结束运行并给出报错. 该参数可以指定单位, 目前 支持以下四个单位:
秒(s), 当输入不带单位时, 默认为秒
分(m)
时(h)
天(d)
# 指定超时时间为 1000 秒 nabu --timeout 1000 nabu --timeout 1000s # 指定超时时间为 90 分钟 nabu --timeout 90m # 指定超时时间为 2 小时 nabu --timeout 2h