Load3DBitMode

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

Performs the image-to-column operation to convert a multi-dimensional feature map into a two-dimensional matrix. The following data paths are supported: A1 -> A2 and B1 -> B2.

Prototype

template <TPosition Dst, TPosition Src, typename T>
__aicore__ inline void LoadData(const LocalTensor<T>& dst, const LocalTensor<T>& src,const Load3DBitModeParam& loadDataParams)

Parameters

**Table 1** Template parameters
Parameter	Description
T	Data types of the source and destination operands. Load3DBitMode API: For the Atlas 350 Accelerator Card, the supported data types are uint8_t, int8_t, fp8_e4m3fn_t, fp8_e5m2_t, hifloat8_t, half, bfloat16_t, uint32_t, int32_t, and float.
Src	Logical position (TPosition) of the source operand, used only by the Load3DBitMode API.
Dst	Logical position (TPosition) of the destination operand, used only by the Load3DBitMode API.

**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: A2: ZZ or NZ format B2: ZN format A1 or B1: There is no format restriction. Generally, the data is in NZ format.
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: Load3DBitModeParam. For details, see Table 3. 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 **Load3DBitModeParam**
Parameter	Description
config0	A parameter of type uint64_t. It forms a union together with a bit-field struct called Load3DBitModeConfig0 (represented as config0BitMode). It is initialized to 0. You can use the class method GetConfig0() to retrieve its value.
config0BitMode	A bit-field struct type called Load3DBitModeConfig0. It forms a union together with config0. For details about the parameter, see Table 4.
config1	A parameter of type uint64_t. It forms a union together with a bit-field struct called Load3DBitModeConfig1 (represented as config1BitMode). It is initialized to 0. You can use the class method GetConfig1() to retrieve its value.
config1BitMode	A bit-field struct type called Load3DBitModeConfig1. It forms a union together with config1. For details about the parameter, see Table 5.

The design principles of the Load3DBitModeParam class parameters are as follows:

A union is a special data structure that allows different data types to be stored in the same memory location. All members of a union share the same memory space, and its size is determined by the largest member. At any given time, only one member can be used.

A bit-field is a special class member that allows precise control over how many bits each variable occupies in memory. In a struct, members are laid out from top to bottom, corresponding to memory from low bits to high bits.

The Load2DBitModeParam class uses both union and bit-field methods. Parameters are expressed using bit values, with the bit-field struct automatically handling the exact number of bits for each input. By leveraging the union, multiple parameters can be combined and passed together. Only one input parameter is needed to contain all required information, and the underlying API only needs to receive a single parameter. Additionally, when you need to modify the value of a specific bit within the parameter, you can do so with loops and bitwise operations, without having to re-pass the entire parameter. This reduces scalar computations and improves performance.

The Load2DBitModeParam class can be directly initialized using an object of the LoadData2DParamsV2 struct type.

template <typename T>
__aicore__ inline Load3DBitModeParam(const LoadData3DParamsV2<T> &loadData3DParams_);

You can also use the Set function of each parameter to modify the parameter value. Because the union is used, you can directly modify config0 and config1 bit by bit to modify the parameters.

**Table 4** Parameters in the **Load3DBitModeConfig0** structure
Parameter	Description
kStep	Transfer length along the width dimension of the destination operand. If the rightmost fractal is not covered, the value must be a multiple of 16 for half and a multiple of 32 for int8_t and uint8_t. No multiple requirement applies when the rightmost fractal is covered. Value range: kStep ∈ [1, 65535]. This parameter has the same meaning as kExtension in Table 4. This parameter is the lowest-order field in the bit-field struct. It occupies 16 bits. You can set and obtain its value using the SetKExtension() and GetKExtension() functions of the Load3DBitModeParam class, respectively.
mStep	Transfer length along the height dimension of the destination operand. If the bottom fractal is not covered, the value must be a multiple of 16 for half, int8_t, and uint8_t. No multiple requirement applies when the bottom fractal is covered. Value range: mStep ∈ [1, 65535]. This parameter has the same meaning as mExtension in Table 4. This parameter is the second-order field in the bit-field struct. It occupies 16 bits. You can set and obtain its value using the SetMExtension() and GetMExtension() functions of the Load3DBitModeParam class, respectively.
kPos	Start position along the width dimension of the destination operand. The value must be a multiple of 16 for half, and a multiple of 32 for int8_t and uint8_t. Value range: [0, 65535]. Default value: 0. This parameter has the same meaning as kStartPt in Table 4. This parameter is the third-order field in the bit-field struct. It occupies 16 bits. You can set and obtain its value using the SetKStartPt() and GetKStartPt() functions of the Load3DBitModeParam class, respectively.
mPos	Start position along the height dimension of the destination operand. If the bottom fractal is not covered, the value must be a multiple of 16 for half, int8_t, and uint8_t. No multiple requirement applies when the bottom fractal is covered. Value range: [0, 65535]. Default value: 0. This parameter has the same meaning as mStartPt in Table 4. This parameter is the highest-order field in the bit-field struct. It occupies 16 bits. You can set and obtain its value using the SetMStartPt() and GetMStartPt() functions of the Load3DBitModeParam class, respectively.

