--- title: 如何使用掩码操作API description: "Mask用于控制矢量计算中参与计算的元素个数，支持以下工作模式及配置方式：" url: https://www.hiascend.com/document/detail/zh/canncommercial/latest/programug/Ascendcopdevg/atlas_ascendc_10_0024.html sourcePath: /source/zh/canncommercial/900/programug/Ascendcopdevg/atlas_ascendc_10_0024.html indexId: 3493bfe45a8606d55f91d29a3d2cca6fb74c8b110d14e6740541937b77a1b9a880 --- # 如何使用掩码操作API Mask用于控制矢量计算中参与计算的元素个数，支持以下工作模式及配置方式： **表1 Mask工作模式** | 工作模式 | 说明 | | --- | --- | | Normal模式 | 默认模式，支持单次迭代内的Mask能力，需要开发者配置迭代次数，额外进行尾块的计算。 Normal模式下，Mask用来控制单次迭代内参与计算的元素个数。 通过调用SetMaskNorm(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc\_api\_07\_0095.html)设置Normal模式。 | | Counter模式 | 简化模式，直接传入计算数据量，自动推断迭代次数，不需要开发者去感知迭代次数、处理非对齐尾块的操作；但是不具备单次迭代内的Mask能力。 Counter模式下，Mask表示整个矢量计算参与计算的元素个数。 通过调用SetMaskCount(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc\_api\_07\_0094.html)设置Counter模式。 | **表2 Mask配置方式** | 配置方式 | 说明 | | --- | --- | | 接口传参（默认） | 通过矢量计算API的入参直接传递Mask值。矢量计算API的模板参数isSetMask（仅部分API支持）用于控制接口传参还是外部API配置，默认值为true，表示接口传参。Mask对应于高维切分计算API中的mask/mask[]参数或者tensor前n个数据计算API中的calCount参数。 | | 外部API配置 | 调用SetVectorMask(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc\_api\_07\_0096.html)接口设置Mask值，矢量计算API的模板参数isSetMask设置为false，接口入参中的Mask参数（对应于高维切分计算API中的mask/mask[]参数或者tensor前n个数据计算API中的calCount参数）不生效。适用于Mask参数相同，多次重复使用的场景，无需在矢量计算API内部反复设置，会有一定的性能优势。 | Mask操作的使用方式如下： **表3 Mask操作的使用方式** | 配置方式 | 工作模式 | 前n个数据计算API | 高维切分计算API | | --- | --- | --- | --- | | 接口传参 | Normal模式 | 不涉及。 | isSetMask模板参数设置为true，通过接口入参传入Mask，根据使用场景配置dataBlockStride、repeatStride、repeatTime参数。 | | 接口传参 | Counter模式 | isSetMask模板参数设置为true，通过接口入参传入Mask。 | isSetMask模板参数设置为true，通过接口入参传入Mask。 根据使用场景配置dataBlockStride、repeatStride参数。repeatTime传入固定值即可，建议统一设置为1，该值不生效。 | | 外部API配置 | Normal模式 | 不涉及。 | 调用SetVectorMask(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc\_api\_07\_0096.html)设置Mask，之后调用高维切分计算API。 isSetMask模板参数设置为false，接口入参中的mask值设置为占位符MASK\_PLACEHOLDER，用于占位，无实际含义。 根据使用场景配置repeatTime、dataBlockStride、repeatStride参数。 | | 外部API配置 | Counter模式 | 调用SetVectorMask(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc\_api\_07\_0096.html)设置Mask，之后调用前n个数据计算API，isSetMask模板参数设置为false；接口入参中的calCount建议设置成1。 | 调用SetVectorMask(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc\_api\_07\_0096.html)设置Mask，之后调用高维切分计算API。 isSetMask模板参数设置为false；接口入参中的mask值设置为MASK\_PLACEHOLDER，用于占位，无实际含义。 根据使用场景配置dataBlockStride、repeatStride参数。repeatTime传入固定值即可，建议统一设置为1，该值不生效。 | 典型场景的使用示例如下： - 场景1：Normal模式 + 外部API配置 + 高维切分计算API 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 AscendC::LocalTensor dstLocal; AscendC::LocalTensor src0Local; AscendC::LocalTensor src1Local; // 1、设置Normal模式 AscendC::SetMaskNorm(); // 2、设置Mask AscendC::SetVectorMask(0xffffffffffffffff, 0xffffffffffffffff); // 逐bit模式 // SetVectorMask(128); // 连续模式 // 3、多次调用矢量计算API, isSetMask模板参数设置为false，接口入参中的mask值设置为占位符MASK_PLACEHOLDER，用于占位，无实际含义 // 根据使用场景配置repeatTime、dataBlockStride、repeatStride参数 // dstBlkStride, src0BlkStride, src1BlkStride = 1, 单次迭代内数据连续读取和写入 // dstRepStride, src0RepStride, src1RepStride = 8, 相邻迭代间数据连续读取和写入 AscendC::Add(dstLocal, src0Local, src1Local, AscendC::MASK_PLACEHOLDER, 1, { 2, 2, 2, 8, 8, 8 }); AscendC::Sub(src0Local, dstLocal, src1Local, AscendC::MASK_PLACEHOLDER, 1, { 2, 2, 2, 8, 8, 8 }); AscendC::Mul(src1Local, dstLocal, src0Local, AscendC::MASK_PLACEHOLDER, 1, { 2, 2, 2, 8, 8, 8 }); // 4、恢复Mask值为默认值 AscendC::ResetMask(); - 场景2：Counter模式 + 外部API配置 + 高维切分计算API 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 AscendC::LocalTensor dstLocal; AscendC::LocalTensor src0Local; AscendC::LocalTensor src1Local; int32_t len = 128; // 参与计算的元素个数 // 1、设置Counter模式 AscendC::SetMaskCount(); // 2、设置Mask AscendC::SetVectorMask(len); // 3、多次调用矢量计算API, isSetMask模板参数设置为false；接口入参中的mask值设置为MASK_PLACEHOLDER，用于占位，无实际含义 // 根据使用场景正确配置dataBlockStride、repeatStride参数。repeatTime传入固定值即可，建议统一设置为1，该值不生效 AscendC::Add(dstLocal, src0Local, src1Local, AscendC::MASK_PLACEHOLDER, 1, { 1, 1, 1, 8, 8, 8 }); AscendC::Sub(src0Local, dstLocal, src1Local, AscendC::MASK_PLACEHOLDER, 1, { 1, 1, 1, 8, 8, 8 }); AscendC::Mul(src1Local, dstLocal, src0Local, AscendC::MASK_PLACEHOLDER, 1, { 1, 1, 1, 8, 8, 8 }); // 4、恢复工作模式 AscendC::SetMaskNorm(); // 5、恢复Mask值为默认值 AscendC::ResetMask(); - 场景3：Counter模式 + 外部API配置 + 前n个数据计算接口配合使用 1 2 3 4 5 6 7 8 9 10 11 12 AscendC::LocalTensor dstLocal; AscendC::LocalTensor src0Local; half num = 2; // 1、设置Mask AscendC::SetVectorMask(128); // 参与计算的元素个数为128 // 2、调用前n个数据计算API，isSetMask模板参数设置为false；接口入参中的calCount建议设置成1。 AscendC::Adds(dstLocal, src0Local, num, 1); AscendC::Muls(dstLocal, src0Local, num, 1); // 3、恢复工作模式 AscendC::SetMaskNorm(); // 4、恢复Mask值为默认值 AscendC::ResetMask(); - 前n个数据计算API接口内部会设置工作模式为Counter模式，所以如果前n个数据计算API配合Counter模式使用时，无需手动调用 SetMaskCount(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc_api_07_0094.html) 设置Counter模式。 - 所有手动使用Counter模式的场景，使用完毕后，需要调用 SetMaskNorm(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc_api_07_0095.html) 恢复工作模式。 - 调用 SetVectorMask(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc_api_07_0096.html) 设置Mask，使用完毕后，需要调用 ResetMask(https://www.hiascend.comdocument/detail/zh/canncommercial/900/API/ascendcopapi/atlasascendc_api_07_0097.html) 恢复Mask值为默认值。 - 使用高维切分计算API配套Counter模式使用时，比前n个数据计算API增加了可间隔的计算，支持dataBlockStride、repeatStride参数。