Scatter

Applicability

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

Function Usage

Scatters the source operand by element to Unified Buffer based on the index positions after the register tensor and index tensor of the source operand and the base address of the result operand in Unified Buffer are given. The following figure shows the scatter process.

Prototype

template <typename T = DefaultType, typename U = DefaultType, typename S, typename V>
__simd_callee__ inline void Scatter(__ubuf__ T* baseAddr, S& srcReg, V& index, MaskReg& mask)

Parameters

**Table 1** Template parameters
Parameter	Description
T	Data type of the destination and source operands.
U	Data type of the index.
S	RegTensor type of the source operand, for example, RegTensor<half>. It is automatically inferred by the compiler and does not need to be specified.
V	RegTensor type of the index value, for example, RegTensor<uint16_t>. It is automatically inferred by the compiler and does not need to be specified.

**Table 2** Function parameters
Parameter	Input/Output	Description
baseAddr	Output	Base address of the destination operand in Unified Buffer. The type is Unified Buffer pointer. Atlas 350 Accelerator Card: For details about the supported data types, see Table 3.
srcReg	Input	Source operand. The type is RegTensor. Atlas 350 Accelerator Card: For details about the supported data types, see Table 3.
index	Input	Index of each element in srcReg relative to baseAddr in Unified Buffer. The index value must be greater than or equal to 0. The type is RegTensor. The IndexT data type must be used together with the data type T of the destination and source operands. For details about the type mapping table, see the constraints. Atlas 350 Accelerator Card: For details about the supported data types, see Table 3.
mask	Input	Validity indicator for the src element. For details, see MaskReg.

Constraints

The data types T and U of the destination and source operands must be used together. The type mapping table is as follows:

**Table 3** Data types of the Scatter operand
T	U
int8_t	uint16_t
uint8_t
int16_t
uint16_t
half
bfloat16_t
int32_t	uint32_t
uint32_t
float
uint64_t	uint32_t
int64_t	uint32_t
uint64_t	uint64_t
int64_t	uint64_t

When T is of the b64 data type, the data types of T, U, and V can only be one of the following combinations:

T	IndexT	RegT	RegIndexT	Remarks
b64	uint32_t	RegTensor<uint64_t, RegTraitNumOne>	RegTensor<uint32_t>	The first 32 index values are valid.
		RegTensor<int64_t, RegTraitNumOne>	RegTensor<uint32_t>	The first 32 index values are valid.
		RegTensor<uint64_t, RegTraitNumTwo>	RegTensor<uint32_t>	-
		RegTensor<int64_t, RegTraitNumTwo>	RegTensor<uint32_t>	-
b64	uint64_t	RegTensor<uint64_t, RegTraitNumOne>	RegTensor<uint64_t, RegTraitNumOne>	-
		RegTensor<int64_t, RegTraitNumOne>	RegTensor<uint64_t, RegTraitNumOne>	-
		RegTensor<uint64_t, RegTraitNumOne>	RegTensor<uint64_t, RegTraitNumTwo>	The first 32 index values are valid.
		RegTensor<int64_t, RegTraitNumOne>	RegTensor<uint64_t, RegTraitNumTwo>	The first 32 index values are valid.
		RegTensor<uint64_t,RegTraitNumTwo>	RegTensor<uint64_t, RegTraitNumTwo>	-
		RegTensor<int64_t,RegTraitNumTwo>	RegTensor<uint64_t, RegTraitNumTwo>	-

When T is of the int8 or uint8 data type, only the even bytes in the source operand tensor are valid. Only the even bytes in the source operand tensor are stored in the result address of Unified Buffer. This means the data at positions 0, 2, 4, ..., 252, and 254 in srcReg is scattered and stored in the destination operand.
The index cannot contain duplicate values. If two or more indexes contain the same data, only the data corresponding to one of the indexes is valid, and it is unknown which data is valid.
The index position must be aligned based on dtype_size (number of bytes of a single element). Otherwise, the data scattering result may be disordered.

Example

template<typename T, typename U>
 __simd_vf__ inline void ScatterVF(__ubuf__ T* dstAddr, __ubuf__ T* src0Addr, __ubuf__ U* src1Addr, uint32_t count, uint32_t oneRepeatSize, uint16_t repeatTimes)
{
    AscendC::Reg::RegTensor<T> srcReg0;
    AscendC::Reg::RegTensor<U> srcReg1;
    AscendC::Reg::MaskReg mask;
    for (uint16_t i = 0; i < repeatTimes; i++) {
        mask = AscendC::Reg::UpdateMask<T>(count);
        AscendC::Reg::LoadAlign(srcReg0, src0Addr + i * oneRepeatSize);
        AscendC::Reg::LoadAlign(srcReg1, src1Addr + i * oneRepeatSize);
        AscendC::Reg::Scatter(dstAddr, srcReg0, srcReg1, mask);
    }
}

Parent topic: Gather and Scatter