工具概述

功能特性

算子调优工具使用请参考工具使用，通过MindStudio Insight展示计算内存热点图、指令流水图以及算子指令热点图等单算子调优能力，具体请参考表1。

命令汇总

• msprof op模式

  登录运行环境，需要先使用op参数开启算子上板调优，再使用msprof op 可选参数 app [arguments]格式调用，可选参数的具体情况请参考表2。具体命令示例如下：

  msprof op --output=/home/projects/output /home/projects/MyApp/out/main blockdim 1 // --output为可选参数，/home/projects/MyApp/out/main为使用的app，blockdim 1为用户app的可选参数 

  表2 msprof op可选参数表

  可选参数	描述	是否必选
  --application 说明： 当前与./app [arguments]兼容，后期将修改为./app [arguments]。	建议使用msprof op ./app [arguments]进行拉取，其中app为指定的可执行文件，如果app未指定路径，默认为使用当前路径，[arguments]为app的参数。	是，指定的可执行文件和--config二选一
  --config	配置为输入算子编译得到的二进制文件*.o，可配置为绝对路径或者相对路径。具体可参考msProf json配置文件说明。 说明： 进行算子上板或者仿真调优之前，需要获取NPU侧可执行文件或算子二进制.o文件。 可参考运行验证算子工程，获取NPU侧可执行文件ascendc_kernels_bbit。 可参考算子编译部署，对算子kernel侧实现进行编译，并获取算子二进制文件*.o。
  --kernel-name	指定要采集的算子名称，支持使用算子名前缀进行模糊匹配。如果不指定，则只对程序运行过程中调度的第一个算子进行采集。 说明： 需与--application配合使用，限制长度为1024，仅支持A-Za-z0-9_中的一个或多个字符。 需要采集多个算子时，支持使用符号"|"进行拼接。例如，--kernel-name="add|abs"表示采集前缀为add和abs的算子。 具体采集的算子数量由--launch-count参数值决定。	否
  --launch-count	设置可以采集算子的最大数量，默认值为1，取值范围为1~100之间的整数。	否
  --launch-skip-before-match	用于设置不需要采集数据的算子数量，从第一个算子开始到指定数目的算子不进行采集，仅对指定数目之后的算子开始采集。 说明： 无论--launch-skip-before-match参数是否命中kernel-name中指定的算子，该项的计数都会增加，且不采集该算子。 此参数的取值范围为0~1000之间的整数。	否
  --aic-metrics	使能算子性能指标的采集能力和算子采集能力指标。 使能算子性能指标的采集能力（ArithmeticUtilization、L2Cache、Memory、MemoryL0、MemoryUB、PipeUtilization、ResourceConflictRatio和Default），可选其中的一项或多项性能指标，选多项时用英文逗号隔开，例如：--aic-metrics=Memory,MemoryL0。 默认使能Default，采集以下性能指标（ArithmeticUtilization、L2Cache、Memory、MemoryL0、MemoryUB、PipeUtilization、ResourceConflictRatio）。 使能算子Kernel侧指定代码段范围内的性能指标采集（KernelScale）。 KernelScale可对算子Kernel侧指定代码段范围进行调优。需先配置--aic-metrics=KernelScale，然后选其中的一项或多项算子性能指标，选多项时用英文逗号隔开，例如：--aic-metrics=KernelScale,Memory,MemoryL0。 默认选择全部算子性能指标进行采集，例如：--aic-metrics=KernelScale。 说明： 指定代码段范围时，需要在算子Kernel侧对应的代码段前后进行设置，具体设置请参见MetricsProfStart和MetricsProfStop接口《Ascend C自定义算子开发指南》的MetricsProfStart和MetricsProfStop接口。 仅Atlas A2训练系列产品支持该功能。 Roofline：使能生成Roofline分析图，并通过MindStudio Insight进行可视化呈现，例如：--aic-metrics=Roofline。具体请参见Roofline分析图。 TimelineDetail：使能生成指令流水图和算子代码热点图，进行可视化呈现，例如：--aic-metrics=TimelineDetail。具体请参见指令流水图和算子代码热点图。 说明： 若要使能此功能，需要参考msprof op simulator配置进行配置。 Occupancy：使能生成核间负载分析图，并通过MindStudio Insight进行可视化呈现，例如：--aic-metrics=Occupancy。具体请参见核间负载分析图。 各物理核之间，会针对耗时、数据吞吐量及Cache命中率分别进行对比，若最大值和最小值的差距大于10%，则说明负载不均衡，命令行界面会给出相应的调优建议。 说明： 仅Atlas A2训练系列产品支持该功能。	否
  --kill	可选择on/off，默认为off，关闭该功能。 若用户配置--kill=on使能该功能，用户程序将会在采集完--launch-count设置的算子数量后，自动停止程序。 说明： 配置--kill=on后，可能会出现因用户程序提前结束而引发的错误日志，用户需自行评估是否使用该功能。 若用户程序为多进程，--kill参数的配置只对子进程生效。	否
  --mstx	该参数决定算子调优工具是否使能用户代码程序中使用的mstx API。 默认为off，表示关闭对mstx API的使能。 若用户配置--mstx=on，算子调优工具将会使能用户代码程序中使用的mstx API。 具体举例如下： msprof op --mstx=on ./add_custom 说明： 当前已支持mstx API中的mstxRangeStartA和mstxRangeEnd接口，功能为使能算子调优的指定区间，具体参数介绍请参见mstxRangeStartA和mstxRangeEnd接口。	否
  --mstx-include	该参数支持在算子调优工具使能mstx API的情况下，仅使能用户指定mstx API 若不配置，则默认使能所有用户代码中使用的mstx API。 若配置，--mstx-include只使能用户指定的mstx API。--mstx-include的输入为用户调用mstx函数时传入的message字符串，使用 | 拼接多个字符串。 具体举例如下： --mstx=on --mstx-include="hello|hi" //仅使能用户传入mstx函数中message参数为hello和hi的mstx API 说明： 不可单独配置，需要与--mstx配合使用。 仅支持message为A-Z a-z 0-9 _这些字符，使用"|"进行拼接。	否
  --replay-mode	算子数据采集的重放模式，可配置为kernel或application，默认为kernel。 若配置为application，则代表是应用级重放。 若配置为kernel，则代表是核函数级重放。 说明： 多卡多算子的场景不支持配置为application。	否
  --output	收集到的性能数据的存放路径，默认在当前目录下保存性能数据。	否
  --help	输出帮助信息。	否

