CANN/asc-devkit矩阵计算数据搬入接口-育师

# 总体说明

【免费下载链接】asc-devkit本项目是CANN 推出的昇腾AI处理器专用的算子程序开发语言，原生支持C和C++标准规范，主要由类库和语言扩展层构成，提供多层级API，满足多维场景算子开发诉求。项目地址: https://gitcode.com/cann/asc-devkit

矩阵计算的搬入是Ascend C编程框架中用于数据搬运的一类核心接口，主要实现Global Memory到L0A Buffer/L0B Buffer之间的数据高效传输。该类接口提供了多种数据搬运模式，能够满足矩阵计算中左右矩阵等数据的搬运需求，通常与Mmad接口配合使用。

矩阵计算的搬入的接口支持多种数据搬运场景，包括但不限于二维格式数据搬运、三维格式转换、压缩数据解压、矩阵转置搬运以及稀疏化数据处理等。通过灵活配置不同的参数结构体，开发者可以精确控制数据的搬运路径、起始位置、搬运长度等关键信息，充分利用硬件的数据搬运能力，最大化算子的整体执行性能。

矩阵计算的搬入接口支持多种数据通路，每种通路对应特定的存储层级和访问特性。

表1数据通路和存储层级

源位置	源地址对齐要求	目的位置	目的地址对齐要求	典型应用场景
Global Memory	1字节	L1 Buffer(A1)	32字节	从全局内存加载左矩阵数据到L1 Buffer。
Global Memory	1字节	L1 Buffer(B1)	32字节	从全局内存加载右矩阵数据到L1 Buffer。
Global Memory	1字节	L0A Buffer(A2)	512字节	从全局内存加载左矩阵数据到L0A Buffer。
Global Memory	1字节	L0B Buffer(B2)	512字节	从全局内存加载右矩阵数据到L0B Buffer。
L1 Buffer(A1)	32字节	L0A Buffer(A2)	512字节	从L1 Buffer加载左矩阵数据到L0A Buffer。
L1 Buffer(B1)	32字节	L0B Buffer(B2)	512字节	从L1 Buffer加载右矩阵数据到L0B Buffer。
L1 Buffer	32字节	BiasTable Buffer	64字节	从L1 Buffer加载存储矩阵计算所需的Bias（偏置）数据到BiasTable Buffer。
L1 Buffer	32字节	Fixpipe Buffer	128字节	从L1 Buffer加载Fixpipe搬运过程中所需的量化参数等数据到Fixpipe Buffer。

[!NOTE]说明 Ascend 950PR/Ascend 950DT因硬件变更，删除GM到L0A Buffer、L0B Buffer的数据通路。产生的影响是原GM到L0A Buffer和L0B Buffer的数据搬运需要拆分为两步，即从GM到L1 Buffer的数据搬运和从L1 Buffer到L0A Buffer、L0B Buffer的数据搬运。

GM->L1 Buffer的接口分类与使用场景

表2GM->L1 Buffer接口

接口类别	主要功能	支持通路	典型应用场景
GM->L1 Buffer连续数据搬运（DataCopy）	将矩阵从Global Memory连续搬运至L1 Buffer，格式和内容保持不变。	GM->L1 Buffer	矩阵计算数据从片外搬入L1 Buffer。
GM->L1 Buffer高维切分数据搬运（DataCopy）	从GM搬运至L1 Buffer，支持通过配置数据块个数、长度、地址间隔实现非连续搬运。	GM->L1 Buffer	矩阵分片、多通道数据的非连续搬运。
GM->L1 Buffer随路转换-ND2NZ搬运（DataCopy）	从GM搬运至L1 Buffer，搬运同时完成ND到NZ分形格式的转换。	GM->L1 Buffer	矩阵计算前将ND格式特征图转为NZ分形格式。
GMToL1-2D矩阵搬运（LoadData）	以512B数据分形为单位，将2D格式矩阵数据从GM搬运至L1 Buffer。	GM->L1 Buffer	普通矩阵计算所需的2D分形数据搬入L1 Buffer。

针对Ascend 950PR/Ascend 950DT，新增GM->L1 Buffer如下接口，请开发者参考表3。

表3GM->L1 Buffer接口

接口类别	主要功能	支持通路	典型应用场景
GM->L1 Buffer随路转换DN2NZ搬运（DataCopy）	从GM搬运至L1 Buffer，搬运同时完成DN到NZ格式的转换。	GM->L1 Buffer	DN格式权重数据搬入L1 Buffer并转换为NZ格式。
GM->L1 Buffer非对齐数据搬运（DataCopyPad）	将数据从GM非对齐搬运至L1 Buffer，支持在数据左/右侧自行填充。	GM->L1 Buffer	GM中非对齐数据搬入L1 Buffer时进行补齐。
GMToL1-2D矩阵搬运V2（LoadData）	使用2DV2指令以512B分形为单位搬运2D格式数据从GM到L1 Buffer。	GM->L1 Buffer	矩阵计算2D分形数据从GM搬入L1 Buffer。

UB->L1 Buffer的接口分类与使用场景

表4UB->L1 Buffer接口

