Ascend C
搜 索

Appearance

版 本
本 页 内 容

GatherMask

产 品 支 持 情 况​

产 品

是 否 支 持

Ascend 950PR/Ascend 950DT

√

Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品

√

Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品

√

Atlas 200I/500 A2 推 理 产 品

√

Atlas 推 理 系 列 产 品AI Core

√

Atlas 推 理 系 列 产 品Vector Core

x

Atlas 训 练 系 列 产 品

x

功 能 说 明​

头 文 件 路 径 为："basic_api/kernel_operator_vec_gather_mask_intf.h"。

以内 置 固 定 模 式或 者用 户 自 定 义 输 入 的Tensor数 值 对 应 的 二 进 制 为gather mask（数 据 收 集 的 掩 码），从 源 操 作 数 中 选 取 元 素 写 入 目 的 操 作 数 中。1为 选 取，0为 不 选 取。

  • 内 置 固 定 模 式：对 应 函 数 原 型 中src1Pattern的 数 据 类 型 为uint8_t类 型。gather mask由src1Pattern参 数 指 定，并 在 所 有repeat迭 代 中 保 持 固 定。src1Pattern取 值 范 围 为[1, 7]。

    • 1：01010101…0101 # 每 个repeat取 偶 数 索 引 元 素
    • 2：10101010…1010 # 每 个repeat取 奇 数 索 引 元 素
    • 3：00010001…0001 # 每 个repeat内 每 四 个 元 素 取 第 一 个 元 素
    • 4：00100010…0010 # 每 个repeat内 每 四 个 元 素 取 第 二 个 元 素
    • 5：01000100…0100 # 每 个repeat内 每 四 个 元 素 取 第 三 个 元 素
    • 6：10001000…1000 # 每 个repeat内 每 四 个 元 素 取 第 四 个 元 素
    • 7：11111111…1111 # 每 个repeat内 取 全 部 元 素

    Ascend 950PR/Ascend 950DT，支 持 模 式1-7。

    Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品，支 持 模 式1-7。

    Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品，支 持 模 式1-7。

    Atlas 推 理 系 列 产 品，支 持 模 式1-7。

    Atlas 200I/500 A2 推 理 产 品，支 持 模 式1-6。

  • 用 户 自 定 义 模 式：对 应 函 数 原 型 中src1Pattern的 数 据 类 型 为LocalTensor，迭 代 间 间 隔 由src1RepeatStride决 定， 迭 代 内src1Pattern连 续 消 耗。

GatherMask接 口 计 算 过 程 如 下 图 所 示，参 数 设 置 为：mask=70，repeatTimes=2，src0Block=0，src0BlockStride=1，src0RepeatStride=8，src1RepeatStride=0。

以 下 示 例 均 基 于Counter模 式，该 模 式 支 持 两 种 配 置 方 式：

  • 配 置 方 式 一：每 次repeat操 作mask个 元 素，总 的 数 据 计 算 量 为repeatTimes * mask个 元 素。mask值 配 置 为 每 一 次repeat计 算 的 元 素 个 数。

  • 配 置 方 式 二：总 的 数 据 计 算 量 为mask个 元 素。mask配 置 为 总 的 数 据 计 算 量。 repeatTimes值 不 生 效，指 令 的 迭 代 次 数 由 源 操 作 数 和mask共 同 决 定。

    Ascend 950PR/Ascend 950DT，支 持 配 置 方 式 一。

    Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品，支 持 配 置 方 式 一。

    Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品，支 持 配 置 方 式 一。

    Atlas 200I/500 A2 推 理 产 品，支 持 配 置 方 式 一。

    Atlas 推 理 系 列 产 品AI Core，支 持 配 置 方 式 二。

图1采 用 内 置 固 定 模 式2进 行 计 算，每 个repeat取 奇 数 索 引 元 素。

