From a7fd65dffc9e3c1dc0f18695c12b596ccad3c6fc Mon Sep 17 00:00:00 2001 From: LinxISA Automation Date: Tue, 8 Sep 2026 10:09:42 +0800 Subject: [PATCH] docs: document explicit-groupM overloads across the TMATMUL family - TMATMUL_ACC/BIAS/MX/MX_ACC/MX_BIAS usage pages: add the groupM overload signature, the groupM parameter row, and the overload- selection entry (per-PE shard size contract: CubeM16 group_M<=64, CubeM32 group_M>64; MX scale storage matches its primary operand) - options.md: extend the explicit group_M entry list with the five family overloads and the D/C valid-shape and MX scale-storage notes - pto-0583-migration.md: mirror the family-wide groupM entries --- docs/tileop-usage/cube/matrix-matrix/TMATMUL_ACC.md | 9 +++++++++ docs/tileop-usage/cube/matrix-matrix/TMATMUL_BIAS.md | 9 +++++++++ docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX.md | 9 +++++++++ .../tileop-usage/cube/matrix-matrix/TMATMUL_MX_ACC.md | 10 ++++++++++ .../cube/matrix-matrix/TMATMUL_MX_BIAS.md | 10 ++++++++++ docs/tileop-usage/migration/pto-0583-migration.md | 11 +++++++++++ docs/tileop-usage/options.md | 11 ++++++++++- 7 files changed, 68 insertions(+), 1 deletion(-) diff --git a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_ACC.md b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_ACC.md index 7812fe8..69f14e8 100644 --- a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_ACC.md +++ b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_ACC.md @@ -24,6 +24,13 @@ PTO_SHARED_INLINE void TMATMUL_ACC( tile_shape_a &a, tile_shape_b &b, const Options &options); +PTO_SHARED_INLINE void TMATMUL_ACC( + tile_shape_d &d, + tile_shape_c &c, + tile_shape_a &a, + tile_shape_b &b, + size_t groupM); + ``` ### 支持的数据类型 @@ -45,6 +52,7 @@ PTO_SHARED_INLINE void TMATMUL_ACC( | `a` | 左操作数或输入 Tile。 | | `b` | 右操作数或输入 Tile。 | | `options` | `fixp::Options` 选项对象；携带量化、激活、转置、缩放以及可选辅助输出配置。 | +| `groupM` | cooperative `Local-A/Shared-B` 场景下的 core-total `group_M`；必须是 `1..128` 的正值。 | ### 重载选择 @@ -52,6 +60,7 @@ PTO_SHARED_INLINE void TMATMUL_ACC( - **带 `Options` 的重载**：需要量化、激活、转置、scale 或辅助输出时传入 `options`。它不是重复声明，而是在相同核心操作数上增加显式属性；仅可启用本操作支持的属性。详见 [fixp::Options 指南](../../options.md)。 +- **带 `groupM` 的重载**：仅用于 cooperative 的 `Local-A/Shared-B` 语义；`groupM` 显式提供 LB0 的 core-total `group_M`，而不是从 Local A shard 推导。`D`（以及 ACC 形式的 `C`）的 valid 行数必须等于 per-PE A shard 大小（`M_per_PE`：CubeM16 对应 `group_M <= 64`，CubeM32 对应 `group_M > 64`）。 ## 使用要求 - Tile 类型必须满足接口模板约束； diff --git a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_BIAS.md b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_BIAS.md index 4f9c950..c3c5eb4 100644 --- a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_BIAS.md +++ b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_BIAS.md @@ -24,6 +24,13 @@ PTO_SHARED_INLINE void TMATMUL_BIAS( tile_shape_b &b, tile_shape_bias &bias, const Options &options); +PTO_SHARED_INLINE void TMATMUL_BIAS( + tile_shape_c &c, + tile_shape_a &a, + tile_shape_b &b, + tile_shape_bias &bias, + size_t groupM); + ``` ### 支持的数据类型 @@ -45,6 +52,7 @@ PTO_SHARED_INLINE void TMATMUL_BIAS( | `b` | 右操作数或输入 Tile。 | | `bias` | 偏置 Tile，用于需要偏置的重载。 | | `options` | `fixp::Options` 选项对象；携带量化、激活、转置、缩放以及可选辅助输出配置。 | +| `groupM` | cooperative `Local-A/Shared-B` 场景下的 core-total `group_M`；必须是 `1..128` 的正值。 | ### Bias Tile 契约 @@ -62,6 +70,7 @@ CUBE layout，不能用于 Bias。 - **带 `Options` 的重载**：需要量化、激活、转置、scale 或辅助输出时传入 `options`。它不是重复声明，而是在相同核心操作数上增加显式属性；仅可启用本操作支持的属性。详见 [fixp::Options 指南](../../options.md)。 +- **带 `groupM` 的重载**：仅用于 cooperative 的 `Local-A/Shared-B` 语义；`groupM` 显式提供 LB0 的 core-total `group_M`，而不是从 Local A shard 推导。`D`（以及 ACC 形式的 `C`）的 valid 行数必须等于 per-PE A shard 大小（`M_per_PE`：CubeM16 对应 `group_M <= 64`，CubeM32 对应 `group_M > 64`）。 ## 使用要求 - Tile 类型必须满足接口模板约束； diff --git a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX.md b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX.md index 7708dcf..d45dddc 100644 --- a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX.md +++ b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX.md @@ -51,6 +51,13 @@ PTO_SHARED_INLINE void TMATMUL_MX(D &d, A &a, B &b, SB &sb, const Options &optio PTO_SHARED_INLINE void TMATMUL_MX(D &d, A &a, B &b); PTO_SHARED_INLINE void TMATMUL_MX(D &d, A &a, SA &sa, B &b); PTO_SHARED_INLINE void TMATMUL_MX(D &d, A &a, B &b, SB &sb); +PTO_SHARED_INLINE void TMATMUL_MX( + tile_shape_c &c, + tile_shape_a &a, + tile_shape_ascale &ascale, + tile_shape_b &b, + tile_shape_bscale &bscale, + size_t groupM); ``` ### 支持的数据类型 @@ -74,6 +81,7 @@ PTO_SHARED_INLINE void TMATMUL_MX(D &d, A &a, B &b, SB &sb); | `b` | 右操作数或输入 Tile。 | | `bscale` | B 操作数的缩放 Tile。 | | `options` | `fixp::Options` 选项对象；携带量化、激活、转置、缩放以及可选辅助输出配置。 | +| `groupM` | cooperative `Local-A/Shared-B` 场景下的 core-total `group_M`；必须是 `1..128` 的正值。 | | `d` | 输出 Tile；成功调用后写入操作结果。 | | `sa` | A 操作数对应的缩放或标量 Tile。 | | `sb` | B 操作数对应的缩放或标量 Tile。 | @@ -84,6 +92,7 @@ PTO_SHARED_INLINE void TMATMUL_MX(D &d, A &a, B &b, SB &sb); - **带 `Options` 的重载**：需要量化、激活、转置、scale 或辅助输出时传入 `options`。它不是重复声明，而是在相同核心操作数上增加显式属性；仅可启用本操作支持的属性。详见 [fixp::Options 指南](../../options.md)。 +- **带 `groupM` 的重载**：仅用于 cooperative 的 `Local-A/Shared-B` 语义；`groupM` 显式提供 LB0 的 core-total `group_M`，而不是从 Local A shard 推导。`D`（以及 ACC 形式的 `C`）的 valid 行数必须等于 per-PE A shard 大小（`M_per_PE`：CubeM16 对应 `group_M <= 64`，CubeM32 对应 `group_M > 64`）。MX 形式的 scale 操作数与其主操作数存储一致（Local A 配 Local scale，Shared B 配 Shared scale）。 ## 使用要求 - Tile 类型必须满足接口模板约束； diff --git a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX_ACC.md b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX_ACC.md index b313d85..f9176d4 100644 --- a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX_ACC.md +++ b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX_ACC.md @@ -57,6 +57,14 @@ PTO_SHARED_INLINE void TMATMUL_MX_ACC(D &d, C &c, A &a, B &b, SB &sb, const Opti PTO_SHARED_INLINE void TMATMUL_MX_ACC(D &d, C &c, A &a, B &b); PTO_SHARED_INLINE void TMATMUL_MX_ACC(D &d, C &c, A &a, SA &sa, B &b); PTO_SHARED_INLINE void TMATMUL_MX_ACC(D &d, C &c, A &a, B &b, SB &sb); +PTO_SHARED_INLINE void TMATMUL_MX_ACC( + tile_shape_d &d, + tile_shape_c &c, + tile_shape_a &a, + tile_shape_sa &scale_a, + tile_shape_b &b, + tile_shape_sb &scale_b, + size_t groupM); ``` ### 支持的数据类型 @@ -81,6 +89,7 @@ PTO_SHARED_INLINE void TMATMUL_MX_ACC(D &d, C &c, A &a, B &b, SB &sb); | `b` | 右操作数或输入 Tile。 | | `scale_b` | B 操作数的缩放 Tile。 | | `options` | `fixp::Options` 选项对象；携带量化、激活、转置、缩放以及可选辅助输出配置。 | +| `groupM` | cooperative `Local-A/Shared-B` 场景下的 core-total `group_M`；必须是 `1..128` 的正值。 | | `sa` | A 操作数对应的缩放或标量 Tile。 | | `sb` | B 操作数对应的缩放或标量 Tile。 | @@ -90,6 +99,7 @@ PTO_SHARED_INLINE void TMATMUL_MX_ACC(D &d, C &c, A &a, B &b, SB &sb); - **带 `Options` 的重载**：需要量化、激活、转置、scale 或辅助输出时传入 `options`。它不是重复声明，而是在相同核心操作数上增加显式属性；仅可启用本操作支持的属性。详见 [fixp::Options 指南](../../options.md)。 +- **带 `groupM` 的重载**：仅用于 cooperative 的 `Local-A/Shared-B` 语义；`groupM` 显式提供 LB0 的 core-total `group_M`，而不是从 Local A shard 推导。`D`（以及 ACC 形式的 `C`）的 valid 行数必须等于 per-PE A shard 大小（`M_per_PE`：CubeM16 对应 `group_M <= 64`，CubeM32 对应 `group_M > 64`）。MX 形式的 scale 操作数与其主操作数存储一致（Local A 配 Local scale，Shared B 配 Shared scale）。 ## 使用要求 - Tile 类型必须满足接口模板约束； diff --git a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX_BIAS.md b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX_BIAS.md index 816f552..5533f6d 100644 --- a/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX_BIAS.md +++ b/docs/tileop-usage/cube/matrix-matrix/TMATMUL_MX_BIAS.md @@ -69,6 +69,14 @@ PTO_SHARED_INLINE void TMATMUL_MX_BIAS( PTO_SHARED_INLINE void TMATMUL_MX_BIAS(D &d, A &a, B &b, Bias &bias); PTO_SHARED_INLINE void TMATMUL_MX_BIAS(D &d, A &a, SA &sa, B &b, Bias &bias); PTO_SHARED_INLINE void TMATMUL_MX_BIAS(D &d, A &a, B &b, SB &sb, Bias &bias); +PTO_SHARED_INLINE void TMATMUL_MX_BIAS( + tile_shape_d &d, + tile_shape_a &a, + tile_shape_sa &scale_a, + tile_shape_b &b, + tile_shape_sb &scale_b, + tile_shape_bias &bias, + size_t groupM); ``` ### 支持的数据类型 @@ -93,6 +101,7 @@ PTO_SHARED_INLINE void TMATMUL_MX_BIAS(D &d, A &a, B &b, SB &sb, Bias &bias); | `scale_b` | B 操作数的缩放 Tile。 | | `bias` | 偏置 Tile，用于需要偏置的重载。 | | `options` | `fixp::Options` 选项对象；携带量化、激活、转置、缩放以及可选辅助输出配置。 | +| `groupM` | cooperative `Local-A/Shared-B` 场景下的 core-total `group_M`；必须是 `1..128` 的正值。 | | `sa` | A 操作数对应的缩放或标量 Tile。 | | `sb` | B 操作数对应的缩放或标量 Tile。 | @@ -102,6 +111,7 @@ PTO_SHARED_INLINE void TMATMUL_MX_BIAS(D &d, A &a, B &b, SB &sb, Bias &bias); - **带 `Options` 的重载**：需要量化、激活、转置、scale 或辅助输出时传入 `options`。它不是重复声明，而是在相同核心操作数上增加显式属性；仅可启用本操作支持的属性。详见 [fixp::Options 指南](../../options.md)。 +- **带 `groupM` 的重载**：仅用于 cooperative 的 `Local-A/Shared-B` 语义；`groupM` 显式提供 LB0 的 core-total `group_M`，而不是从 Local A shard 推导。`D`（以及 ACC 形式的 `C`）的 valid 行数必须等于 per-PE A shard 大小（`M_per_PE`：CubeM16 对应 `group_M <= 64`，CubeM32 对应 `group_M > 64`）。MX 形式的 scale 操作数与其主操作数存储一致（Local A 配 Local scale，Shared B 配 Shared scale）。 ## 使用要求 - Tile 类型必须满足接口模板约束； diff --git a/docs/tileop-usage/migration/pto-0583-migration.md b/docs/tileop-usage/migration/pto-0583-migration.md index fea27ca..3ecc23f 100644 --- a/docs/tileop-usage/migration/pto-0583-migration.md +++ b/docs/tileop-usage/migration/pto-0583-migration.md @@ -98,6 +98,17 @@ TMATMUL(c, local_a, shared_b, groupM); This keeps `LB0` aligned with the ASL cooperative `group_M` contract while the Local shard descriptor remains per-PE. +The same explicit-`groupM` entry exists across the matrix family +(basic, parameter-free forms): + +```cpp +TMATMUL_ACC(d, c, local_a, shared_b, groupM); +TMATMUL_BIAS(d, local_a, shared_b, bias, groupM); +TMATMUL_MX(d, local_a, scale_a, shared_b, scale_b, groupM); +TMATMUL_MX_ACC(d, c, local_a, scale_a, shared_b, scale_b, groupM); +TMATMUL_MX_BIAS(d, local_a, scale_a, shared_b, scale_b, bias, groupM); +``` + For a non-CUBE Tile, the same spelling remains the normal `B.IOT` transport: ```cpp diff --git a/docs/tileop-usage/options.md b/docs/tileop-usage/options.md index a4a6c6a..a556403 100644 --- a/docs/tileop-usage/options.md +++ b/docs/tileop-usage/options.md @@ -339,6 +339,13 @@ Shared form 使用四 PE cooperative、mask `1111`，Shared Right 当前要求 ```cpp TMATMUL(d, local_a, shared_b, groupM); TMATMUL(d, local_a, shared_b, options, groupM); + +// 其余矩阵族接口提供相同的显式 groupM 入口（basic 形式）： +TMATMUL_ACC(d, c, local_a, shared_b, groupM); +TMATMUL_BIAS(d, local_a, shared_b, bias, groupM); +TMATMUL_MX(d, local_a, scale_a, shared_b, scale_b, groupM); +TMATMUL_MX_ACC(d, c, local_a, scale_a, shared_b, scale_b, groupM); +TMATMUL_MX_BIAS(d, local_a, scale_a, shared_b, scale_b, bias, groupM); ``` 其中： @@ -347,7 +354,9 @@ TMATMUL(d, local_a, shared_b, options, groupM); - `local_a` 仍表示每 PE 的 Local shard； - `shared_b` 仍表示 `K×N` 的 Shared 右操作数； - `options` 仍然遵循本页 `fixp::Options` 约束，可与 `groupM` 一起使用； -- 该入口仅用于 `Local-A/Shared-B` cooperative 场景，不影响 `Local/Local`、`Local/Shared-Right` 或 `Shared-Left/Shared-Right` 的既有调用方式。 +- 该入口仅用于 `Local-A/Shared-B` cooperative 场景，不影响 `Local/Local`、`Local/Shared-Right` 或 `Shared-Left/Shared-Right` 的既有调用方式； +- `D`（以及 ACC 形式的 `C`）valid 行数必须等于 per-PE A shard 大小（`M_per_PE`：CubeM16 对应 `group_M <= 64`，CubeM32 对应 `group_M > 64`）； +- MX 形式的 scale 操作数与其主操作数存储一致（Local A 配 Local scale，Shared B 配 Shared scale）。 ### 操作支持速查