GatherMask
产品支持情况
功能说明
以内置固定模式对应的二进制或者用户自定义输入的Tensor数值对应的二进制为gather mask（数据收集的掩码），从源操作数中选取元素写入目的操作数中。
函数原型
用户自定义模式
template <typename T, typename U, GatherMaskMode mode = defaultGatherMaskMode> __aicore__ inline void GatherMask(const LocalTensor<T>& dst, const LocalTensor<T>& src0, const LocalTensor<U>& 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 LocalTensor<T>& dst, const LocalTensor<T>& src0, const uint8_t src1Pattern, const bool reduceMode, const uint32_t mask, const GatherMaskParams& gatherMaskParams, uint64_t& rsvdCnt)
参数说明
表 1模板参数说明
表 2参数说明
表 3GatherMaskParams结构体参数说明
返回值说明
无
约束说明
操作数地址对齐要求请参见通用地址对齐约束。
操作数地址重叠约束请参考通用地址重叠约束。
若调用该接口前为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次repeat；
- src0BlockStride = 1，源操作数src0Local单次迭代内datablock之间无间隔；
- src0RepeatStride = 4，源操作数src0Local相邻迭代间的间隔为4个datablock，所以第二次repeat从第33个元素开始处理。
- src1Pattern配置为用户自定义模式。src1RepeatStride = 0，src1Pattern相邻迭代间的间隔为0个datablock，所以第二次repeat仍从src1Pattern的首地址开始处理。
图 1Counter模式配置方式一示意图
![](https://raw.gitcode.com/cann/asc-devkit/raw/68eb55191616e7a7b08961a5c82a706272353b5f/docs/api/figures/Counter模式配置方式一示意图.png "Counter模式配置方式一示意图"?utm_source=gitcode_repo_files)下图为Counter模式配置方式二示意图：
- mask = 70，一共计算70个元素；
- repeatTimes配置不生效，根据源操作数和mask自动推断：源操作数的数据类型为uint32_t，每个迭代处理256Bytes数据，一个迭代处理64个元素，共需要进行2次repeat；
- src0BlockStride = 1，源操作数src0Local单次迭代内datablock之间无间隔；
- src0RepeatStride = 4，源操作数src0Local相邻迭代间的间隔为4个datablock，所以第二次repeat从第33个元素开始处理。
- src1Pattern配置为用户自定义模式。src1RepeatStride = 0，src1Pattern相邻迭代间的间隔为0个datablock，所以第二次repeat仍从src1Pattern的首地址开始处理。
图 2Counter模式配置方式二示意图
![](https://raw.gitcode.com/cann/asc-devkit/raw/68eb55191616e7a7b08961a5c82a706272353b5f/docs/api/figures/Counter模式配置方式二示意图.png "Counter模式配置方式二示意图"?utm_source=gitcode_repo_files)内置固定模式样例示例，完整的调用样例可参考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] 输入数据src1Pattern：src1Pattern = 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] 输出数据rsvdCnt：128
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
简介及应用设计)
