CANN/asc-devkit：LoadData 2D矩阵搬运V2 API文档

# LoadData2D矩阵搬运V2【免费下载链接】asc-devkit本项目是CANN 推出的昇腾AI处理器专用的算子程序开发语言原生支持C和C标准规范主要由类库和语言扩展层构成提供多层级API满足多维场景算子开发诉求。项目地址: https://gitcode.com/cann/asc-devkit产品支持情况Ascend 950PR/Ascend 950DT支持Atlas A3 训练系列产品/Atlas A3 推理系列产品不支持Atlas A2 训练系列产品/Atlas A2 推理系列产品不支持Atlas 200I/500 A2 推理产品不支持Atlas 推理系列产品AI Core不支持Atlas 推理系列产品Vector Core不支持Atlas 训练系列产品不支持Kirin X90不支持Kirin 9030不支持功能说明头文件路径为basic_api/kernel_operator_mm_intf.h。负责完成普通矩阵计算所需的2D格式数据的搬运以大小为512字节的数据分形为单位进行支持如下数据通路L1 Buffer-L0A Buffer、L1 Buffer-L0B Buffer。对于不同的数据类型每个数据分形对应的矩阵如下对于b4数据类型每个数据分形在L0A Buffer中为一个16×64的矩阵在L0B Buffer中为一个64×16的矩阵。对于b8数据类型每个数据分形在L0A Buffer中为一个16×32的矩阵在L0B Buffer中为一个32×16的矩阵。对于b16数据类型每个数据分形为一个16×16的矩阵。对于b32数据类型每个数据分形在L0A Buffer中为一个16×8的矩阵在L0B Buffer中为一个8×16的矩阵。函数原型template typename T __aicore__ inline void LoadData(const LocalTensorT dst, const LocalTensorT src, const LoadData2DParamsV2 loadDataParams)参数说明表1模板参数说明参数名称含义T源操作数和目的操作数的数据类型。表2通用参数说明参数名称输入/输出含义dst输出目的操作数类型为LocalTensor。分形约束参考矩阵计算输入搬运约束。起始地址对齐约束参考对齐约束。数据类型和src的数据类型保持一致。支持的物理存储位置为L0A BufferTPosition: A2/L0B BufferTPosition: B2。src输入源操作数类型为LocalTensor。分形约束参考矩阵计算输入搬运约束。起始地址对齐约束参考对齐约束。数据类型和dst的数据类型保持一致。支持的物理存储位置为L1 BufferTPosition: A1/B1。loadDataParams输入LoadData参数结构体类型为LoadData2DParamsV2具体参考表3。表3LoadData2DParamsV2结构体内参数说明参数名称含义mStartPosition以M×K矩阵为例源矩阵M轴方向的起始位置单位为16个元素。kStartPosition以M×K矩阵为例源矩阵K轴方向的起始位置单位为32字节。mStep以M×K矩阵为例源矩阵M轴方向搬运长度单位为16个元素。取值范围mStep∈[0, 255]。通过ifTranspose参数启用转置功能时mStep除需满足取值范围外还需满足以下额外约束•当数据类型为b4时mStep必须是4的倍数•当数据类型为b8时mStep必须是2的倍数•当数据类型为b16时mStep必须是1的倍数•当数据类型为b32时mStep无额外约束。注mStep0表示不执行搬运该接口将被视为NOP空操作。kStep以M×K矩阵为例源矩阵K轴方向搬运长度单位为32字节。取值范围kStep∈[0, 255]。通过ifTranspose参数启用转置功能时kStep除需满足取值范围外还需满足以下额外约束•当数据类型为b4、b8或b16时kStep没有额外约束•当数据类型为b32时kStep必须是2的倍数。注kStep0表示不执行搬运该接口将被视为NOP空操作。srcStride以M×K矩阵为例源矩阵K方向前一个分形起始地址与后一个分形起始地址的间隔单位512字节。dstStride以M×K矩阵为例目标矩阵K方向前一个分形起始地址与后一个分形起始地址的间隔单位512字节。ifTranspose是否启用转置功能对每个分形矩阵进行转置默认为false• true启用• false不启用注意只有L1 BufferTPosition: A1-L0A BufferTPosition: A2和L1 BufferTPosition: B1-L0B BufferTPosition: B2通路才能开启转置。开启转置功能时支持b4、b8、b16、b32数据类型。sid预留参数配置为0即可。注兼容旧款产品接口传入Ascend 950PR/Ascend 950DT产品不做处理。LoadData2DParamsV2结构体在不启用转置时示意图如下参数设置值和解释说明如下mStartPosition2表示源矩阵M轴方向的起始位置为第32个元素2×16个元素。kStartPosition2表示源矩阵K轴方向的起始位置为第32个元素2×32字节。mStep2表示源矩阵M轴方向搬运长度为32个元素2×16个元素。kStep3表示源矩阵K轴方向搬运长度为48个元素3×32字节。srcStride5表示源矩阵K方向前一个分形起始地址与后一个分形起始地址的间隔为1280个元素5×512字节。dstStride3表示目的矩阵K方向前一个分形起始地址与后一个分形起始地址的间隔为768个元素3×512字节。ifTransposefalse表示不启用转置。sid0预留参数配置为0即可。图1LoadData2DParamsV2结构体参数示例以half数据类型不启用转置为例数据类型支持的数据类型int8_t、uint8_t、fp4x2_e2m1_t、fp4x2_e1m2_t、hifloat8_t、fp8_e5m2_t、fp8_e4m3fn_t、half、bfloat16_t、int32_t、uint32_t、float。返回值说明无约束说明mStep和kStep为0时表示不执行搬运该接口将被视为NOP空操作。当目的地址位于L0A Buffer/L0B Buffer时地址必须512字节对齐当源地址或目的地址位于L1 Buffer时地址必须32字节对齐。对于矩阵转置操作不同的数据类型需要满足不同的mStep和kStep约束b4数据类型时mStep必须是4的倍数b8数据类型时mStep必须是2的倍数b16数据类型时mStep必须是1的倍数b32数据类型时kStep必须是2的倍数。关键特性说明非转置场景搬入及搬运起始位置计算利用mStep和kStep搬运多个方向的数据块以[M, K]的NZ分形为例mStartPosition为2说明M方向搬运起始位置是在距离源操作数起始位置M轴方向16×232个元素的位置。kStartPosition为2说明K方向搬运起始位置是距离源操作数起始位置K轴方向32B×264B的位置。srcStride为5表示源操作数中K方向前一个分形起始地址与后一个分形起始地址的间隔为5。dstStride为3表示目的操作数中K方向前一个分形起始地址与后一个分形起始地址的间隔为3。起始地址计算公式为$$startAddr srcAddr (kStartPosition \times \lvert srcStride \rvert mStartPosition) \times 512B$$因此最终的搬运起始位置为第十三个分形矩阵源操作数起始地址开始为第1个分形矩阵。图2搬运起始位置示意图转置场景搬入对b4/b8/b16/b32的矩阵转置操作需要满足mStep和kStep的约束b4数据类型时mStep必须是4的倍数。b8数据类型时mStep必须是2的倍数。b16数据类型时mStep必须是1的倍数。b32数据类型时kStep必须是2的倍数。各数据类型转置示意图如下图3b4数据类型转置示意图图4b8数据类型转置示意图图5b16数据类型转置示意图图6b32数据类型转置示意图调用示例示例代码片段如下仅展示样例中的部分代码完整使用样例请参见LoadData2D矩阵搬运V2样例。// LoadData: Nz - Nz uint32_t m 40; uint32_t k 70; uint32_t fractalShape[2] {16, 32 / sizeof(half)}; uint32_t fractalSize fractalShape[0] * fractalShape[1]; uint16_t mStep (m fractalShape[0] - 1) / fractalShape[0]; AscendC::LoadData2DParamsV2 loadDataParams; loadDataParams.mStep mStep; loadDataParams.kStep (k fractalShape[1] - 1) / fractalShape[1]; loadDataParams.srcStride mStep; loadDataParams.dstStride mStep; loadDataParams.ifTranspose false; AscendC::LoadData(a2Local, a1Local, loadDataParams);【免费下载链接】asc-devkit本项目是CANN 推出的昇腾AI处理器专用的算子程序开发语言原生支持C和C标准规范主要由类库和语言扩展层构成提供多层级API满足多维场景算子开发诉求。项目地址: https://gitcode.com/cann/asc-devkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考