**Table 5** Parameters in the **Load3DBitModeConfig1** structure
Parameter	Description
strideW	Stride of the convolution kernel along the width dimension of the source operand. Value range: strideW ∈ [1, 63]. This parameter has the same meaning as strideW in Table 4. This parameter is the lowest-order field in the bit-field struct. It occupies 6 bits. You can set and obtain its value using the SetStrideW() and GetStrideW() functions of the Load3DBitModeParam class, respectively.
strideH	Stride of the convolution kernel along the height dimension of the source operand. Value range: strideH ∈ [1, 63]. This parameter has the same meaning as strideH in Table 4. This parameter is the second-order field in the bit-field struct. It occupies 6 bits. You can set and obtain its value using the SetStrideH() and GetStrideH() functions of the Load3DBitModeParam class, respectively.
Wk	Width of the convolution kernel. Value range: Wk ∈ [1, 255]. This parameter has the same meaning as filterW in Table 4. This parameter is the third-order field in the bit-field struct. It occupies 8 bits. You can set and obtain its value using the SetFilterW() and GetFilterW() functions of the Load3DBitModeParam class, respectively.
Hk	Height of the convolution kernel. Value range: Hk ∈ [1, 255]. This parameter has the same meaning as filterH in Table 4. This parameter is the fourth-order field in the bit-field struct. It occupies 8 bits. You can set and obtain its value using the SetFilterH() and GetFilterH() functions of the Load3DBitModeParam class, respectively.
dilationW	Width dilation of the convolution kernel. Value range: dilationW ∈ [1, 255]. This parameter has the same meaning as dilationFilterW in Table 4. This parameter is the fifth-order field in the bit-field struct. It occupies 8 bits. You can set and obtain its value using the SetDilationFilterW() and GetDilationFilterW() functions of the Load3DBitModeParam class, respectively.
dilationH	Height dilation of the convolution kernel. Value range: dilationH ∈ [1, 255]. This parameter has the same meaning as dilationFilterH in Table 4. This parameter is the sixth-order field in the bit-field struct. It occupies 8 bits. You can set and obtain its value using the SetDilationFilterH() and GetDilationFilterH() functions of the Load3DBitModeParam class, respectively.
filterW	Whether to add 256 elements to the width of the convolution kernel based on filterW. true: yes; false: no. This parameter has the same meaning as filterSizeW in Table 4. This parameter is the seventh-order field in the bit-field struct. It occupies 1 bit. You can set and obtain its value using the SetFilterSizeW() and GetFilterSizeW() functions of the Load3DBitModeParam class, respectively.
filterH	Whether to add 256 elements to the height of the convolution kernel based on filterH. true: yes; false: no. This parameter has the same meaning as filterSizeH in Table 4. This parameter is the eighth-order field in the bit-field struct. It occupies 1 bit. You can set and obtain its value using the SetFilterSizeH() and GetFilterSizeH() functions of the Load3DBitModeParam class, respectively.
transpose	A bool specifying whether to transpose the entire target matrix. This parameter is valid only when the destination TPosition is set to A2 and the source operand is of the half type. Default value: false. true: enabled. false: disabled. This parameter has the same meaning as enTranspose in Table 4. This parameter is the ninth-order field in the bit-field struct. It occupies 1 bit. You can set and obtain its value using the SetTranspose() and GetTranspose() functions of the Load3DBitModeParam class, respectively.
fmatrixCtrl	Whether the LoadData3DV2 instruction retrieves FeatureMap attribute descriptions from the left or right matrix. It works with SetFmatrix and can only be set to false (default). true: Retrieve FeatureMap attribute descriptions from the right matrix. false: Retrieve FeatureMap attribute descriptions from the left matrix. This parameter has the same meaning as fMatrixCtrl in Table 4. This parameter is the tenth-order field in the bit-field struct. It occupies 1 bit. You can set and obtain its value using the SetFmatrixCtrl() and GetFmatrixCtrl() functions of the Load3DBitModeParam class, respectively.
sizeChannel	Number of channels of the source operand. Value range: [1, 63]. The values of sizeChannel are as follows: For uint32_t, int32_t, and float, the value can be 4, N × 8, or N × 8 + 4. For half and bfloat16, the value can be 4, 8, N × 16, N × 16 + 4, or N × 16 + 8. For int8_t and uint8_t, the value can be 4, 8, 16, 32 × N, N × 32 + 4, N × 32 + 8, or N × 32 + 16. For int4b_t, the value can be 8, 16, 32, N × 64, N × 64 + 8, N × 64 + 16, or N × 64 + 32. This parameter has the same meaning as channelSize in Table 4. This parameter is the highest-order field in the bit-field struct. It occupies 16 bits. You can set and obtain its value using the SetChannelSize() and GetChannelSize() functions of the Load3DBitModeParam class, respectively.

Restrictions

For details about the operand address alignment requirements, see General Address Alignment Restrictions.

Returns

None

Examples

This example is supported on the Atlas inference product AI Core.

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;
uint8_t padList[4] = {padLeft, padRight, padTop, padBottom};
LoadData3DParamsV2 param = { padList, H, W, 0, 0, 0, -1, -1, strideW, strideH, Kw, Kh, dilationW, dilationH, 1, 0, fmRepeat, 0, (half)(0)};
Load3DBitModeParam paramBitMode(param);  
AscendC::LoadData<A2, A1, half>(featureMapA2, featureMapA1, paramBitMode);
AscendC::LoadData(weightB2, weightB1, { 0, weRepeat, 1, 0, 0, false, 0 });

Parent topic: LoadData