自定义算子工程生成工具

功能描述

原始框架类型为MindSpore的算子，自定义算子工程生成工具可根据原型定义文件输出算子开发相关交付件，包括算子实现和算子信息文件、算子原语文件。

工具说明

通过可执行文件“msopgen”生成自定义算子工程，其功能和安装路径如下。

使用前提

• CANN组合包提供进程级环境变量设置脚本，供用户在进程中引用，以自动完成环境变量设置。执行命令参考如下，以下示例均为root或非root用户默认安装路径，请以实际安装路径为准。

  # 以root用户安装toolkit包
  . /usr/local/Ascend/ascend-toolkit/set_env.sh 
  # 以非root用户安装toolkit包
  . ${HOME}/Ascend/ascend-toolkit/set_env.sh 

• 安装依赖（可选）：

  pip3 install xlrd==1.2.0

  工具输入为IR原型定义Excel文件时，需要安装xlrd依赖。

• 安装mindspore框架，安装方法参见MindSpore官网。

使用方法

1. 准备输入文件

   自定义算子工程生成工具支持输入三种类型文件创建算子工程，分别为：

   • 适配昇腾AI处理器算子IR定义文件（.json）
   • TensorFlow的原型定义文件（.txt）

     MindSpore算子工程创建支持以TensorFlow框架原型定义文件做为输入。

   • 适配昇腾AI处理器算子IR定义文件（.xlsx）

   请用户选择一种文件完成输入文件的准备工作。

   • 适配昇腾AI处理器算子IR定义的json文件的准备工作
     • 用户可从CANN组件路径“python/site-packages/op_gen/json_template”获取模板文件

       MS_json.json进行修改，其参数配置说明请参见表2：

       表2 MindSpore算子工程json文件配置参数说明

       配置字段		类型	含义	是否必选
       op	-	字符串	算子的Operator Type。	是
       input_desc	-	列表	输入参数描述。	否
       	name	字符串	算子输入参数的名称。
       	param_type	字符串	参数类型： required optional dynamic 未配置默认为required
       	type	列表	算子参数的类型。 包含如下取值： I8_Default,I16_Default,I32_Default,I64_Default,U8_Default,U16_Default,U32_Default,U64_Default,BOOL_Default等。
       output_desc	-	列表	输出参数描述。	是
       	name	字符串	算子输出参数的名称。
       	param_type	字符串	参数类型： required optional dynamic 未配置默认为required
       	type	列表	算子参数的类型。 包含如下取值： I8_Default,I16_Default,I32_Default,I64_Default,U8_Default,U16_Default,U32_Default,U64_Default,BOOL_Default等。
       attr	-	列表	属性描述。	否
       	name	字符串	算子属性参数的名称。
       	param_type	字符串	参数类型： required optional 未配置默认为required
       	type	字符串	算子参数的类型。 包含如下取值： I8_Default,I16_Default,I32_Default,I64_Default,U8_Default,U16_Default,U32_Default,U64_Default,BOOL_Default等。
       	default_value	-	默认值。

       

       json文件可以配置多个算子，json文件为列表，列表中每一个元素为一个算子。

       • 若存在op同名算子，会以后一算子创建算子工程。
       • 若input_desc或output_desc中的name参数相同，则后一个会覆盖前一参数。
       • 更多type取值请参见MindSpore官方提供的DataType。
   • TensorFlow的原型定义文件（.txt）的准备工作。

     TensorFlow的原型定义文件（.txt）中内容可从TensorFlow开源社区获取，例如，Add算子的原型定义在TensorFlow开源社区中/tensorflow/core/ops/math_ops.cc文件中，在文件中搜索“Add”找到Add对应的原型定义，内容如下所示：

     REGISTER_OP("Add")
         .Input("x: T")
         .Input("y: T")
         .Output("z: T")
         .Attr(
             "T: {bfloat16, half, float, double, uint8, int8, int16, int32, int64, "
             "complex64, complex128, string}")
         .SetShapeFn(shape_inference::BroadcastBinaryOpShapeFn);

     将以上内容另存为**.txt文件。

     

     每个**.txt文件仅能包含一个算子的原型定义。

     自定义算子工程生成工具只解析算子类型、Input、Output、Attr中内容，其他内容可以不保存在**.txt中。

   • 适配昇腾AI处理器算子IR定义的Excel文件准备工作

     用户可从CANN安装路径下的“toolkit/tools/msopgen/template”目录下获取模板文件Ascend_IR_Template.xlsx进行修改。请基于“Op”页签进行修改，“Op”页签可以定义多个算子。配置示例如下所示：

     表3 IR原型定义表示例

     预留行								-
     Op	Classify	Name	Type	TypeRange	Required	Doc	Attr_Default_value	Format
     Reshape	INPUT	x	tensor	I8_Default,I16_Default,I32_Default,I64_Default,U8_Default,U16_Default,U32_Default,U64_Default,BOOL_Default	TRUE	-	-	ND
     	INPUT	shape	tensor	I32_Default,I64_Default	FALSE	-	-	-
     	DYNAMIC_OUTPUT	y	tensor	I8_Default,I16_Default,I32_Default,I64_Default,U8_Default,U16_Default,U32_Default,U64_Default,BOOL_Default	FALSE	-	-	ND
     	ATTR	axis	int	-	FALSE	-	0	-
     	ATTR	num_axes	int	-	FALSE	-	-1	-
     ReshapeD	INPUT	x	tensor	I8_Default,I16_Default,I32_Default,I64_Default,U8_Default,U16_Default,U32_Default,U64_Default,BOOL_Default	TRUE	-	-	ND
     	OUTPUT	y	tensor	I8_Default,I16_Default,I32_Default,I64_Default,U8_Default,U16_Default,U32_Default,U64_Default,BOOL_Default	TRUE	-	-	ND
     	ATTR	shape	list_int	-	FALSE	-	{}	-
     	ATTR	axis	int	-	FALSE	-	0	-
     	ATTR	num_axes	int	-	FALSE	-	-1	-

     

     • 请直接基于模板文件的第一个页签“Op”进行修改，实现算子的原型定义输入文件。
     • 请不要删除“Op”页签的前三行以及列。
     • 在TypeRange中应填写MindSpore支持的类型，参见表5。

       若TypeRange中包含MindSpore不支持的类型时，则会出现告警。

