Gatherb(ISASI)
产品支持情况
- Ascend 950PR/Ascend 950DT：支持
- Atlas A3 训练系列产品/Atlas A3 推理系列产品：支持
- Atlas A2 训练系列产品/Atlas A2 推理系列产品：支持
- Atlas 200I/500 A2 推理产品：支持
- Atlas 推理系列产品AI Core：不支持
- Atlas 推理系列产品Vector Core：不支持
- Atlas 训练系列产品：不支持
功能说明
头文件路径为："basic_api/kernel_operator_vec_gather_intf.h"。
Gatherb接口接受输入张量（src）、DataBlock偏移张量（offset），根据索引位置将输入张量按DataBlock（32字节）收集到结果张量（dst）中。
接口计算原理和参考伪代码如下：
Python
import numpy as np
def Gatherb(dst, src, offset, repeatTime, repeatParams):
inputType = np.dtype("uint16")
outputType = np.dtype("uint16")
oneDataBlockSize = 32;
if repeatParams.dstBlkStride == 0:
repeatParams.dstBlkStride = 1
for i in range(repeatTime):
for j in range(8):
srcBlockStartIndex = offset[i * 8 + j] // inputType.itemsize
srcBlockEndIndex = srcBlockStartIndex + oneDataBlockSize // inputType.itemsize
dstBlockStartIndex = (i * oneDataBlockSize * repeatParams.dstRepStride + j * oneDataBlockSize * repeatParams.dstBlkStride) // outputType.itemsize
dstBlockEndIndex = (i * oneDataBlockSize * repeatParams.dstRepStride + j * oneDataBlockSize * repeatParams.dstBlkStride + oneDataBlockSize) // outputType.itemsize
dst[dstBlockStartIndex : dstBlockEndIndex] = src[srcBlockStartIndex : srcBlockEndIndex]
完整示例请参考：Gatherb真值计算。
函数原型
C++
template <typename T>
__aicore__ inline void Gatherb(const LocalTensor<T>& dst, const LocalTensor<T>& src, const LocalTensor<uint32_t>& offset, const uint8_t repeatTime, const GatherRepeatParams& repeatParams)
参数说明
表1 模板参数说明
| 参数名 | 描述 |
|---|---|
| T | 操作数数据类型。 |
表2 参数说明
| 参数名称 | 输入/输出 | 含义 |
|---|---|---|
| dst | 输出 | 目的操作数，类型为LocalTensor，支持的TPosition为VECIN/VECCALC/VECOUT。 LocalTensor的起始地址需要按照32字节对齐。 |
| src | 输入 | 源操作数，类型为LocalTensor，支持的TPosition为VECIN/VECCALC/VECOUT。 LocalTensor的起始地址需要按照32字节对齐。 |
| offset | 输入 | 每个DataBlock在源操作数中对应的地址偏移，类型为LocalTensor，支持的TPosition为VECIN/VECCALC/VECOUT。 LocalTensor的起始地址需要按照32字节对齐。 该偏移量是相对于src的基地址而言的。每个元素值要大于等于0，单位为字节。取值要求见约束说明。 |
| repeatTime | 输入 | 指令迭代次数，每次迭代完成8个DataBlock的数据收集，取值范围：repeatTime∈[0,255]。 |
| repeatParams | 输入 | 用于控制指令迭代的相关参数。 GatherRepeatParams参数说明请参考表3。 |
| 参数名称 | 含义 |
|---|---|
| dstBlkStride | 单次迭代内，矢量目的操作数不同DataBlock间地址步长，单位为DataBlock。 注：当dstBlkStride值为0时，默认按照1来处理。 |
| dstRepStride | 相邻迭代间，矢量目的操作数相同DataBlock地址步长，单位为DataBlock。 |
| blockNumber | 注：预留的扩展参数，当前因后续架构升级，该参数已废弃，不对其进行业务处理。 |
| src0BlkStride | 注：预留的扩展参数，当前因后续架构升级，该参数已废弃，不对其进行业务处理。 |
| src1BlkStride | 注：预留的扩展参数，当前因后续架构升级，该参数已废弃，不对其进行业务处理。 |
| src0RepStride | 注：预留的扩展参数，当前因后续架构升级，该参数已废弃，不对其进行业务处理。 |
| src1RepStride | 注：预留的扩展参数，当前因后续架构升级，该参数已废弃，不对其进行业务处理。 |
| repeatStrideMode | 注：预留的扩展参数，当前因后续架构升级，该参数已废弃，不对其进行业务处理。 |
| strideSizeMode | 注：预留的扩展参数，当前因后续架构升级，该参数已废弃，不对其进行业务处理。 |
数据类型
Ascend 950PR/Ascend 950DT，支持的数据类型为：int8_t、uint8_t、int16_t、uint16_t、half、bfloat16_t、int32_t、uint32_t、float、int64_t、uint64_t。
Atlas A3 训练系列产品/Atlas A3 推理系列产品，支持的数据类型为：uint16_t、uint32_t。
Atlas A2 训练系列产品/Atlas A2 推理系列产品，支持的数据类型为：uint16_t、uint32_t。
Atlas 200I/500 A2 推理产品，支持的数据类型为：int8_t、uint8_t、int16_t、uint16_t、half、bfloat16_t、int32_t、uint32_t、float、int64_t。
约束说明
- 操作数地址对齐要求请参见Unified Buffer地址对齐约束。
- 不支持源操作数与目的操作数使用同一块内存地址。
- offset的取值要求如下：
- 取值应保证src元素类型位宽对齐。
- 偏移地址后需要32字节对齐。
- 偏移地址后不能超出UB大小数据的范围。
- 地址偏移的取值范围：不能超出uint32_t的范围。
- repeatTime取值范围：repeatTime∈[0,255]。
- 当参数count或repeatTime取值为0时，该接口的行为如下：
- 针对如下型号，当参数repeatTime取值为0时，不会执行计算操作，不会对目的操作数进行写入，该接口将被视为NOP（空操作）。
- Atlas A3 训练系列产品/Atlas A3 推理系列产品
- Atlas A2 训练系列产品/Atlas A2 推理系列产品
- 针对Ascend 950PR/Ascend 950DT，该接口通过VF调用Reg矢量计算API实现兼容，当参数repeatTime取值为0时，不保证该接口被视为NOP（空操作）。
- 针对如下型号，当参数repeatTime取值为0时，不会执行计算操作，不会对目的操作数进行写入，该接口将被视为NOP（空操作）。
- 针对如下型号，当dstBlkStride取值为0时，默认按照1来处理。
- Atlas A3 训练系列产品/Atlas A3 推理系列产品
- Atlas A2 训练系列产品/Atlas A2 推理系列产品
调用示例
完整使用样例请参见Gather类样例场景四。
C++
uint32_t bufferLen = 128;
AscendC::GatherRepeatParams params{1, 8};
uint8_t repeatTime = bufferLen * sizeof(uint16_t) / 256;
AscendC::Gatherb<uint16_t>(y_buf, x_buf, offset_buf, repeatTime, params); // repeatTime重复迭代次数，每次迭代完成8个datablock的数据收集
结果示例：
输入数据(offsetLocal): [224 192 160 128 96 64 32 0]
输入数据(srcLocal): [0 1 2 3 4 5 6 7 ... 120 121 122 123 124 125 126 127]
输出数据(dstGlobal):[
112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127
96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
...
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
]