• msprof op simulator模式

  登录运行环境，使用msprof op simulator开启算子仿真调优功能，并配合使用仿真可选参数和用户待调优程序（blockdim 1）进行调优，仿真可选参数请参考表3。具体命令示例如下：

  msprof op simulator --output=/home/projects/output /home/projects/MyApp/out/main blockdim 1   // --output为可选参数，/home/projects/MyApp/out/main为使用的app，blockdim 1为用户app的可选参数

  表3 msprof op simulator可选参数说明

  可选参数	描述	是否必选
  --application 说明： 当前与./app [arguments]兼容，后期将修改为./app [arguments]。	建议使用msprof op simulator ./app [arguments]进行拉取，其中app为指定的可执行文件，如果app未指定路径，默认为使用当前路径，[arguments]为app的参数。	是，指定的可执行文件、--config和--export三选一
  --config	配置为算子编译得到的二进制文件*.o，可配置为绝对路径或者相对路径。具体可参考msProf json配置文件说明。 说明： 进行算子上板或者仿真调优之前，需要获取NPU侧可执行文件或算子二进制.o文件。 可参考运行验证算子工程，获取NPU侧可执行文件ascendc_kernels_bbit，并从用户的可执行文件中提取*.o文件。 可参考算子编译部署，算子编译时会自动生成*.o文件。
  --export	指定包含单算子仿真结果文件夹，直接对该仿真结果进行解析，并通过MindStudio Insight展示单算子单核或多核的指令流水图。 说明： 该指定文件夹只允许存放多核数据及算子核函数文件aicore_binary.o，所以需要将--config中配置的二进制文件名称（*.o）手动修改为aicore_binary.o。 若用户仅提供dump文件，则指令流水图中将无法生成代码行映射，如需查看代码行，则需要在dump中存放aicore_binary.o名称的算子核函数文件。
  --kernel-name	指定要采集的算子名称，支持使用算子名前缀进行模糊匹配。如果不指定，则只对程序运行过程中调度的第一个算子进行采集。 说明： 需与--application配合使用，限制长度为1024，仅支持A-Za-z0-9_中的一个或多个字符。 需要采集多个算子时，支持使用符号"|"进行拼接。例如，--kernel-name="add|abs"表示采集前缀为add和abs的算子。 具体采集的算子数量由--launch-count参数值决定。	否
  --launch-count	设置可以采集算子的最大数量，默认值为1，取值范围为1~100之间的整数。	否
  --aic-metrics	使能算子性能指标采集。支持以下性能指标采集项，默认全部采集。 PipeUtilization ResourceConflictRatio 说明： PipeUtilization为计算单元和搬运单元指令耗时占比，且为必选项。例如：--aic-metrics=PipeUtilization。 ResourceConflictRatio为资源冲突占比，支持展示SET_FLAG/WAIT_FLAG指令，且仅适用于Atlas A2训练系列产品。 当配置--aic-metrics=PipeUtilization时，关闭SET_FLAG,WAIT_FLAG指令。	否
  --mstx	该参数决定算子调优工具是否使能用户代码程序中使用的mstx API。--mstx参数可选择on/off。默认为off，off表示关闭对mstx API的使能。 若用户配置--mstx=on，算子调优工具将会使能用户代码程序中使用的mstx API。 具体举例如下： msprof op simulator --mstx=on ./add_custom 说明： 当前已支持mstx API中的mstxRangeStartA和mstxRangeEnd接口，功能为使能算子调优的指定区间，具体参数介绍请参见mstxRangeStartA和mstxRangeEnd接口。	否
  --mstx-include	该参数支持在msProf工具使能用户指定mstx API。 若不配置，则默认使能所有用户代码中使用的mstx API。 若配置，--mstx-include仅使能用户指定的mstx API。--mstx-include的输入为用户调用mstx函数时传入的message字符串，多个字符串需使用"|"拼接。 具体举例如下： --mstx=on --mstx-include="hello|hi" //仅使能用户传入mstx函数中message参数为hello和hi的mstx API 说明： 不可单独配置，需要与--mstx配合使用。 仅支持message为A-Z a-z 0-9 _这些字符，使用"|"进行拼接。	否
  --soc-version	用于在--application和--export模式下指定仿真器类型，选取范围可参考${INSTALL_DIR}/tools/simulator路径下的仿真器类型。 说明： ${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。例如，若安装的Ascend-cann-toolkit软件包，则安装后文件存储路径为：$HOME/Ascend/ascend-toolkit/latest。 若不配置，需要使用LD_LIBRARY_PATH环境变量设置仿真器类型。 export LD_LIBRARY_PATH=${INSTALL_DIR}/tools/simulator/Ascendxxxyy/lib:$LD_LIBRARY_PATH	否
  --output	收集到的性能数据的存放路径，默认在当前目录下保存性能数据。	否
  --help	输出帮助信息。	否

msprof op分段调优原则

1. 使用--launch-skip-before-match命令筛选算子调优范围，筛选原则如下：
   • 若已配置--launch-skip-before-match，从第一个算子开始到指定数目的算子不进行采集，仅对指定数目之后的算子开始采集。
   • 若未配置，不进行筛选。
2. 在步骤一的基础上，使用--mstx命令筛选算子调优范围，筛选原则如下：
   • 若已配置--mstx，只采集mstxRangeStartA和mstxRangeEnd接口使能范围内的算子。
   • 若未配置，不进行筛选。
3. 在步骤二的基础上，使用--kernel-name命令筛选算子调优范围，筛选原则如下：
   • 若已配置--kernel-name，只采集--kernel-name范围内的算子。
   • 若未配置--kernel-name，则只对程序运行过程中调度的第一个算子进行采集。
4. 在步骤三的基础上，使用--aic-metrics命令筛选算子调优数据的采集项，筛选原则如下：
   • 若已配置--aic-metrics，选择算子性能指标的采集项。
   • 若未配置--aic-metrics，默认采集全部算子性能指标。
5. 通过步骤一至步骤四逐层过滤，可获得实际的调优算子数量以及性能指标的采集范围。
6. 使能--kill=on功能的情况下，将实际调优的算子数量与--launch-count值进行对比，从而决定是否需要自动停止程序。

   若实际已调优算子数量小于等于--launch-count值，则继续执行。否则，实际已调优算子数量达到--launch-count设置的算子数值时，会自动停止程序。

调用场景