docs: document explicit-groupM overloads across the TMATMUL family (follow-up to #87)

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,13 +52,15 @@ 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` 的正值。 |
 
 ### 重载选择
 
 - **基础重载**：不传 `options`，使用该操作的默认后处理属性。
 - **带 `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 类型必须满足接口模板约束；

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 类型必须满足接口模板约束；

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 类型必须满足接口模板约束；

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 类型必须满足接口模板约束；

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 类型必须满足接口模板约束；

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

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）。
 
 ### 操作支持速查