Star725
1026
代码
代码
Issues60
Pull Requests204
Actions
项目讨论
Wiki
分析
Star725
1026
已合并
fix-ticket-and-issue #4787
Chen_hangxin7创建于 8月1日
fix-ticket-and-issue #4787
已合并
Chen_hangxin7创建于 8月1日
从gcw_atM8lhjZ/asc-devkit_9397master合入到cann/asc-devkitmaster
共 8 个文件变更+145-88
Mdocs/zh/api/SIMD-API/basic_api/memory_vector_compute/SIMD_compute/mask.md+22-8
@@ -21,11 +21,21 @@ Mask（掩码）是Ascend C中用于控制数据元素是否参与计算的标
21**图1** 掩码机制说明 21**图1** 掩码机制说明
22![](../../../../figures/mask_mechanism.png)<a id="图1-掩码机制说明"></a>22![](../../../../figures/mask_mechanism.png)<a id="图1-掩码机制说明"></a>
23 23 
24-<!-- npu="950" id1 -->
25> [!NOTE]说明24> [!NOTE]说明
26>25>
27-> 该掩码处理能力在Atlas A2 训练系列产品/Atlas A2 推理系列产品和Atlas A3 训练系列产品/Atlas A3 推理系列产品上为硬件原生支持能力；在Ascend 950PR/Ascend 950DT上为保证兼容性进行了软仿实现，其硬件底层提供的能力与Atlas A2 训练系列产品/Atlas A2 推理系列产品和Atlas A3 训练系列产品/Atlas A3 推理系列产品存在一定差异。26+> <!-- npu="A3,910b" id1 -->
28-<!-- end id1 -->27+> - 针对如下型号，Mask为硬件原生支持能力。调用Tensor前n个数据计算接口时，接口内部会将Mask设置为Counter模式，并在计算完成后恢复为系统默认的Normal模式。
28+> <!-- npu="A3" id2 -->
29+> - Atlas A3 训练系列产品/Atlas A3 推理系列产品
30+> <!-- end id2 -->
31+> <!-- npu="910b" id3 -->
32+> - Atlas A2 训练系列产品/Atlas A2 推理系列产品
33+> <!-- end id3 -->
34+> <!-- end id1 -->
35+> <!-- npu="950" id4 -->
36+> 在Ascend 950PR/Ascend 950DT上，Mask为保证兼容性采用软仿实现，其硬件底层提供的能力与Atlas A2 训练系列产品/Atlas A2 推理系列产品和Atlas A3 训练系列产品/Atlas A3 推理系列产品存在一定差异。<br>
37+> 推荐使用Tensor前n个数据计算接口，该接口通过VF调用[Reg矢量计算API](../../reg_vector_compute/reg_vector_compute.md)实现兼容。Tensor前n个数据计算接口内部不会将Mask模式切换为Normal模式。若调用该接口前已通过[SetMaskCount](../mask_operations/SetMaskCount.md)设置为Counter模式，接口调用后仍为Counter模式；后续计算需要使用Normal模式时，需手动调用[SetMaskNorm](../mask_operations/SetMaskNorm.md)进行设置。
38+> <!-- end id4 -->
29 39 
30### 掩码配置方式40### 掩码配置方式
31 41 
@@ -53,9 +63,12 @@ Mask操作的使用方式如下：
53 63 
54|配置方式|工作模式|前n个数据计算API|高维切分计算API|64|配置方式|工作模式|前n个数据计算API|高维切分计算API|
55|:---|:---|:---|:---|65|:---|:---|:---|:---|
56-|[接口内设置Mask](#接口内设置Mask)|[Normal模式](#mask-mode)|isSetMask模板参数设置为true，通过接口入参传入mask，根据使用场景配置dataBlockStride、repeatStride参数。|isSetMask模板参数设置为true，通过接口入参传入mask，根据使用场景配置dataBlockStride、repeatStride参数。repeatTime传入固定值即可，建议统一设置为1，该值不生效。|66+|[接口内设置Mask](#接口内设置mask)|[Normal模式](#mask-mode)|不涉及。|isSetMask模板参数设置为true，通过接口入参传入mask，根据使用场景配置dataBlockStride、repeatStride、repeatTime参数。|
57-|[接口内设置Mask](#接口内设置Mask)|[Counter模式](#mask-mode)|不涉及。|isSetMask模板参数设置为true，通过接口入参传入mask，根据使用场景配置dataBlockStride、repeatStride参数。repeatTime传入固定值即可，建议统一设置为1，该值不生效。|67+|[接口内设置Mask](#接口内设置mask)|[Counter模式](#mask-mode)|isSetMask模板参数设置为true，通过接口入参传入mask。|isSetMask模板参数设置为true，通过接口入参传入mask。<br>根据使用场景配置dataBlockStride、repeatStride参数。repeatTime传入固定值即可，建议统一设置为1，该值不生效。|
58-|[接口外设置Mask](#接口外设置Mask)|[Normal模式](#mask-mode)|isSetMask模板参数设置为false，调用[SetVectorMask](../mask_operations/SetVectorMask.md)设置Mask，之后调用前n个数据计算API；接口入参中的count建议设置成1。|调用[SetVectorMask](../mask_operations/SetVectorMask.md)设置Mask，之后调用高维切分计算API。<br>&bull; isSetMask模板参数设置为false，接口入参中的mask参数不生效；根据使用场景配置dataBlockStride、repeatStride参数。repeatTime传入固定值即可，建议统一设置为1，该值不生效。|68+|[接口外设置Mask](#接口外设置mask)|[Normal模式](#mask-mode)|不涉及。|调用[SetVectorMask](../mask_operations/SetVectorMask.md)设置Mask，之后调用高维切分计算API。<br>&bull; isSetMask模板参数设置为false，接口入参中的mask值设置为占位符`MASK_PLACEHOLDER`，用于占位，无实际含义。<br>&bull;根据使用场景配置repeatTime、dataBlockStride、repeatStride参数。|
69+|[接口外设置Mask](#接口外设置mask)|[Counter模式](#mask-mode)|isSetMask模板参数设置为false，调用[SetVectorMask](../mask_operations/SetVectorMask.md)设置Mask，之后调用前n个数据计算API；接口入参中的count建议设置成1。|调用[SetVectorMask](../mask_operations/SetVectorMask.md)设置Mask，之后调用高维切分计算API。<br>&bull; isSetMask模板参数设置为false；接口入参中的mask值设置为`MASK_PLACEHOLDER`，用于占位，无实际含义。<br>&bull;根据使用场景配置dataBlockStride、repeatStride参数。repeatTime传入固定值即可，建议统一设置为1，该值不生效。|
70+ 
71+用户需根据接口使用场景和参数配置正确选择掩码配置方式，如[图2 两种配置方式代码对比](#图2-两种配置方式代码对比)所示：
59 72 
60**图2** 两种配置方式代码对比 73**图2** 两种配置方式代码对比
61![](../../../../figures/two_config_comparison.png)<a id="图2-两种配置方式代码对比"></a>74![](../../../../figures/two_config_comparison.png)<a id="图2-两种配置方式代码对比"></a>
@@ -72,7 +85,7 @@ Mask操作的使用方式如下：
72 85 
73- **前n个数据计算**86- **前n个数据计算**
74 87 
75- 采用[Counter模式](#mask-mode)进行前n个数据计算，接口内部会先调用SetMaskCount，然后根据接口参数count调用SetVectorMask，再进行计算，计算完成后调用ResetMask、SetMaskNorm恢复系统默认Normal模式。88+ 采用[Counter模式](#mask-mode)进行前n个数据计算，通过接口参数count指定参与计算的元素个数，接口内部会自动完成计算所需的Mask处理。不同产品的Mask模式恢复行为存在差异，具体请参考[概述](#概述)中的说明。
76 89 
77 调用示例：90 调用示例：
78 91 
@@ -278,7 +291,8 @@ Mask操作的使用方式如下：
278 291 
279|参数名称|输入/输出|含义|292|参数名称|输入/输出|含义|
280|:---|:---|:---|293|:---|:---|:---|
281-|count|输入|参与计算的元素个数。<br>在Counter模式下，当isSetMask = false，count会被转换成掩码表示。前count位设置为1，表示前count个元素参与计算。<br>接口提供两种模式的mask参数：<br>&bull;逐bit模式：输入为mask数组mask[]，直接设置mask寄存器的值，输入的mask数组长度大于等于2，其中有效的位数与操作数的类型有关：<br>当操作数为16位时，一次迭代中有128个元素参与计算，需要使用两个uint64\_t类型的数据进行设置，数组有效长度为2，maskLow∈[0, 2<sup>64</sup>-1]， maskHigh∈[0, 2<sup>64</sup>-1]；<br>当操作数为32位时，一次迭代有64个数参与计算，仅需一个uint64\_t的数据即可，数组有效长度为1，maskLow∈[0, 2<sup>64</sup>-1]， maskHigh = 0；<br>当操作数为64位时，一次迭代有32个元素参与计算，数组长度为1，mask[0]的有效位数为32，maskLow∈[0, 2<sup>32</sup>-1]，maskHigh = 0。<br>例如，mask=[8, 2]，8和2分别表示低位的64bit和高位的64bit，8=0b1000，表示仅第4个元素参与计算；2=0b0010表示第66（64+2）个元素参与计算。<br>&bull;连续模式：输入为uint64\_t的值mask，表示mask寄存器从低位开始连续多少位被设置为1，表示前面连续的多少个元素参与计算。取值范围和操作数的数据类型有关，数据类型不同，每次迭代内能够处理的元素个数最大值不同。<br>当操作数为16位时，mask∈[0, 128]；<br>当操作数为32位时，mask∈[0, 64]；<br>当操作数为64位时，mask∈[0, 32]。<br>注：连续模式下，mask超出范围按照对应数据类型下mask最大值计算；mask = 0表示指令不会执行计算操作，该接口将被视为NOP（空操作）；若设成了负值可能产生未定义行为。|294+|count|输入|参与计算的元素个数。<br>在Counter模式下，当isSetMask = false，count会被转换成掩码表示。前count位设置为1，表示前count个元素参与计算，其余元素被屏蔽。|
295+|mask[]/mask|输入|mask存储在一个128bit的寄存器中，在掩码Normal模式下从低位到高位按位控制参与计算的元素，该位的值为1表示参与计算，0表示不参与，最多可以控制128个元素是否参与计算，有效位数与参与计算的数据类型有关。<br>接口提供两种方式设置掩码Normal模式下的mask，控制每次迭代内参与计算的元素。<br>&bull;逐bit模式：输入为uint64\_t类型的数组mask[]，直接设置mask寄存器的值，输入的mask数组长度大于等于2，其中有效的位数与操作数的类型有关：<br>当操作数为16位时，一次迭代中有128个元素参与计算，需要使用两个uint64\_t类型的数据进行设置，数组有效长度为2，maskLow∈[0, 2<sup>64</sup>-1]， maskHigh∈[0, 2<sup>64</sup>-1]；<br>当操作数为32位时，一次迭代有64个数参与计算，仅需一个uint64\_t的数据即可，数组有效长度为1，maskLow∈[0, 2<sup>64</sup>-1]， maskHigh = 0；<br>当操作数为64位时，一次迭代有32个元素参与计算，数组长度为1，mask[0]的有效位数为32，maskLow∈[0, 2<sup>32</sup>-1]，maskHigh = 0。<br>例如，mask=[8, 2]，8和2分别表示低位的64bit和高位的64bit，8=0b1000，表示仅第4个元素参与计算；2=0b0010表示第66（64+2）个元素参与计算。<br>&bull;连续模式：输入为uint64\_t的值mask，表示mask寄存器从低位开始连续多少位被设置为1，表示前面连续的多少个元素参与计算。取值范围和操作数的数据类型有关，数据类型不同，每次迭代内能够处理的元素个数最大值不同。<br>当操作数为16位时，mask∈[0, 128]；<br>当操作数为32位时，mask∈[0, 64]；<br>当操作数为64位时，mask∈[0, 32]。<br>注：连续模式下，mask超出范围按照对应数据类型下mask最大值计算；mask = 0表示指令不会执行计算操作，该接口将被视为NOP（空操作）；若设成了负值可能产生未定义行为。|
282 296 
283> [!CAUTION]注意297> [!CAUTION]注意
284>298>
Mdocs/zh/api/SIMD-API/basic_api/memory_vector_compute/compare_and_select/Compare.md+72-63
@@ -63,9 +63,9 @@
63 dst = src0 != src1;63 dst = src0 != src1;
64 ```64 ```
65 65 
66- <!-- npu="310b" id15 -->66+ <!-- npu="310b" id10 -->
67 Atlas 200I/500 A2 推理产品暂不支持整个Tensor参与计算的运算符重载。67 Atlas 200I/500 A2 推理产品暂不支持整个Tensor参与计算的运算符重载。
68- <!-- end id15 -->68+ <!-- end id10 -->
69 69 
70- Tensor前n个数据计算70- Tensor前n个数据计算
71 71 
@@ -111,91 +111,91 @@
111| mask/mask[] | 输入 | mask用于控制每次迭代内参与计算的元素。详细设置参考[掩码](../SIMD_compute/mask.md)。 |111| mask/mask[] | 输入 | mask用于控制每次迭代内参与计算的元素。详细设置参考[掩码](../SIMD_compute/mask.md)。 |
112| repeatTime | 输入 | 重复迭代次数。矢量计算单元，每次读取连续的256Bytes数据进行计算，为完成对输入数据的处理，必须通过多次迭代（repeat）才能完成所有数据的读取与计算。repeatTime表示迭代的次数。<br>关于该参数的具体描述请参考[高维切分](../SIMD_compute/high_dim_split.md)。 |112| repeatTime | 输入 | 重复迭代次数。矢量计算单元，每次读取连续的256Bytes数据进行计算，为完成对输入数据的处理，必须通过多次迭代（repeat）才能完成所有数据的读取与计算。repeatTime表示迭代的次数。<br>关于该参数的具体描述请参考[高维切分](../SIMD_compute/high_dim_split.md)。 |
113| repeatParams | 输入 | 控制操作数地址步长的参数。[BinaryRepeatParams](../../aux_data_structures/BinaryRepeatParams.md)类型，包含操作数相邻迭代间相同DataBlock的地址步长，操作数同一迭代内不同DataBlock的地址步长等参数。<br>相邻迭代间的地址步长参数说明请参考[repeatStride](../SIMD_compute/high_dim_split.md)；同一迭代内DataBlock的地址步长参数说明请参考[dataBlockStride](../SIMD_compute/high_dim_split.md)。 |113| repeatParams | 输入 | 控制操作数地址步长的参数。[BinaryRepeatParams](../../aux_data_structures/BinaryRepeatParams.md)类型，包含操作数相邻迭代间相同DataBlock的地址步长，操作数同一迭代内不同DataBlock的地址步长等参数。<br>相邻迭代间的地址步长参数说明请参考[repeatStride](../SIMD_compute/high_dim_split.md)；同一迭代内DataBlock的地址步长参数说明请参考[dataBlockStride](../SIMD_compute/high_dim_split.md)。 |
114-| count | 输入 | 参与计算的元素个数。设置count时，需要保证count个元素所占空间256字节对齐。未对齐部分元素不参与计算，仅完整对齐块有效。 |114+| count | 输入 | 参与计算的元素个数。关于该参数的具体说明请参考[连续计算](../SIMD_compute/continuous_compute.md)。 |
115 115 
116### mask/mask[]参数说明116### mask/mask[]参数说明
117 117 
118-<!-- npu="950" id16 -->118+<!-- npu="950" id11 -->
119- 针对Ascend 950PR/Ascend 950DT，设置有效。119- 针对Ascend 950PR/Ascend 950DT，设置有效。
120+<!-- end id11 -->
121+ 
122+<!-- npu="A3" id12 -->
123+- 针对Atlas A3 训练系列产品/Atlas A3 推理系列产品，保留参数，设置无效。
124+<!-- end id12 -->
125+ 
126+<!-- npu="910b" id13 -->
127+- 针对Atlas A2 训练系列产品/Atlas A2 推理系列产品，保留参数，设置无效。
128+<!-- end id13 -->
129+ 
130+<!-- npu="310b" id14 -->
131+- 针对Atlas 200I/500 A2 推理产品，设置有效。
132+<!-- end id14 -->
133+ 
134+<!-- npu="310p" id15 -->
135+- 针对Atlas 推理系列产品AI Core，保留参数，设置无效。
136+<!-- end id15 -->
137+ 
138+<!-- npu="910" id16 -->
139+- 针对Atlas 训练系列产品，保留参数，设置无效。
120<!-- end id16 -->140<!-- end id16 -->
121 141 
122-<!-- npu="A3" id17 -->142+<!-- npu="x90" id17 -->
123-- 针对Atlas A3 训练系列产品/Atlas A3 推理系列产品，保留参数，设置无效。143+- 针对Kirin X90，保留参数，设置无效。
124<!-- end id17 -->144<!-- end id17 -->
125 145 
126-<!-- npu="910b" id18 -->146+<!-- npu="9030" id18 -->
127-- 针对Atlas A2 训练系列产品/Atlas A2 推理系列产品，保留参数，设置无效。
128-<!-- end id18 -->
129- 
130-<!-- npu="310b" id19 -->
131-- 针对Atlas 200I/500 A2 推理产品，设置有效。
132-<!-- end id19 -->
133- 
134-<!-- npu="310p" id20 -->
135-- 针对Atlas 推理系列产品AI Core，保留参数，设置无效。
136-<!-- end id20 -->
137- 
138-<!-- npu="910" id21 -->
139-- 针对Atlas 训练系列产品，保留参数，设置无效。
140-<!-- end id21 -->
141- 
142-<!-- npu="x90" id22 -->
143-- 针对Kirin X90，保留参数，设置无效。
144-<!-- end id22 -->
145- 
146-<!-- npu="9030" id23 -->
147- 针对Kirin 9030，保留参数，设置无效。147- 针对Kirin 9030，保留参数，设置无效。
148-<!-- end id23 -->148+<!-- end id18 -->
149 149 
150## 数据类型150## 数据类型
151 151 
152-<!-- npu="950" id24 -->152+<!-- npu="950" id19 -->
153- 针对Ascend 950PR/Ascend 950DT153- 针对Ascend 950PR/Ascend 950DT
154 - T支持的数据类型为：int8_t、uint8_t、int16_t、uint16_t、half、bfloat16_t、int32_t、uint32_t、float、int64_t、uint64_t、double。其中，int8\_t/uint8\_t/int64\_t/uint64\_t/double数据类型仅支持tensor前n个数据计算接口和整个tensor参与计算的运算符重载。154 - T支持的数据类型为：int8_t、uint8_t、int16_t、uint16_t、half、bfloat16_t、int32_t、uint32_t、float、int64_t、uint64_t、double。其中，int8\_t/uint8\_t/int64\_t/uint64\_t/double数据类型仅支持tensor前n个数据计算接口和整个tensor参与计算的运算符重载。
155 - U支持的数据类型为：int8_t、uint8_t。155 - U支持的数据类型为：int8_t、uint8_t。
156-<!-- end id24 -->156+<!-- end id19 -->
157 157 
158-<!-- npu="A3" id25 -->158+<!-- npu="A3" id20 -->
159- 针对Atlas A3 训练系列产品/Atlas A3 推理系列产品159- 针对Atlas A3 训练系列产品/Atlas A3 推理系列产品
160 - T支持的数据类型为：half（所有CMPMODE都支持）、float（所有CMPMODE都支持）、int32_t（只支持CMPMODE::EQ）。160 - T支持的数据类型为：half（所有CMPMODE都支持）、float（所有CMPMODE都支持）、int32_t（只支持CMPMODE::EQ）。
161 - U支持的数据类型为：int8_t、uint8_t。161 - U支持的数据类型为：int8_t、uint8_t。
162-<!-- end id25 -->162+<!-- end id20 -->
163 163 
164-<!-- npu="910b" id26 -->164+<!-- npu="910b" id21 -->
165- 针对Atlas A2 训练系列产品/Atlas A2 推理系列产品165- 针对Atlas A2 训练系列产品/Atlas A2 推理系列产品
166 - T支持的数据类型为：half（所有CMPMODE都支持）、float（所有CMPMODE都支持）、int32_t（只支持CMPMODE::EQ）。166 - T支持的数据类型为：half（所有CMPMODE都支持）、float（所有CMPMODE都支持）、int32_t（只支持CMPMODE::EQ）。
167 - U支持的数据类型为：int8_t、uint8_t。167 - U支持的数据类型为：int8_t、uint8_t。
168-<!-- end id26 -->168+<!-- end id21 -->
169 169 
170-<!-- npu="310b" id27 -->170+<!-- npu="310b" id22 -->
171- 针对Atlas 200I/500 A2 推理产品171- 针对Atlas 200I/500 A2 推理产品
172 - T支持的数据类型为：half、float。172 - T支持的数据类型为：half、float。
173 - U支持的数据类型为：int8_t、uint8_t。173 - U支持的数据类型为：int8_t、uint8_t。
174-<!-- end id27 -->174+<!-- end id22 -->
175 175 
176-<!-- npu="310p" id28 -->176+<!-- npu="310p" id23 -->
177-- 针对Atlas 推理系列产品AI Core177+- 针对Atlas 推理系列产品 AI Core
178 - T支持的数据类型为：half、float。178 - T支持的数据类型为：half、float。
179 - U支持的数据类型为：int8_t、uint8_t。179 - U支持的数据类型为：int8_t、uint8_t。
180-<!-- end id28 -->180+<!-- end id23 -->
181 181 
182-<!-- npu="910" id29 -->182+<!-- npu="910" id24 -->
183- 针对Atlas 训练系列产品183- 针对Atlas 训练系列产品
184 - T支持的数据类型为：half、float。184 - T支持的数据类型为：half、float。
185 - U支持的数据类型为：int8_t、uint8_t。185 - U支持的数据类型为：int8_t、uint8_t。
186-<!-- end id29 -->186+<!-- end id24 -->
187 187 
188-<!-- npu="x90" id30 -->188+<!-- npu="x90" id25 -->
189- 针对Kirin X90189- 针对Kirin X90
190 - T支持的数据类型为：half（所有CMPMODE都支持）、float（所有CMPMODE都支持）、int32_t（只支持CMPMODE::EQ）。190 - T支持的数据类型为：half（所有CMPMODE都支持）、float（所有CMPMODE都支持）、int32_t（只支持CMPMODE::EQ）。
191 - U支持的数据类型为：uint8_t。191 - U支持的数据类型为：uint8_t。
192-<!-- end id30 -->192+<!-- end id25 -->
193 193 
194-<!-- npu="9030" id31 -->194+<!-- npu="9030" id26 -->
195- 针对Kirin 9030195- 针对Kirin 9030
196 - T支持的数据类型为：half（所有CMPMODE都支持）、float（所有CMPMODE都支持）、int32_t（只支持CMPMODE::EQ）。196 - T支持的数据类型为：half（所有CMPMODE都支持）、float（所有CMPMODE都支持）、int32_t（只支持CMPMODE::EQ）。
197 - U支持的数据类型为：uint8_t。197 - U支持的数据类型为：uint8_t。
198-<!-- end id31 -->198+<!-- end id26 -->
199 199 
200## 返回值说明<a name="section128671456102513"></a>200## 返回值说明<a name="section128671456102513"></a>
201 201 
@@ -207,23 +207,32 @@
207 207 
208- dst按照小端顺序排序成二进制结果，对应src中相应位置的数据比较结果。208- dst按照小端顺序排序成二进制结果，对应src中相应位置的数据比较结果。
209 209 
210-<!-- npu="A3,910b,950" id10 -->210+<!-- npu="A3,910b,950" id27 -->
211- 当参数count或repeatTime取值为0时，该接口的行为如下：211- 当参数count或repeatTime取值为0时，该接口的行为如下：
212- <!-- npu="A3,910b" id11 -->212+ <!-- npu="A3,910b" id28 -->
213 - 针对如下型号，该接口不会执行计算操作，不会对目的操作数进行写入，该接口将被视为NOP（空操作）。213 - 针对如下型号，该接口不会执行计算操作，不会对目的操作数进行写入，该接口将被视为NOP（空操作）。
214- <!-- npu="A3" id12 -->214+ <!-- npu="A3" id29 -->
215 - Atlas A3 训练系列产品/Atlas A3 推理系列产品215 - Atlas A3 训练系列产品/Atlas A3 推理系列产品
216- <!-- end id12 -->216+ <!-- end id29 -->
217- <!-- npu="910b" id13 -->217+ <!-- npu="910b" id30 -->
218 - Atlas A2 训练系列产品/Atlas A2 推理系列产品218 - Atlas A2 训练系列产品/Atlas A2 推理系列产品
219- <!-- end id13 -->219+ <!-- end id30 -->
220- <!-- end id11 -->220+ <!-- end id28 -->
221- <!-- npu="950" id14 -->221+ <!-- npu="950" id31 -->
222 - 针对Ascend 950PR/Ascend 950DT，该接口通过VF调用[Reg矢量计算API](../../reg_vector_compute/reg_vector_compute.md)实现兼容，当参数count或repeatTime取值为0时，不保证该接口将被视为NOP（空操作）。222 - 针对Ascend 950PR/Ascend 950DT，该接口通过VF调用[Reg矢量计算API](../../reg_vector_compute/reg_vector_compute.md)实现兼容，当参数count或repeatTime取值为0时，不保证该接口将被视为NOP（空操作）。
223- <!-- end id14 -->223+ <!-- end id31 -->
224-<!-- end id10 -->224+<!-- end id27 -->
225 225 
226-- **使用整个tensor参与计算的运算符重载功能，src0和src1需满足256字节对齐；使用tensor前n个数据参与计算的接口，设置count时，需要保证count个元素所占空间256字节对齐。**226+- 使用整个tensor参与计算的运算符重载功能，src0和src1需满足256字节对齐。
227+<!-- npu="A3,910b" id32 -->
228+- 针对如下型号，使用tensor前n个数据参与计算的接口，设置count时，需要保证count个元素所占空间256字节对齐。未对齐部分元素不参与计算，仅完整对齐块有效。
229+ <!-- npu="A3" id33 -->
230+ - Atlas A3 训练系列产品/Atlas A3 推理系列产品
231+ <!-- end id33 -->
232+ <!-- npu="910b" id34 -->
233+ - Atlas A2 训练系列产品/Atlas A2 推理系列产品
234+ <!-- end id34 -->
235+<!-- end id32 -->
227 236 
228## 调用示例<a name="section642mcpsimp"></a>237## 调用示例<a name="section642mcpsimp"></a>
229 238 
@@ -262,7 +271,7 @@
262 11 11 11 11 11 11 11 11 13 13 13 13 13 13 13 13 17 17 17 17 17 17 17 17 19 19 19 19 19 19 19 19 ]271 11 11 11 11 11 11 11 11 13 13 13 13 13 13 13 13 17 17 17 17 17 17 17 17 19 19 19 19 19 19 19 19 ]
263 输入数据src1Local：[ 2 2 2 2 2 2 2 2 4 4 4 4 4 4 4 4 6 6 6 6 6 6 6 6 8 8 8 8 8 8 8 8272 输入数据src1Local：[ 2 2 2 2 2 2 2 2 4 4 4 4 4 4 4 4 6 6 6 6 6 6 6 6 8 8 8 8 8 8 8 8
264 10 10 10 10 10 10 10 10 12 12 12 12 12 12 12 12 14 14 14 14 14 14 14 14 16 16 16 16 16 16 16 16 ]273 10 10 10 10 10 10 10 10 12 12 12 12 12 12 12 12 14 14 14 14 14 14 14 14 16 16 16 16 16 16 16 16 ]
265- 输出数据dstLocal： [ 0 127 127 127 0 0 0 0 ]274+ 输出数据dstLocal： [ 0(0b00000000) 255(0b11111111) 255(0b11111111) 255(0b11111111) 0(0b00000000) 0(0b00000000) 0(0b00000000) 0(0b00000000) ]
266 275 
267 GT：大于276 GT：大于
268 输入数据src0Local：[ 2 3 5 7 11 13 17 19 ... ]277 输入数据src0Local：[ 2 3 5 7 11 13 17 19 ... ]
@@ -288,7 +297,7 @@
288 NE：不等于297 NE：不等于
289 输入数据src0Local：[ 2 3 5 7 11 13 17 19 ... ]298 输入数据src0Local：[ 2 3 5 7 11 13 17 19 ... ]
290 输入数据src1Local：[ 2 4 6 8 10 12 14 16 ... ]299 输入数据src1Local：[ 2 4 6 8 10 12 14 16 ... ]
291- 输出数据dstLocal： [ 126(0b11111110) ... ]300+ 输出数据dstLocal： [ 254(0b11111110) ... ]
292 ```301 ```
293 302 
294- Tensor高维切分计算，mask逐bit模式303- Tensor高维切分计算，mask逐bit模式
@@ -316,15 +325,15 @@
316 输入数据src1Local：[ 2 2 2 2 2 2 2 2 4 4 4 4 4 4 4 4 6 6 6 6 6 6 6 6 8 8 8 8 8 8 8 8325 输入数据src1Local：[ 2 2 2 2 2 2 2 2 4 4 4 4 4 4 4 4 6 6 6 6 6 6 6 6 8 8 8 8 8 8 8 8
317 10 10 10 10 10 10 10 10 12 12 12 12 12 12 12 12 14 14 14 14 14 14 14 14 16 16 16 16 16 16 16 16 ]326 10 10 10 10 10 10 10 10 12 12 12 12 12 12 12 12 14 14 14 14 14 14 14 14 16 16 16 16 16 16 16 16 ]
318 输入数据masks：{ 858993459, 0 }327 输入数据masks：{ 858993459, 0 }
319- 输出数据dstLocal： [ 51 51 51 51 0 0 0 0 ]328+ 输出数据dstLocal： [ 51(0b00110011) 51(0b00110011) 51(0b00110011) 51(0b00110011) 0(0b00000000) 0(0b00000000) 0(0b00000000) 0(0b00000000) ]
320 ```329 ```
321 330 
322- Tensor高维切分计算，mask连续模式331- Tensor高维切分计算，mask连续模式
323 332 
324 ```cpp333 ```cpp
325 // mask控制每次迭代参与计算的连续元素个数334 // mask控制每次迭代参与计算的连续元素个数
326- // 例如，对float类型数据，每次迭代处理256B / sizeof(float) = 64个元素，因此mask可取值1至64335+ // 例如，对float类型数据，每次迭代处理256B / sizeof(float) = 64个元素
327- uint64_t mask = 28;336+ uint64_t mask = 64;
328 // repeat: 1, dstBlkStride: 1, src0BlkStride: 1, src1BlkStride: 1, dstRepStride: 1, src0RepStride: 8, src1RepStride: 8337 // repeat: 1, dstBlkStride: 1, src0BlkStride: 1, src1BlkStride: 1, dstRepStride: 1, src0RepStride: 8, src1RepStride: 8
329 AscendC::Compare(dstLocal, src0Local, src1Local, AscendC::CMPMODE::LT, mask, 1, { 1, 1, 1, 1, 8, 8 });338 AscendC::Compare(dstLocal, src0Local, src1Local, AscendC::CMPMODE::LT, mask, 1, { 1, 1, 1, 1, 8, 8 });
330 AscendC::Compare(dstLocal, src0Local, src1Local, AscendC::CMPMODE::GT, mask, 1, { 1, 1, 1, 1, 8, 8 });339 AscendC::Compare(dstLocal, src0Local, src1Local, AscendC::CMPMODE::GT, mask, 1, { 1, 1, 1, 1, 8, 8 });
@@ -342,6 +351,6 @@
342 11 11 11 11 11 11 11 11 13 13 13 13 13 13 13 13 17 17 17 17 17 17 17 17 19 19 19 19 19 19 19 19 ]351 11 11 11 11 11 11 11 11 13 13 13 13 13 13 13 13 17 17 17 17 17 17 17 17 19 19 19 19 19 19 19 19 ]
343 输入数据src1Local：[ 2 2 2 2 2 2 2 2 4 4 4 4 4 4 4 4 6 6 6 6 6 6 6 6 8 8 8 8 8 8 8 8352 输入数据src1Local：[ 2 2 2 2 2 2 2 2 4 4 4 4 4 4 4 4 6 6 6 6 6 6 6 6 8 8 8 8 8 8 8 8
344 10 10 10 10 10 10 10 10 12 12 12 12 12 12 12 12 14 14 14 14 14 14 14 14 16 16 16 16 16 16 16 16 ]353 10 10 10 10 10 10 10 10 12 12 12 12 12 12 12 12 14 14 14 14 14 14 14 14 16 16 16 16 16 16 16 16 ]
345- 输入数据mask：28354+ 输入数据mask：64
346- 输出数据dstLocal： [ 127 127 127 16 0 0 0 0 ]355+ 输出数据dstLocal： [ 255(0b11111111) 255(0b11111111) 255(0b11111111) 255(0b11111111) 0(0b00000000) 0(0b00000000) 0(0b00000000) 0(0b00000000) ]
347 ```356 ```
Mdocs/zh/api/SIMD-API/basic_api/memory_vector_compute/compare_and_select/Select.md+5-0
@@ -245,6 +245,11 @@ Kirin 9030，支持模式0、1、2。
245 - tensor前n个数据计算接口以及传入mask参数的tensor高维切分计算接口不涉及8KB Unified Buffer临时空间的占用。245 - tensor前n个数据计算接口以及传入mask参数的tensor高维切分计算接口不涉及8KB Unified Buffer临时空间的占用。
246 <!-- end id16 -->246 <!-- end id16 -->
247<!-- end id11 -->247<!-- end id11 -->
248+<!-- npu="310b" id33 -->
249+- Atlas 200I/500 A2 推理产品不支持如下函数原型：
250+ - tensor高维切分计算Select模式1中，不传入mask参数的函数原型（需配合[SetVectorMask](../mask_operations/SetVectorMask.md)、[SetCmpMask_ISASI](SetCmpMask_ISASI.md)使用）。
251+ - tensor高维切分计算Select模式0和模式2中，不传入mask参数的函数原型（需配合[SetVectorMask](../mask_operations/SetVectorMask.md)、[SetCmpMask_ISASI](SetCmpMask_ISASI.md)使用）。
252+<!-- end id33 -->
248 253 
249## 调用示例<a name="section642mcpsimp"></a>254## 调用示例<a name="section642mcpsimp"></a>
250 255 
Mdocs/zh/api/SIMD-API/basic_api/memory_vector_compute/mask_operations/SetMaskCount.md+4-0
@@ -56,6 +56,10 @@ __aicore__ inline void SetMaskCount()
56 56 
57- 设置为Counter模式的场景，需要在矢量计算使用完之后调用[SetMaskNorm](SetMaskNorm.md)将Mask模式恢复为Normal模式，以避免影响后续计算。57- 设置为Counter模式的场景，需要在矢量计算使用完之后调用[SetMaskNorm](SetMaskNorm.md)将Mask模式恢复为Normal模式，以避免影响后续计算。
58 58 
59+<!-- npu="950" id10 -->
60+- 针对Ascend 950PR/Ascend 950DT，Mask为软仿实现，Tensor前n个数据计算接口内部不会将Mask模式切换为Normal模式。若当前场景已通过本接口设置为Counter模式，接口调用后仍为Counter模式；后续计算需要使用Normal模式时，需手动调用[SetMaskNorm](SetMaskNorm.md)进行设置。
61+<!-- end id10 -->
62+ 
59## 调用示例<a name="section837496171220"></a>63## 调用示例<a name="section837496171220"></a>
60 64 
61请参考[Counter模式调用示例](SetVectorMask.md#section837496171220)。65请参考[Counter模式调用示例](SetVectorMask.md#section837496171220)。
Mdocs/zh/api/SIMD-API/basic_api/memory_vector_compute/mask_operations/SetMaskNorm.md+4-0
@@ -54,6 +54,10 @@ __aicore__ inline void SetMaskNorm()
54 54 
55- 本接口推荐配合API中IsSetMask模板参数使用，当isSetMask为false时，支持用户调用本接口手动管理Normal模式并通过[SetVectorMask](SetVectorMask.md)设置Normal模式下的掩码。55- 本接口推荐配合API中IsSetMask模板参数使用，当isSetMask为false时，支持用户调用本接口手动管理Normal模式并通过[SetVectorMask](SetVectorMask.md)设置Normal模式下的掩码。
56 56 
57+<!-- npu="950" id10 -->
58+- 针对Ascend 950PR/Ascend 950DT，Mask为软仿实现，Tensor前n个数据计算接口内部不会将Mask模式切换为Normal模式。若当前场景已通过[SetMaskCount](SetMaskCount.md)设置为Counter模式，接口调用后仍为Counter模式；后续计算需要使用Normal模式时，需手动调用本接口进行设置。
59+<!-- end id10 -->
60+ 
57## 调用示例<a name="section837496171220"></a>61## 调用示例<a name="section837496171220"></a>
58 62 
59请参考[Normal模式调用示例](SetVectorMask.md#section837496171220)。63请参考[Normal模式调用示例](SetVectorMask.md#section837496171220)。
Mdocs/zh/api/SIMD-API/basic_api/reg_vector_compute/MaskReg_compute/Select.md+36-15
@@ -57,22 +57,43 @@ __simd_callee__ inline void Select(MaskReg& dst, MaskReg& src0, MaskReg& src1, M
57 57 
58## 调用示例<a name="section932512912207"></a>58## 调用示例<a name="section932512912207"></a>
59 59 
60+如下示例处理32个`float`类型的数据，通过`Select`组合两个不同范围的掩码。`maskFirstHalf`的前16位为1、后16位为0，因此生成的`selMask`在前16位使用`maskFirstQuarter`的对应位，在后16位使用`maskFullLength`的对应位。最后，`StoreAlign`仅搬出`selMask`中有效位对应的源数据。
61+ 
60```cpp62```cpp
61-template <typename T>63+__simd_vf__ inline void SelectVF(__ubuf__ float* dstAddr, __ubuf__ float* srcAddr)
62-__simd_vf__ inline void SelectVF(ubuf T* dstAddr, ubuf T* srcAddr, uint32_t count, uint32_t oneRepeatSize, uint16_t repeatTimes)
63{64{
64- AscendC::Reg::RegTensor srcReg;65+ AscendC::Reg::RegTensor<float> srcReg;
65- AscendC::Reg::MaskReg maskFull = AscendC::Reg::CreateMask<T, AscendC::Reg::MaskPattern::ALL>();66+ AscendC::Reg::MaskReg maskFirstQuarter =
66- AscendC::Reg::MaskReg maskNone = AscendC::Reg::CreateMask<T, AscendC::Reg::MaskPattern::ALLF>();67+ AscendC::Reg::CreateMask<float, AscendC::Reg::MaskPattern::VL8>();
67- AscendC::Reg::MaskReg maskVL1 = AscendC::Reg::CreateMask<T, AscendC::Reg::MaskPattern::VL1>();68+ AscendC::Reg::MaskReg maskFirstHalf =
68- AscendC::Reg::MaskReg newMask;69+ AscendC::Reg::CreateMask<float, AscendC::Reg::MaskPattern::VL16>();
69- AscendC::Reg::MaskReg mask;70+ AscendC::Reg::MaskReg maskFullLength =
70- AscendC::Reg::Select(newMask, maskFull, maskNone, maskVL1);71+ AscendC::Reg::CreateMask<float, AscendC::Reg::MaskPattern::VL32>();
71- for (uint16_t i = 0; i < repeatTimes; ++i) {72+ AscendC::Reg::MaskReg selMask;
72- mask = AscendC::Reg::UpdateMask(count);73+ // 前16位从maskFirstQuarter取值，后16位从maskFullLength取值。
73- AscendC::Reg::LoadAlign(srcReg, srcAddr + i * oneRepeatSize);74+ AscendC::Reg::Select(selMask, maskFirstQuarter, maskFullLength, maskFirstHalf);
74- AscendC::Reg::Adds(srcReg, srcReg, 0, newMask);75+ // 仅搬入maskFullLength指示的前32个元素。
75- AscendC::Reg::StoreAlign(dstAddr + i * oneRepeatSize, srcReg, mask);76+ AscendC::Reg::LoadAlign<float, AscendC::Reg::DataCopyMode::DATA_BLOCK_COPY>(
76- }77+ srcReg, srcAddr, 1, maskFullLength);
78+ AscendC::Reg::StoreAlign(dstAddr, srcReg, selMask);
77}79}
78```80```
81+ 
82+输入数据如下，`srcAddr`的前16个元素为`1.0`、后16个元素为`2.0`，`dstAddr`的32个元素均为`0.0`：
83+ 
84+```text
85+srcAddr = [1.0, 1.0, ..., 1.0, 2.0, 2.0, ..., 2.0]
86+dstAddr = [0.0, 0.0, ..., 0.0]
87+```
88+ 
89+`Select`执行后，`selMask`的前8位为1、第9位至第16位为0、后16位为1，其余位均为0。`selMask`是`MaskReg`类型，因此其中的值表示掩码比特：
90+ 
91+```text
92+selMask = [1, 1, ..., 1, 0, 0, ..., 0, 1, 1, ..., 1]
93+```
94+ 
95+`StoreAlign`执行后，`dstAddr`的前8个元素为`1.0`，第9个至第16个元素保持初始值`0.0`，后16个元素为`2.0`：
96+ 
97+```text
98+dstAddr = [1.0, 1.0, ..., 1.0, 0.0, 0.0, ..., 0.0, 2.0, 2.0, ..., 2.0]
99+```
Mdocs/zh/api/SIMD-API/basic_api/reg_vector_compute/compare_and_select/Squeeze.md+1-1
@@ -34,7 +34,7 @@
34 34 
35![Squeeze计算示意图](../../../../figures/reg_squeeze.png)35![Squeeze计算示意图](../../../../figures/reg_squeeze.png)
36 36 
37-特别地，当模板参数store取值为`GatherMaskMode::STORE_REG`时，`Squeeze`会将有效元素的总字节数存入AR特殊寄存器。此时配合使用[连续非对齐搬出](../reg_data_store/StoreUnAlign_continuous.md)的场景3接口（无需显式传入偏移量），`StoreUnAlign`会自动从AR寄存器读取有效字节数作为地址偏移，参考[调用示例](#调用示例)。37+特别地，当模板参数store取值为`GatherMaskMode::STORE_REG`时，`Squeeze`会将有效元素的总字节数存入[AR特殊寄存器](../../special_register_access/GetSpr.md#table37531617424)。此时配合使用[连续非对齐搬出](../reg_data_store/StoreUnAlign_continuous.md)的场景3接口（无需显式传入偏移量），`StoreUnAlign`会自动从AR寄存器读取有效字节数作为地址偏移，参考[调用示例](#调用示例)。
38 38 
39## 函数原型<a name="section620mcpsimp"></a>39## 函数原型<a name="section620mcpsimp"></a>
40 40 
Mdocs/zh/api/SIMD-API/basic_api/special_register_access/GetSpr.md+1-1
@@ -49,7 +49,7 @@ __aicore__ inline int64_t GetSpr()
49 49 
50| 取值 | 含义 |50| 取值 | 含义 |
51|------|------|51|------|------|
52-| AR | 通常配合[Squeeze](../reg_vector_compute/compare_and_select/Squeeze.md)，Reg矢量计算API一起使用；[Squeeze](../reg_vector_compute/compare_and_select/Squeeze.md)，Reg矢量计算API会存储有效元素的总字节数到AR特殊寄存器。 |52+| AR | AR寄存器通常配合Reg矢量计算API [Squeeze](../reg_vector_compute/compare_and_select/Squeeze.md)和[连续非对齐搬出](../reg_vector_compute/reg_data_store/StoreUnAlign_continuous.md)的场景3（无需显式传入偏移量）接口一起使用，寄存器会存储有效元素的总字节数。 |
53 53 
54## 数据类型<a name="section3853852112218"></a>54## 数据类型<a name="section3853852112218"></a>
55 55