Matmul使用说明

Ascend C提供一组Matmul高阶API，方便用户快速实现Matmul矩阵乘法的运算操作。

Matmul的计算公式为：C = A * B + Bias，其示意图如下。

A、B为源操作数，A为左矩阵，形状为[M, K]；B为右矩阵，形状为[K, N]。
C为目的操作数，存放矩阵乘结果的矩阵，形状为[M, N]。
Bias为矩阵乘偏置，形状为[1, N]。对A*B结果矩阵的每一行都采用该Bias进行偏置。

图1 Matmul矩阵乘示意图

说明

下文中提及的M轴方向，即为A矩阵纵向；K轴方向，即为A矩阵横向或B矩阵纵向；N轴方向，即为B矩阵横向；尾轴，即为矩阵最后一个维度。

Kernel侧实现Matmul矩阵乘运算的步骤概括为：

创建Matmul对象。
初始化操作。
设置左矩阵A、右矩阵B、Bias。
完成矩阵乘操作。
结束矩阵乘操作。

使用Matmul API实现矩阵乘运算的具体步骤如下：

创建Matmul对象。

创建Matmul对象的示例如下：

默认为MIX模式（包含矩阵计算和矢量计算），该场景下通常不定义ASCENDC_CUBE_ONLY宏，如果在程序中使用了ASCENDC_CUBE_ONLY宏，则必须使用ASCEND_IS_AIC宏和ASCEND_IS_AIV宏将Cube计算和Vector计算隔离开。
纯Cube模式（只有矩阵计算）场景下，建议在代码中定义ASCENDC_CUBE_ONLY宏，避免额外的性能开销。

Text

// 纯cube模式（只有矩阵计算）场景下，需要设置该代码宏，并且必须在#include "lib/matmul_intf.h"之前设置
// #define ASCENDC_CUBE_ONLY
#include "lib/matmul_intf.h"

typedef AscendC::MatmulType<AscendC::TPosition::GM, CubeFormat::ND, half> aType;
typedef AscendC::MatmulType<AscendC::TPosition::GM, CubeFormat::ND, half> bType;
typedef AscendC::MatmulType<AscendC::TPosition::GM, CubeFormat::ND, float> cType;
typedef AscendC::MatmulType<AscendC::TPosition::GM, CubeFormat::ND, float> biasType;
AscendC::Matmul<aType, bType, cType, biasType> mm;

创建对象时需要传入A、B、C、Bias的参数类型信息，类型信息通过MatmulType来定义，包括：内存逻辑位置、数据格式、数据类型、数据来源的内存逻辑位置。

Text

template <
    AscendC::TPosition POSITION, CubeFormat FORMAT, typename TYPE, bool ISTRANS = false,
    LayoutMode LAYOUT = LayoutMode::NONE, bool IBSHARE = false, TPosition SRCPOS = TPosition::GM>
struct MatmulType {
    constexpr static AscendC::TPosition pos = POSITION;
    constexpr static CubeFormat format = FORMAT;
    using T = TYPE;
    constexpr static bool isTrans = ISTRANS;
    constexpr static LayoutMode layout = LAYOUT;
    constexpr static bool ibShare = IBSHARE;
    constexpr static TPosition srcPos = SRCPOS;
};

表1 MatmulType参数说明

