SetFmatrixBitMode

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

Sets the attribute description of a feature map when Load3Dv1/Load3Dv2 is called. If the template parameter isSetFMatrix of Load3Dv1 or Load3Dv2 is set to false, the description of the feature map attributes (including l1H, l1W, and padList. For details, see Table 3 and Table 4) transferred by Load3Dv1 or Load3Dv2 does not take effect. Developers need to use this API to set the parameters.

Prototype

__aicore__ inline void SetFmatrix(const SetFMatrixBitModeParams& param, const FmatrixMode& fmatrixMode)

Parameters

Table 1 Parameters

Parameter

Input/Output

Description

fmatrixMode

Input

Whether the LoadData instruction obtains information from the left or right register. The FmatrixMode type is defined as follows. Currently, only FMATRIX_LEFT is supported. Both the left and right matrices use this configuration.

enum class FmatrixMode : uint8_t {
    FMATRIX_LEFT = 0,
    FMATRIX_RIGHT = 1,
}; 

param

Input

The parameter is of the type SetFMatrixBitMode. For details, see Table 2.

**Table 2** Parameters in **SetFMatrixBitMode**
Parameter	Description
config0	A parameter of type uint64_t. It forms a union together with a bit-field struct called SetFMatrixBitModeConfig0 (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 SetFMatrixBitModeConfig0. It forms a union together with config0. For details about the parameter, see Table 3.

The design principles of the SetFMatrixBitMode 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 SetFMatrixBitMode 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 SetFMatrixBitMode class can be directly initialized using an object of the LoadData3DParamsV2 struct type.

template <typename T>
__aicore__ inline SetFMatrixBitModeParams(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 bit by bit to modify the parameters.

**Table 3** Parameters in the **SetFMatrixBitModeConfig0** structure
Parameter	Description
l1H	Height of the source operand. Value range: l1H ∈ [1, 32767]. This parameter is the lowest-order field in the bit-field struct. It occupies 16 bits. You can set its value using the SetL1H() function of the SetFMatrixBitMode class.
l1W	Width of the source operand. Value range: l1W ∈ [1, 32767]. This parameter is the second-order field in the bit-field struct. It occupies 16 bits. You can set its value using the SetL1W() function of the SetFMatrixBitMode class.
padList0	This parameter corresponds to the value of padding_left in the padding list of Table 1. Value range: [0, 255]. Default value: 0. This parameter is the third-order field in the bit-field struct. It occupies 8 bits. You can set its value using the SetPadList() function of the SetFMatrixBitMode class.
padList1	This parameter corresponds to the value of padding_right in the padding list of Table 1. Value range: [0, 255]. Default value: 0. This parameter is the fourth-order field in the bit-field struct. It occupies 8 bits. You can set its value using the SetPadList() function of the SetFMatrixBitMode class.
padList2	This parameter corresponds to the value of padding_top in the padding list of Table 1. Value range: [0, 255]. Default value: 0. This parameter is the fifth-order field in the bit-field struct. It occupies 8 bits. You can set its value using the SetPadList() function of the SetFMatrixBitMode class.
padList3	This parameter corresponds to the value of padding_bottom in the padding list of Table 1. Value range: [0, 255]. Default value: 0. This parameter is the highest-order field in the bit-field struct. It occupies 8 bits. You can set its value using the SetPadList() function of the SetFMatrixBitMode class.

Restrictions

This API must be used together with Load3Dv1 or Load3Dv2 and must be called prior to Load3Dv1 or Load3Dv2.
For details about the operand address alignment requirements, see General Address Alignment Restrictions.

Examples

AscendC::TPipe pipe;

AscendC::TQue<AscendC::TPosition::A1, 1> inQueueFmA1;
AscendC::TQue<AscendC::TPosition::A2, 1> inQueueFmA2;
// weight queue
AscendC::TQue<AscendC::TPosition::B1, 1> inQueueWeB1;
AscendC::TQue<AscendC::TPosition::B2, 1> inQueueWeB2;
pipe.InitBuffer(inQueueFmA1, 1, featureMapA1Size * sizeof(fmap_T));
pipe.InitBuffer(inQueueFmA2, 1, featureMapA2Size * sizeof(fmap_T));
pipe.InitBuffer(inQueueWeB1, 1, weightA1Size * sizeof(weight_T));
pipe.InitBuffer(inQueueWeB2, 1, weightB2Size * sizeof(weight_T));
pipe.InitBuffer(outQueueCO1, 1, dstCO1Size * sizeof(dstCO1_T));

AscendC::LocalTensor<fmap_T> featureMapA1 = inQueueFmA1.DeQue<fmap_T>();
AscendC::LocalTensor<weight_T> weightB1 = inQueueWeB1.DeQue<weight_T>();
AscendC::LocalTensor<fmap_T> featureMapA2 = inQueueFmA2.AllocTensor<fmap_T>();
AscendC::LocalTensor<weight_T> weightB2 = inQueueWeB2.AllocTensor<weight_T>();
uint16_t channelSize = 32;
uint16_t H = 4, W = 4;
uint8_t Kh = 2, Kw = 2;
uint16_t Cout = 16;
uint16_t C0, C1;
uint8_t dilationH = 2, dilationW = 2;

uint8_t padList[PAD_SIZE] = {0, 0, 0, 0};
AscendC::SetFmatrix(H, W, padList, FmatrixMode::FMATRIX_LEFT);
/*  
SetFMatrixBitModeParams param;
param.SetL1H(H);
param.SetL1W(W);
param.SetPadList(padList);
AscendC::SetFmatrix(param, FmatrixMode::FMATRIX_LEFT);
*/ 
AscendC::SetLoadDataPaddingValue(0);
AscendC::SetLoadDataRepeat({0, 1, 0});
AscendC::SetLoadDataBoundary((uint32_t)0);
static constexpr AscendC::IsResetLoad3dConfig LOAD3D_CONFIG = {false,false};
AscendC::LoadData<fmap_T, LOAD3D_CONFIG>(featureMapA2, featureMapA1,
    { padList, H, W, channelSize, k, howoRound, 0, 0, 1, 1, Kw, Kh, dilationW, dilationH, false, false, 0 });
AscendC::LoadData(weightB2, weightB1, { 0, weRepeat, 1, 0, 0, false, 0 });

inQueueFmA2.EnQue<fmap_T>(featureMapA2);
inQueueWeB2.EnQue<weight_T>(weightB2);
inQueueFmA1.FreeTensor(featureMapA1);
inQueueWeB1.FreeTensor(weightB1);

Parent topic: Data Movement