Gatherb (ISASI)

Applicability

Product	Supported
Atlas 350 Accelerator Card	√
Atlas A3 training product/Atlas A3 inference product	√
Atlas A2 training product/Atlas A2 inference product	√
Atlas 200I/500 A2 inference product	√
Atlas inference product AI Core	x
Atlas inference product Vector Core	x
Atlas training product	x

Function Usage

Gathers a given input tensor to the result tensor based on the provided offset address and the specified data block granularity.

Prototype

template <typename T>
__aicore__ inline void Gatherb(const LocalTensor<T>& dst, const LocalTensor<T>& src0, const LocalTensor<uint32_t>& offset, const uint8_t repeatTime, const GatherRepeatParams& repeatParams)

Parameters

**Table 1** Parameters in the template
Parameter	Description
T	Operand data type. For the Atlas 350 Accelerator Card, the supported data types are int8_t, uint8_t, int16_t, uint16_t, int32_t, uint32_t, half, float, bfloat16_t, uint64_t, and int64_t. For the Atlas A3 training product/Atlas A3 inference product, the supported data types are uint16_t and uint32_t. For the Atlas A2 training product/Atlas A2 inference product, the supported data types are uint16_t and uint32_t. For the Atlas 200I/500 A2 inference product, the supported data types are int8_t, uint8_t, int16_t, uint16_t, half, float, int32_t, uint32_t, bfloat16_t, and int64_t.

**Table 2** Parameters
Parameter	Input/Output	Meaning
dst	Output	Destination operand. The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT. The start address of LocalTensor must be 32-byte aligned.
src0	Input	Source operand. The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT. The start address of LocalTensor must be 32-byte aligned. The source operand must have the same data type as the destination operand.
offset	Input	Address offset of each data block in the source operand. The type is LocalTensor, and TPosition can be VECIN, VECCALC, or VECOUT. The start address of LocalTensor must be 32-byte aligned. The offset is relative to the base address of src0. The size of each element is at least 0, in bytes. Ensure that the offset address is 32-byte aligned.
repeatTime	Input	Number of iteration repeats. Data of eight data blocks is collected in each repeat. Data range: repeatTimes ∈ [0,255].
repeatParams	Input	Instruction iteration parameters. The type is GatherRepeatParams. For details, see ${INSTALL_DIR}/include/ascendc/basic_api/interface/kernel_struct_gather.h. Replace *${INSTALL_DIR}* with the CANN installation path. dstBlkStride and dstRepStride can be set by users. For details about the parameters, see Table 3.

**Table 3** Parameters in the GatherRepeatParams structure
Parameter	Meaning
dstBlkStride	Address stride of the vector destination operand between different data blocks in a single iteration.
dstRepStride	Address stride of the vector destination operand for the same data block between adjacent iterations.
blockNumber	Reserved parameter. This parameter is reserved for future functions. You can use the default value.
src0BlkStride
src1BlkStride
src0RepStride
src1RepStride
repeatStrideMode
strideSizeMode

Restrictions

None

Examples

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 indicates the number of iterations. Data of eight data blocks is collected in each iteration.

Result example:

Input (offsetLocal): [224 192 160 128 96 64 32 0]
Input (srcLocal): [0 1 2 3 4 5 6 7 ... 120 121 122 123 124 125 126 127]
Output (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
]

Parent topic: Data Padding