工具概述
msProf工具用于采集和分析运行在昇腾AI处理器上算子的关键性能指标，用户可根据输出的性能数据，快速定位算子的软、硬件性能瓶颈，提升算子性能的分析效率。
当前支持基于不同运行模式（上板或仿真）和不同文件形式（可执行文件或算子二进制.o文件）进行性能数据的采集和自动解析。
- msProf工具的使用依赖CANN包中的msopprof可执行文件，该文件中的接口使用和msprof op一致，该文件为CANN包自带，无需单独安装。
- msProf工具不支持多线程算子的检测。
- msProf工具的仿真功能需要运行在0卡上。若修改可见卡号，则会导致仿真失败。
- msProf工具的上板功能配置为--aic-metrics=TimelineDetail时， 会启用仿真功能。此时，若修改可见卡号，会导致上板和仿真都报错。
- 通过键盘输入“CTRL+C”后，算子执行将会被停止，工具会根据当前已有信息生成性能数据文件。若不需要生成该文件，可再次键盘输入“CTRL+C”指令。
- 若未指定--output参数，需确保群组和其他组的用户不具备当前路径的上一级目录的写入权限。
命令汇总
- 建议限制对可执行文件或用户程序（application）的操作权限，避免提权风险。
- 不建议进行高危操作（删除文件、删除目录、修改密码及提权命令等），避免安全风险。
- msprof 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 [msprof op参数] ./app进行拉取，其中app为指定的可执行文件，如果app未指定路径，默认为使用当前路径。
是，指定的可执行文件和--config二选一
--config
配置为输入算子编译得到的二进制文件*.o，可配置为绝对路径或者相对路径。具体可参考msProf json配置文件说明。
说明：进行算子上板或者仿真调优之前，可通过以下两种方式获取算子二进制*.o文件。
- 参考运行验证算子工程，获取NPU侧可执行文件ascendc_kernels_bbit，并从用户的可执行文件中提取*.o文件。
- 参考算子编译部署，算子编译时会自动生成*.o文件。
- 需确保群组和其他组的用户不具备--config指定的json文件及上一级目录的写入权限。同时，需要确保json文件的上一级目录属主为当前用户。
--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。
- 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
收集到的性能数据的存放路径，默认在当前目录下保存性能数据。
说明：需确保群组和其他组的用户不具备--output指定输出路径的上一级目录的写入权限。同时，需要确保--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 [msprof op simulator 参数] ./app 进行拉取，其中app为用户指定的可执行文件，如果app未指定路径，默认为使用当前路径。
是，指定的可执行文件、--config和--export三选一
--config
配置为算子编译得到的二进制文件*.o，可配置为绝对路径或者相对路径。具体可参考msProf json配置文件说明。
说明：进行算子上板或者仿真调优之前，可通过以下两种方式获取算子二进制*.o文件。
- 参考运行验证算子工程，获取NPU侧可执行文件ascendc_kernels_bbit，并从用户的可执行文件中提取*.o文件。
- 参考算子编译部署，算子编译时会自动生成*.o文件。
- 需确保群组和其他组的用户不具备--config指定的json文件及上一级目录的写入权限。同时，需要确保json文件的上一级目录属主为当前用户。
--export
指定包含单算子仿真结果文件夹，直接对该仿真结果进行解析，并通过MindStudio Insight展示单算子单核或多核的指令流水图。
说明：- 该指定文件夹只允许存放多核数据及算子核函数文件aicore_binary.o，所以需要将--config中配置的二进制文件名称（*.o）手动修改为aicore_binary.o。
- 若用户仅提供dump文件，则指令流水图中将无法生成代码行映射，如需查看代码行，则需要在dump中存放aicore_binary.o名称的算子核函数文件。
- 需确保群组和其他组的用户不具备--export指定目录以及--export指定目录内所有文件的写入权限。同时，需要确保指定目录属主为当前用户。
--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。
默认为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路径下的仿真器类型。
若不配置，需要使用LD_LIBRARY_PATH环境变量设置仿真器类型。export LD_LIBRARY_PATH=${INSTALL_DIR}/tools/simulator/Ascendxxxyy/lib:$LD_LIBRARY_PATH说明：${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。例如，若安装的Ascend-cann-toolkit软件包，则安装后文件存储路径为：$HOME/Ascend/ascend-toolkit/latest。
否
--output
收集到的性能数据的存放路径，默认在当前目录下保存性能数据。
说明：需确保群组和其他组的用户不具备--output指定输出路径的上一级目录的写入权限。同时，需要确保--output指定目录的上一级目录属主为当前用户。
否
--help
输出帮助信息。
否
msprof op分段调优原则
- 使用--launch-skip-before-match命令筛选算子调优范围，筛选原则如下：
- 若已配置--launch-skip-before-match，从第一个算子开始到指定数目的算子不进行采集，仅对指定数目之后的算子开始采集。
- 若未配置，不进行筛选。
- 在步骤一的基础上，使用--mstx命令筛选算子调优范围，筛选原则如下：
- 若已配置--mstx，只采集mstxRangeStartA和mstxRangeEnd接口使能范围内的算子。
- 若未配置，不进行筛选。
- 在步骤二的基础上，使用--kernel-name命令筛选算子调优范围，筛选原则如下：
- 若已配置--kernel-name，只采集--kernel-name范围内的算子。
- 若未配置--kernel-name，则只对程序运行过程中调度的第一个算子进行采集。
- 在步骤三的基础上，使用--aic-metrics命令筛选算子调优数据的采集项，筛选原则如下：
- 若已配置--aic-metrics，选择算子性能指标的采集项。
- 若未配置--aic-metrics，默认采集Default部分的算子性能指标，KernelScale、TimelineDetail、Roofline、Occupancy部分的算子性能指标将无法采集。
- 通过步骤一至步骤四逐层过滤，可获得实际的调优算子数量以及性能指标的采集范围。
- 使能--kill=on功能的情况下，将实际调优的算子数量与--launch-count值进行对比，从而决定是否需要自动停止程序。
若实际已调优算子数量小于等于--launch-count值，则继续执行。否则，实际已调优算子数量达到--launch-count设置的算子数值时，会自动停止程序。
调用场景
- Kernel直调：核函数运行验证的场景。
- Kernel直调的场景，详细信息可参考Kernel直调。
- Kernel直调的场景，需先配置好前置条件，然后执行以下命令：
msprof op simulator ./main // main为用户算子程序名称，包含待调优算子的程序名
- 可选：若算子已在上板运行模式下，但用户又需要在不重新编译的情况下，对其进行仿真调优，可通过以下操作步骤实现。
- 在任意目录下，创建一个指向libruntime_camodel.so的软连接，名称为libruntime.so。
ln -s /{simulator_path}/lib/libruntime_camodel.so /{so_path}/libruntime.so //例如，若使用root用户默认路径安装CANN包，simulator_path为/usr/local/Ascend/ascend-toolkit/latest/tools/simulator/Ascendxxxyy - 将创建的软链接的父目录加入到环境变量LD_LIBRARY_PATH中。
export LD_LIBRARY_PATH={so_path}:$LD_LIBRARY_PATH
- 在任意目录下，创建一个指向libruntime_camodel.so的软连接，名称为libruntime.so。
- Ascend CL单算子调用：单算子API执行的场景。
- 第三方框架算子调用：Pytorch框架的场景。
