Load2D

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	√
Atlas inference product Vector Core	x
Atlas training product	√

Function Usage

Supports data transfer over the following paths:

GM -> A1; GM -> B1; GM -> A2; GM -> B2;

A1 -> A2; B1 -> B2.

Prototype

Load2D API

        
             template <typename T>
__aicore__ inline void LoadData(const LocalTensor<T>& dst, const LocalTensor<T>& src, const LoadData2DParams& loadDataParams)
template <typename T> 
__aicore__ inline void LoadData(const LocalTensor<T>& dst, const GlobalTensor<T>& src, const LoadData2DParams& loadDataParams)

Load2Dv2 API

        
             template <typename T>
__aicore__ inline void LoadData(const LocalTensor<T>& dst, const LocalTensor<T>& src,const LoadData2DParamsV2& loadDataParam)
template <typename T>
__aicore__ inline void LoadData(const LocalTensor<T>& dst, const GlobalTensor<T>& src,const LoadData2DParamsV2& loadDataParam)

Parameters

**Table 1** Template parameters
Parameter	Description
T	Data types of the source and destination operands. Load2D API: For the Atlas training product , the supported data types are uint8_t, int8_t, uint16_t, int16_t, and half. For the Atlas inference product AI Core, the supported data types are int4b_t, uint8_t, int8_t, uint16_t, int16_t, and half. For the int4b_t type, only the A1 -> A2 and B1 -> B2 paths are supported. For the Atlas A2 training product / Atlas A2 inference product , the supported data types are int4b_t, uint8_t, int8_t, uint16_t, int16_t, half, bfloat16_t, uint32_t, int32_t, and float. For the int4b_t type, only the A1 -> A2 and B1 -> B2 paths are supported. For the Atlas A3 training product / Atlas A3 inference product , the supported data types are int4b_t, uint8_t, int8_t, uint16_t, int16_t, half, bfloat16_t, uint32_t, int32_t, and float. For the int4b_t type, only the A1 -> A2 and B1 -> B2 paths are supported. For the Atlas 200I/500 A2 inference product , the supported data types are uint8_t, int8_t, uint16_t, int16_t, half, bfloat16_t, uint32_t, int32_t, and float. For the Atlas 350 Accelerator Card, the supported data types are uint8_t, int8_t, uint16_t, int16_t, half, bfloat16_t, uint32_t, int32_t, and float. Only the following data paths are supported: GM->A1, GM->B1, A1->A2, and B1->B2. Load2Dv2 API: For the Atlas 350 Accelerator Card: When loading data from GM into A1 or B1, the supported data types are int8_t, uint8_t, fp4x2_e2m1_t, fp4x2_e1m2_t, hifloat8_t, fp8_e5m2_t, fp8_e4m3fn_t, half, bfloat16_t, int32_t, uint32_t, and float. When loading data from A1 to A2 or from B1 to B2, the following data types are supported: int8_t, uint8_t, fp4x2_e2m1_t, fp4x2_e1m2_t, hifloat8_t, fp8_e5m2_t, fp8_e4m3fn_t, half, bfloat16_t, int32_t, uint32_t, and float

**Table 2** Common parameters
Parameter	Input/Output	Description
dst	Output	Destination operand, which is of the LocalTensor type. The sequential arrangement of data is determined by TPosition of the destination operand. The constraints are as follows: When storing data in A2, use the ZZ or NZ format, with the fractal matrix size of 16 × (32 bytes/sizeof(T)). When storing data in B2, use the ZN format, with the fractal matrix size of (32 bytes/sizeof(T)) × 16. When storing data in A1 or B1, there is no format restriction. Generally, the data is in NZ format, with the fractal matrix size of 16 × (32 bytes/sizeof(T)).
src	Input	Source operand, which is of the LocalTensor or GlobalTensor type. Its data type must be the same as that of dst.
loadDataParams	Input	LoadData parameter structure. Supported types are as follows: LoadData2DParams. For details, see Table 3. LoadData2DParamsV2. For details, see Table 4. For details, see ${INSTALL_DIR}/include/ascendc/basic_api/interface/kernel_struct_mm.h. Replace ${INSTALL_DIR} with the actual path for storing files after the CANN software is installed.