图2、图3采 用 用 户 自 定 义 模 式 进 行 计 算，自 定 义 输 入 的Tensor为[0x99999999,...,0x99999999]，对 应 二 进 制 为1001…1001，每 四 个 元 素 取 第 一 个 和 第 四 个 元 素。

图 1 GatherMask内 置 固 定 模 式 计 算 示 意 图

图 2 GatherMask用 户 自 定 义 模 式 计 算 示 意 图（配 置 方 式 一）

图 3 GatherMask用 户 自 定 义 模 式 计 算 示 意 图（配 置 方 式 二）

函 数 原 型​

  • 用 户 自 定 义 模 式

    C++
    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)

  • 内 置 固 定 模 式

    C++
    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 模 板 参 数 说 明

参 数 名 称描 述
T源 操 作 数src0和 目 的 操 作 数dst的 数 据 类 型。
U用 户 自 定 义 模 式 下src1Pattern的 数 据 类 型。
mode预 留 参 数，为 后 续 功 能 做 预 留，当 前 提 供 默 认 值，用 户 无 需 设 置 该 参 数。

表 2 参 数 说 明

参 数 名 称输 入/输 出描 述
dst输 出目 的 操 作 数。
类 型 为LocalTensor，支 持 的TPosition为VECIN/VECCALC/VECOUT。
LocalTensor的 起 始 地 址 需 要32字 节 对 齐。
src0输 入源 操 作 数。
类 型 为LocalTensor，支 持 的TPosition为VECIN/VECCALC/VECOUT。
LocalTensor的 起 始 地 址 需 要32字 节 对 齐。
数 据 类 型 需 要 与 目 的 操 作 数 保 持 一 致。
src1Pattern输 入gather mask（数 据 收 集 的 掩 码），分 为 内 置 固 定 模 式 和 用 户 自 定 义 模 式 两 种，根 据 内 置 固 定 模 式 对 应 的 二 进 制 掩 码 或 者 用 户 自 定 义 输 入 的Tensor数 值 对 应 的 二 进 制 掩 码 从 源 操 作 数 中 选 取 元 素 写 入 目 的 操 作 数 中。1为 选 取，0为 不 选 取。具 体 说 明 请 参 考功 能 说 明。
注：内 置 固 定 模 式 下src1RepeatStride参 数 无 效。
reduceMode输 入用 于 选 择mask参 数 模 式，数 据 类 型 为bool，支 持 如 下 取 值：
• false：Normal模 式。该 模 式 下，每 次repeat操 作256Bytes数 据，总 的 数 据 计 算 量 为repeatTimes * 256Bytes。此 模 式 下mask参 数 无 效，建 议 设 置 为0。
• true：Counter模 式。根 据mask等 参 数 含 义 的 不 同，该 模 式 存 在 两 种 配 置 方 式。具 体 说 明 请 参 考功 能 说 明。
两 种 取 值 都 支 持：
• 按 需 配 置src0BlockStride、src0RepeatStride参 数。
• 支 持src1Pattern配 置 为 内 置 固 定 模 式 或 用 户 自 定 义 模 式。用 户 自 定 义 模 式 下 可 根 据 实 际 情 况 配 置src1RepeatStride。
mask输 入用 于 控 制 每 次 迭 代 内 参 与 计 算 的 元 素。根 据reduceMode，分 为 两 种 模 式：
• Normal模 式：mask无 效，建 议 设 置 为0。
• Counter模 式：取 值 范 围[1, 232 – 1]。不 同 的 版 本 型 号Counter模 式 下，mask参 数 表 示 含 义 不 同。具 体 配 置 规 则 参 考 上 文reduceMode参 数 描 述。
gatherMaskParams输 入控 制 操 作 数 地 址 步 长 的 数 据 结 构，GatherMaskParams类 型。
具 体 参 数 说 明表3 GatherMaskParams结 构 体 参 数 说 明。
rsvdCnt输 出该 条 指 令 筛 选 后 保 留 下 来 的 元 素 计 数，对 应dstLocal中 有 效 元 素 个 数，数 据 类 型 为uint64_t。

