扩展功能

json配置文件说明

编写算子的定义json文件，配置参数的具体说明请参考表 1 json文件配置参数说明和表 2 test_case参数字段说明。

例如，json配置文件的命名为add_test.json，开发者可基于该模板修改测试数据及其他配置参数。

{
  "kernel_name": "add_custom",
  "kernel_path": "./add_custom.o",
  "blockdim": 8,
  "mode": "ca",
  "device_id": 0,
  "magic": "RT_DEV_BINARY_MAGIC_ELF_AIVEC",
  "test_cases": [
    {
      "case_name": "Test_AddCustom_001",
      "param_desc": [
        {
          "param_type": "input",
          "type": "float16",
          "shape": [
            8,
            2048
          ],
          "data_path": "./input_x.bin",
          "name": "x"
        },
        {
          "param_type": "input",
          "type": "float16",
          "shape": [
            8,
            2048
          ],
          "data_path": "./input_y.bin",
          "name": "y"
        },
        {
          "param_type": "output",
          "type": "float16",
          "shape": [
            8,
            2048
          ],
          "name": "z"
        },
        {
          "param_type": "workspace",
          "user_workspace_size": 4096
        },
        {
          "param_type": "tiling",
          "tiling_data_size": 8,
          "tiling_data_path": "./tiling.bin"
        }
      ]
    }
  ]
}

表 1 json文件配置参数说明

参数名称	参数描述	类型	是否必选
kernel_name	核函数名称。	string	是
kernel_path	核函数二进制.o文件所在路径，可配置为绝对路径或者相对路径。	string	是
blockdim	核函数运行所需的核数，默认值：1。	int	否
mode	测试模式。 - 上板：onboard - 性能仿真：ca	string	是
device_id	运行时使用AI处理器的ID，默认值：0。	int	否
tiling_key	当前动态算子的tiling key。	uint64	否
magic	算子类型。 - Cube算子：RT_DEV_BINARY_MAGIC_ELF_AICUBE - Vector算子：RT_DEV_BINARY_MAGIC_ELF_AIVEC - Mix融合算子：RT_DEV_BINARY_MAGIC_ELF（仅Atlas A3 训练系列产品/Atlas A3 推理系列产品和Atlas A2 训练系列产品/Atlas A2 推理系列产品支持配置）	string	是
test_cases	测试数据，支持列表，每个元素包含一个用例。详细说明可参考表 2 test_case参数字段说明。	list	是

Note

tiling_key参数仅适用于动态算子。
在使用magic参数时，Atlas 推理系列产品需配置为RT_DEV_BINARY_MAGIC_ELF。
在使用test_cases参数时，算子上板或仿真调优时仅支持配置单个用例。

表 2 test_case参数字段说明

参数			说明	类型	是否必选
case_name	-	-	测试用例的名称，需唯一。	string	是
param_desc	-	-	用例描述，支持列表，每个元素代表一个核函数参数。	list	是
-	param_type	input/output/workspace/tiling/fftsAddr	参数类型。	string	是
-	type	-	输入输出数据支持的数据类型，例如：uint8、int16、int32、float16、float32、float等。当“param_type”为input、output时必选。	string	否
-	shape	-	输入输出Tensor支持的形状，所有输入输出Tensor需支持相同数量的形状。例如：[8, 3, 256, 256]。若输入非法的形状会报错，例如：[0]。当“param_type”为input、output时必选。	list	否
-	data_path	-	输入数据bin文件的路径。当“param_type”为input时必须输入data_path或value_range，且data_path优先级更高。若json文件的"data_path"字段为空，需将json文件中设置为"data_path":"null"。json文件具体内容请参见json配置文件说明。	string	否
-	name	-	参数名称，需唯一。当“param_type”为input、output时必选。	string	否
-	user_workspace_size	-	用户设置的workspace_size大小。当“param_type”为workspace时必选。	int	否
-	tiling_data_size	-	tiling数据大小。当“param_type”为tiling时必选。	int	否
-	tiling_data_path	-	tiling数据bin文件所在路径。当“param_type”为tiling时必选。	string	否
-	data_size	-	fftsAddr的data_size大小。当“param_type”为fftsAddr时必选。	int	否

