| 算子名称 | XXX |
|---|---|
| 编制人/日期 | XXX/2021-12-27 |
| 修订人 | 修订日期 | 修订描述 |
|---|---|---|
| XXX | 2020-12-27 | 首次提交 |
本文档为 XXX 算子的设计文档，包括需求分析、接口设计、方案设计、性能优化记录。
- 算子接口描述
- 功能描述
- 框架版本 + 对应源码路径
- 需求对应网络
- 网络中用到的规模
- 是否需要支持原位
- 是否需要支持 stride 机制
- 框架单元测试阈值指标（可选）
该需求分析为框架原生算子实现功能的需求分析，对于框架原生支持但 MLU-OPS 当前版本不支持的功能，需要在1.4算子限制 章节中显式注明。未明确注明不支持的功能，默认 MLU-OPS 全部支持。
example:
| 算子功能简介 | 简要填写算子功能，详细描述在 1.2 中进行说明 |
|---|---|
| 需求来源 | PyTorch/TensorFlow/... |
| 应用网络 | resnet50/... |
| 输入数据类型 | half, float |
| 输入 Shape | input1: [batches, hi, wi, channels]; input2: [batches, 4] |
| 输入 Layout | input1: NHWC; input2: ARRAY |
| 输出数据类型 | half, float... |
| 输出 Shape | [batches, ho, wo, channels] |
| 输出 Layout | NHWC |
| 模式(可选） | |
| 是否含有 dim/axis 等类似语义的参数且该参数支持负数/其他特殊处理 | 有 dim/axis 参数且需要支持负数 / 不含带 dim/axis 语义的参数等 (例如 scatter 算子接口中的 dim 参数支持为负，当 dim=-1 时，实际在最低维上做计算) |
| 是否含有 labels/index 等类似语义的参数且该参数支持负数/界外情况/其他特殊处理 | 有 labels 参数，labels 取值在 dim 范围之外时输出为 Nan / 有 index 参数，要求 index 支持负数 / 不含带 labels/index 语义的参数等 (例如 sparse_softmax_ce_logits 算子支持 label 取值在 dim 范围之外，advanced_index 算子支持负数 index 等) |
| 是否需要支持原位 | 是/否 |
| 是否需要支持 stride 机制 | 是/否 |
| 是否需要支持广播 | 是/否 (若是，列清楚具体哪些参数要支持) |
| 0 元素检查是否直接返回 | 是/否 |
| 其他特殊需求(在线量化，融合，转数提前等，可选) | |
| 本次开发优先支持的规模/模式 | 优先支持 xxx 模式/NHWC 的 layout |
详细描述算子功能和应用场景，若有公式，详细描述公式。最好能给一个简单的 example。
备注：
1、需要根据算子算法的定义，考虑对边界值进行处理，比如 sign 算子，计算输出输入数据的符号，就需要考虑当输入是 0 的时候怎么处理，是否存在+0，-0 等。
2、index/axis 类的算子，可能存在 index 越界/负数 dim/axis 的情况，调研的时候需要注意。
| 参数 | 语义 | 类型（输入/输出） | 支持类型 | 物理布局 | 规模限制 |
|---|---|---|---|---|---|
| input1 | 输入 | half, float | NHWC | 无 | |
| input2 | 输入 | half, float | ARRAY | 无 | |
| mode | 输入 | / | 无 | ||
| output | 输出 | NHWC | 无 |
详细描述与框架需求相比，算子尚有哪些功能/模式/范围/数据类型/xxx 不支持。 使用表格或分段列出均可。
注意：凡是没有在此处列出，但最终被框架检测到的算子限制，均会被视为算子 bug。
在此处列出的限制，算子内做好防呆。
example:
| 限制类型 | 详细说明 |
|---|---|
| 数据类型限制 | 不支持 input 和 output 同时为 half |
| 布局限制 | 不支持 NCHW 的 Layout, 需要明确感知 layout 的算子才需要说明限制, 对于不需要感知 layout 的算子, 不要加额外的防呆 |
| 规模限制 | output_size <= 384KB |
| 功能限制 | 不支持 xxx 模式/不支持 xx 和 xxx 的模式组合 |
| 数据范围限制 | half 类型下，数据需满足[xx, xx]范围，否则有精度问题 |
| 原位限制 | 不支持原位 |
| stride 限制 | 不支持 stride 机制 |
| 广播限制 | xxx 参数不支持广播 |
| xx 限制 | xxx |
按照精度验收标准的要求明确本算子的精度标准。
例如：本算子属于纯 IO 类算子，验收标准为 diff3=0。
- TensorFlow
# 给出TensorFlow接口- PyTorch
# 给出PyTorch接口# 给出BANGPy MLU-OPS算子接口
# 算子接口名称(module参数)注意: 这里的 算子接口名称 的格式是 MluOp + 算子名称(首字母大写)，module参数 即执行 tcp.BuildBANG 时传入的 inputs + outputs 参数
可以在这里简单描述算子的整个流程，便于开发的时候理清楚思路，review 的同事对算子的实现有一个直观的理解。
一些基本的拆分原则：
1、拆分逻辑尽量保持均匀，避免出现负载不均衡，避免出现多核芯片单核工作，多核围观的情况出现。
2、尽可能保证拆分不会产生性能很差的 IO pattern，比如 stride 过大的访存，datasize 特别小的访存，非对齐的访存等等。
3、尽量保证拆分的时候不会造成重复的 IO，比如对 conv，如果对 HW 做拆分，由于有 kernel 的存在，hw 的 overlap 部分就会有重复的 IO。
4、拆分一定是和算子整体方案密切相关的，虽然模板把方案分成了几部分，但是这只是提醒大家关注这些重要的指标，并不是一部分一部分分开考虑的，最终方案肯定是拆分，资源分配，指令流水综合权衡得到的结果。
1、资源分配
| 表项 | 分配策略 |
|---|---|
| NRAM | 举例: 保存 node 数据 |
| WRAM | 举例: 保存卷积滤波张量数据 |
| SRAM | 举例：暂时存储 IO 的输入输出数据，卷积滤波张量最先 load 在 SM 上然后 broadcast |
| DRAM(workspace) | 举例：存储计算中的临时数据，比如 ci 拆分情况下的部分和 |
2、流水设计
BANGPy 具有自动流水的功能，使用 for_range 能够高效的构建多级流水，要说明是否使用了自动流水或针对哪一部分计算进行了自动流水处理，说明流水的结构，如 lcs ， llccs ， lclcs等，以及对于当前算子使用这种流水结构的目的或优点，关于自动流水的使用说明，可以参考 BANGPy用户手册 的6.1.4章节。
3、Autotuning
如果使用了autotuning功能，请说明搜索空间的生成规则和预计的搜索次数，关于autotuning的使用说明，可以参考 BANGPy用户手册 的6.2章节。
4、其他优化
其他针对不同情况下的输入，如不同的输入尺寸，所要做的特殊计算处理或多种流水处理也可以选择在这里进行说明，便于review。
1、对每一个函数命名变量命名都有充分的注释
2、避免魔鬼数字，对于确定的数字尽量使用全局变量来替代
3、代码风格遵守PEP8编码规范
-
算子在网络中用到的规模： xxx
-
边界 case： xxx
其他可根据需要进行补充。算子开发完毕后，补充测试报告链接。
- 列出算子需要做的防呆，比如
1、对于 nram/sram/wram 的使用 size 进行检查防呆；
2、test 方法中过滤掉未支持的 target ；
或其他的防呆内容，便于review。
只需列出在测试过程中发现的性能/精度异常的规模。
example:
| 提交日期 | 问题规模 | 问题描述 | 是否已修复 |
|---|---|---|---|
| 2021-9-8 | N >= 128 | 性能问题 | 是 |
| H >= 128 | 性能问题 | 否 | |
| W >= 128 | 精度问题 | 否 | |
| 2021-10-8 | C >= 128 | 精度问题 | 否 |
此项仅填写未在 4.1 中列出的规模，否则填入 4.1.
example:
| 提交日期 | 修复规模 | 修复问题 |
|---|---|---|
| 2021-9-8 | C == 1 | 性能提升 |
| 2021-10-8 | C 不对齐 | 精度修复 |