2. 创建算子工程。

   进入msopgen工具所在目录执行如下命令，参数说明请参见表4。

   ./msopgen gen -i {operator define file} -f {framework type} -c {Compute Resource} -out {Output Path}

   表4 参数说明

   参数名称	参数描述	是否必选
   gen	用于生成算子开发交付件。	是
   -i， --input	算子定义文件路径，可配置为绝对路径或者相对路径。工具执行用户需要有此路径的可读权限。 算子定义文件支持如下三种类型： 适配昇腾AI处理器算子IR定义文件（.json） TensorFlow的原型定义文件（.txt） 适配昇腾AI处理器算子IR定义文件（.xlsx）	是
   -f， --framework	框架类型。 TensorFlow框架，参数值：tf或者tensorflow Caffe框架，参数值：caffe PyTorch框架，参数值：pytorch MindSpore框架，参数值：ms或者mindspore ONNX框架，参数值：onnx 说明： 所有参数值大小写不敏感。	是
   -c， --compute_unit	算子使用的计算资源。 针对TBE算子，配置格式为：ai_core-{Soc Version}，ai_core与{Soc Version}之间用中划线“-”连接。 请根据实际昇腾AI处理器版本进行选择。 说明： {Soc Version}可从CANN软件安装后文件存储路径的"compiler/data/platform_config"路径下查看支持的昇腾AI处理器的类型，对应“*.ini”文件的名字即为${soc_version}。 针对AI CPU算子，请配置为：aicpu。	是
   -out， --output	生成文件所在路径，可配置为绝对路径或者相对路径，并且工具执行用户具有可读写权限。 若不配置，则默认生成在执行命令的当前路径。	否
   -m， --mode	生成交付件模式。 0：创建新的算子工程，若指定的路径下已存在算子工程，则会报错退出。 1：在已有的算子工程中追加算子。 默认值：0。	否
   -op， --operator	此参数针对-i为算子IR定义文件的场景。 配置算子的类型，如：Conv2DTik。 若不配置此参数，当IR定义文件中存在多个算子时，工具会提示用户选择算子。	否

   示例：

   使用MS_json.json模板作为输入创建MindSpore框架适配Ascend910处理器的算子工程。

   1. 进入msopgen工具所在目录执行命令。
      TBE算子执行命令示例：

      ./msopgen gen -i json_path/MS_json.json -f ms -c ai_core-ascend910 -out ./output_data

      AI CPU算子执行命令示例：

      ./msopgen gen -i json_path/MS_json.json -f ms -c aicpu -out ./output_data

      -i 参数请输入MS_json.json实际绝对路径或相对路径。

      例如："${INSTALL_DIR}/toolkit/python/site-packages/op_gen/json_template/MS_json.json"

   2. 选择算子（可选）：
      • 若输入MS_json.json文件只有一个算子原型定义或使用-op参数指定算子类型请跳过此步骤。
      • 若输入MS_json.json文件中包含多个原型定义，且没有使用-op参数指定算子类型工具会提示输入选择的算子序号，选择算子。
   3. 查看算子工程目录：

      算子工程目录生成在 -out 所指定的目录下：./output_data。

      TBE算子工程目录结构如下所示：

      |——mindspore
           |——impl
               |--xx_impl.py      //实现算子和注册算子信息 py文件
           |——op_proto
               |--xx.py      //算子原语py文件

      AI CPU算子工程目录结构如下所示：

      ├── cpukernel
      │   ├── CMakeLists.txt
      │   ├── impl        //算子代码实现文件目录
      │   │   ├── xx_kernels.cc
      │   │   └── xx_kernels.h
      │   ├── op_info_cfg
      │   │   └── aicpu_kernel
      │   │       └── xx.ini      //算子信息库定义文件
      │   └── toolchain.cmake
      ├── framework      //算子插件实现文件目录
      │   ├──mindspore     //原始框架类型为MindSpore时生成的算子适配插件代码所在目录
      │       └── impl
      │   │       └── xx_impl.py      //实现算子和注册算子信息py文件
      │       └── op_proto
      │   │       └── xx.py      //算子原语py文件
      ├── op_proto     //算子原型定义文件及CMakeList文件所在目录   
      │   ├── xx.h
      │   ├── xx.cc
      │   ├── CMakeLists.txt
      ├── scripts     //自定义算子工程打包相关脚本所在目录

3. 在算子工程中追加算子（可选）。

   若需要在已存在的算子工程目录下追加其他自定义算子，请按照1准备输入文件**.json，并以**.json为输入。MindSpore AICPU算子工程不能够追加非MindSpore框架的算子，因为生成的交付件不同，也不能追加MindSpore TBE算子。再次执行此工具时添加“-m 1”参数，进入msopgen工具所在目录执行如下命令：

   ./msopgen gen -i json_path/**.json -f ms -c ai_core-ascend910 -out ./output_data -m 1

以上实现算子和注册算子信息文件、算子原语文件仅仅为工程生成的模板文件，目的为降低开发者的代码开发工作量，简化开发流程。具体实现代码需要参见MindSpore教程>自定义算子进行对应交付件的修改。