Note

“output”中参数取值的个数都要与“input”一致，否则测试用例生成会失败。例如：“input”的type支持的类型个数为2，则“output”的type支持的类型个数也需要为2。同理，所有input和output中的type、shape和value_range的取值个数也需要保持一致。
一个算子所有“input”中参数取值的个数都要一致，否则测试用例生成会失败。所有“input”中的type、shape和value_range的取值个数也需要保持一致。

mstx扩展功能

mstx接口简介

mstx接口是MindStudio提供的一个性能分析接口，它允许用户在应用程序中插入特定的标记，以便在性能分析时能够更精确地定位关键代码区域，具体接口明细请参见表 1 C/C++ mstx接口列表和表 2 Python mstx接口列表。具体接口的使用情况请参考《MindStudio mstx API参考》。

表 1 C/C++ mstx接口列表

接口名称	接口说明	msOpProf工具支持情况
mstxRangeStartA	mstx range指定范围能力的起始位置标记。	支持
mstxRangeEnd	mstx range指定范围能力的结束位置标记。	支持

表 2 Python mstx接口列表

接口名称	接口说明	msOpProf工具支持情况
mstx.range_start	mstx range指定范围能力的起始位置标记。	支持
mstx.range_end	mstx range指定范围能力的结束位置标记。	支持

mstx接口的使用

msOpProf工具允许用户通过mstx接口实现特定算子调优的功能，使用mstx接口可以自定义采集代码段范围内或指定关键函数的开始和结束时间点，并识别关键函数或计算API等信息，对性能问题快速定界。
默认情况下mstx接口不使能。若用户在应用程序中调用mstx接口，工具会根据具体使用场景使能mstx打点功能。例如配置--mstx=on使能用户程序中的mstx API，并可以通过--mstx-include使能用户程序中特定的mstx API，具体使用可分别参见msopprof模式用户指南的“命令参考”和msopprof simulator模式用户指南的“命令参考”中的--mstx和--mstx-include参数。
mstx当前提供了两种API的使用方式：库文件和头文件，以链接为例：
Note
- 此样例工程不支持Atlas A3 训练系列产品。
- ${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。
- 在${git_clone_path}/samples/operator/ascendc/0_introduction/1_add_frameworklaunch/AclNNInvocation/src/CMakeLists.txt路径下新增库文件libms_tools_ext.so，地址为：${INSTALL_DIR}/lib64/libms_tools_ext.so。
```
# Header path
include_directories(
     ...
    ${CUST_PKG_PATH}/include
)
...
target_link_libraries( 
    ...
    dl
)
```
- 在${git_clone_path}/samples/operator/ascendc/0_introduction/1_add_frameworklaunch/AclNNInvocation/src/main.cpp路径下，将用户程序编译链接dl库，对应的头文件ms_tools_ext.h地址：${INSTALL_DIR}/include/mstx。
```
...
#include "mstx/ms_tools_ext.h"
...
```

调用示例

启动msOpProf工具后，执行msprof op --mstx=on --mstx-include=range1 --launch-count=2 python cal.py命令，将会采集range1范围内的算子，即sub和mul算子。

import mstx
import torch
import torch_npu
 
x = torch.Tensor([1,2,3,4]).npu()
y = torch.Tensor([1,2,3,4]).npu()

a = x + y
range1_id = mstx.range_start("range1", None)
b = a - x
c = a * x
mstx.range_end(range1_id)
range2_id = mstx.range_start("range2", None)
d = x / y
range3_id = mstx.range_start("range3", None)
e = torch.abs(y)
mstx.range_end(range3_id)
f = x + e
mstx.range_end(range2_id)