参数	说明
POSITION	内存逻辑位置。针对Ascend 950PR/Ascend 950DT： A矩阵可设置为TPosition::GM，TPosition::VECOUT，TPosition::TSCM B矩阵可设置为TPosition::GM，TPosition::VECOUT，TPosition::TSCM Bias可设置为TPosition::GM，TPosition::VECOUT，TPosition::TSCM C矩阵可设置为TPosition::GM，TPosition::VECIN 注意，A矩阵、B矩阵或Bias矩阵设置为TPosition::VECOUT或TPosition::TSCM时，对应矩阵用于单核计算的数据必须全部在Unified Buffer或L1 Buffer上，具体样例请参考matmul_vecout样例、自定义数据来源为VECOUT的TSCM输入的Matmul算子样例、自定义数据来源为GM的TSCM输入的Matmul算子样例。针对Atlas A3 训练系列产品/Atlas A3 推理系列产品： A矩阵可设置为TPosition::GM，TPosition::VECOUT，TPosition::TSCM B矩阵可设置为TPosition::GM，TPosition::VECOUT，TPosition::TSCM Bias可设置为TPosition::GM，TPosition::VECOUT C矩阵可设置为TPosition::GM，TPosition::VECIN, TPosition::CO1 注意，C矩阵设置为TPosition::CO1时，C矩阵的数据排布格式仅支持CubeFormat::NZ，C矩阵的数据类型仅支持float、int32_t。针对Atlas A2 训练系列产品/Atlas A2 推理系列产品： A矩阵可设置为TPosition::GM，TPosition::VECOUT，TPosition::TSCM B矩阵可设置为TPosition::GM，TPosition::VECOUT，TPosition::TSCM Bias可设置为TPosition::GM，TPosition::VECOUT C矩阵可设置为TPosition::GM，TPosition::VECIN, TPosition::CO1 注意，C矩阵设置为TPosition::CO1时，C矩阵的数据排布格式仅支持CubeFormat::NZ，C矩阵的数据类型仅支持float、int32_t。针对Atlas 推理系列产品AI Core： A矩阵可设置为TPosition::GM，TPosition::VECOUT B矩阵可设置为TPosition::GM，TPosition::VECOUT Bias可设置为TPosition::GM，TPosition::VECOUT C矩阵可设置为TPosition::GM，TPosition::VECIN 针对Atlas 200I/500 A2 推理产品： A矩阵可设置为TPosition::GM B矩阵可设置为TPosition::GM Bias可设置为TPosition::GM C矩阵可设置为TPosition::GM 针对Kirin X90: A矩阵可设置为TPosition::GM，TPosition::VECOUT，TPosition::TSCM B矩阵可设置为TPosition::GM，TPosition::VECOUT, TPosition::TSCM Bias可设置为TPosition::GM，TPosition::VECOUT C矩阵可设置为TPosition::GM，TPosition::CO1 针对Kirin 9030： A矩阵可设置为TPosition::TSCM B矩阵可设置为TPosition::TSCM Bias可设置为TPosition::GM C矩阵可设置为TPosition::GM
FORMAT	数据的物理排布格式。针对Ascend 950PR/Ascend 950DT： A矩阵可设置为CubeFormat::ND，CubeFormat::NZ，CubeFormat::COLUMN_MAJOR，CubeFormat::VECTOR B矩阵可设置为CubeFormat::ND，CubeFormat::NZ，CubeFormat::COLUMN_MAJOR Bias可设置为CubeFormat::ND C矩阵可设置为CubeFormat::ND，CubeFormat::NZ，CubeFormat::ND_ALIGN，CubeFormat::COLUMN_MAJOR 针对Ascend 950PR/Ascend 950DT，请注意：仅在非MxMatmul场景中，A、B、C矩阵Format支持CubeFormat::COLUMN_MAJOR。当Format为CubeFormat::COLUMN_MAJOR时，对应矩阵仅支持内存逻辑位置为TPosition::GM。输入A矩阵或B矩阵设置为TPosition::TSCM时，对应的Format仅支持CubeFormat::NZ。 C矩阵设置为TPosition::VECIN，CubeFormat::ND时，要求尾轴32字节对齐，比如数据类型是half的情况下，N要求是16的倍数。针对Atlas A3 训练系列产品/Atlas A3 推理系列产品： A矩阵可设置为CubeFormat::ND，CubeFormat::NZ, CubeFormat::VECTOR B矩阵可设置为CubeFormat::ND，CubeFormat::NZ Bias可设置为CubeFormat::ND C矩阵可设置为CubeFormat::ND，CubeFormat::NZ，CubeFormat::ND_ALIGN 针对Atlas A2 训练系列产品/Atlas A2 推理系列产品： A矩阵可设置为CubeFormat::ND，CubeFormat::NZ, CubeFormat::VECTOR B矩阵可设置为CubeFormat::ND，CubeFormat::NZ Bias可设置为CubeFormat::ND C矩阵可设置为CubeFormat::ND，CubeFormat::NZ，CubeFormat::ND_ALIGN 针对Atlas 推理系列产品AI Core： A矩阵可设置为CubeFormat::ND，CubeFormat::NZ B矩阵可设置为CubeFormat::ND，CubeFormat::NZ Bias可设置为CubeFormat::ND C矩阵可设置为CubeFormat::ND，CubeFormat::NZ，CubeFormat::ND_ALIGN 注意：针对Atlas 推理系列产品AI Core，C矩阵设置为CubeFormat::ND时，要求尾轴32字节对齐，比如数据类型是half的情况下，N要求是16的倍数。针对Atlas 200I/500 A2 推理产品： A矩阵可设置为CubeFormat::ND，CubeFormat::NZ B矩阵可设置为CubeFormat::ND，CubeFormat::NZ Bias可设置为CubeFormat::ND C矩阵可设置为CubeFormat::ND，CubeFormat::NZ 针对Kirin X90: A矩阵可设置为CubeFormat::ND，CubeFormat::NZ, CubeFormat::VECTOR B矩阵可设置为CubeFormat::ND，CubeFormat::NZ Bias可设置为CubeFormat::ND C矩阵可设置为CubeFormat::ND，CubeFormat::NZ，CubeFormat::ND_ALIGN 针对Kirin 9030： A矩阵可设置为CubeFormat::NZ，CubeFormat::VECTOR B矩阵可设置为CubeFormat::NZ Bias可设置为CubeFormat::ND C矩阵可设置为CubeFormat::ND 注意: 针对Atlas 200I/500 A2 推理产品，C矩阵设置为TPosition::VECIN或者TPosition::TSCM，CubeFormat::ND时，要求尾轴32字节对齐，比如数据类型是half的情况下，N要求是16的倍数；C矩阵设置为TPosition::VECIN或者TPosition::TSCM，CubeFormat::NZ时，N要求是16的倍数。关于CubeFormat::NZ格式的A矩阵、B矩阵、C矩阵的对齐约束，请参考表3。
TYPE	数据类型。针对Ascend 950PR/Ascend 950DT： 1、非MxMatmul场景： A矩阵可设置为half、float、bfloat16_t 、int8_t、fp8_e4m3fn_t、fp8_e5m2_t、hifloat8_t B矩阵可设置为half、float、bfloat16_t 、int8_t、fp8_e4m3fn_t、fp8_e5m2_t、hifloat8_t Bias可设置为half、float、int32_t、bfloat16_t C矩阵可设置为half、float、bfloat16_t、int32_t、int8_t、fp8_e4m3fn_t、hifloat8_t 2、MxMatmul场景： A矩阵可设置为fp8_e4m3fn_t、fp8_e5m2_t、fp4x2_e2m1_t、fp4x2_e1m2_t B矩阵可设置为fp8_e4m3fn_t、fp8_e5m2_t、fp4x2_e2m1_t、fp4x2_e1m2_t Bias可设置为half、float、bfloat16_t C矩阵可设置为half、float、bfloat16_t 针对Atlas A3 训练系列产品/Atlas A3 推理系列产品： A矩阵可设置为half、float、bfloat16_t 、int8_t、int4b_t B矩阵可设置为half、float、bfloat16_t 、int8_t、int4b_t Bias可设置为half、float、int32_t C矩阵可设置为half、float、bfloat16_t、int32_t、int8_t 针对Atlas A2 训练系列产品/Atlas A2 推理系列产品： A矩阵可设置为half、float、bfloat16_t 、int8_t、int4b_t B矩阵可设置为half、float、bfloat16_t 、int8_t、int4b_t Bias可设置为half、float、int32_t C矩阵可设置为half、float、bfloat16_t、int32_t、int8_t 针对Atlas 推理系列产品AI Core： A矩阵可设置为half、int8_t B矩阵可设置为half、int8_t Bias可设置为float、int32_t C矩阵可设置为half、float、int8_t、int32_t 针对Atlas 200I/500 A2 推理产品： A矩阵可设置为half、float、bfloat16_t 、int8_t B矩阵可设置为half、float、bfloat16_t 、int8_t Bias矩阵可设置为half、float、int32_t C矩阵可设置为half、float、bfloat16_t、int32_t 针对Kirin X90: A矩阵可设置为half、int8_t B矩阵可设置为half、int8_t Bias可设置为half、int32_t C矩阵可设置为half、int32_t、int8_t 针对Kirin 9030： A矩阵可设置为half B矩阵可设置为half Bias可设置为half C矩阵可设置为half 注意：除fp8_e4m3fn_t/fp8_e5m2_t两种数据类型、B矩阵为int8_t数据类型外，A矩阵和B矩阵数据类型需要一致，具体数据类型组合关系请参考表2。A矩阵和B矩阵为int4b_t数据类型时，矩阵内轴的数据个数必须为偶数。例如，A矩阵为int4b_t数据类型且不转置时，singleCoreK必须是偶数。
ISTRANS	是否开启支持矩阵转置的功能。 true：开启支持矩阵转置的功能，运行时可以分别通过SetTensorA和SetTensorB中的isTransposeA、isTransposeB参数设置A、B矩阵是否转置。若设置A、B矩阵转置，Matmul会认为A矩阵形状为[K, M]，B矩阵形状为[N, K]。 false：默认值，不开启支持矩阵转置的功能，通过SetTensorA和SetTensorB不能设置A、B矩阵的转置情况。Matmul会认为A矩阵形状为[M, K]，B矩阵形状为[K, N]。注意，由于L1 Buffer上的矩阵数据有分形对齐的约束，A、B矩阵转置和不转置时所需的L1空间可能不相同，在开启支持矩阵转置功能时，必须保证按照Matmul Tiling参数申请的L1空间不超过L1 Buffer的规格，判断方式为(depthA1Ceil(baseM/c0Size)baseK + depthB1Ceil(baseN/c0Size)baseK) * db * sizeof(dtype) < L1Size，db表示L1是否开启double buffer，取值1（不开启double buffer）或2（开启double buffer），其余参数的含义请参考表1。 Kirin 9030不支持此参数。
LAYOUT	表征数据的排布。 NONE：默认值，表示不使用BatchMatmul；其他选项表示使用BatchMatmul。 NORMAL：BMNK的数据排布格式，具体可参考IterateBatch中对该数据排布的介绍。 BSNGD：原始BSH shape做reshape后的数据排布，具体可参考IterateBatch中对该数据排布的介绍。 SBNGD：原始SBH shape做reshape后的数据排布，具体可参考IterateBatch中对该数据排布的介绍。 BNGS1S2：一般为前两种数据排布进行矩阵乘的输出，S1S2数据连续存放，一个S1S2为一个batch的计算数据，具体可参考IterateBatch中对该数据排布的介绍。 Kirin 9030不支持此参数。
IBSHARE	是否开启IBShare（IntraBlock Share）。IBShare的功能是能够复用L1 Buffer上相同的A矩阵或B矩阵数据，复用的矩阵必须在L1 Buffer上全载。A矩阵和B矩阵仅有一个开启IBShare的场景，与IBShare模板配合使用，具体参数设置详见表2。注意，A矩阵和B矩阵同时开启IBShare的场景，表示L1 Buffer上的A矩阵和B矩阵同时复用，需要满足：同一算子中其它Matmul对象的A矩阵和B矩阵也必须同时开启IBShare； Atlas A2 训练系列产品/Atlas A2 推理系列产品，获取矩阵计算结果时，只支持调用IterateAll接口，且只支持输出到GlobalTensor，即计算结果放置于Global Memory的地址。 Atlas A3 训练系列产品/Atlas A3 推理系列产品，获取矩阵计算结果时，只支持调用IterateAll接口，且只支持输出到GlobalTensor，即计算结果放置于Global Memory的地址。 Ascend 950PR/Ascend 950DT，获取矩阵计算结果时，支持输出到GlobalTensor和LocalTensor。输出到LocalTensor，即计算结果放置于Local Memory的场景，默认实现策略与SplitM模板策略相同，且仅支持输出数据类型为float，仅支持Norm模板。 Ascend 950PR/Ascend 950DT支持该参数。 Atlas A3 训练系列产品/Atlas A3 推理系列产品支持该参数。 Atlas A2 训练系列产品/Atlas A2 推理系列产品支持该参数。 Atlas 推理系列产品AI Core不支持该参数。 Atlas 200I/500 A2 推理产品不支持该参数。 Kirin X90不支持此参数。 Kirin 9030不支持此参数。
SRC_POSITION	该参数仅支持Ascend 950PR/Ascend 950DT。 A/B矩阵的POSITION参数配置为TPosition::TSCM时，必须要设置TSCM中矩阵数据的来源的内存逻辑位置，默认为TPosition::GM。针对Ascend 950PR/Ascend 950DT： A矩阵可设置为TPosition::GM，TPosition::VECOUT B矩阵可设置为TPosition::GM，TPosition::VECOUT

