nabu 使用手册 ============== .. toctree:: :maxdepth: 2 :caption: Contents: 概述 :::::::::: nabu是⽤于Thor进⾏PPA性能测试的⼆进制⼯具,其集成了lec检查、输出数据解析、特异性tcl脚本⽣ 成等⼀系列功能，并作为case-manager后端执⾏⼯具。本⽂旨在列举nabu的简易使⽤⽅法及对应 case 的添加流程. --------------------- nabu 基础使用教程 ::::::::::::::::::: 1. 环境配置与 case 准备 --------------------------- nabu的启动依赖于两个对象 **\* 综合工具 RainaSynth** nabu 使用环境变量 **RAINA_PATH** 来寻找综合工具 RainaSynth. .. code:: bash # 使用 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 示例 ------------------------ .. _default_use: * 默认以当前路径为 cases 路径, 此时会执行该 dir 下所有 case, 若无 case, 则检查当前目录是否在一个 case 内部. .. code:: bash # 假设存在一个目录 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 并执行, 其他参数与 :ref:`默认启动路径 ` 一致. .. code:: bash # 假设存在一个目录 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 输出如下: .. code:: [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 效果如图: .. image:: images/compare_feature.png -\-cpu_num ------------------------ 指定 nabu 多进程数量, 默认为当前机器最大核心数的一半以防止过多的占用资源. :: nabu --cpu_num 8 -\-version ------------------------ 输出当前 nabu 版本. :: nabu --version -\-continue/-c ------------------------ 在执行 case 过程中, 用户可使用 ctrl+c 停止执行 case, 此时可使用 -\-continue 参数继续上次执行任务 .. code:: bash # 执行一些 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 功能模块参数的指令, 其使用较为多变复杂, 并可搭配 :ref:`配置文件 ` 使用, 进阶使用请参考 :ref:`-\\\\-config 配置表 `. -\-config 是一个可重复使用的参数, 用于更改多个配置, 输入格式为. :: nabu --config [mod.attr=value] # eg: 打开 lec 检查并指定 lec rpc 调用的端口为 12345 nabu --config case.ENABLE_LEC=on --config lec.PORT=12345 .. _option_nabu_ymal: -\-yaml ------------------------ 指定本次 case 执行使用的配置文件, 例如, 用户编辑了一份 custom.yaml 文件, 其内容如下: :: case.ENABLE_LEC: false case.timeout: 10m 此时 **nabu --yaml ./custom.yaml** 执行的所有 case 均将关闭 lec 检查并且设置超时时间为 10 min. nabu 的配置文件内容可参考 :ref:`配置文件 ` 部分. -\-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 更加详细的使用请参考 :ref:`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 来说, 其判定应当满足以下四个要求: 1. NabuCase 是一个 directory. 2. NabuCase 中包含 golden 目录, 其下存放用于对比的 golden 文件. 3. NabuCase 中包含一个 tcl 文件, 其描述了本 case 的执行流程. 4. NabuCase 中包含一个 src 目录, 其下存放了本 case 使用的 RTL 文件(支持 file_list). nabu 工具使用的 case 仓库是 PPA_testcases 仓库. 由于 NabuCase 的判定是非递归的, 这意味着 nabu case 的存放 是展平的, 对于任意指定的 dir, nabu 仅仅会查找当前目录的所有 nabu case, 若未找到, 则检查自身是否是一个 nabu case. .. _nabu_config_file: nabu 的配置文件 :::::::::::::::::: nabu 使用 yaml 文件作为配置文件, ".maatCfg.yaml" 文件作为其默认的配置文件名, 且用户可以使用 :ref:`-\\\\-yaml ` 参数指定自定义的配置文件. nabu 每次启动时均会按照如下顺序去读取本次执行过程使用的配置(从低到高). * /usr/local/etc/.maatCfg.yaml * /etc/.maatCfg.yaml * ~/.maatCfg.yaml * 用户使用 -\-yaml 指定的路径 * case 目录下的 .maatCfg.yaml 文件 * 使用 -\-config 更改的配置 nabu 拥有数个不同层级的模块, 每个模块拥有各自不同的配置, 对于最顶层的配置, 可以直接写配置名即可. 如: .. code:: yaml # 指定用户自定义配置文件路径 CONFIG_PATH : ./my_config.yaml # 指定 case 在执行完成后清除输出文件 CLEAN_WHEN_FINISH : True # 指定 case 执行等级为 3 LEVEL : 3 对于 nabu 中的子模块配置, 则使用 mod.attr 的方式去指定配置, 可有效防止同名配置冲突的问题. 如: .. code:: yaml # 指定 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 .. _nabu_config_table: config 配置一览表 :::::::::::::::::: 与 :ref:`nabu 的配置文件 ` 类似, 因为 nabu 拥有数个不同层级的模块, 每个模块拥有各自不同的 配置, 对于最顶层的配置, 可以直接写配置名即可, 对于 nabu 中的子模块配置, 则使用 mod.attr 的方式去指定配置. .. code:: bash # 开启 fake run, 同时将 case 模块的 lec 检查关闭 nabu --config FAKE_RUN=true --config case.ENABLE_LEC=false .. include:: config_table.rst .. _nabu_tag: 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 .. image:: images/nabu_tags.png 3. 用户自定义 tag ------------------ 当用户需要使用自定义 tag 时, 需要使用 -\-config 指定 CMDS_PATH 参数导入用户的 tag 文件. :: nabu --tag user_tag --config CMDS_PATH=user_tags.py