昇腾C GatherMask函数文档

GatherMask产品支持情况产品是否支持Ascend 950PR/Ascend 950DT√Atlas A3 训练系列产品 / Atlas A3 推理系列产品√Atlas A2 训练系列产品 / Atlas A2 推理系列产品√Atlas 200I/500 A2 推理产品√Atlas 推理系列产品 AI Core√Atlas 推理系列产品 Vector CorexAtlas 训练系列产品x功能说明以内置固定模式对应的二进制或者用户自定义输入的Tensor数值对应的二进制为gather mask数据收集的掩码从源操作数中选取元素写入目的操作数中。函数原型用户自定义模式template typename T, typename U, GatherMaskMode mode defaultGatherMaskMode __aicore__ inline void GatherMask(const LocalTensorT dst, const LocalTensorT src0, const LocalTensorU src1Pattern, const bool reduceMode, const uint32_t mask, const GatherMaskParams gatherMaskParams, uint64_t rsvdCnt)内置固定模式template typename T, GatherMaskMode mode defaultGatherMaskMode __aicore__ inline void GatherMask(const LocalTensorT dst, const LocalTensorT src0, const uint8_t src1Pattern, const bool reduceMode, const uint32_t mask, const GatherMaskParams gatherMaskParams, uint64_t rsvdCnt)参数说明表 1模板参数说明参数名称含义T源操作数src0和目的操作数dst的数据类型。Ascend 950PR/Ascend 950DT支持的数据类型为int8_t/uint8_t/int16_t/uint16_t/half/bfloat16_t/float/int32_t/uint32_tAtlas A3 训练系列产品 / Atlas A3 推理系列产品支持的数据类型为half/bfloat16_t/uint16_t/int16_t/float/uint32_t/int32_tAtlas A2 训练系列产品 / Atlas A2 推理系列产品支持的数据类型为half/bfloat16_t/uint16_t/int16_t/float/uint32_t/int32_tAtlas 200I/500 A2 推理产品支持的数据类型为half/uint16_t/int16_t/float/uint32_t/int32_tAtlas 推理系列产品 AI Core支持的数据类型为half/uint16_t/int16_t/float/uint32_t/int32_tU用户自定义模式下src1Pattern的数据类型。支持的数据类型为uint8_t/uint16_t/uint32_t。当目的操作数数据类型为uint8_t/int8_t时src1Pattern应为uint8_t数据类型。当目的操作数数据类型为b16时src1Pattern应为uint16_t数据类型。当目的操作数数据类型为float/uint32_t/int32_t时src1Pattern应为uint32_t数据类型。mode预留参数为后续功能做预留当前提供默认值用户无需设置该参数。表 2参数说明参数名称输入/输出含义dst输出目的操作数。类型为LocalTensor支持的TPosition为VECIN/VECCALC/VECOUT。LocalTensor的起始地址需要32字节对齐。src0输入源操作数。类型为LocalTensor支持的TPosition为VECIN/VECCALC/VECOUT。LocalTensor的起始地址需要32字节对齐。数据类型需要与目的操作数保持一致。src1Pattern输入gather mask数据收集的掩码分为内置固定模式和用户自定义模式两种根据内置固定模式对应的二进制或者用户自定义输入的Tensor数值对应的二进制从源操作数中选取元素写入目的操作数中。1为选取0为不选取。内置固定模式src1Pattern数据类型为uint8_t取值范围为[1,7]所有repeat迭代使用相同的gather mask。不支持配置src1RepeatStride。101010101…0101 # 每个repeat取偶数索引元素210101010…1010 # 每个repeat取奇数索引元素300010001…0001 # 每个repeat内每四个元素取第一个元素400100010…0010 # 每个repeat内每四个元素取第二个元素501000100…0100 # 每个repeat内每四个元素取第三个元素610001000…1000 # 每个repeat内每四个元素取第四个元素711111111...1111 # 每个repeat内取全部元素Ascend 950PR/Ascend 950DT支持模式1-7Atlas A3 训练系列产品 / Atlas A3 推理系列产品支持模式1-7Atlas A2 训练系列产品 / Atlas A2 推理系列产品支持模式1-7Atlas 200I/500 A2 推理产品支持模式1-7Atlas 推理系列产品 AI Core支持模式1-6用户自定义模式src1Pattern数据类型为LocalTensor迭代间间隔由src1RepeatStride决定 迭代内src1Pattern连续消耗。LocalTensor的起始地址需要32字节对齐。reduceMode输入用于选择mask参数模式数据类型为bool支持如下取值。falseNormal模式。该模式下每次repeat操作256Bytes数据总的数据计算量为repeatTimes * 256Bytes。mask参数无效建议设置为0。按需配置repeatTimes、src0BlockStride、src0RepeatStride参数。支持src1Pattern配置为内置固定模式或用户自定义模式。用户自定义模式下可根据实际情况配置src1RepeatStride。trueCounter模式。根据mask等参数含义的不同该模式有以下两种配置方式配置方式一每次repeat操作mask个元素总的数据计算量为repeatTimes * mask个元素。mask值配置为每一次repeat计算的元素个数。按需配置repeatTimes、src0BlockStride、src0RepeatStride参数。支持src1Pattern配置为内置固定模式或用户自定义模式。用户自定义模式下可根据实际情况配置src1RepeatStride。配置方式二总的数据计算量为mask个元素。mask配置为总的数据计算量。repeatTimes值不生效指令的迭代次数由源操作数和mask共同决定。按需配置src0BlockStride、src0RepeatStride参数。支持src1Pattern配置为内置固定模式或用户自定义模式。用户自定义模式下可根据实际情况配置src1RepeatStride。Ascend 950PR/Ascend 950DT支持配置方式一Atlas A3 训练系列产品 / Atlas A3 推理系列产品支持配置方式一Atlas A2 训练系列产品 / Atlas A2 推理系列产品支持配置方式一Atlas 200I/500 A2 推理产品支持配置方式一Atlas 推理系列产品 AI Core支持配置方式二mask输入用于控制每次迭代内参与计算的元素。根据reduceMode分为两种模式Normal模式mask无效建议设置为0。Counter模式取值范围[1, 232– 1]。不同的版本型号Counter模式下mask参数表示含义不同。具体配置规则参考上文reduceMode参数描述。gatherMaskParams输入控制操作数地址步长的数据结构GatherMaskParams类型。具体定义请参考${INSTALL_DIR}/include/ascendc/basic_api/interface/kernel_struct_gather.h${INSTALL_DIR}请替换为CANN软件安装后文件存储路径。具体参数说明表3。rsvdCnt输出该条指令筛选后保留下来的元素计数对应dstLocal中有效元素个数数据类型为uint64_t。表 3GatherMaskParams结构体参数说明参数名称含义src0BlockStride用于设置src0同一迭代不同DataBlock间的地址步长起始地址之间的间隔。单位为DataBlock。repeatTimes迭代次数。src0RepeatStride用于设置src0相邻迭代间的地址步长起始地址之间的间隔。单位为DataBlock。src1RepeatStride用于设置src1相邻迭代间的地址步长起始地址之间的间隔。单位为DataBlock。返回值说明无约束说明操作数地址对齐要求请参见通用地址对齐约束。操作数地址重叠约束请参考通用地址重叠约束。若调用该接口前为Counter模式在调用该接口后需要显式设置回Counter模式接口内部执行结束后会设置为Normal模式。调用示例用户自定义Tensor样例示例完整的调用样例可参考Gather类样例场景二。uint32_t mask 70; // 每次迭代内参与计算的元素 uint64_t rsvdCnt 0; // 保留下来的元素个数 // src0Local源操作数 // src1Local存放数据收集的掩码的Tensor // dstLocal目的操作数 // reduceMode true; 使用Counter模式 // {}中的参数为 // src0BlockStride 1; 单次迭代内数据间隔1个datablock即数据连续读取和写入 // repeatTimes 2; Counter模式时仅在部分产品型号下会生效 // src0RepeatStride 4; 源操作数迭代间数据间隔4个datablock // src1RepeatStride 0; src1迭代间数据间隔0个datablock即原位置读取 AscendC::GatherMask (dstLocal, src0Local, src1Local, true, mask, { 1, 2, 4, 0 }, rsvdCnt);下图为Counter模式配置方式一示意图mask 70每一次repeat计算70个元素repeatTimes 2共进行2次repeatsrc0BlockStride 1源操作数src0Local单次迭代内datablock之间无间隔src0RepeatStride 4源操作数src0Local相邻迭代间的间隔为4个datablock所以第二次repeat从第33个元素开始处理。src1Pattern配置为用户自定义模式。src1RepeatStride 0src1Pattern相邻迭代间的间隔为0个datablock所以第二次repeat仍从src1Pattern的首地址开始处理。图 1Counter模式配置方式一示意图下图为Counter模式配置方式二示意图mask 70一共计算70个元素repeatTimes配置不生效根据源操作数和mask自动推断源操作数的数据类型为uint32_t每个迭代处理256Bytes数据一个迭代处理64个元素共需要进行2次repeatsrc0BlockStride 1源操作数src0Local单次迭代内datablock之间无间隔src0RepeatStride 4源操作数src0Local相邻迭代间的间隔为4个datablock所以第二次repeat从第33个元素开始处理。src1Pattern配置为用户自定义模式。src1RepeatStride 0src1Pattern相邻迭代间的间隔为0个datablock所以第二次repeat仍从src1Pattern的首地址开始处理。图 2Counter模式配置方式二示意图内置固定模式样例示例完整的调用样例可参考Gather类样例场景一。uint32_t mask 0; // 每次迭代内参与计算的元素normal模式下mask建议设置为0 uint64_t rsvdCnt 0; // 用于保存筛选后保留下来的元素个数 uint8_t src1Pattern 2; // 内置固定模式 // src0Local源操作数 // src1Pattern 存放数据收集的掩码的Tensor // src0Local目的地址与源地址复用 // reduceMode false; 使用normal模式 // {}中的参数为 // src0BlockStride 1; 单次迭代内数据间隔1个Block即数据连续读取和写入 // repeatTimes 4;重复迭代4次 // src0RepeatStride 8;源操作数迭代数据间隔8个datablock // src1RepeatStride 0;重复一次故设置为0 AscendC::GatherMask(src0Local, src0Local, src1Pattern, false, mask, { 1, 4, 8, 0 }, rsvdCnt);结果示例如下输入数据src0Local[1 2 3 ... 256] 输入数据src1Patternsrc1Pattern 2; 输出数据dstLocal[ 2 4 6 8 10 12 14 16 18 20 22 24 26 28 30 32 34 36 38 40 42 44 46 48 50 52 54 56 58 60 62 64 66 68 70 72 74 76 78 80 82 84 86 88 90 92 94 96 98 100 102 104 106 108 110 112 114 116 118 120 122 124 126 128 130 132 134 136 138 140 142 144 146 148 150 152 154 156 158 160 162 164 166 168 170 172 174 176 178 180 182 184 186 188 190 192 194 196 198 200 202 204 206 208 210 212 214 216 218 220 222 224 226 228 230 232 234 236 238 240 242 244 246 248 250 252 254 256 undefined ..undefined] 输出数据rsvdCnt128创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考