{operator_name} Blaze 算子设计文档【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills⚠️SubAgent 生成此文档时必须替换以下占位符{operator_name}→ 实际算子名称0. 概述0.1 基本信息项目内容算子名称算子类别MatMul / MatMulVector 融合 / MX 量化 MatMul / GroupMatmul需求类型特定用例shape[...], dtype... / 通用支持数据类型A , B , C 支持芯片Ascend950DAV_3510特殊约束0.2 用户原始需求#需求内容121. 算子设计1.1 数学公式输入: A - shape [M, K], dtype B - shape [K, N], dtype 输出: C - shape [M, N], dtype 数学公式: C f(A, B)1.2 数据流数据流应紧跟数学公式展开先说明逻辑计算如何映射到 GM/L1/L0/UB/GM再继续设计 Kernel、Epilogue、Tiling 和工程目录。纯 MatmulGM → L1 → L0A/L0B → MMAD → L0C → Fixpipe → GM普通 CV 融合场景GM → L1 → L0A/L0B → MMAD → L0C → Fixpipe(SPLIT_M) → UB → Epilogue → GMSplitM 说明DUAL_DST_SPLIT_M将 L0C 的 M 行对半切分到两个 AIV SubBlock。每个 AIV 从各自 UB offset 0 读取半份数据UB 读取不需要 sub-block 偏移GM 读写需要 sub-block 偏移。MX CV / Grouped CV 等特殊场景 请结合/ascendc-blaze-best-practice中对应场景文档补充 scale / groupList / context 等额外输入在数据流中的位置。1.3 Kernel 入口与组件组装参考/ascendc-blaze-best-practiceskill 的references/development/step2-kernel-design.md。开发路径决策决策项选择理由开发路径blaze_custom / blaze 库Dispatch modeNO_FULL_LOAD / A_FULL_LOAD / MatmulWithScaleMxTiling 引擎MatmulTilingSwat / MatmulTilingAFullLoad / QuantMatmulTilingSwatKernel 签名项目值修饰符__cube__/__mix__(aicCount, aivCount)GM_ADDR 参数dA, dB, [dScaleA, dScaleB,] [dBias,] dC, tilingData模板参数TransA, TransB [, CubeFormat]参考文档路径文档位置blaze_custom/ascendc-blaze-best-practice→references/modules/blaze-custom/blaze 库/ascendc-blaze-best-practice→references/modules/blaze-library/组件组装层代码库选用组件来源文件说明Launcher入口文件按 trans/format 分发Kernel循环驱动BlockMmadL1/L0/MMAD 流水Scheduler多核调度DispatchPolicydispatch tagEpilogue融合场景AIV 侧后处理tensor_api-Te::Copy/Mmad/Fixpipethird_party/tensor_api/硬件指令1.4 Epilogue 设计融合场景参考/ascendc-blaze-best-practicereferences/scenarios/fusion-matmul-development.mdreferences/modules/blaze-custom/development/epilogue-dev-guide.mdreferences/modules/blaze-custom/development/epilogue-membase-design.mdreferences/modules/blaze-custom/development/epilogue-regbase-design.md非融合场景本节简写“不涉及 Vector Epilogue”即可。Epilogue 基本信息项值是否融合场景是 / 否Epilogue 类型无 / RegBase / MemBase / 自定义开发路径blaze_custom / 不涉及Epilogue 文件op_kernel/include/blaze_custom/epilogue/{epilogue_name}.h/ 不涉及接口形式Init/GetTensor/operator()/ 不涉及普通 MatMul Vector 融合使用blaze_custom路线自定义 Epilogue 必须放在op_kernel/include/blaze_custom/epilogue/下不要放在op_kernel/顶层。公式分析步骤操作输入类型输出类型①CastL0CType → ComputeType②③CastComputeType → OutputTypedtype 链路L0CType ──Cast──▶ ComputeType ──[公式链]──▶ ComputeType ──Cast──▶ OutputType额外输入输入shapedtypebroadcastLoadDistUB 分区布局分区顺序Buffer 名称存储内容数据类型大小 / 行数生命周期说明1cLocal_L0C2UB 的 MatMul 结果L0CTypematmulAreaBytes或splitMRows × nAlign固定不可释放由 C 部分 Fixpipe 写入Epilogue 消费2extraBufA_额外输入 A如 per-channel scale / biasComputeType/ 输入 dtypenAlign × sizeof(T)或按设计填写tile 内复用 / stage 内复用列依赖输入通常按 tile 加载3extraBufB_额外输入 B如 per-token scale / row-dependent inputComputeType/ 输入 dtypestageRows × ...或按设计填写stage 级行依赖输入通常按 stage 加载4tmpBuf_中间结果仅 MemBase 需要ComputeType/OutputType按设计填写stage 级RegBase 一般不需要此块5outBuf_输出 stagingOutputTypestageRows × nAlignOut × sizeof(OutputType)stage 级DataCopyPad写回 GM 前的暂存区约束要求cLocal_优先级最高必须先保证 L0C2UB 的 MatMul 结果完整落入 UB。RegBase 路径优先将中间值保留在RegTensor减少tmpBuf_占用。MemBase 路径应显式列出tmpBuf_是否存在及其大小。所有依赖 M 维的额外输入必须说明其是否按 stage 加载以及 GM offset 是否受 SplitM /GetSubBlockIdx()影响。UB 预算汇总项公式 / 数值说明nAlignL0Cceil(baseN / (32/sizeof(L0CDataType))) * (32/sizeof(L0CDataType))UB 行对齐宽度不是L0C cube 边长 16splitMRowsceil(baseM / GetTaskRation())单个 AIV 的 MatMul 结果行数matmulAreaBytessplitMRows * nAlignL0C * sizeof(L0CDataType)L0C2UB 结果区行步长是nAlignL0CextraBufBytes所有额外输入 staging 总和tmpBufBytesMemBase 中间结果区RegBase 可填0outBufBytes输出 stagingremainBytesTOTAL_UB_SIZE - matmulAreaBytes供 Epilogue 使用的剩余空间totalEpilogueBytesextraBufBytes tmpBufBytes outBufBytesEpilogue 总占用可行性结论totalEpilogueBytes remainBytes/ 否是否满足 UB 预算同步指令清单同步方向指令用途必须性AIC → AIVCrossCoreSetFlag/CrossCoreWaitFlagAIC 通知 AIV 可以消费 UB 中 MatMul 结果CV 必需AIV → AICCrossCoreSetFlag/CrossCoreWaitFlagAIV 通知 AIC 可以继续覆盖 UBCV 必需MTE2 → VSetFlag/WaitFlagHardEvent::MTE2_V额外输入搬入完成后再开始 Vector 计算必需V → MTE2SetFlag/WaitFlagHardEvent::V_MTE2Vector 用完输入 buffer 后允许下一轮覆盖按 stage 复用时必需V → MTE3SetFlag/WaitFlagHardEvent::V_MTE3Vector 计算完成后才能启动写回必需MTE3 → VSetFlag/WaitFlagHardEvent::MTE3_V写回结束后允许下一轮 Vector 或 buffer 复用多轮 stage 时必需CopyL0C2UB Trait 选择Trait适用场景UB 数据分布CopyL0C2UBSplitMTraitDUAL_DST_SPLIT_M__mix__(1,2)标准 CVM 对半分片各 AIV 从各自 UB offset 0 读取CopyL0C2UBNonSplitTraitDUAL_DST_DISABLE单 AIV 调试全量数据在 UB offset 0__mix__(1,2)CV 场景必须使用CopyL0C2UBSplitMTrait。matmul_block_mmad.h参考模板已默认使用 SplitMTrait。SplitM 偏移参考表操作是否需要 SubBlock 偏移公式UB 读取 cLocal_否cLocal_.GetPhyAddr() row * nAlignGM 读取 row-dependent input是stageM0 tileM0 GetSubBlockIdx() * halfM stageRowOffsetGM 写回 output是gmRowOffset subM0 * N tileN0关键GM 侧 offset 需要加 sub-block 偏移UB 侧不需要。DUAL_DST_SPLIT_M硬件已自动分片UB 读取从 offset 0 开始。localRows0 时如 curM1 时 V1early return 即可CV 同步由 kernel 层处理。DataCopyPad stride 单位方向srcStridedstStrideGM → UBbytes32 字节单位UB → GM32 字节单位bytes当 UB 行按nAlign对齐排布时nAlign * sizeof(T)是 32 的倍数UB 侧 stride 恒等于 0直接传0。Epilogue 实现伪代码必须含同步指令本节必须给出可实现级伪代码而不只是数学公式。伪代码至少应覆盖Init/GetTensor/operator()三接口的职责SplitM /GetTaskRation()/GetSubBlockIdx()对行数和 offset 的影响extra input 的 GM offset 与加载顺序MTE2 / V / MTE3的同步指令输出写回顺序tail tile / ODD-M / ODD-N 的处理要点Init(params, baseM, baseN, problemShape): // 1. 绑定额外输入和输出 GM 地址 // 2. 计算 cLocal_ / extraBuf / tmpBuf / outBuf 的 UB 偏移 // matmulAreaBytes splitMRows * nAlignL0C * sizeof(L0CDataType) // 行步长是 nAlignL0C不是 L0C cube 边长 16 // 3. 预发射首轮反向依赖 // SetFlagV_MTE2(eventID) — 每个 stage 级 extra input buffer 各一个 // SetFlagMTE3_V(0) — output buffer // 注意tile 级与 stage 级 extra input 使用不同 eventID如 0 和 1 GetTensor(): // 返回 L0C2UB 的目标 UB Tensor通常为 cLocal_ operator()(blockShape, gmOffset, flagId): // 1. 计算 SplitM 行数 // halfM ceilDiv(curM, GetTaskRation()) // localRows (curM odd) ? (halfM - GetSubBlockIdx()) : halfM // 若 localRows 0: return // V1 无数据CV 同步由 kernel 层处理 // 2. 计算 GM offset需要 sub-block 偏移 // subM0 tileM0 GetSubBlockIdx() * halfM // 3. UB 读取从 offset 0不需要 sub-block 偏移SplitM 已硬件分片 // 4. 按 stage 循环处理 localRows // ---- tile 级 extra input加载一次跨 stage 只读复用---- WaitFlagV_MTE2(tileEventID) DataCopyPad(extraBufA_, ...) // GM→UB, dstStride0 (UB 32B 对齐) SetFlagMTE2_V(tileEventID); WaitFlagMTE2_V(tileEventID) for each stage: // stage 级 extra input每 stage 覆盖GM offset 含 sub-block 偏移 WaitFlagV_MTE2(stageEventID) DataCopyPad(extraBufB_, ...) // GM→UB, dstStride0 SetFlagMTE2_V(stageEventID); WaitFlagMTE2_V(stageEventID) WaitFlagMTE3_V(0) // 等上一轮 MTE3 读完 outBuf_ __VEC_SCOPE__ / Vector compute: // 从 cLocal_ offset 0 读取SplitM 已硬件分片 // Load / Cast / [USER COMPUTE] / Store SetFlagV_MTE2(stageEventID) // 通知可覆盖 extraBufB_ SetFlagV_MTE3(0); WaitFlagV_MTE3(0) DataCopyPad(outputGM[subM0*N tileN0 stageOffset*N], ...) // UB→GM, srcStride0 SetFlagMTE3_V(0) // 通知可覆盖 outBuf_ SetFlagV_MTE2(tileEventID) // 通知可覆盖 extraBufA_ ~Destructor(): // 排空所有反向依赖的 WaitFlag1.5 Tiling 设计必须加载/ascendc-blaze-best-practice优先查阅references/tiling/tiling-selection.md结合当前场景查找可复用的 Blaze tiling 实现并写明具体来源文件。禁止只写“使用 MatmulTilingSwat”而不说明文件和字段映射。项目值场景基础 MatMul / 普通 CV / MX CV / GroupMatMul复用 tiling 实现MatmulTilingSwat / MatmulTilingAFullLoad / QuantMatmulTilingSwat / Group... / 自定义派生来源文件/ascendc-blaze-best-practice中的具体文件是否需要改造是 / 否改造原因dtype / layout / full-load / group / epilogue buffer / 其他TilingData 目标文件op_tiling/{operator_name}_tiling_data.hTiling 计算目标文件op_tiling/{operator_name}_tiling.hbaseMbaseNbaseKL1 depth (depthA1/depthB1)kL1usedCoreNum强制动态计算dbL0cTilingData 字段规划字段类型说明m, n, kuint32_t矩阵维度baseM, baseN, baseKuint32_ttile 尺寸...Tiling 字段映射DESIGN 字段对应 Blaze Params 字段来源结构体/文件说明baseMbaseNbaseKkL1usedCoreNuml0cDB1.6 工程目录目标设计本节基于 §1.3 组件组装、§1.4 Epilogue 设计和 §1.5 Tiling 设计推导最终工程目录结构。目标目录必须以/ascendc-direct-invoke-template的 Blaze 样例工程结构为基础并结合本算子的开发场景确定不要混用 Add/Vector 模板的op_host/结构。1.6.1 模板来源与开发场景项值模板 skill/ascendc-direct-invoke-template样例目录references/matmul_blaze_template/样例默认场景MX 量化 MatMul 示例本算子场景纯 MatMul / 普通 CV 融合 / MX CV / GroupMatMul目标开发路径blaze library / blaze_custom / 受控组合是否需要自定义 Epilogue是 / 否是否需要 PyTorch 接入是 / 否1.6.2 目标目录结构根据本算子实际选用的库和模块填写目标目录。普通 CV 融合示例operators/{operator_name}/ ├── CMakeLists.txt ├── run.sh ├── README.md ├── {operator_name}.cpp ├── test_{operator_name}_torch.py ├── common/ │ ├── acl_utils.h │ ├── common_utils.h │ └── io_utils.h ├── op_kernel/ │ ├── {operator_name}_kernel.h │ ├── {operator_name}_kernel.cpp │ └── include/ │ ├── blaze/ │ ├── tensor_api/ │ └── blaze_custom/ │ ├── block/ │ ├── kernel/ │ ├── policy/ │ ├── utils/ │ └── epilogue/ │ └── {epilogue_name}.h ├── op_tiling/ │ ├── {operator_name}_tiling_data.h │ └── {operator_name}_tiling.h ├── op_extension/ │ ├── {operator_name}_torch.cpp │ ├── register.cpp │ └── ops.h └── scripts/ ├── gen_data.py ├── golden.py └── verify_result.py目录约束路径约束op_kernel/include/blaze/外部 Blaze 依赖可保留不做业务改写op_kernel/include/tensor_api/外部 tensor_api 依赖可保留不做业务改写op_kernel/include/blaze_custom/自定义 Blaze 组件路径只有选择 blaze_custom、CV 融合或受控组合时使用op_kernel/include/blaze_custom/epilogue/普通 CV 融合自定义 Epilogue 必须放在此处op_kernel/顶层只放目标 Kernel 入口/Wrapper不放自定义 Epilogue 组件工程根目录Blaze 样例 launcher 与 torch 测试在根目录改造不引入op_host/scripts/只保留目标算子的输入生成、Golden 和验证脚本1.6.3 样例工程改造映射复制references/matmul_blaze_template/后必须按下表将样例业务文件改造成目标算子文件。不能仅从 CMake 中移除后保留未使用的样例业务文件。样例文件/目录本算子处理方式目标文件/目录依据test_matmul_blaze.cpp重命名并改写 / 删除{operator_name}.cpp根目录 launchertest_matmul_blaze_torch.py重命名并改写 / 删除test_{operator_name}_torch.pyPyTorch 测试入口op_kernel/matmul_blaze_kernel.h重命名并改写 / 删除op_kernel/{operator_name}_kernel.hKernel 类型链op_kernel/matmul_blaze_kernel.cpp重命名并改写 / 删除op_kernel/{operator_name}_kernel.cppKernel wrapperop_extension/matmul_blaze_torch.cpp重命名并改写 / 删除op_extension/{operator_name}_torch.cppPyTorch extensionop_extension/register.cpp改写后保留 / 删除op_extension/register.cpp注册目标算子op_extension/ops.h改写后保留 / 删除op_extension/ops.h声明目标算子op_tiling/matmul_tiling_data.h重命名并改写 / 删除op_tiling/{operator_name}_tiling_data.hTilingDataop_tiling/matmul_tiling_stub.h改写为正式 tiling / 删除op_tiling/{operator_name}_tiling.hmock tiling 不进入正式实现scripts/gen_data_mxfp8.py改写 / 删除scripts/gen_data.py非 MX 场景不得保留 MX 语义scripts/gen_data_mxfp4.py改写 / 删除scripts/gen_data.py或删除非 FP4 场景不得保留scripts/verify_result.py改写后保留scripts/verify_result.py精度验证common/保留common/ACL/IO 工具op_kernel/include/blaze/保留op_kernel/include/blaze/外部依赖op_kernel/include/tensor_api/保留op_kernel/include/tensor_api/外部依赖op_kernel/include/blaze_custom/保留并扩展 / 删除op_kernel/include/blaze_custom/自定义组件1.6.4 CMake target 源文件设计Target源文件{operator_name}{operator_name}.cpp;op_kernel/{operator_name}_kernel.cpp{operator_name}_opsop_kernel/{operator_name}_kernel.cpp;op_extension/{operator_name}_torch.cpp;op_extension/register.cpp未列入上述 target 的样例业务源文件不应保留在工程中blaze/、tensor_api/、blaze_custom/公共头文件除外。2. 确认清单数据流已明确§1.2Kernel 入口签名已明确§1.3开发路径已决策blaze_custom / blaze 库§1.3各层组装组件已选定§1.3融合场景UB 分区已规划§1.4Tiling 引擎已选择§1.5工程目录目标和样例改造映射已明确§1.6分支场景已覆盖CV 融合专项确认CopyL0C2UB Trait 已选为CopyL0C2UBSplitMTraitDUAL_DST_SPLIT_MUB 读取 cLocal_ 不含 sub-block 偏移SplitM 已硬件分片matmulAreaBytes行步长为nAlignL0C非 L0C cube 边长 16DataCopyPad UB 侧 stride 传 0nAlign 保证 32B 对齐GM 侧 stride 传 bytestile 级与 stage 级 extra input 使用不同 eventID避免假依赖Init 预发射所有反向 SetFlag析构排空所有 WaitFlaglocalRows0边界场景已处理early returnCV 同步由 kernel 层处理per-callnAlign从blockShapeN计算非 Init 时baseN正确处理 tail tile【免费下载链接】cannbot-skillsCANNBot 是面向 CANN 开发的用于提升开发效率的系列智能体本仓库为其提供可复用的 Skills 模块。项目地址: https://gitcode.com/cann/cannbot-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考