表2 Matmul输入输出数据类型的支持列表

A矩阵	B矩阵	Bias	C矩阵	支持平台
float	float	float/half	float/half/bfloat16_t	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品 Atlas 200I/500 A2 推理产品
half	half	float	float	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品 Atlas 推理系列产品AI Core Atlas 200I/500 A2 推理产品
half	half	half	float/bfloat16_t	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品 Atlas 200I/500 A2 推理产品
int8_t	int8_t	int32_t	int32_t/half	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品 Atlas 推理系列产品AI Core Atlas 200I/500 A2 推理产品 Kirin X90
int4b_t	int4b_t	int32_t	int32_t/half	Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品
bfloat16_t	bfloat16_t	float	float	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品 Atlas 200I/500 A2 推理产品
bfloat16_t	bfloat16_t	half	float/half	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品
half	half	float	int8_t	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品
bfloat16_t	bfloat16_t	float	int8_t	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品
int8_t	int8_t	int32_t	int8_t	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品 Atlas 推理系列产品AI Core Kirin X90
half	half	float	half/bfloat16_t	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品 Atlas A2 训练系列产品/Atlas A2 推理系列产品 Atlas 推理系列产品AI Core Atlas 200I/500 A2 推理产品
half	half	half	half/bfloat16_t	Ascend 950PR/Ascend 950DT Atlas A3 训练系列产品/Atlas A3 推理系列产品

