Copy（L0C Buffer到Unified Buffer数据搬运）
说明
本接口为试验接口，在后续版本中可能会调整或改进，不保证后续兼容性。请开发者在使用过程中关注后续版本更新。
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持
- Atlas 200I/500 A2 推理产品：不支持
- Atlas 推理系列产品AI Core：不支持
- Atlas 推理系列产品Vector Core：不支持
- Atlas 训练系列产品：不支持
功能说明
头文件路径为：tensor_api/tensor.h。
Tensor API通过Copy接口统一执行不同通路数据搬运。该接口用于将L0C Buffer中的矩阵计算结果搬运到Unified Buffer。L0C Buffer中的数据通常为Mmad的输出，数据格式为NZ。搬运到Unified Buffer时，接口会根据目的张量格式自动选择NZ到ND、NZ到DN或NZ到NZ的随路格式转换。
L0C Buffer到Unified Buffer搬运支持不量化输出、float到half或bfloat16_t的直接转换输出，以及配合标量或张量量化参数的随路量化输出。随路Relu、双目的模式和舍入方式通过CopyL0C2UBTrait配置。Mmad与Fixpipe细粒度并行相关的unitFlag通过FixpipeParams配置。
接口支持batch模式。batch模式用于一次完成多块矩阵计算结果的搬运。Layout在原矩阵Layout最外层增加Batch维度。源张量为NZ格式，分形固定为16×16，可通过MakeFrameLayout<NZLayoutPtn>(batch, m, n)构造。目的张量可通过MakeFrameLayout<NDLayoutPtn>(batch, m, n)、MakeFrameLayout<DNLayoutPtn>(batch, m, n)、MakeFrameLayout<NDExtLayoutPtn>(batch, m, n)、MakeFrameLayout<DNExtLayoutPtn>(batch, m, n)或MakeFrameLayout<NZLayoutPtn, DstType>(batch, m, n)构造。NZ格式可通过模板参数DstType指定目的数据类型，C0表示NZ格式的列分形大小，默认为16。
随路量化、随路Relu、随路格式转换、随路通道拆分以及随路通道合并的有效组合、中间数据类型和数据路径如下图所示。图中的F32到F16、F32到BF16为非量化模式，仅进行cast。其余路径为不量化、随路scalar或tensor量化模式。针对Ascend 950PR/Ascend 950DT，还支持NZ2DN随路格式转换。
图1 L0C2UB流程图
函数原型
执行L0C Buffer到Unified Buffer的非量化搬运。
C++template <typename AtomType, typename DstTensor, typename SrcTensor> __aicore__ inline void Copy(const CopyAtom<AtomType>& atomCopy, const DstTensor& dst, const SrcTensor& src)执行L0C Buffer到Unified Buffer的量化搬运。
C++template <typename AtomType, typename DstTensor, typename SrcTensor, typename QuantParam, Std::enable_if_t<IsCopyQuantParamV<QuantParam>, int> Enable> __aicore__ inline void Copy(const CopyAtom<AtomType>& atomCopy, const DstTensor& dst, const SrcTensor& src, const QuantParam& quant)使用默认trait构造搬运原子对象。
C++template <typename CopyOperationType> __aicore__ inline constexpr auto MakeCopy(const CopyOperationType& copyOperation)使用指定trait构造搬运原子对象。
C++template <typename CopyOperationType, typename CopyTraitType> __aicore__ inline constexpr auto MakeCopy(const CopyOperationType& copyOperation, const CopyTraitType& copyTrait)
参数说明
表1 Copy接口参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| atomCopy | 输入 | 搬运原子对象，可由MakeCopy(CopyL0C2UB{})或MakeCopy(CopyL0C2UB{}, CopyL0C2UBTraitDefault{})构造。 |
| dst | 输出 | 目的张量，存储位置为Location::UB。数据格式支持ND、DN和NZ。 |
| src | 输入 | 源张量，存储位置为Location::L0C，数据格式为NZ，通常为Mmad的计算结果。 |
| quant | 输入 | 可选量化参数。传入uint64_t时表示scalar量化参数，传入张量时表示tensor量化参数，张量位于L1 Buffer，元素类型为uint64_t。 |
| fixpipeParams | 输入 | 可选搬运参数，类型为FixpipeParams，通过atomCopy的with接口绑定到搬运原子对象，未绑定时使用默认值。 |
表2 MakeCopy接口参数说明
| 参数名 | 输入/输出 | 描述 |
|---|---|---|
| copyOperation | 输入 | 搬运操作对象。L0C Buffer到Unified Buffer搬运取CopyL0C2UB{}。 |
| copyTrait | 输入 | 搬运trait对象。L0C Buffer到Unified Buffer搬运默认取CopyL0C2UBTraitDefault{}。 |
CopyL0C2UBTrait说明
CopyL0C2UBTrait用于配置L0C Buffer到Unified Buffer搬运的静态特性。
struct CopyL0C2UBTrait {
RoundMode roundMode = RoundMode::DEFAULT;
bool enableRelu = false;
bool enableChannelSplit = false;
DualDstMode dualDstCtl = DUAL_DST_DISABLE;
};
表3 CopyL0C2UBTrait成员说明
| 成员 | 默认值 | 描述 |
|---|---|---|
| roundMode | RoundMode::DEFAULT | 舍入模式。RoundMode::HYBRID仅在源类型为float、目的类型为hifloat8_t的量化输出场景支持。 |
| enableRelu | false | 是否使能随路Relu。 |
| enableChannelSplit | false | 是否使能输出数据通道拆分。 |
| dualDstCtl | DUAL_DST_DISABLE | 双目标模式控制，取值包括DUAL_DST_DISABLE、DUAL_DST_SPLIT_M、DUAL_DST_SPLIT_N。详细说明参见L0C Buffer到Unified Buffer双目标模式。 |
使用自定义trait的示例：
constexpr CopyL0C2UBTrait l0c2ubTrait = {
RoundMode::DEFAULT,
false,
false,
DUAL_DST_DISABLE
};
struct CopyL0C2UBTraitCustom {
using TraitType = CopyL0C2UBTrait;
static constexpr const TraitType value = l0c2ubTrait;
};
FixpipeParams说明
FixpipeParams用于配置运行时搬运参数。
struct FixpipeParams {
uint8_t unitFlag = 0;
bool subBlockId = false;
};
表4 FixpipeParams成员说明
| 成员 | 默认值 | 描述 |
|---|---|---|
| unitFlag | 0 | 控制Mmad指令和Fixpipe指令的细粒度并行。0表示不使能，2表示使能且执行后不复位单元标记位，3表示使能且执行后复位单元标记位。使能时，MmadParams和FixpipeParams中的unitFlag需要配套设置为2或3。 |
| subBlockId | false | 在启用单目标模式时指示目标UB的编号。 |
数据类型
L0C Buffer到Unified Buffer搬运根据是否传入量化参数自动选择量化模式。
表5 数据类型说明
| 源张量类型（L0C Buffer） | 目的张量类型（Unified Buffer） | 调用形式 | 说明 |
|---|---|---|---|
int32_t | int8_t、uint8_t | Copy(atom, dst, src, quant) | scalar或tensor量化输出。 |
float | int8_t、uint8_t | Copy(atom, dst, src, quant) | scalar或tensor量化输出。 |
float | fp8_e4m3fn_t、hifloat8_t | Copy(atom, dst, src, quant) | scalar或tensor量化输出。hifloat8_t支持RoundMode::DEFAULT和RoundMode::HYBRID。 |
int32_t | half、bfloat16_t | Copy(atom, dst, src, quant) | scalar或tensor量化输出。 |
float | half | Copy(atom, dst, src) | 直接转换输出，对应F32到F16。 |
float | bfloat16_t | Copy(atom, dst, src) | 直接转换输出，对应F32到BF16。 |
float | half、bfloat16_t | Copy(atom, dst, src, quant) | scalar或tensor量化输出。 |
int32_t | int32_t | Copy(atom, dst, src) | 不量化输出。 |
float | float | Copy(atom, dst, src) | 不量化输出。 |
float | float | Copy(atom, dst, src, quant) | scalar或tensor量化输出。 |
不传入quant时，接口选择不量化或直接转换模式，传入uint64_t时选择scalar量化模式，传入Tensor API张量时选择tensor量化模式。
返回值说明
Copy无返回值。MakeCopy返回CopyAtom对象。
约束说明
- 源矩阵
NZ格式，地址要求64字节对齐。目的矩阵地址要求32字节对齐。 - 目的矩阵为
NZ输出时，N方向大小需要为16的倍数；b8类型通道合并场景为32的倍数，float使能enableChannelSplit通道拆分场景为8的倍数。 - tensor量化参数张量应位于L1 Buffer，元素类型为
uint64_t，地址要求32字节对齐。详细约束参见随路量化。 - 使能
unitFlag时，需要配合Mmad同时使能。 - 使用
RoundMode::HYBRID时，源类型必须为float，目的类型必须为hifloat8_t。 - 目的布局为
NZ时，不支持dualDstCtl设置为DUAL_DST_SPLIT_N。双目标模式详细约束参见L0C Buffer到Unified Buffer双目标模式。 - 通道合并特性硬件自动使能，不能通过参数配置。详细约束参见Int8 Channel Merge。
关键特性
L0C Buffer到Unified Buffer搬运涉及随路量化、随路Relu、Int8 Channel Merge、L0C Buffer到Unified Buffer双目标模式和batch搬运等关键特性。
调用示例
不量化输出
#include "tensor_api/tensor.h"
using namespace AscendC::Te;
__aicore__ inline void CopyL0CToUB()
{
auto l0c = MakeTensor(MakeMemPtr(l0cAddr), MakeFrameLayout<NZLayoutPtn, 16>(m, n));
auto ub = MakeTensor(MakeMemPtr(ubAddr), MakeFrameLayout<NDExtLayoutPtn>(m, n));
FixpipeParams params;
auto atom = MakeCopy(CopyL0C2UB{}).with(params);
Copy(atom, ub, l0c);
}
scalar量化输出
#include "tensor_api/tensor.h"
using namespace AscendC::Te;
__aicore__ inline void CopyL0CToUB()
{
auto l0c = MakeTensor(MakeMemPtr(l0cAddr), MakeFrameLayout<NZLayoutPtn, 16>(m, n));
auto ub = MakeTensor(MakeMemPtr(ubAddr), MakeFrameLayout<NDExtLayoutPtn>(m, n));
uint64_t quant = 1;
auto atom = MakeCopy(CopyL0C2UB{}).with(FixpipeParams{});
Copy(atom, ub, l0c, quant);
}
tensor量化输出
#include "tensor_api/tensor.h"
using namespace AscendC::Te;
__aicore__ inline void CopyL0CToUB()
{
auto l0c = MakeTensor(MakeMemPtr(l0cAddr), MakeFrameLayout<NZLayoutPtn, 16>(m, n));
auto ub = MakeTensor(MakeMemPtr(ubAddr), MakeFrameLayout<NDExtLayoutPtn>(m, n));
auto quant = MakeTensor(MakeMemPtr(l1QuantAddr), MakeFrameLayout<NDExtLayoutPtn>(1, n));
auto atom = MakeCopy(CopyL0C2UB{}).with(FixpipeParams{});
Copy(atom, ub, l0c, quant);
}
batch模式输出
#include "tensor_api/tensor.h"
using namespace AscendC::Te;
__aicore__ inline void CopyBatchL0CToUB()
{
constexpr uint32_t batch = 3;
constexpr uint32_t m = 32;
constexpr uint32_t n = 64;
__cc__ float l0cBuf[batch * m * n];
__ubuf__ half ubBuf[batch * m * n];
auto l0c = MakeTensor(MakeMemPtr(l0cBuf), MakeFrameLayout<NZLayoutPtn>(batch, m, n));
auto ub = MakeTensor(MakeMemPtr(ubBuf), MakeFrameLayout<NDExtLayoutPtn>(batch, m, n));
auto atom = MakeCopy(CopyL0C2UB{}).with(FixpipeParams{});
Copy(atom, ub, l0c);
}