**Table 3** Parameters in the **LoadData2DParams** structure
Parameter	Description
startIndex	Fractal matrix ID. It specifies from which fractal matrix in the source operand the data transfer begins. If it is set to 0, the transfer starts from the first fractal matrix of the source operand. Value range: startIndex ∈ [0, 65535]. Unit: 512 bytes. Default value: 0.
repeatTimes	Number of iterations. 512-byte data can be processed in each iteration. Value range: repeatTimes ∈ [1, 255].
srcStride	In adjacent iterations, the interval between the start addresses of consecutive fractal matrices in the source operand. It is measured in units of 512 bytes. Value range: srcStride ∈ [0, 65535]. Default value: 0.
sid	Reserved parameter. Set it to 0.
dstGap	In adjacent iterations, the interval between the end address of one fractal matrix and the start address of the next fractal matrix in the destination operand. It is measured in units of 512 bytes. Value range: dstGap ∈ [0, 65535]. Default value: 0. Note: For the Atlas training product , this parameter is not supported.
ifTranspose	Whether to enable the transpose function for each fractal matrix. The default value is false. true: enabled. false: disabled. Note: When loading data from A1 to A2 or from B1 to B2, the transpose function can be enabled. When the transpose function is enabled, the source and destination operands support only the b16 data type.
addrMode	Address update mode. Default value: false. true: Decrement. In each iteration, the new address is obtained by subtracting srcStride from the previous address. false: Increment. In each iteration, the new address is obtained by adding srcStride to the previous address.

**Table 4** Parameters in the **LoadData2DParamsV2** structure
Parameter	Description
mStartPosition	For an M × K matrix, this parameter specifies the start position along the M-axis of the source matrix, measured in units of 16 elements.
kStartPosition	For an M × K matrix, this parameter specifies the start position along the K-axis of the source matrix, measured in units of 32 bytes.
mStep	For an M × K matrix, this parameter specifies the transfer length along the M-axis of the source matrix, measured in units of 16 elements. Value range: mStep ∈ [0, 255]. When the transpose function is enabled by setting ifTranspose, mStep must meet the following additional constraints in addition to the value range of [0, 255]: When the data type is b4, mStep must be a multiple of 4. When the data type is b8, mStep must be a multiple of 2. When the data type is b16, mStep must be a multiple of 1. When the data type is b32, there is no additional constraint on mStep.
kStep	For an M × K matrix, this parameter specifies the transfer length along the K-axis of the source matrix, measured in units of 32 bytes. Value range: kStep ∈ [0, 255]. When the transpose function is enabled by setting ifTranspose, kStep must meet the following additional constraints in addition to the value range of [0, 255]: When the data type is b4, b8, or b16, there is no additional constraint on kStep. When the data type is b32, kStep must be a multiple of 2.
srcStride	For an M × K matrix, this parameter specifies the interval between the start addresses of consecutive fractal matrices along the K-axis of the source matrix, measured in units of 512 bytes.
dstStride	For an M × K matrix, this parameter specifies the interval between the start address of one fractal matrix and the start address of the next fractal matrix along the K-axis of the destination matrix. The unit is 512 bytes.
ifTranspose	Whether to enable the transpose function for each fractal matrix. The default value is false. true: enabled. false: disabled. Note: The transpose function can be enabled only when data is transferred from A1 to A2 or from B1 to B2. When the transpose function is enabled, the restrictions on the supported data types are as follows: For the Atlas 350 Accelerator Card, the source and destination operands support the b4, b8, b16, and b32 data types.
sid	Reserved parameter. Set it to 0.

Figure 1 Parameters in the LoadData2DParamsV2 structure

Restrictions

For details about the operand address alignment requirements, see General Address Alignment Restrictions.
For the Atlas inference product AI Core, when the Mmad API is used and the data type of matrix B is S4, if the transpose function is enabled by setting ifTranspose, only 64 × 64 fractal blocks are supported.

Returns

None

Examples

      
           uint16_t C1 = 2;
uint16_t H = 4, W = 4;
uint8_t Kh = 2, Kw = 2;
uint16_t Cout = 16;
uint16_t C0 = 16;
uint8_t dilationH = 2, dilationW = 2;
uint8_t padTop = 1, padBottom = 1, padLeft = 1, padRight = 1;
uint8_t strideH = 1, strideW = 1;
uint16_t coutBlocks, ho, wo, howo, howoRound;
uint32_t featureMapA1Size, weightA1Size, featureMapA2Size, weightB2Size, dstSize, dstCO1Size;
uint8_t padList[4] = {padLeft, padRight, padTop, padBottom};
featureMapA2Size = howoRound * (C1 * Kh * Kw * C0);
fmRepeat = featureMapA2Size / (16 * C0);

AscendC::LocalTensor<half> featureMapA1 = inQueueFmA1.DeQue<half>();
AscendC::LocalTensor<half> featureMapA2 = inQueueFmA2.AllocTensor<half>();

AscendC::LoadData<A2, A1, half>(featureMapA2, featureMapA1, 
{ padList, H, W, 0, 0, 0, -1, -1, strideW, strideH, Kw, Kh, dilationW, dilationH, 1, 0, fmRepeat, 0, (half)(0)});

LoadData2DParamsV2 param = { padList, H, W, 0, 0, 0, -1, -1, strideW, strideH, Kw, Kh, dilationW, dilationH, 1, 0, fmRepeat, 0, (half)(0)};
Load2DBitModeParam paramBitMode(param); 
AscendC::LoadData<A2, A1, half>(featureMapA2, featureMapA1, paramBitMode);

Parent topic: LoadData