2.2.2. 数据结构

2.2.2.3. LocalTensor

2.2.2.4. GlobalTensor

2.2.3. 数据结构(TensorAPI，试验特性)

2.2.3.1. Layout数据结构

2.2.3.2. Tensor数据结构

2.2.3.3. 工具函数

2.2.4. 辅助数据结构

2.2.4.1. Coordinate

2.2.4.2. Layout

2.2.4.3. TensorTrait

2.2.4.6. TensorDesc

2.2.5. 数据搬运导览

2.2.5.1. 概览

2.2.6. 矩阵计算（ISASI）

2.2.6.1. 概述

2.2.6.2. 矩阵计算分形介绍

2.2.6.3. 矩阵计算的搬入

2.2.6.4. 矩阵搬入辅助配置接口

2.2.6.5. Mmad计算

2.2.6.6. Mmad计算关键特性说明

2.2.6.7. Mmad计算辅助配置接口

2.2.6.8. 矩阵计算的搬出

2.2.6.9. 矩阵搬出关键特性说明

2.2.6.10. 矩阵搬出辅助配置接口

2.2.7. 矩阵计算（Tensor API，试验特性）

2.2.7.2. 矩阵计算的搬入

2.2.7.3. Mmad计算

2.2.7.4. Mmad计算关键特性说明