表 3 GatherMaskParams结 构 体 参 数 说 明

参 数 名 称描 述
src0BlockStride用 于 设 置src0同 一 迭 代 不 同DataBlock间 的 地 址 步 长（起 始 地 址 之 间 的 间 隔）。单 位 为DataBlock。详 细 说 明 请 参 考dataBlockStride。
repeatTimes重 复 迭 代 次 数。矢 量 计 算 单 元，每 次 读 取 连 续 的256Bytes数 据 进 行 计 算，为 完 成 对 输 入 数 据 的 处 理，必 须 通 过 多 次 迭 代（repeat）才 能 完 成 所 有 数 据 的 读 取 与 计 算。repeatTimes表 示 迭 代 的 次 数。
关 于 该 参 数 的 具 体 描 述 请 参 考高 维 切 分。
src0RepeatStride用 于 设 置src0相 邻 迭 代 间 的 地 址 步 长（起 始 地 址 之 间 的 间 隔）。单 位 为DataBlock。详 细 说 明 请 参 考repeatStride。
src1RepeatStride用 于 设 置src1相 邻 迭 代 间 的 地 址 步 长（起 始 地 址 之 间 的 间 隔）。单 位 为DataBlock。详 细 说 明 请 参 考repeatStride。

数 据 类 型​

表 4 数 据 类 型 组 合 情 况

src0数 据 类 型src1Pattern数 据 类 型dst数 据 类 型
int8_t
uint8_tint8_t
uint8_t
uint8_tuint8_t
int16_tuint16_tint16_t
uint16_tuint16_tuint16_t
halfuint16_thalf
bfloat16_t
uint16_tbfloat16_t
int32_tuint32_tint32_t
uint32_tuint32_tuint32_t
floatuint32_tfloat

返 回 值 说 明​

无

约 束 说 明​

  • 操 作 数 地 址 对 齐 要 求 请 参 见通 用 地 址 对 齐 约 束。

  • 操 作 数 地 址 重 叠 约 束 请 参 考通 用 地 址 重 叠 约 束。

  • 采 用 内 置 固 定 模 式 时，配 置src1RepeatStride参 数 无 效。

  • 若 调 用 该 接 口 前 为Counter模 式，在 调 用 该 接 口 后 需 要 显 式 设 置 回Counter模 式（接 口 内 部 执 行 结 束 后 会 设 置 为Normal模 式）。

调 用 示 例​

<<<<<<< HEAD

  • 用 户 自 定 义Tensor示 例，完 整 的 调 用 样 例 可 参 考Gather类 样 例场 景 二。 =======
  • 用 户 自 定 义Tensor样 例 示 例，完 整 的 调 用 样 例 可 参 考Gather类 样 例场 景 二。

2cee38201 (cOptimize 01_simd_cpp_api sample directory structure)

Text
```cpp
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);
```

  • 内 置 固 定 模 式 示 例，完 整 的 调 用 样 例 可 参 考Gather类 样 例场 景 一。

    C++
    uint32_t mask = 0; // 每 次 迭 代 内 参 与 计 算 的 元 素，normal模 式 下mask建 议 设 置 为0
uint64_t rsvdCnt = 0; // 用 于 保 存 筛 选 后 保 留 下 来 的 元 素 个 数
uint8_t src1Pattern = 2; // 内 置 固 定 模 式

// src0Local：源 操 作 数
// src1Pattern：内 置 固 定 模 式 取 值
// 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);

    结 果 示 例 如 下：

    Text
    输 入 数 据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

免 责 声 明：本 站 内 容 由 asc-devkit 仓 master 分 支 自 动 编 译 生 成，属 于 持 续 开 发 版 本，可 能 存 在 缺 陷，仅 供 预 览 与 参 考。如 需 稳 定 及 商 用 资 料，请 查 阅 官 方 昇 腾 社 区。

Copyright Huawei Technologies Co., Ltd.