Mmad
产 品 支 持 情 况
| 产 品 | 是 否 支 持（ 不 传 入bias的 原 型 ） | 是 否 支 持（ 传 入bias的 原 型 ） |
|---|---|---|
| Ascend 950PR/Ascend 950DT | √ | √ |
| Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品 | √ | √ |
| Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品 | √ | √ |
| Atlas 200I/500 A2 推 理 产 品 | √ | √ |
| Atlas 推 理 系 列 产 品AI Core | √ | x |
| Atlas 推 理 系 列 产 品Vector Core | x | x |
| Atlas 训 练 系 列 产 品 | √ | x |
| Kirin X90 | √ | √ |
| Kirin 9030 | √ | x |
功 能 说 明
头 文 件 路 径 为：#include "basic_api/kernel_operator_mm_intf.h"。
Mmad接 口 是Ascend C面 向 昇 腾AI芯 片 的 矩 阵 乘 加 核 心 计 算 接 口，专 为 高 性 能 算 子 开 发 设 计，封 装 了 昇 腾NPU硬 件 的 矩 阵 乘 加 计 算 能 力，广 泛 用 于 神 经 网 络 层（如 全 连 接 层、卷 积 层）、数 值 计 算 类 算 子 的 开 发。
Mmad接 口 实 现 昇 腾NPU矩 阵 乘 计 算 能 力，其 数 学 表 达 式 为：
$$C = A \times B + C$$
针 对Ascend 950PR/Ascend 950DT：
表 1 矩 阵 计 算 矩 阵A、B、C解 释 说 明
| 矩 阵 计 算 逻 辑 | 矩 阵 计 算 物 理 位 置 | 维 度 | 输 入/输 出 数 据 格 式 | 数 据 类 型 |
|---|---|---|---|---|
| A | L0A Buffer | M x K | Nz | 数 据 类 型 |
| B | L0B Buffer | K x N | Zn | |
| C | L0C Buffer | M x N，可 支 持 使 用 偏 置 矩 阵Bias进 行 初 始 化，维 度 为1 x N | Nz |
针 对Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品 和Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品：
表 2 矩 阵 计 算 矩 阵A、B、C解 释 说 明
| 矩 阵 计 算 逻 辑 | 矩 阵 计 算 物 理 位 置 | 维 度 | 输 入/输 出 数 据 格 式 | 数 据 类 型 |
|---|---|---|---|---|
| A | L0A Buffer | M x K | Zz | 数 据 类 型 |
| B | L0B Buffer | K x N | Zn | |
| C | L0C Buffer | M x N，可 支 持 使 用 偏 置 矩 阵Bias进 行 初 始 化，维 度 为1 x N | Nz |
函 数 原 型
不 传 入bias
C++template <typename T, typename U, typename S> __aicore__ inline void Mmad(const LocalTensor<T>& dst, const LocalTensor<U>& fm, const LocalTensor<S>& filter, const MmadParams& mmadParams)传 入bias
C++template <typename T, typename U, typename S, typename V> __aicore__ inline void Mmad(const LocalTensor<T>& dst, const LocalTensor<U>& fm, const LocalTensor<S>& filter, const LocalTensor<V>& bias, const MmadParams& mmadParams)
参 数 说 明
表 3 参 数 说 明
| 参 数 名 称 | 输 入/输 出 | 含 义 |
|---|---|---|
| dst | 输 出 | 目 的 操 作 数，结 果 矩 阵c，类 型 为LocalTensor，支 持 的 物 理 存 储 位 置 为L0C Buffer（TPosition:CO1）。 LocalTensor的 起 始 地 址 需 要 按 照1024字 节 对 齐。 |
| fm | 输 入 | 源 操 作 数，左 矩 阵a，类 型 为LocalTensor，支 持 的 物 理 存 储 位 置 为L0A Buffer（TPosition: A2）。 LocalTensor的 起 始 地 址 需 要 按 照512字 节 对 齐。 |
| filter | 输 入 | 源 操 作 数，右 矩 阵b，类 型 为LocalTensor，支 持 的 物 理 存 储 位 置 为L0B Buffer（TPosition: B2）。 LocalTensor的 起 始 地 址 需 要 按 照512字 节 对 齐。 |
| bias | 输 入 | 源 操 作 数，bias矩 阵，类 型 为LocalTensor，支 持 的 物 理 存 储 位 置 为BT Buffer（TPosition:C2）。 LocalTensor的 起 始 地 址 需 要 按 照64字 节 对 齐。 |
| mmadParams | 输 入 | 矩 阵 乘 相 关 参 数。该 参 数 类 型 的 具 体 定 义 请 参 考${INSTALL_DIR}/include/ascendc/basic_api/interface/kernel_struct_mm.h，${INSTALL_DIR}请 替 换 为CANN软 件 安 装 后 文 件 存 储 路 径。 MmadParams参 数 说 明 请 参 考表4。 |
| 参 数 名 称 | 含 义 |
|---|---|
| m | 左 矩 阵Height，取 值 范 围：m∈[0，4095]。默 认 值 为0。 |
| n | 右 矩 阵Width，取 值 范 围：n∈[0，4095]。默 认 值 为0。 |
| k | 左 矩 阵Width、右 矩 阵Height，取 值 范 围：k∈[0，4095]。默 认 值 为0。 |
| cmatrixInitVal | 是 否 使 能C矩 阵 默 认 初 始 化 清 零 操 作。默 认 值true。 true：C矩 阵 默 认 初 始 化 为0；false：C矩 阵 不 进 行 默 认 操 作，通 过 设 置cmatrixSource参 数 进 行 初 始 化。 |
| cmatrixSource | 配 置C矩 阵 初 始 值 是 否 来 源 于BT Buffer。默 认 值 为false。 false：不 对L0C进 行 初 始 化 操 作； true：使 用BT Buffer(TPosition:C2)的 数 据 对L0C进 行 初 始 化 操 作。 Atlas 训 练 系 列 产 品，仅 支 持 配 置 为false。 Atlas 推 理 系 列 产 品AI Core，仅 支 持 配 置 为false。 Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品，支 持 配 置 为true/false。 Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品，支 持 配 置 为true/false。 Atlas 200I/500 A2 推 理 产 品，支 持 配 置 为true/false。 Ascend 950PR/Ascend 950DT，支 持 配 置 为true/false。 Kirin X90仅 支 持 配 置 为false。 Kirin 9030仅 支 持 配 置 为false。 注 意：带bias输 入 的 接 口 配 置 该 参 数 无 效，会 根 据bias输 入 的 位 置 来 判 断C矩 阵 初 始 值 是 否 来 源 于BT Buffer。 |
| isBias | 该 参 数 废 弃，新 开 发 内 容 不 要 使 用 该 参 数。如 果 需 要 累 加 初 始 矩 阵，请 使 用 带bias的 接 口 来 实 现；也 可 以 通 过cmatrixInitVal和cmatrixSource参 数 配 置C矩 阵 的 初 始 值 来 源 来 实 现。推 荐 使 用 带bias的 接 口，相 比 于 配 置cmatrixInitVal和cmatrixSource参 数 更 加 简 单 方 便。 配 置 是 否 需 要 累 加 初 始 矩 阵，默 认 值 为false，取 值 说 明 如 下： false：矩 阵 乘，无 需 累 加 初 始 矩 阵，C = A * B。true：矩 阵 乘 加，需 要 累 加 初 始 矩 阵，C += A * B。 |
| disableGemv | M=1时，该 参 数 用 来 配 置Mmad计 算 是 否 开 启GEMV模 式。 false：开 启GEMV模 式。true：关 闭GEMV模 式。 该 参 数 仅 支 持 如 下 型 号： Ascend 950PR/Ascend 950DT |
| unitFlag | unitFlag可 以 控 制Mmad指 令 和Fixpipe指 令 细 粒 度 的 并 行，使 能 该 功 能 后，硬 件 每 计 算 完 一 个 分 形，计 算 结 果 就 会 被 搬 出。取 值 说 明 如 下： 0（2'b00）：不 使 能unitFlag； 1（2'b01）：保 留 值； 2（2'b10）：使 能unitFlag，硬 件 执 行 完 指 令 之 后，不 复 位 单 元 标 记 位； 3（2'b11）：使 能unitFlag，硬 件 执 行 完 指 令 之 后，复 位 单 元 标 记 位。 使 能 该 功 能 时，须 将Mmad指 令 和Fixpipe指 令 的unitFlag值 设 置 为2或3。 该 参 数 仅 支 持 如 下 型 号： Ascend 950PR/Ascend 950DT Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品 Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品。参 数 设 置 方 案 和 特 性 细 节 可 参 考： UnitFlag特 性 说 明 |
| kDirectionAlign | K方 向 对 齐 的 核 心 功 能 是 通 过 kDirectionAlign 参 数 控 制 在 使 用float数 据 类 型 时，L0A和L0B矩 阵 在K方 向 上 的 对 齐 方 式。取 值 说 明 如 下： false：默 认 值，K方 向 对 齐 到 ceil(K / 8) * 8。true：K 方 向 对 齐 到 ceil(K/16)*16。Atlas 训 练 系 列 产 品，仅 支 持 配 置 为false。 Atlas 推 理 系 列 产 品AI Core，仅 支 持 配 置 为false。 Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品，仅 支 持 配 置 为true/false。 Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品，仅 支 持 配 置 为true/false。 Atlas 200I/500 A2 推 理 产 品，仅 支 持 配 置 为false。 Ascend 950PR/Ascend 950DT，仅 支 持 配 置 为false。 Kirin X90支 持 配 置 为true/false。 Kirin 9030支 持 配 置 为true/false。 特 性 细 节 可 参 考：kDirectionAlign特 性 说 明 |
| fmOffset | 左 矩 阵offset（整 个 左 矩 阵 对 应 一 个 值），支 持Scalar（应 与src_fm.dtype一 致）/立 即 数，默 认0。 注：未 使 用，兼 容 旧 款 产 品 接 口 传 入，Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品 及 往 后 产 品 不 做 处 理。 |
| enSsparse | 使 能 结 构 化 稀 疏 特 性，默 认false； 注：未 使 用，兼 容 旧 款 产 品 接 口 传 入，Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品 及 往 后 产 品 不 做 处 理。 |
| enWinogradA | 指 示 矩 阵a是 否 通 过winograd_feature_map_transform() 生 成，用 于 支 持winograd特 性，bool类 型，默 认false； 注：未 使 用，兼 容 旧 款 产 品 接 口 传 入，Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品 及 往 后 产 品 不 做 处 理。 |
| enWinogradB | 指 示 矩 阵b是 否 通 过winograd_weight_transform() 生 成，用 于 支 持winograd特 性，bool类 型，默 认false； 注：未 使 用，兼 容 旧 款 产 品 接 口 传 入，Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品 及 往 后 产 品 不 做 处 理。 |
数 据 类 型
表 5 dst、fm、filter支 持 的 精 度 类 型 组 合（Ascend 950PR/Ascend 950DT）
| 左 矩 阵fm type | 右 矩 阵filter type | 结 果 矩 阵dst type |
|---|---|---|
| int8_t | int8_t | int32_t |
| half | half | float |
| float | float | float |
| bfloat16_t | bfloat16_t | float |
| fp8_e4m3fn_t | fp8_e4m3fn_t | float |
| fp8_e4m3fn_t | fp8_e5m2_t | float |
| fp8_e5m2_t | fp8_e4m3fn_t | float |
| fp8_e5m2_t | fp8_e5m2_t | float |
| hifloat8_t | hifloat8_t | float |
表 6 dst、fm、filter、bias支 持 的 精 度 类 型 组 合（Ascend 950PR/Ascend 950DT）
| 左 矩 阵fm type | 右 矩 阵filter type | bias type | 结 果 矩 阵dst type |
|---|---|---|---|
| int8_t | int8_t | int32_t | int32_t |
| half | half | float | float |
| float | float | float | float |
| bfloat16_t | bfloat16_t | float | float |
| fp8_e4m3fn_t | fp8_e4m3fn_t | float | float |
| fp8_e4m3fn_t | fp8_e5m2_t | float | float |
| fp8_e5m2_t | fp8_e4m3fn_t | float | float |
| fp8_e5m2_t | fp8_e5m2_t | float | float |
| hifloat8_t | hifloat8_t | float | float |
表 7 dst、fm、filter支 持 的 精 度 类 型 组 合（Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品）（Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品）（Atlas 200I/500 A2 推 理 产 品）
| 左 矩 阵fm type | 右 矩 阵filter type | 结 果 矩 阵dst type |
|---|---|---|
| int8_t | int8_t | int32_t |
| half | half | float |
| float | float | float |
| bfloat16_t | bfloat16_t | float |
| int4b_t | int4b_t | int32_t |
表 8 dst、fm、filter、bias支 持 的 精 度 类 型 组 合（Atlas A2 训 练 系 列 产 品/Atlas A2 推 理 系 列 产 品）（Atlas A3 训 练 系 列 产 品/Atlas A3 推 理 系 列 产 品）（Atlas 200I/500 A2 推 理 产 品）
| 左 矩 阵fm type | 右 矩 阵filter type | bias type | 结 果 矩 阵dst type |
|---|---|---|---|
| int8_t | int8_t | int32_t | int32_t |
| half | half | float | float |
| float | float | float | float |
| bfloat16_t | bfloat16_t | float | float |
表 9 dst、fm、filter支 持 的 精 度 类 型 组 合（Atlas 推 理 系 列 产 品AI Core）
| 左 矩 阵fm type | 右 矩 阵filter type | 结 果 矩 阵dst type |
|---|---|---|
| int8_t | int8_t | int32_t |
| uint8_t | int8_t | int32_t |
| uint8_t | uint8_t | int32_t |
| half | half | half 说 明： 该 精 度 类 型 组 合，精 度 无 法 达 到 双 千 分 之 一，且 后 续 处 理 器 版 本 不 支 持 该 类 型 转 换，建 议 直 接 使 用half输 入float输 出。 双 千 分 之 一 是 指 每 个 实 际 数 据 和 真 值 数 据 之 间 的 误 差 不 超 过 千 分 之 一，误 差 超 过 千 分 之 一 的 数 据 总 和 不 超 过 总 数 据 数 的 千 分 之 一。 |
| half | half | float |
| int4b_t | int4b_t | int32_t |
表 10 dst、fm、filter支 持 的 精 度 类 型 组 合（Atlas 训 练 系 列 产 品）
| 左 矩 阵fm type | 右 矩 阵filter type | 结 果 矩 阵dst type |
|---|---|---|
| uint8_t | uint8_t | uint32_t |
| int8_t | int8_t | int32_t |
| uint8_t | int8_t | int32_t |
| half | half | half 说 明： 该 精 度 类 型 组 合，精 度 无 法 达 到 双 千 分 之 一，且 后 续 处 理 器 版 本 不 支 持 该 类 型 转 换，建 议 直 接 使 用half输 入float输 出。 双 千 分 之 一 是 指 每 个 实 际 数 据 和 真 值 数 据 之 间 的 误 差 不 超 过 千 分 之 一，误 差 超 过 千 分 之 一 的 数 据 总 和 不 超 过 总 数 据 数 的 千 分 之 一。 |
| half | half | float |
表 11 dst、fm、filter、bias支 持 的 精 度 类 型 组 合 （Kirin X90）
| 左 矩 阵fm type | 右 矩 阵filter type | bias type | 结 果 矩 阵dst type |
|---|---|---|---|
| int8_t | int8_t | int32_t | int32_t |
| half | half | half | half |
表 12 dst、fm、filter、bias支 持 的 精 度 类 型 组 合 （Kirin 9030）
| 左 矩 阵fm type | 右 矩 阵filter type | bias type | 结 果 矩 阵dst type |
|---|---|---|---|
| half | half | half | half |
返 回 值 说 明
无
约 束 说 明
结 果 矩 阵C只 支 持 位 于CO1（存 储 位 置 为L0C Buffer），左 矩 阵A只 支 持 位 于A2（存 储 位 置 为L0A Buffer），右 矩 阵B只 支 持 位 于B2（存 储 位 置 为L0B Buffer）。
当M、K、N中 的 任 意 一 个 值 为0时，表 示 指 令 不 会 执 行，该 接 口 将 被 视 为NOP（空 操 作）。
当M = 1时，会 默 认 开 启GEMV（General Matrix-Vector Multiplication）功 能。在 这 种 情 况 下，Mmad API从L0A Buffer读 取 数 据 时，会 以ND格 式 进 行 读 取，而 不 会 将 其 视 为ZZ格 式。所 以 此 时 左 矩 阵 需 要 直 接 按 照ND格 式 进 行 排 布（GEMV特 性 说 明）。要 注 意 的 是，开 启GEMV的 情 况 下，A矩 阵 的 起 始 地 址 仍 要 求512字 节 对 齐。
一 般 来 说，一 次Mmad计 算 至 少 完 成 一 次A(16*16*half) * B(16*16*half)数 据 块 计 算。但 实 际 计 算 时M、K、N有 效 值 可 能 不 是16的 倍 数，从 而 有 部 分 数 据 为 无 效 数 据。以M=30，K=70，N=40为 例 来 介 绍 无 效 数 据 与 有 效 数 据 的 排 布 方 式。
数 据 为half类 型，当M=30，K=70，N=40的 时 候，A2（L0A Buffer）中 有2x5个16x16矩 阵，B2（L0B Buffer）中 有5x3个16x16矩 阵，CO1（L0C Buffer）中 有2x3个16x16矩 阵。在 这 种 场 景 下M、K和N都 不 是16的 倍 数，A2中 右 下 角 的 矩 阵 实 际 有 效 的 数 据 只 有14x6个，但 是 也 需 要 占 一 个16x16矩 阵 的 空 间，其 他 无 效 数 据 在 计 算 中 会 被 忽 略。一 个16x16分 形 的 数 据 块 中，无 效 数 据 与 有 效 数 据 排 布 的 方 式 示 意 如 下：
同 步 优 化 说 明
当 矩 阵 计 算 沿K轴 进 行 累 加 时，中 间 结 果 通 常 需 要 写 入 同 一 块L0C Buffer。理 论 上，在 连 续 两 次Mmad接 口 调 用 之 间，应 插 入PipeBarrier(PIPE_M)，以 确 保 前 一 次Mmad的 写 操 作 已 完 成，再 进 行 下 一 轮Mmad的 读 操 作，从 而 保 证 数 据 一 致 性。
然 而，当 矩 阵 维 度m和n超 过 一 定 阈 值 时，由 于 计 算 量 足 够 大，数 据 访 问 模 式 具 备 良 好 的 局 部 性 和 流 水 线 并 行 潜 力，硬 件 调 度 器 能 够 自 动 处 理 写-读 依 赖 问 题。此 时 无 需 插 入PipeBarrier(PIPE_M)，Mmad指 令 可 并 行 执 行，从 而 显 著 提 升 计 算 性 能。
阈 值 公 式：$$(m / 16) * (n / 16) < 10$$
当 计 算 量 小 于 阈 值 时，需 要 插 入PipeBarrier(PIPE_M)。
C++if ((m / 16) * (n / 16) < 10) { AscendC::PipeBarrier<PIPE_M>(); }当 计 算 量 大 于 阈 值 时，不 需 要 插 入PipeBarrier(PIPE_M)。
UnitFlag特 性 约 束 说 明
Mmad和Fixpipe接 口 均 提 供 了 `unitFlag` 参 数 来 控 制 该 功 能 的 启 用，需 确 保 两 者 同 步 开 启，才 能 正 常 生 效。
当 希 望 控 制 同 一 块L0C内 存 空 间 能 持 续 只 被 多 条Mmad或 多 条Fixpipe指 令 操 作 时，需 将 对 应 的 前n-1条 指 令 的unitFlag值 设 置 为2，维 持 被 操 作 内 存 空 间 的 持 续 占 用 状 态，最 后 一 条 指 令 设 置 为3，解 除 被 占 用 状 态。
当 启 用 `unitFlag` 功 能 后，建 议Mmad的 计 算 数 据 量 与Fixpipe搬 出 的 数 据 量 保 持 一 致。若Mmad计 算 了 大 块 数 据（M × N = 128 × 128），但Fixpipe只 搬 出 了 其 中 一 部 分 数 据（M × N = 64 × 64），则 可 能 会 导 致 执 行 异 常，可 以 通 过SetFixPipeConfig()接 口 重 置L0C的 状 态，详 细 操 作 方 式 见UnitFlag特 性 说 明中 的 示 例。
特 殊 值/边 界 值 约 束 说 明
对 于 浮 点 类 型INF/NaN输 入 输 出，可 以 通 过CTRL寄 存 器（控 制 寄 存 器）的CTRL[48]比 特 位 进 行 设 置，控 制 浮 点 数 计 算 时 的 饱 和 模 式：
非 饱 和 模 式：CTRL[48]设 置 成1'b1，INF/NaN保 持 原 输 出。
饱 和 模 式：CTRL[48]设 置 成1'b0，INF输 出 会 被 饱 和 为±MAX，NaN输 出 会 被 饱 和 为0。
C++// 设 置CTRL[48]为0，使 能 浮 点 数 计 算 饱 和 模 式 AscendC::AscendCUtils::SetOverflow(0);注：Mmad指 令 应 避 免NaN输 入，否 则 可 能 会 产 生 执 行 报 错。
对 于 整 数 类 型 只 有 饱 和 模 式。
调 用 示 例
矩 阵 乘 的 样 例 请 参 考Mmad样 例。