2.2.7.6. 矩阵计算的搬出

2.2.7.7. 矩阵搬出关键特性说明

2.2.8. Memory矢量计算

2.2.8.2. SIMD计算说明

2.2.8.3. 数据搬运

2.2.8.4. 数据搬运辅助配置接口

2.2.8.5. 基础算术

2.2.8.6. 逻辑计算

2.2.8.7. 复合计算

2.2.8.8. 比较与选择

2.2.8.9. 类型转换

2.2.8.10. 类型转换辅助配置接口

2.2.8.11. 归约计算

2.2.8.12. 归约计算辅助配置接口

2.2.8.13. 数据排布转换

2.2.8.14. 数据填充

2.2.8.15. 排序组合（ISASI）

2.2.8.16. 离散与聚合

2.2.8.17. 掩码操作

2.2.8.18. 数据重排（ISASI）

2.2.9. Reg矢量计算

2.2.9.2. 寄存器数据类型

2.2.9.3. 辅助数据类型

2.2.9.4. VF调用

2.2.9.6. Reg数据搬入

2.2.9.7. Reg数据搬出

2.2.9.8. MaskReg计算

2.2.9.9. 基础算术

2.2.9.10. 逻辑计算

2.2.9.11. 复合计算

2.2.9.12. 比较与选择

2.2.9.13. 类型转换

2.2.9.14. 归约计算

2.2.9.15. 数据填充

2.2.9.16. 离散操作

2.2.9.17. 数据重排

2.2.9.18. 数据压缩

2.2.9.19. 直方图计算

2.2.9.20. 索引操作

2.2.9.21. 同步控制

2.2.9.22. 系统变量访问

2.2.10. 标量计算

2.2.11. 资源管理

2.2.11.1. TPipe

2.2.11.3. TBufPool

2.2.11.4. 自定义TBufPool

2.2.11.5. TQue

2.2.11.6. TSCM

2.2.11.7. TQueBind

2.2.11.8. TBuf

2.2.11.9. workspace