MindStudio Ops Generator工具用户指南
算子工程创建简介
完成算子分析和原型定义后，可使用MindStudio Ops Generator（算子工程工具，msOpGen）生成自定义算子工程，并进行编译部署。工具
具有如下功能：
- 基于算子原型定义输出算子工程。
- 基于性能仿真环境生成的dump数据文件输出算子仿真流水图文件。
具体流程请参考图1 msOpGen工具使用流程介绍。
使用前准备
按照环境要求进行配置后，可直接使用msOpGen工具的相关功能。
进行算子开发之前，需要安装配套版本的CANN Toolkit开发套件包和ops算子包并配置CANN环境变量，请参见《CANN 软件安装指南》。本节不再给出安装示例。
-
出于安全性及权限最小化角度考虑，本代码仓中的工具均不应使用root等高权限账户进行操作，建议使用普通用户权限安装执行。
-
使用算子开发工具前，请确保执行用户的umask值大于等于0027，否则会造成获取的性能数据所在目录和文件权限过大。
-
使用算子工具前，请保证使用最小权限原则（如：禁止other用户可写，禁止666或777）。
-
不建议配置或运行其他用户目录下的自定义脚本，避免提权风险。
-
下载代码样例时，需执行以下命令指定分支版本。
git clone https://gitee.com/ascend/samples.git -b master
算子工程创建功能介绍
功能说明
msOpGen目前已支持的功能如下：包括算子工程创建、算子实现（Host侧&Kernel侧）、算子工程编译部署以及解析算子仿真流水图文件等。
表 1 msOpGen工具功能
注意事项
用户按照输入的配置参数生成算子模板后，建议在运行前确认算子工程代码的安全性。
命令格式
执行如下命令，参数说明请参见表1 创建算子工程参数说明。用户按照输入的配置参数生成算子模板后，建议在运行前确认算子工程代码的安全性。
msopgen gen -i {*.json} -f {framework type} -c {Compute Resource} -lan cpp -out {Output Path}
参数说明
表 1 创建算子工程参数说明
msOpGen工具其他参数说明可参考表2 参数说明。
| 参数名称 | 参数描述 | 说明 |
|---|---|---|
| compile | 编译TBE&AI CPU算子工程时使用。 | 具体请参见算子交付件独立编译。 |
使用示例
创建算子工程
-
编写算子的原型定义json文件，用于生成算子开发工程。json文件的配置参数详细说明请参考表1 json文件配置参数说明。
例如，AddCustom算子的json文件命名为add_custom.json，文件内容如下：
[ { "op": "AddCustom", "input_desc": [ { "name": "x", "param_type": "required", "format": [ "ND", "ND", "ND" ], "type": [ "fp16", "float", "int32" ] }, { "name": "y", "param_type": "required", "format": [ "ND", "ND", "ND" ], "type": [ "fp16", "float", "int32" ] } ], "output_desc": [ { "name": "z", "param_type": "required", "format": [ "ND", "ND", "ND" ], "type": [ "fp16", "float", "int32" ] } ] } ]例如，ReduceMaxCustom算子（包含属性）的json文件命名为reduce_max_custom.json，文件内容如下：
[ { "op": "ReduceMaxCustom", "input_desc": [ { "name": "x", "param_type": "required", "format": ["ND"], "type": ["float16"] } ], "output_desc": [ { "name": "y", "param_type": "required", "format": ["ND"], "type": ["float16"] }, { "name": "idx", "param_type": "required", "format": ["ND"], "type": ["int32"] } ], "attr": [ { "name": "reduceDim", "param_type": "required", "type": "int" }, { "name": "isKeepDim", "param_type": "optional", "type": "int", "default_value": 1 } ] } ]- required（必选）
- optional （可选）
- dynamic（动态输入）
- Ascend C或TBE算子取值范围：float、half、float16 (fp16)、float32 (fp32)、int8、int16、int32、int64、uint8、uint16、uint32、uint64、qint8、qint16、qint32、quint8、quint16、quint32、bool、double、string、resource、complex64、complex128、bf16、numbertype、realnumbertype、quantizedtype、all、BasicType、IndexNumberType、bfloat16。
- MindSpore数据类型取值范围：None_None、BOOL_None、BOOL_Default、BOOL_5HD、BOOL_FracZ、BOOL_FracNZ、BOOL_C1HWNCoC0、BOOL_NCHW、BOOL_NHWC、BOOL_NDHWC、I8_None、I8_Default、I8_5HD、I8_FracZ、I8_FracNZ、I8_C1HWNCoC0、I8_NCHW、I8_NHWC、I8_HWCN、I8_NDHWC、U8_None、U8_Default、U8_5HD、U8_FracZ、U8_FracNZ、U8_C1HWNCoC0、U8_NCHW、U8_NHWC、U8_HWCN、U8_NDHWC、I16_None、I16_Default、I16_5HD、I16_FracZ、I16_FracNZ、I16_C1HWNCoC0、I16_NCHW、I16_NHWC、I16_HWCN、I16_NDHWC、U16_None、U16_Default、U16_5HD、U16_FracZ、U16_FracNZ、U16_C1HWNCoC0、U16_NCHW、U16_NHWC、U16_HWCN、U16_NDHWC、I32_None、I32_Default、I32_5HD、I32_FracZ、I32_FracNZ、I32_C1HWNCoC0、I32_NCHW、I32_NHWC、I32_HWCN、I32_NDHWC、U32_None、U32_Default、U32_5HD、U32_FracZ、U32_FracNZ、U32_C1HWNCoC0、U32_NCHW、U32_NHWC、U32_HWCN、U32_NDHWC、I64_None、I64_Default、I64_5HD、I64_FracZ、I64_FracNZ、I64_C1HWNCoC0、I64_NCHW、I64_NHWC、I64_HWCN、I64_NDHWC、U64_None、U64_Default、U64_5HD、U64_FracZ、U64_FracNZ、U64_C1HWNCoC0、U64_NCHW、U64_NHWC、U64_HWCN、U64_NDHWC、F16_None、F16_Default、F16_5HD、F16_FracZ、F16_FracNZ、F16_C1HWNCoC0、F16_NCHW、F16_NHWC、F16_HWCN、F16_NDHWCi、F16_FracZNLSTM、F32_None、F32_Default、F32_5HD、F32_FracZ、F32_FracNZ、F32_C1HWNCoC0、F32_NCHW、F32_NHWC、F32_HWCN、F32_NDHWC、F32_FracZNLSTM、F64_None、F64_Default、F64_5HD、F64_FracZ、F64_FracNZ、F64_C1HWNCoC0、F64_NCHW、F64_NHWC、F64_HWCN、F64_NDHWC。
说明：- 不同计算操作支持的数据类型不同，详细请参见《Ascend C算子开发接口》。
- format与type需一一对应。若仅填充其中一项的唯一值，msOpGen工具将会以未填充项的唯一输入值为准自动补充至已填充项的长度。例如用户配置为format:["ND"] /type:["fp16","float","int32"]，msOpGen工具将会以format的唯一输入值（"ND"）为准自动补充至type参数的长度，自动补充后的配置为format:["ND","ND","ND"]/type:["fp16","float","int32"]。
- required
- optional
- dynamic
- Ascend C或TBE算子取值范围：float、half、float16 (fp16)、float32 (fp32)、int8、int16、int32、int64、uint8、uint16、uint32、uint64、qint8、qint16、qint32、quint8、quint16、quint32、bool、double、string、resource、complex64、complex128、bf16、numbertype、realnumbertype、quantizedtype、all、BasicType、IndexNumberType、bfloat16。
- MindSpore数据类型取值范围：None_None、BOOL_None、BOOL_Default、BOOL_5HD、BOOL_FracZ、BOOL_FracNZ、BOOL_C1HWNCoC0、BOOL_NCHW、BOOL_NHWC、BOOL_NDHWC、I8_None、I8_Default、I8_5HD、I8_FracZ、I8_FracNZ、I8_C1HWNCoC0、I8_NCHW、I8_NHWC、I8_HWCN、I8_NDHWC、U8_None、U8_Default、U8_5HD、U8_FracZ、U8_FracNZ、U8_C1HWNCoC0、U8_NCHW、U8_NHWC、U8_HWCN、U8_NDHWC、I16_None、I16_Default、I16_5HD、I16_FracZ、I16_FracNZ、I16_C1HWNCoC0、I16_NCHW、I16_NHWC、I16_HWCN、I16_NDHWC、U16_None、U16_Default、U16_5HD、U16_FracZ、U16_FracNZ、U16_C1HWNCoC0、U16_NCHW、U16_NHWC、U16_HWCN、U16_NDHWC、I32_None、I32_Default、I32_5HD、I32_FracZ、I32_FracNZ、I32_C1HWNCoC0、I32_NCHW、I32_NHWC、I32_HWCN、I32_NDHWC、U32_None、U32_Default、U32_5HD、U32_FracZ、U32_FracNZ、U32_C1HWNCoC0、U32_NCHW、U32_NHWC、U32_HWCN、U32_NDHWC、I64_None、I64_Default、I64_5HD、I64_FracZ、I64_FracNZ、I64_C1HWNCoC0、I64_NCHW、I64_NHWC、I64_HWCN、I64_NDHWC、U64_None、U64_Default、U64_5HD、U64_FracZ、U64_FracNZ、U64_C1HWNCoC0、U64_NCHW、U64_NHWC、U64_HWCN、U64_NDHWC、F16_None、F16_Default、F16_5HD、F16_FracZ、F16_FracNZ、F16_C1HWNCoC0、F16_NCHW、F16_NHWC、F16_HWCN、F16_NDHWCi、F16_FracZNLSTM、F32_None、F32_Default、F32_5HD、F32_FracZ、F32_FracNZ、F32_C1HWNCoC0、F32_NCHW、F32_NHWC、F32_HWCN、F32_NDHWC、F32_FracZNLSTM、F64_None、F64_Default、F64_5HD、F64_FracZ、F64_FracNZ、F64_C1HWNCoC0、F64_NCHW、F64_NHWC、F64_HWCN、F64_NDHWC。
说明：- 不同计算操作支持的数据类型不同，详细请参见《Ascend C算子开发接口》。
- format与type需一一对应。若仅填充其中一项的唯一值，msOpGen工具将会以未填充项的唯一输入值为准自动补充至已填充项的长度。例如用户配置为format:["ND"] /type:["fp16","float","int32"]，msOpGen工具将会以format的唯一输入值（"ND"）为准自动补充至type参数的长度，自动补充后的配置为format:["ND","ND","ND"]/type:["fp16","float","int32"]。
- required
- optional
int、bool、float、string、list_int、list_float、list_bool、list_list_int，其他请自行参考《Ascend C算子开发接口》中的“ Host API > 原型注册与管理 > OpAttrDef > OpAttrDef”章节进行修改。
Note
- json文件可以配置多个算子，json文件为列表，列表中每一个元素为一个算子。
- 若input_desc或output_desc中存在相同name参数，则后一个会覆盖前一参数。
- input_desc，output_desc中的type需按顺序一一对应匹配，format也需按顺序一一对应匹配。 例如，第一个输入x的type配置为[“int8”,“int32”]，第二个输入y的type配置为[“fp16”,“fp32”]，输出z的type配置为[“int32”,“int64”]，最终这个算子支持输入(“int8”,“fp16”)生成int32，或者(“int32”,“fp32”)生成int64，即输入和输出的type是垂直对应的，类型不能交叉。
- input_desc，output_desc中的type与format需一一对应匹配，数量保持一致。type的数据类型为以下取值（"numbertype"、"realnumbertype"、"quantizedtype"、"BasicType"、"IndexNumberType"、"all"）时，需识别实际的type数量是否与format数量保持一致，若数量不一致，创建工程会收到报错提示，同时format按照type的个数进行补齐，继续生成算子工程。若type的取值为基本数据类型（如：“int32”），且与format无法一一对应时，创建工程会收到报错提示，并停止运行。
- json文件可对“attr”算子属性进行配置，具体请参考编写原型定义文件。
- 算子的Operator Type需要采用大驼峰的命名方式，即采用大写字符区分不同的语义，具体请参见算子工程编译的须知内容。
-
以生成AddCustom的算子工程为例，执行如下命令，参数说明请参见表1 json文件配置参数说明。
msopgen gen -i {*.json} -f {framework type} -c {Compute Resource} -lan cpp -out {Output Path} -
命令执行完后，会在指定目录下生成算子工程目录，工程中包含算子实现的模板文件，编译脚本等。
算子工程目录生成在-out所指定的目录下：./output_data，目录结构如下所示：
output_data ├── build.sh // 编译入口脚本 ├── CMakeLists.txt // 算子工程的CMakeLists.txt ├── CMakePresets.json // 编译配置项 ├── framework // 算子插件实现文件目录，单算子模型文件的生成不依赖算子适配插件，无需关注 ├── op_host // Host侧实现文件 │ ├── add_custom.cpp // 算子原型注册、shape推导、信息库、tiling实现等内容文件 │ ├── CMakeLists.txt ├── op_kernel // Kernel侧实现文件 │ ├── CMakeLists.txt │ ├── add_custom.cpp // 算子代码实现文件 │ ├── add_custom_tiling.h // 算子tiling定义文件 -
在算子工程中追加算子。若需要在已存在的算子工程目录下追加其他自定义算子，命令行需配置“-m 1”参数。
msopgen gen -i json_path/*.json -f tf -c ai_core-{Soc Version} -out ./output_data -m 1- -i：指定算子原型定义文件add_custom.json所在路径。
- -c：参数中{Soc Version}为AI处理器的型号。
在算子工程目录下追加 .json中的算子。MindSpore算子工程不能够添加非MindSpore框架的算子。
-
完成算子工程创建，进行算子开发。
算子开发
- 完成算子相关的开发适配，包括算子核函数的开发和tiling实现等，详细内容请参考《Ascend C算子开发指南》中的工程化算子开发章节。
- 可参考文档进行开发，完成op_host/add_custom_tiling.h、op_host/add_custom.cpp和op_kernel/add_custom.cpp的实现。
- 算子实现完成后，进入算子编译部署。
算子编译部署
-
编译Ascend C算子Kernel侧代码实现文件*.cpp，分为源码发布和二进制发布两种方式。
- 源码发布： 不对算子Kernel侧实现进行编译，保留算子Kernel源码文件*.cpp。该方式可以支持算子的在线编译、通过ATC模型转换的方式编译算子的场景。
- 二进制发布： 对算子Kernel侧实现进行编译，生成描述算子相关信息的json文件*.json和算子二进制文件*.o。如果需要直接调用算子二进制，则使用该编译方式。
-
编译Ascend C算子Host侧代码实现文件*.cpp、*.h。
- 将原型定义和shape推导实现编译成算子原型定义动态库libcust_opsproto_*.so，并生成算子原型对外接口op_proto.h。
- 将算子信息库定义编译成信息库定义文件*.json。
- 将tiling实现编译成tiling动态库liboptiling.so等。
- 自动生成单算子API调用代码和头文件aclnn_*.h，并编译生成单算子API调用的动态库libcust_opapi.so。
完成算子Kernel、Host侧的开发后，需要对算子工程进行编译，生成自定义算子安装包*.run，具体编译操作流程请参考图1 算子工程编译示意图。
-
修改工程目录下的CMakePresets.json中cacheVariables的配置项，完成工程编译相关配置。CMakePresets.json文件内容如下，参数说明请参见表1 需要开发者配置的常用参数列表。
{ "version": 1, "cmakeMinimumRequired": { "major": 3, "minor": 19, "patch": 0 }, "configurePresets": [ { "name": "default", "displayName": "Default Config", "description": "Default build using Unix Makefiles generator", "generator": "Unix Makefiles", "binaryDir": "${sourceDir}/build_out", "cacheVariables": { "CMAKE_BUILD_TYPE": { "type": "STRING", "value": "Release" }, "ENABLE_SOURCE_PACKAGE": { "type": "BOOL", "value": "True" }, "ENABLE_BINARY_PACKAGE": { "type": "BOOL", "value": "True" }, "ASCEND_COMPUTE_UNIT": { "type": "STRING", "value": "ascendxxx" }, "ENABLE_TEST": { "type": "BOOL", "value": "True" }, "vendor_name": { "type": "STRING", "value": "customize" }, "ASCEND_PYTHON_EXECUTABLE": { "type": "STRING", "value": "python3" }, "CMAKE_INSTALL_PREFIX": { "type": "PATH", "value": "${sourceDir}/build_out" }, "ENABLE_CROSS_COMPILE": { //使能交叉编译，请根据实际环境进行配置 "type": "BOOL", "value": "False" }, "CMAKE_CROSS_PLATFORM_COMPILER": { //请替换为交叉编译工具安装后的实际路径 "type": "PATH", "value": "/usr/bin/aarch64-linux-gnu-g++" }, "ASCEND_PACK_SHARED_LIBRARY": { "type": "BOOL", "value": "False" } } } ] }表 1 需要开发者配置的常用参数列表
- “Release”，Release版本，不包含调试信息，编译最终发布的版本。
- “Debug”，“Debug”版本，包含调试信息，便于开发者开发和调试。
-
支持自定义编译选项。
通过修改算子工程op_kernel目录下的CMakeLists.txt文件，使用add_ops_compile_options来增加编译选项。
add_ops_compile_options(OpType COMPUTE_UNIT soc_version1 soc_version2 ... OPTIONS option1 option2 ...)表 2 具体参数介绍
-
在算子工程目录下执行如下命令，进行算子工程编译。
./build.sh编译成功后，会在当前目录下创建build_out目录，并在build_out目录下生成自定义算子安装包custom_opp_<target_os>_<target_architecture>.run。
Note
注册算子类型后，框架会根据算子类型获取算子注册信息，同时在编译和运行时按照一定的规则匹配算子实现文件名称和Kernel侧核函数名称。为了保证正确匹配，算子类型、算子实现文件名称和核函数名称需要遵循如下定义规则。通常情况下，开发者只需要保证创建算子工程时原型定义json文件中算子类型op的参数值为大驼峰命名方式即可，工程创建后自动生成的代码即满足该规则。在手动编写算子原型定义和算子实现文件时需要按照如下规则定义。 算子类型需要采用大驼峰的命名方式，即采用大写字符区分不同的语义。 算子实现文件名称、核函数名称需相同，均为算子类型转换为下划线命名方式后的值。下文描述了通过算子类型转换成算子实现文件名称和核函数名称的过程：
- 首字符的大写字符转换为小写字符。例如：Abc -> abc。
- 大写字符的前一个字符为小写字符或数字，则在大写字符前插一个下划线“_”，并将该字符转换为小写字符。例如：AbcDef -> abc_def。
- 大写字符前一个字符为大写字符且后一个字符是小写字符，则在大写字符前插一个下划线“_”，并将该字符转换为小写字符。例如：AbcAAc -> abc_a_ac。
- 其他大写字符转换为小写字符，小写字符保持不变。
-
进行算子包部署。
-
自定义算子安装包部署。
在自定义算子包所在路径下，执行如下命令，安装自定义算子包。
./custom_opp_<target_os>_<target_architecture>.run --install-path=<path> # 其中--install-path为可选参数，用于指定自定义算子包的安装目录。支持指定绝对路径，运行用户需要具有指定安装路径的读写权限。下文描述中的<vendor_name>为算子工程编译时CMakePresets.json配置文件中字段“vendor_name”的取值，默认为"customize"。
-
默认安装场景，不配置--install-path参数，安装成功后会将编译生成的自定义算子相关文件部署到
${INSTALL_DIR}/opp/vendors/<vendor_name>目录。${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。例如，若安装的Ascend-cann-toolkit软件包，安装后文件存储路径示例为：$HOME/Ascend/cann。Note
自定义算子包默认安装路径
${INSTALL_DIR}/opp/vendors的目录权限与CANN软件包安装用户和安装配置有关。如果因权限不足导致自定义算子包安装失败，可使用--install-path参数并配置环境变量ASCEND_CUSTOM_OPP_PATH来指定安装目录（参考指定目录安装场景）或者联系CANN软件包的安装用户修改vendors目录权限来解决。详细的案例请参考《Ascend C算子开发指南》中“FAQ >调用算子时出现无法打开config.ini的报错及算子包部署时出现权限不足报错”章节。 -
指定目录安装场景，配置--install-path参数，安装成功后会将编译生成的自定义算子相关文件部署到
<path>/vendors/<vendor_name>目录，并在<path>/vendors/<vendor_name>/bin目录下新增set_env.bash，写入当前自定义算子包相关的环境变量。Note
如果部署算子包时通过配置--install-path参数指定了算子包的安装目录，则在使用自定义算子前，需要执行
source <path>/vendors/<vendor_name>/bin/set_env.bash命令，set_env.bash脚本中将自定义算子包的安装路径追加到环境变量ASCEND_CUSTOM_OPP_PATH中，使自定义算子在当前环境中生效。
命令执行成功后，自定义算子包中的相关文件将部署至当前环境中。
-
-
以默认安装场景为例，可查看部署后的目录结构，如下所示：
├── opp //算子库目录 │ ├── vendors //自定义算子所在目录 │ ├── config.ini │ └── vendor_name1 // 存储对应厂商部署的自定义算子，此名字为编译自定义算子安装包时配置的vendor_name，若未配置，默认值为customize │ ├── framework //自定义算子插件库 │ ├── op_api │ │ ├── include │ │ │ └── aclnn_xx.h //算子调用API声明文件 │ │ └── lib │ │ └── libcust_opapi.so │ ├── op_impl │ │ └── ai_core │ │ └── tbe │ │ ├── config │ │ │ └── ${soc_version} //AI处理器类型 │ │ │ └── aic-${soc_version}-ops-info.json //自定义算子信息库文件 │ │ ├── vendor_name1_impl //自定义算子实现代码文件 │ │ │ └── dynamic │ │ │ ├── xx.cpp │ │ │ └── xx.py │ │ ├── kernel //自定义算子二进制文件 │ │ │ └── ${soc_version} //AI处理器类型 │ │ │ └── config │ │ └── op_tiling │ │ ├── lib │ │ └── liboptiling.so │ └── op_proto //自定义算子原型库所在目录 │ ├── inc │ │ └── op_proto.h │ └── lib │ ├── vendor_name2 // 存储厂商vendor_name2部署的自定义算子Note
参数值：<soc_version>，查询方法如下：
- 非Atlas A3 训练系列产品/Atlas A3 推理系列产品：在安装昇腾AI处理器的服务器执行
npu-smi info命令进行查询，获取Chip Name信息。实际配置值为AscendChip Name，例如Chip Name取值为xxxyy，实际配置值为Ascendxxxyy。当Ascendxxxyy为代码样例的路径时，需要配置为ascendxxxyy。 - Atlas A3 训练系列产品/Atlas A3 推理系列产品：在安装昇腾AI处理器的服务器执行
npu-smi info -t board -i id -c chip_id命令进行查询，获取Chip Name和NPU Name信息，实际配置值为Chip Name_NPU Name。例如Chip Name取值为Ascendxxx，NPU Name取值为1234，实际配置值为Ascendxxx_1234。当Ascendxxx_1234为代码样例的路径时，需要配置为ascendxxx_1234。
其中：- id：设备id，通过
npu-smi info -l命令查出的NPU ID即为设备id。 - chip_id：芯片id，通过
npu-smi info -m命令查出的Chip ID即为芯片id。
- id：设备id，通过
- 非Atlas A3 训练系列产品/Atlas A3 推理系列产品：在安装昇腾AI处理器的服务器执行
-
配置自定义算子优先级。
多算子包共存的情况下，若不同的算子包目录下存在相同OpType的自定义算子，则以优先级高的算子包目录下的算子为准。下面介绍如何配置算子包优先级：
-
默认安装场景
当
opp/vendors目录下存在多个厂商的自定义算子时，您可通过配置opp/vendors目录下的config.ini文件，配置自定义算子包的优先级。config.ini文件的配置示例如下：load_priority=vendor_name1,vendor_name2,vendor_name3- load_priority：优先级配置序列的关键字，不允许修改。
- vendor_name1,vendor_name2,vendor_name3：自定义算子厂商的优先级序列，按照优先级从高到低的顺序进行排列。
-
指定目录安装场景
指定目录安装场景下，如果需要多个自定义算子包同时生效，分别执行各算子包安装路径下的set_env.bash脚本即可。每次脚本执行都会将当前算子包的安装路径追加到ASCEND_CUSTOM_OPP_PATH环境变量的最前面。因此可以按照脚本执行顺序确定优先级：脚本执行顺序越靠后，算子包优先级越高。
比如先执行
source <path>/vendor_name1/bin/set_env.bash，后执行source <path>vendor_name2/bin/set_env.bash，vendor_name2算子包的优先级高于vendor_name1。ASCEND_CUSTOM_OPP_PATH示例如下：ASCEND_CUSTOM_OPP_PATH=<path>/vendor_name2:<path>/vendor_name1 -
指定目录安装场景下安装的算子包优先级高于默认方式安装的算子包。
-
-
基于msOpST工具，进行算子Kernel测试，验证算子的功能。
-
基于msSanitizer工具，进行算子内存和异常检测，定位算子精度异常。
-
基于msDebug工具，进行算子上板调试，逐步确认算子精度异常。
-
基于msOpProf工具，生成计算内存热力图、指令流水图、及算子指令热点图统计信息，协助用户进一步优化算子性能。
-
经过以上操作步骤，确定算子精度和性能达到交付标准后，方可正常使用。
输出说明
查看算子仿真流水图
msOpGen工具通过解析用户生成的dump文件，并生成算子仿真流水图文件（trace.json）。
-
参考链接，在
${git_clone_path}/samples/operator/ascendc/0_introduction/1_add_frameworklaunch路径下运行install.sh文件，并生成CustomOp文件夹。Note
此样例工程不支持Atlas A3 训练系列产品/Atlas A3 推理系列产品和Atlas 训练系列产品。
./install.sh -v Ascendxxxyy # xxxyy为用户实际使用的具体芯片类型 -
编译算子工程。
-
参考编译前准备章节，完成编译相关配置。
-
在算子工程目录CustomOp下，执行如下命令，进行算子工程编译。
Note
若要生成算子仿真流水图，需要将当前目录下CMakePresets.json文件中CMAKE_BUILD_TYPE修改为“Debug”。
编译完成后，将会在build_out目录生成.run算子包。
./build.sh
-
-
在自定义算子包所在路径下，执行如下命令，部署算子包。
./build_out/custom_opp_<target_os>_<target_architecture>.run -
切换到AclNNInvocation仓的目录
${git_clone_path}/samples/operator/ascendc/0_introduction/1_add_frameworklaunch/AclNNInvocation，执行以下命令。./run.sh -
使能环境变量后，请参考《msOpProf工具用户指南》中的“工具使用>msprof op simulator”功能进行仿真，并生成dump数据。
export LD_LIBRARY_PATH=${git_clone_path}/samples/operator/ascendc/0_introduction/1_add_frameworklaunch/CustomOp/build_out/op_host/:$LD_LIBRARY_PATH -
生成算子仿真流水图文件。
执行如下命令，参数说明请参见表1 参数说明。
msopgen sim -c core{id} -d xx/{path of dump data} -subc {sub core id} -out {output path} -reloc {path of .o file or executable file}表 1 参数说明
dump文件名带有veccore{id}或cubecore{id}时，需配置此参数指定待解析的dump文件。如文件名为core0.veccore0.instr_log.dump，“veccore0”即为subcore id。
配置为Kernel侧算子编译后生成的.o文件或可执行文件所在路径。
进行流水图与代码行的映射，并生成代码行和指令耗时.csv文件。
说明：基于算子工程编译生成包含调试信息的.o文件（路径为${git_clone_path}/samples/operator/ascendc/0_introduction/1_add_frameworklaunch/CustomOp/build_out/op_kernel/binary/ascendxxxy/add_custom/AddCustom_*.o），即需要修改CMakePresets.json中CMAKE_BUILD_TYPE为“Debug”，具体可参考编译操作。
执行以下命令。
示例一：
msopgen sim -c core0 -d xx/{model}/ca/add_custom/add_custom_pre_static_add_custom -out ./output_data -subc cubecore0 -reloc xx/.o- -c：指定待解析dump文件的core id，如：core0。
- -d：指定性能仿真环境下生成的dump文件所在路径。例如："{model}/ca/add_custom/add_custom_pre_static_add_custom"。
- -subc：指定待解析dump文件的subcore id，如文件名为core0.cubecore0.instr_log.dump，“cubecore0”即为subcore id。（仅Atlas A3 训练系列产品/Atlas A3 推理系列产品和Atlas A2 训练系列产品/Atlas A2 推理系列产品需配置该参数）
- -reloc：指定Kernel侧算子编译生成的.o文件或可执行文件所在路径。
示例二：
msopgen sim -c core0 -d xx/{model}/ca/add_custom/add_custom_pre_static_add_custom -out ./output_data -mix- -c：指定待解析dump文件的core id，如：core0。
- -d：指定性能仿真环境下生成的dump文件所在路径。例如：{model}/ca/add_custom/add_custom_pre_static_add_custom。
- -mix：配置此参数表示支持展示Mix融合算子。
-
查看算子仿真流水图文件。
可以在Chrome浏览器中输入“chrome://tracing“地址，将输出路径下的dump2trace_core*.json文件拖到空白处打开，通过键盘上的快捷键（W：放大，S：缩小，A：左移，D：右移）进行查看，如下图所示。
表 2 字段说明
数据搬运流水，数据搬运方向为：FIXPIPE L0C -> OUT/L1。（仅Atlas A3 训练系列产品/Atlas A3 推理系列产品和Atlas A2 训练系列产品/Atlas A2 推理系列产品支持展示）
-
查看代码行或指令耗时文件。
在输出路径下打开代码行耗时文件{核编号}_code_exe_prof.csv，如下图所示。
在输出路径下打开指令耗时文件{核编号}_instr_exe_prof.csv，如下图所示。
通过文件中的“call count“及“cycles“字段可以分别查看代码行或指令的调用次数和累计耗时。
算子测试简介
使用msOpGen工具完成自定义算子包部署后，可选择使用MindStudio Ops System Test（算子测试，msOpST）工具进行ST（System Test）测试，在真实的硬件环境中，对算子的输入输出进行测试，以验证算子的功能是否正确。
测试用例通常包括各种不同类型的数据输入和预期输出，以及一些边界情况和异常情况的测试。通过ST测试，可以确保算子功能的正确性，并且能够在实际应用中正常运行。
使用前准备
进行算子开发之前，需要安装配套版本的CANN Toolkit开发套件包和ops算子包并配置CANN环境变量，请参见《CANN 软件安装指南》。本节不再给出安装示例。完成相关配置后，可直接使用msOpST工具的相关功能。
- 使用此工具生成算子测试用例前，需要将要测试的算子部署到算子库中，具体请参见算子编译部署。
- 若在实现算子ST功能验证时使用到AI框架，请完成所需AI框架的安装。
- TensorFlow框架的安装请参见《TensorFlow 1.15模型迁移指南》的“环境准备 > 安装开源框架TensorFlow 1.15”章节。
- TensorFlow 2.6.5 框架的安装请参见《TensorFlow 2.6.5模型迁移指南》的“环境准备 > 安装开源框架TensorFlow 2.6.5”章节。
- PyTorch框架的安装请参见《Ascend Extension for PyTorch 软件安装指南》。
算子测试功能介绍
功能说明
msOpST支持生成算子的ST测试用例并在硬件环境中执行。具有如下功能：
- 根据用户定义并配置的算子期望数据生成函数，回显期望算子输出和实际算子输出的对比测试结果，具体请参见生成测试用例定义文件。
- 根据算子测试用例定义文件生成ST测试数据及测试用例执行代码，在硬件环境上执行算子测试用例，具体请参见生成/执行测试用例。
- 自动生成运行报表（st_report.json）功能，报表记录了测试用例信息及各阶段运行情况，具体请参见生成/执行测试用例。
- 自动生成算子调用核函数的上板测试框架，进行算子的测试验证，具体请参见生成单算子上板测试框架。
注意事项
无
命令格式
执行如下命令生成算子测试用例定义文件，详细参数说明请参见表1 生成算子测试用例定义文件的参数说明。
msopst create -i {operator.cpp file} -out {output path} -m {pb file} -q
参数说明
-
生成算子测试用例定义文件。
表 1 生成算子测试用例定义文件的参数说明
配置为TensorFlow模型文件的路径，可配置为绝对路径或者相对路径。
若配置此参数，工具会从TensorFlow模型文件中获取首层算子的shape信息，并自动dump出算子信息库定义文件中算子的shape、dtype以及属性的value值，如果dump出的值在算子信息库定义文件所配置的范围内，则会自动填充到生成的算子测试用例定义文件中；否则会报错。
-
生成/执行测试用例。
表 2 生成/执行测试用例的参数说明
算子测试用例定义文件的路径，可配置为绝对路径或者相对路径。具体请参见《MindStudio Ops Generator典型案例》中的msOpST测试用例定义文件
说明：- 非Atlas A3 训练系列产品/Atlas A3 推理系列产品：在安装昇腾AI处理器的服务器执行npu-smi info命令进行查询，获取Chip Name信息。实际配置值为AscendChip Name，例如Chip Name取值为xxxyy，实际配置值为Ascendxxxyy。当Ascendxxxyy为代码样例的路径时，需要配置为ascendxxxyy。
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：在安装昇腾AI处理器的服务器执行npu-smi info -t board -i id -c chip_id命令进行查询，获取Chip Name和NPU Name信息，实际配置值为Chip Name_NPU Name。例如Chip Name取值为Ascendxxx，NPU Name取值为1234，实际配置值为Ascendxxx_1234。当Ascendxxx_1234为代码样例的路径时，需要配置为ascendxxx_1234。
生成文件所在路径，可配置为绝对路径或者相对路径，并且工具执行用户具有可读写权限。若不配置该参数，则默认生成在执行命令的当前路径。
- 配置为需要执行的case的名字，若需要同时运行多个case，多个case之间使用逗号分隔。
- 若配置为“all”，或者不配置此参数，代表执行所有case。
配置自定义精度标准，取值为含两个元素的列表："[threshold1，threshold2]"。
- threshold1：算子输出结果与标杆数据误差阈值，若误差大于该值则记为误差数据。
- threshold2：误差数据在全部数据占比阈值。若误差数据在全部数据占比小于该值，则精度达标，否则精度不达标。
ST测试高级功能配置文件（msopst.ini）存储路径，可配置为绝对路径或者相对路径。
用户可通过修改msopst.ini配置文件，实现如下高级功能：
- ST测试源码可编辑。
- 已编辑的ST测试源码可执行。
- 设置Host日志级别环境变量。
- 设置日志是否在控制台显示。
- 设置atc模型转换的日志级别。
- 设置atc模型转换运行环境的操作系统类型及架构。
- 设置模型精度。
- 读取算子在AI处理器上运行的性能数据。
若未配置--config_file文件，模型将强制使用FP16类型精度，msopst.ini配置文件的详细说明请参见表1 msopst.ini文件参数说明。
针对比对失败的用例，获取算子期望数据与实际用例执行结果不一致的数据。若未设置此参数，默认为：“false”。
-
生成单算子上板测试框架。
表 3 生成单算子上板测试框架参数说明
使用示例
生成测试用例定义文件
指导用户使用msOpST工具生成算子测试用例定义文件（*.json），作为算子ST测试用例的输入。
-
获取并编辑待测试Host侧算子的实现文件（.cpp文件）。
msOpST工具根据待测Host侧算子的实现文件生成算子ST测试用例定义文件，在算子工程文件中Host侧算子的实现文件路径如下所示。
可以单击链接获取文档中对应的Host侧算子实现文件add_custom.cpp进行参考。
Note
此样例工程不支持Atlas A3 训练系列产品/Atlas A3 推理系列产品。
├── framework/tf_plugin // 算子插件实现文件目录，单算子模型文件的生成不依赖算子适配插件，无需关注 ├── op_host // Host侧实现文件 │ ├── add_custom_tiling.h // 算子tiling定义文件 │ ├── add_custom.cpp // 算子原型注册、shape推导、信息库、tiling实现等内容文件 ├── op_kernel // Kernel侧实现文件 │ ├── CMakeLists.txt │ ├── add_custom.cpp // 算子代码实现文件 -
执行如下命令生成算子测试用例定义文件，详细参数说明请参见表1 生成算子测试用例定义文件的参数说明。
msopst create -i {operator.cpp file} -out {output path} -m {pb file} -qNote
示例如下： 以AddCustom算子为例，执行如下命令:
msopst create -i Op_implementation/add_custom.cpp -out ./output请将Op_implementation更换为Host侧算子的实现文件所在路径。 命令执行成功后，会在当前路径的output目录下生成算子测试用例定义文件：AddCustom_case_timestamp.json。
-
创建算子ST测试用例定义文件“AddCustom_case.json”。该文件的模板如下，您可以基于如下模板进行修改，“*.json”文件支持的全量字段说明参见表1 算子测试用例定义json文件。不同场景下的测试用例定义文件的样例可参见《MindStudio Ops Generator典型案例》中的“msOpST测试用例定义文件”。
[ { "case_name": "Test_OpType_001", "op": "OpType", "input_desc": [ { "format": [], "type": [], "shape": [], "data_distribute": [ "uniform" ], "value_range": [ [ 0.1, 1.0 ] ] } ], "output_desc": [ { "format": [], "type": [], "shape": [] } ] } ]表 1 算子测试用例定义json文件
-
（可选）如果您需要得到实际算子输出与期望输出的比对结果，需要参考此步骤自定义期望数据生成函数。
-
自定义实现add算子期望数据生成函数。
在Python文件中实现算子期望数据生成函数，文件目录和文件名称可自定义，如“/home/test/test_add_st.py”。
例如Add算子的期望数据生成函数实现如下：
def calc_expect_func(x1, x2, y): res = x1["value"] + x2["value"] return [res, ]Note
用户需根据开发的自定义算子完成算子期望数据生成函数。测试用例定义文件中的全部Input、Output、Attr的name作为算子期望数据生成函数的输入参数，若Input是可选输入，请将该输入指定默认值传参。
例如，某算子输入中的x3为可选输入时，定义该算子的期望数据生成函数如下。
def calc_expect_func(x1, x2, x3=None, y=None) -
在ST测试用例定义文件“OpType_xx.json”中增加比对函数。配置算子测试用例定义文件。
在步骤2 执行如下命令生成算子测试用例定义文件中的算子测试用例定义文件_AddCustom_case_timestamp_.json增加"calc_expect_func_file"参数，参数值为"/home/test/test_add_st.py:calc_expect_func"。
[ { "case_name":"Test_AddCustom_001", "op": "AddCustom", "calc_expect_func_file": "/home/test/test_add_st.py:calc_expect_func", #配置生成算子期望输出数据的实现文件 "input_desc": [...] ... ... } ]
-
生成/执行测试用例
指导用户根据算子测试用例定义文件生成ST测试数据及测试用例执行代码，在硬件环境上执行算子测试用例。
-
ST测试用例执行时，会使用AscendCL接口加载单算子模型文件并执行，所以需要配置AscendCL应用编译所需其他环境变量，如下所示。
export DDK_PATH=${INSTALL_DIR} export NPU_HOST_LIB=${INSTALL_DIR}/${arch-os}/devlibNote
${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。- {arch-os}中arch表示操作系统架构，os表示操作系统。
-
执行如下命令生成/执行测试用例，具体参数介绍请参见表1 生成算子测试用例定义文件的参数说明
msopst run -i {*.json} -soc {soc version} -out {output path} -c {case name} -d {device id} -conf {msopst.ini path} -err_thr "[threshold1,threshold2]"-
msopst.ini文件的路径为：
${INSTALL_DIR}/python/site-packages/bin/。 -
msopst.ini文件参数说明如下表所示。
Note
msopst.ini文件默认使用FP16精度模式，如需使用其他精度模式需手动修改表1 msopst.ini文件参数说明中atc_singleop_advance_option的--precision_mode参数。
表 1 msopst.ini文件参数说明
- True
- False（默认）
详情请参见表2 msOpST的运行模式。
- True
- False（默认）
- True
- False
获取算子性能模式。若设置为True，运行成功后在run/out/prof/JOBxxx/summary目录下生成一系列性能结果文件，用户只需查看op_summary_0_1.csv即可。
- 0：DEBUG级别
- 1：INFO级别
- 2：WARNING级别
- 3：ERROR级别（默认）
- 4：NULL级别，不输出日志
- 0：屏幕不打印输出（默认）
- 1：屏幕打印输出
--log参数取值:- debug：输出debug/info/warning/error/event级别的运行信息
- info：输出info/warning/error/event级别的运行信息
- warning：输出warning/error/event级别的运行信息
- error：输出error/event级别的运行信息（默认）
- null：不输出日志信息
--precision_mode参数取值:- force_fp16：表示算子支持fp16和fp32时，强制选择fp16（默认）
- force_fp32：表示算子支持fp16和fp32时，强制选择fp32
- allow_fp32_to_fp16：表示如果算子支持fp32，则保留原始精度fp32；如果不支持fp32，则选择fp16
- must_keep_origin_dtype：表示保持原图精度
- allow_mix_precision：表示混合精度模式
atc_singleop_advance_option="--log=info --host_env_os=linux --host_env_cpu=aarch64 --precision_mode=force_fp16"
若模型编译环境的操作系统及其架构与模型运行环境不一致时，则需使用--host_env_os和--host_env_cpu参数设置模型运行环境的操作系统类型。如果不设置，则默认取模型编译环境的操作系统架构，即atc所在环境的操作系统架构。
- X86_64：X86_64架构
- aarch64：arm64架构
HOST_ARCH="aarch64"
TOOL_CHAIN="/usr/bin/g++"
表 2 msOpST的运行模式
-
命令行执行示例：
-
不启用msOpST工具的高级功能，执行如下命令生成ST测试用例并执行。
msopst run -i xx/AddCustom_case_timestamp.json -soc {soc version} -out ./output -
启动msOpST工具的高级功能，仅生成ST测试用例，用户修改ST测试用例后，再执行ST测试用例。
-
执行命令，编辑msopst.ini文件
vim ${INSTALL_DIR}/python/site-packages/bin/msopst.ini将msOpST工具的运行模式修改为模式2，按照表2 msOpST的运行模式修改
only_gen_without_run和only_run_without_gen参数的取值。只生成ST测试代码，不运行ST测试代码。 -
执行如下命令生成ST测试源码。
msopst run -i xx/AddCustom_case_timestamp.json -soc {soc version} -out ./output -conf xx/msopst.ini-conf参数请修改为msopst.ini配置文件的实际路径。
ST测试用例生成后，用户可根据需要自行修改ST测试用例代码。
-
修改msopst.ini文件，修改运行模式为仅执行ST测试用例。
执行命令，编辑msopst.ini文件
vim ${INSTALL_DIR}/python/site-packages/bin/msopst.ini将msOpST工具的运行模式修改为模式3，按照表2 msOpST的运行模式修改
only_gen_without_run和only_run_without_gen参数的取值。不生成ST测试代码，只运行ST测试代码。 -
执行如下命令运行已修改的ST测试源码。
msopst run -i xx/AddCustom_case_timestamp.json -soc {soc version} -out ./output -conf xx/msopst.ini
-
-
-
-
-
若运行模式为仅生成ST测试用例代码，不执行ST测试用例，会在-out指定的目录下生成时间戳目录，时间戳目录下将生成以算子的OpType命名的存储测试用例代码的文件夹，目录结构如下所示：
{time_stamp} │ ├── OpType │ │ ├── CMakeLists.txt // 编译规则文件 │ │ ├── inc // 测试用例代码所用头文件 │ │ │ ├── common.h │ │ │ ├── op_execute.h │ │ │ ├── op_runner.h │ │ │ ├── op_test_desc.h │ │ │ └── op_test.h │ │ ├── run // 测试用例执行相关文件存储目录 │ │ │ └── out │ │ │ └── test_data │ │ │ └── config │ │ │ └── acl.json //用于进行acl初始化，请勿修改此文件 │ │ │ └── acl_op.json // 用于构造单算子模型文件的算子描述文件 │ │ │ └── data │ │ │ └── expect │ │ │ └── Test_xxx.bin │ │ ├── src │ │ │ └── CMakeLists.txt // 编译规则文件 │ │ │ └── common.cpp // 公共函数，读取二进制文件函数的实现文件 │ │ │ └── main.cpp // 初始化算子测试用例并执行用例 │ │ │ └── op_execute.cpp //针对单算子调用的AscendCL接口进行了封装 │ │ │ └── op_runner.cpp //加载单算子模型文件进行执行的接口进行了封装 │ │ │ └── op_test.cpp //定义了算子的测试类 │ │ │ └── op_test_desc.cpp //对算子测试用例信息的加载和读入 │ │ │ └── testcase.cpp //测试用例的定义文件 -
若运行模式为既生成ST测试代码，又运行ST测试代码，命令执行完成后，会打印测试用例执行结果，并会在-out指定的目录下生成时间戳目录，时间戳目录下将生成以算子的OpType命名的存储测试用例及测试结果的文件夹，目录结构如下所示：
{time_stamp} │ ├── OpType │ │ ├── build │ │ │ └── intermediates //编译产生中间文件 │ │ │ └── xxx │ │ ├── CMakeLists.txt // 编译规则文件 │ │ ├── inc │ │ │ ├── common.h │ │ │ ├── op_execute.h │ │ │ ├── op_runner.h │ │ │ ├── op_test_desc.h │ │ │ └── op_test.h │ │ ├── run // 测试用例执行相关文件存储目录 │ │ │ └── out │ │ │ ├── fusion_result.json │ │ │ ├── main // 算子测试用例执行的可执行文件 │ │ │ ├── op_models // 单算子的离线模型文件 │ │ │ ├── xx.om │ │ │ ├── result_files │ │ │ ├── result.txt │ │ │ ├── Test_xxx_output_x.bin // 运行测试用例生成的结果数据的二进制文件 │ │ │ └── test_data //测试数据相关文件存储目录 │ │ │ ├── config │ │ │ ├── acl_op.json // 用于构造单算子模型文件的算子描述文件 │ │ │ ├── acl.json //用于进行acl初始化，请勿修改此文件 │ │ │ ├── data //构造的测试数据 │ │ │ ├──expect │ │ │ ├──Test_xxxx.bin //期望的输出结果的二进制文件 │ │ │ ├──st_error_reports │ │ │ ├──Test_xxxx.csv //用于保存比对结果不一致的数据 │ │ │ ├──Test_xxxx.bin //测试数据的二进制文件 │ │ └── src │ │ ├── CMakeLists.txt // 编译规则文件 │ │ ├── common.cpp // 公共函数，读取二进制文件函数的实现文件 │ │ ├── main.cpp // 初始化算子测试用例并执行用例 │ │ ├── op_execute.cpp //针对单算子调用的AscendCL接口进行了封装 │ │ ├── op_runner.cpp //加载单算子模型文件进行执行的接口进行了封装 │ │ ├── op_test.cpp //定义了算子的测试类 │ │ ├── op_test_desc.cpp //对算子测试用例信息的加载和读入 │ │ └── testcase.cpp //测试用例的定义文件 │ └── st_report.json //运行报表命令运行成功后，会生成报表st_report.json，记录了测试的信息以及各阶段运行情况，用户运行出问题以后，可基于报表查询运行信息，以便问题定位。同时，st_report.json报表可以对比测试结果。st_report.json保存在图1 运行结果示例中“The st_report saved in”路径下。
表 3 st_report.json报表主要字段及含义
- expect_data_path：期望计算结果路径。
- case_name：测试用例名称。
- input_data_path：输入数据路径。
- planned_output_data_paths：实际计算结果输出路径。
- op_params：算子参数信息。
- status：阶段运行状态，表示运行成功或者失败。
- result：输出结果
- stage_name：阶段名称。
- cmd：运行命令。
-
-
根据运行环境的架构在开发环境上搭建环境。
-
ST测试用例执行时，会使用AscendCL接口加载单算子模型文件并执行，需要在开发环境上根据运行环境的架构配置AscendCL应用编译所需其他环境变量。
-
当开发环境和运行环境架构相同时，环境变量如下所示。
export DDK_PATH=${INSTALL_DIR} export NPU_HOST_LIB=${INSTALL_DIR}/{arch-os}/devlib -
当开发环境和运行环境架构不同时，环境变量如下所示。
export DDK_PATH=${INSTALL_DIR}/{arch-os} export NPU_HOST_LIB=${INSTALL_DIR}/{arch-os}/devlib
Note
${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。以root用户安装为例，安装后文件默认存储路径为：/usr/local/Ascend/cann。- {arch-os}中arch表示操作系统架构（需根据运行环境的架构选择），os表示操作系统（需根据运行环境的操作系统选择）。
-
-
-
在开发环境启动msOpST工具的高级功能，仅生成ST测试用例。
-
执行命令，编辑msopst.ini文件。
vim ${INSTALL_DIR}/python/site-packages/bin/msopst.ini -
将msOpST工具的运行模式修改为模式2，按照表2 msOpST的运行模式修改“only_gen_without_run“和“only_run_without_gen“参数的取值。只生成ST测试代码，不运行ST测试代码。
-
若开发环境和运行环境架构不同，按照表1 msopst.ini文件参数说明修改“HOST_ARCH“和“TOOL_CHAIN“参数的取值。
-
执行如下命令生成ST测试源码。
msopst run -i xx/AddCustom_case_timestamp.json -soc {soc version} -out {output path} -conf xx/msopst.ini-conf参数请修改为msopst.ini配置文件的实际路径。
ST测试用例生成后，用户可根据需要自行修改ST测试用例代码。
-
执行完成后，将在{output path}下生成ST测试用例，并使用g++编译器生成可执行文件main。同时，屏幕打印信息中展示此次一共运行几个用例，测试用例运行的情况，并生成报表st_report.json，保存在打印信息中“The st report saved in”所示路径下，报表具体信息请参见表3 st_report.json报表主要字段及含义。
-
-
执行测试用例。
-
将开发环境的算子工程目录的run目录下的out文件夹拷贝至运行环境任一目录，例如上传到
${INSTALL_DIR}/Ascend_project/run_add/目录下。 -
在运行环境中执行out文件夹下的可执行文件。
进入out文件夹所在目录，执行如下命令：
chmod +x main ./main
-
-
执行完成后，打印信息提示此次用例运行的情况，如图2 运行结果所示。
生成单算子上板测试框架
通过指定Ascend C算子的ST测试用例定义文件（.json）和实现文件kernel_name.cpp，自动生成调用核函数的上板测试框架，进行算子的测试验证，最终查看输出结果确认算子功能是否正确。
Note
- 该功能仅支持Atlas 推理系列产品和Atlas 训练系列产品，不支持Atlas A2 训练系列产品/Atlas A2 推理系列产品和Atlas A3 训练系列产品/Atlas A3 推理系列产品。
- 所有参数不支持输入addr及tiling属性。
- 支持使用#ifndef__CCE_KT_TEST__对核函数的调用进行封装的场景。
-
请用户完成以下输入文件的准备工作。
- 算子ST测试用例定义文件（*.json文件）。
- Kernel侧算子实现文件（*.cpp文件），具体可参考《Ascend C算子开发指南》中的“算子实现 > 工程化算子开发 > Kernel侧算子实现”章节。
-
生成调用Kernel函数的测试代码，执行如下命令，具体参数介绍请参见生成单算子上板测试框架参数说明。
msopst ascendc_test -i xx/OpType_case.json -kernel xx/add_custom.cpp -out ./output_data -
查看执行结果。
命令执行完成后，会打印"Process finished!"提示信息，并会在-out指定的目录下生成时间戳目录，时间戳目录下将生成以算子的OpType命名的存储测试用例及测试结果的文件夹，目录结构如下所示：
{time_stamp} │ ├── OpType │ │ ├── CMakeLists.txt // 编译规则文件 │ │ ├── data │ │ │ └── xx.bin │ │ │ └── xx.bin │ │ ├── data_utils.h │ │ ├── main.cpp // 测试框架 │ │ └── run.sh // 调用测试框架的脚本文件 │ └── st_report.json //运行报表命令运行成功后，会生成报表st_report.json，记录了测试的信息以及各阶段运行情况，用户运行出问题以后，可基于报表查询运行信息，以便问题定位。同时，st_report.json报表可以对比测试结果。
st_report.json保存在如下“The st_report saved in”路径中。
2024-01-17 08:40:55 (3271037) - [INFO] Create 1 sub test cases for Test_AddCustom_001. 2024-01-17 08:40:55 (3271037) - [INFO] [STEP2] [data_generator.py] Generate data for testcase. 2024-01-17 08:40:55 (3271037) - [INFO] Start to generate the input data for Test_AddCustom_001_case_001_ND_float. 2024-01-17 08:40:55 (3271037) - [INFO] Generate data for testcase in $HOME/AddCustom/output/20240117084055/AddCustom/data. 2024-01-17 08:40:55 (3271037) - [INFO] [STEP3] [gen_ascendc_test.py] Generate test code of calling of kernel function for AscendC operator. 2024-01-17 08:40:55 (3271037) - [INFO] Content appended to $HOME/AddCustom/output/20240117084055/AddCustom/main.cpp successfully. 2024-01-17 08:40:55 (3271037) - [INFO] AscendC operator test code files for kernel implement have been successfully generated. 2024-01-17 08:40:55 (3271037) - [INFO] If you want to execute kernel function in Ascend aihost or cpu, please execute commands: cd $HOME/AddCustom/output/20240117084055/AddCustom && bash run.sh <KERNEL_NAME>(add_custom) <SOC_VERSION>(ascendxxxyy) <CORE_TYPE>(AiCore/VectorCore) <RUN_MODE>(cpu/npu). For example: cd $HOME/AddCustom/output/20240117084055/AddCustom && bash run.sh add_custom ascendxxxyy AiCore npu 2024-01-17 08:40:55 (3271037) - [INFO] Process finished! 2024-01-17 08:40:55 (3271037) - [INFO] The st report saved in: $HOME/AddCustom/output/20240117084055/st_report.json.表 1 st_report.json报表主要字段及含义
- expect_data_path：期望计算结果路径。
- case_name：测试用例名称。
- input_data_path：输入数据路径。
- planned_output_data_paths：实际计算结果输出路径。
- op_params：算子参数信息。
- status：阶段运行状态，表示运行成功或者失败。
- result：输出结果。
- stage_name：阶段名称。
- cmd：运行命令。
-
修改run.sh文件中的ASCEND_HOME_DIR。
ASCEND_HOME_DIR为CANN软件包安装路径，请根据实际情况进行修改。
# 指向昇腾软件包安装地址，导出环境变量 if [ ! $ASCEND_HOME_DIR ]; then export ASCEND_HOME_DIR=${INSTALL_DIR} fi source $ASCEND_HOME_DIR/bin/set_env.bash -
进入执行测试框架的脚本文件所在目录，如下命令进行测试框架代码的上板验证。
bash run.sh <kernel_name> <soc_version> <core_type> <run_mode>表 2 脚本参数介绍
脚本执行完毕会出现类似如下打印，输出"succeed"字样表示完成上板验证。
INFO: compile op on npu succeed! [INFO] Succeeded to exec acl api aclrtCreateContext(&context, deviceId) [INFO] Succeeded to exec acl api aclrtCreateStream(&stream) [INFO] Succeeded to exec acl api aclrtMallocHost((void**)(&xHost), xByteSize) [INFO] Succeeded to exec acl api aclrtMalloc((void**)&xDevice, xByteSize, ACL_MEM_MALLOC_HUGE_FIRST) [INFO] Succeeded to exec acl api aclrtMemcpy(xDevice, xByteSize, xHost, xByteSize, ACL_MEMCPY_HOST_TO_DEVICE) [INFO] Succeeded to exec acl api aclrtMallocHost((void**)(&yHost), yByteSize) [INFO] Succeeded to exec acl api aclrtMalloc((void**)&yDevice, yByteSize, ACL_MEM_MALLOC_HUGE_FIRST) [INFO] Succeeded to exec acl api aclrtMemcpy(yDevice, yByteSize, yHost, yByteSize, ACL_MEMCPY_HOST_TO_DEVICE) [INFO] Succeeded to exec acl api aclrtMallocHost((void**)(&zHost), zByteSize) [INFO] Succeeded to exec acl api aclrtMalloc((void**)&zDevice, zByteSize, ACL_MEM_MALLOC_HUGE_FIRST) [INFO] Succeeded to exec acl api aclrtSynchronizeStream(stream) [INFO] Succeeded to exec acl api aclrtMemcpy(zHost, zByteSize, zDevice, zByteSize, ACL_MEMCPY_DEVICE_TO_HOST) [INFO] aclrtDestroyStream successfully. INFO: execute op on npu succeed!
输出说明
- 生成/执行测试用例输出结果请参见开发环境与运行环境合设场景输出结果和开发环境与运行环境分设场景输出结果。
- 生成单算子上板测试框架输出结果请参见步骤5-脚本执行完毕打印。