接口类别	主要功能	支持通路	典型应用场景
UB->L1 Buffer连续数据搬运（DataCopy）	将数据从Unified Buffer连续搬运至L1 Buffer，格式和内容保持不变。	UB->L1 Buffer	矢量计算结果从UB传入L1 Buffer供矩阵计算使用。
UB->L1 Buffer高维切分数据搬运（DataCopy）	从UB搬运至L1 Buffer，支持通过块参数配置实现非连续搬运。	UB->L1 Buffer	UB中非连续排列数据搬入L1 Buffer。
UB->L1 Buffer随路转换ND2NZ搬运（DataCopy）	从UB搬运至L1 Buffer，搬运同时完成ND到NZ分形格式转换。	UB->L1 Buffer	UB中ND格式数据搬入L1 Buffer并转为NZ格式。
UB->L1 Buffer非对齐数据搬运（DataCopyPad）	将数据从UB非对齐搬运至L1 Buffer，支持在数据左/右侧自行填充。	UB->L1 Buffer	UB中非32B对齐边界数据的搬移与补齐。

L1 Buffer->L0A/B Buffer的接口分类与使用场景

表5L1 Buffer->L0A/B Buffer接口

接口类别	主要功能	支持通路	典型应用场景
LoadData（2D矩阵搬运）	以512B分形为单位搬运2D格式矩阵数据，支持L1 Buffer->L0A Buffer/L0B Buffer通路及分形转置。	L1 Buffer->L0A Buffer、L1 Buffer->L0B Buffer	矩阵计算数据从L1 Buffer搬入L0A Buffer/L0B Buffer计算缓冲区。
LoadData（卷积数据搬运）	将NC1HWC0格式Feature Map完成Image to Column展开后，以512B分形为单位搬入L0A Buffer/L0B Buffer。	L1 Buffer->L0A Buffer、L1 Buffer->L0B Buffer	卷积的im2col展开与矩阵计算数据搬入。
LoadDataWithTranspose	搬运2D格式数据并伴随转置操作，将多个分形拼接为方块矩阵后转置再拆分搬入L0A Buffer/L0B Buffer。	L1 Buffer->L0A Buffer、L1 Buffer->L0B Buffer	矩阵计算中需转置的A/B矩阵搬入L0 Buffer。
L1 Buffer->BiasTable Buffer数据搬运	将矩阵计算的bias参数从L1 Buffer搬运至BiasTable Buffer。	L1 Buffer->BiasTable Buffer	矩阵乘后加偏置（bias add）参数搬入。
L1 Buffer->Fixpipe Buffer数据搬运	将随路量化和随路ReLU参数从L1 Buffer搬运至Fixpipe Buffer。	L1 Buffer->Fixpipe Buffer	矩阵计算结果的随路量化、激活参数搬入。

[!NOTE]说明针对Ascend 950PR/Ascend 950DT，LoadDataWithTranspose仅支持L1 Buffer->L0B Buffer通路，不支持L1 Buffer->L0A Buffer通路。

针对Atlas A2训练系列产品/Atlas A2推理系列产品和Atlas A3训练系列产品/Atlas A3推理系列产品，支持L1 Buffer->L0B Buffer如下接口，请开发者参考表6。

表6L1 Buffer->L0B Buffer接口

接口类别	主要功能	支持通路	典型应用场景
LoadDataWithSparse	搬运4选2结构化稀疏矩阵计算所需的稠密化权重矩阵和索引矩阵。	L1 Buffer->L0B Buffer	稀疏矩阵乘法计算数据搬入。

针对Ascend 950PR/Ascend 950DT，新增L1 Buffer->L0A/B Buffer如下接口，请开发者参考表7。

表7L1 Buffer->L0A/B Buffer接口

接口类别	主要功能	支持通路	典型应用场景
LoadData（2D矩阵搬运V2）	以512B分形为单位搬运2D格式矩阵数据，使用V2参数结构，支持更多数据类型。	L1 Buffer->L0A Buffer、L1 Buffer->L0B Buffer	矩阵计算数据搬入L0A Buffer/L0B Buffer，支持b4数据类型。
LoadData（BitMode2D矩阵搬运）	LoadData（2D矩阵搬运V2）的bit模式变体，支持按位操作的数据搬运。	L1 Buffer->L0A Buffer、L1 Buffer->L0B Buffer	用于追求极致Scalar性能的普通矩阵数据搬运。
LoadData（MX矩阵搬运）	LoadData（2D矩阵搬运V2）的MX格式扩展，支持MX格式矩阵数据搬运。	L1 Buffer->L0A Buffer、L1 Buffer->L0B Buffer	MX浮点格式的矩阵数据搬入。
LoadData（BitMode卷积数据搬运）	LoadData（卷积数据搬运）的bit模式变体，支持按位操作的3D数据搬运。	L1 Buffer->L0A Buffer、L1 Buffer->L0B Buffer	用于追求极致Scalar性能的卷积im2col展开与搬入。

辅助配置接口说明

表8辅助配置接口

接口名称	功能说明	配合使用的接口
Fill	初始化设置L1 Buffer/L0A Buffer/L0B Buffer的值。	-
SetFmatrix	设置FeatureMap属性描述。	LoadData（卷积数据搬运）
SetLoadDataBoundary	设置L1 Buffer边界值。	LoadData（卷积数据搬运）
SetLoadDataRepeat	设置Repeat参数实现多迭代搬运。	LoadData（卷积数据搬运）
SetLoadDataPaddingValue	设置Padding填充值。	LoadData（卷积数据搬运）
LoadDataUnzip	将GM上的数据解压并搬运到L1 Buffer（A1/B1）或L0B Buffer（B2）上。	LoadUnzipIndex
LoadImageToLocal	将图像数据从Global Memory搬运到Local Memory。	SetAippFunctions
LoadUnzipIndex	加载GM上的压缩索引表到内部寄存器。	-
SetAippFunctions	设置图片预处理（AIPP，AI Core pre-process）相关参数。	LoadImageToLocal