Merged
fix docs about compact=1 #7261
ChenYongji123Add on 9 days ago
fix docs about compact=1 #7261
Merged
Merged fromChenYongji123/pypto_compactmasterintocann/pyptomaster
Total: 3 files changed+10-10
| @@ -30,7 +30,7 @@ pypto_pro.language.TileType( | |||
| 30 | layout: Optional[TensorLayout] = None, | 30 | layout: Optional[TensorLayout] = None, |
| 31 | fractal: Optional[int] = None, | 31 | fractal: Optional[int] = None, |
| 32 | pad: Optional[Union[TilePad, int]] = None, | 32 | pad: Optional[Union[TilePad, int]] = None, |
| 33 | - compact: Optional[int] = None, | 33 | + compact: Optional[int] = 1, |
| 34 | ) -> TileType | 34 | ) -> TileType |
| 35 | ``` | 35 | ``` |
| 36 | 36 | ||
| @@ -45,7 +45,7 @@ pypto_pro.language.TileType( | |||
| 45 | | layout | 输入 | 可选，排布方式，[pypto_pro.language.TensorLayout](TensorLayout.md)枚举值或None（默认）。不指定时按内存空间取默认值（详见[约束说明](#约束说明)）。L1 Buffer未指定layout时使用NZ，也可以显式指定ZN；数据类型为DT_UINT64或DT_INT64时，还可以显式指定ND。BiasTable Buffer默认且仅支持ND；L0A_MX Buffer仅支持ZZ，L0B_MX Buffer仅支持NN；UB的可用布局由具体Tile API约束。 | | 45 | | layout | 输入 | 可选，排布方式，[pypto_pro.language.TensorLayout](TensorLayout.md)枚举值或None（默认）。不指定时按内存空间取默认值（详见[约束说明](#约束说明)）。L1 Buffer未指定layout时使用NZ，也可以显式指定ZN；数据类型为DT_UINT64或DT_INT64时，还可以显式指定ND。BiasTable Buffer默认且仅支持ND；L0A_MX Buffer仅支持ZZ，L0B_MX Buffer仅支持NN；UB的可用布局由具体Tile API约束。 | |
| 46 | | fractal | 输入 | 可选，分形大小，整数或None（默认）。L0C Buffer中的FP32/INT32 Tile在未指定时自动设为1024；L1 Buffer中layout为ZZ或NN的DT_FP8E8M0 Tile及L0A_MX Buffer/L0B_MX Buffer中的Tile默认且仅支持fractal=32；其他取值要求由具体Tile API决定。 | | 46 | | fractal | 输入 | 可选，分形大小，整数或None（默认）。L0C Buffer中的FP32/INT32 Tile在未指定时自动设为1024；L1 Buffer中layout为ZZ或NN的DT_FP8E8M0 Tile及L0A_MX Buffer/L0B_MX Buffer中的Tile默认且仅支持fractal=32；其他取值要求由具体Tile API决定。 | |
| 47 | | pad | 输入 | 可选，填充模式，支持[pypto_pro.language.TilePad](TilePad.md)类型或int类型。当为int类型时取值范围为[0, 3]：<br>- 0：不填充。<br>- 1：补零。<br>- 2：补最大值。<br>- 3：补最小值。<br>非法值报ValueError，非法类型报TypeError。 | | 47 | | pad | 输入 | 可选，填充模式，支持[pypto_pro.language.TilePad](TilePad.md)类型或int类型。当为int类型时取值范围为[0, 3]：<br>- 0：不填充。<br>- 1：补零。<br>- 2：补最大值。<br>- 3：补最小值。<br>非法值报ValueError，非法类型报TypeError。 | |
| 48 | -| compact | 输入 | 可选，Tile缓冲区的紧凑布局模式，描述Tile在搬运、重排和矩阵计算路径中的布局解释方式，不改变数据类型，也不代替valid_shape对实际有效区域的描述。取值如下：<br>- **0或None**：不启用紧凑模式。此时L1 Buffer→L0A Buffer/L0B Buffer的[move](../memory_data_movement/move.md)完全按物理shape搬运，set_validshape在该搬运路径上不生效。<br>- **1**：使用普通紧凑模式。数据在valid_shape向上对齐到分形粒度的有效空间内连续排布，Tile声明的其余空间空闲在尾部，详见[普通紧凑模式的数据排布](#普通紧凑模式的数据排布)。通常用于尾块场景，与set_validshape搭配使用。在L1 Buffer上配置与否对结果无影响。与phase搭配使用时，如果存在尾块，L0C Buffer必须配置compact=1，否则可能会卡死。compact不会填充无效区域，需要填充时通过pad参数或fillpad补齐。compact不改变缓冲区的分配大小，只改变数据在缓冲区内的排布，因此把多个Tile拼成一个更宽的操作数时需特别注意地址偏移，详见[多Tile拼接的尾块处理](#多tile拼接的尾块处理)。<br>- **2**：使用RowPlusOne紧凑模式。仅在UB Tile中配置，用于避免以该Tile为源作搬运时的bank冲突，详见[RowPlusOne紧凑模式的数据排布](#rowplusone紧凑模式的数据排布)。NZ格式下每个分形列多预留一行物理空间，仅作占位不参与计算，因此申请Tile的物理shape时须包含多出来的这一行，数据使用时通过set_validshape配置实际的有效行数；ZN格式同理，多预留的是一列。 | | 48 | +| compact | 输入 | 可选，Tile缓冲区的紧凑布局模式，描述Tile在搬运、重排和矩阵计算路径中的布局解释方式，不改变数据类型，也不代替valid_shape对实际有效区域的描述。取值如下：<br>- **0**：不启用紧凑模式。此时L1 Buffer→L0A Buffer/L0B Buffer的[move](../memory_data_movement/move.md)完全按物理shape搬运，set_validshape在该搬运路径上不生效。<br>- **1（默认）**：使用普通紧凑模式。数据在valid_shape向上对齐到分形粒度的有效空间内连续排布，Tile声明的其余空间空闲在尾部，详见[普通紧凑模式的数据排布](#普通紧凑模式的数据排布)。通常用于尾块场景，与set_validshape搭配使用。在L1 Buffer上配置与否对结果无影响。与phase搭配使用时，如果存在尾块，L0C Buffer必须配置compact=1，否则可能会卡死。compact不会填充无效区域，需要填充时通过pad参数或fillpad补齐。compact不改变缓冲区的分配大小，只改变数据在缓冲区内的排布，因此把多个Tile拼成一个更宽的操作数时需特别注意地址偏移，详见[多Tile拼接的尾块处理](#多tile拼接的尾块处理)。<br>- **2**：使用RowPlusOne紧凑模式。仅在UB Tile中配置，用于避免以该Tile为源作搬运时的bank冲突，详见[RowPlusOne紧凑模式的数据排布](#rowplusone紧凑模式的数据排布)。NZ格式下每个分形列多预留一行物理空间，仅作占位不参与计算，因此申请Tile的物理shape时须包含多出来的这一行，数据使用时通过set_validshape配置实际的有效行数；ZN格式同理，多预留的是一列。 | |
| 49 | 49 | ||
| 50 | ## 约束说明 | 50 | ## 约束说明 |
| 51 | 51 | ||
| @@ -73,7 +73,7 @@ layout不指定时，按内存空间自动取默认值： | |||
| 73 | 1、分形粒度D=16行×16列，共512字节（0x200）； | 73 | 1、分形粒度D=16行×16列，共512字节（0x200）； |
| 74 | 2、实际搬运数据的有效空间为[ceil16(8), ceil16(24)] = [16, 32]，共2个分形； | 74 | 2、实际搬运数据的有效空间为[ceil16(8), ceil16(24)] = [16, 32]，共2个分形； |
| 75 | 75 | ||
| 76 | - 不配置 compact：数据按 shape=[64,64] 排布 | 76 | + 显式配置 compact=0：数据按 shape=[64,64] 排布 |
| 77 | 77 | ||
| 78 | 0 16 32 48 64 ← 列 | 78 | 0 16 32 48 64 ← 列 |
| 79 | 0 ┌────┬────┬────┬────┐ | 79 | 0 ┌────┬────┬────┬────┐ |
| @@ -293,7 +293,7 @@ def matmul_wide_alias( | |||
| 293 | ) | 293 | ) |
| 294 | x_l0a = pl.make_tile_group( | 294 | x_l0a = pl.make_tile_group( |
| 295 | type=pl.TileType( | 295 | type=pl.TileType( |
| 296 | - shape=[64, 64], dtype=pl.DT_FP16, target_memory=pl.MemorySpace.Left, layout=pl.NZ | 296 | + shape=[64, 64], dtype=pl.DT_FP16, target_memory=pl.MemorySpace.Left, layout=pl.NZ, compact=0 |
| 297 | ), | 297 | ), |
| 298 | addrs=0x0000, | 298 | addrs=0x0000, |
| 299 | mutex_ids=[2, 3], | 299 | mutex_ids=[2, 3], |
| @@ -316,7 +316,7 @@ def matmul_wide_alias( | |||
| 316 | c_l0c = pl.make_tile_group( | 316 | c_l0c = pl.make_tile_group( |
| 317 | type=pl.TileType( | 317 | type=pl.TileType( |
| 318 | shape=[64, 128], dtype=pl.DT_FP32, target_memory=pl.MemorySpace.Acc, | 318 | shape=[64, 128], dtype=pl.DT_FP32, target_memory=pl.MemorySpace.Acc, |
| 319 | - layout=pl.NZ, fractal=1024, valid_shape=[-1, -1], | 319 | + layout=pl.NZ, fractal=1024, valid_shape=[-1, -1], compact=0, |
| 320 | ), | 320 | ), |
| 321 | addrs=0x0000, | 321 | addrs=0x0000, |
| 322 | mutex_ids=[5], | 322 | mutex_ids=[5], |
| @@ -332,7 +332,7 @@ def matmul_wide_alias( | |||
| 332 | pl.load(cur_y, y, [0, 0]) | 332 | pl.load(cur_y, y, [0, 0]) |
| 333 | pl.move(br, cur_y) | 333 | pl.move(br, cur_y) |
| 334 | 334 | ||
| 335 | - # 两块L0A Buffer中的Tile不设置compact=1和set_validshape，数据全量搬运，确保拼接后的整块L0A Buffer中数据排布连续 | 335 | + # 两块L0A Buffer中的Tile显式设置compact=0，不调用set_validshape，数据全量搬运，确保拼接后的整块L0A Buffer中数据排布连续 |
| 336 | al_1 = x_l0a.next() | 336 | al_1 = x_l0a.next() |
| 337 | pl.move(al_1, cur_x, [0, 0]) | 337 | pl.move(al_1, cur_x, [0, 0]) |
| 338 | al_2 = x_l0a.next() | 338 | al_2 = x_l0a.next() |
| @@ -341,7 +341,7 @@ def matmul_wide_alias( | |||
| 341 | al = x_wide.next() | 341 | al = x_wide.next() |
| 342 | pl.matmul(ac, al, br) | 342 | pl.matmul(ac, al, br) |
| 343 | 343 | ||
| 344 | - # L0C Buffer不设置compact=1，store按matmul的写入格式搬运；set_validshape控制搬运的数据量； | 344 | + # L0C Buffer显式设置compact=0，store按matmul的写入格式搬运；set_validshape控制搬运的数据量； |
| 345 | pl.set_validshape(ac, [40, 128]) | 345 | pl.set_validshape(ac, [40, 128]) |
| 346 | pl.store(out, ac, [0, 0]) | 346 | pl.store(out, ac, [0, 0]) |
| 347 | 347 | ||
| @@ -26,7 +26,7 @@ tile_type = pypto_pro.language.TileType( | |||
| 26 | layout=None, | 26 | layout=None, |
| 27 | fractal=None, | 27 | fractal=None, |
| 28 | pad=None, | 28 | pad=None, |
| 29 | - compact=None, | 29 | + compact=1, |
| 30 | ) | 30 | ) |
| 31 | ``` | 31 | ``` |
| 32 | 32 | ||
| @@ -39,7 +39,7 @@ tile_type = pypto_pro.language.TileType( | |||
| 39 | | layout | Tile的物理排布，如ND、DN、NZ、ZN、NN或ZZ；省略时按内存空间推导默认值 | | 39 | | layout | Tile的物理排布，如ND、DN、NZ、ZN、NN或ZZ；省略时按内存空间推导默认值 | |
| 40 | | fractal | 分形大小；部分内存空间和数据类型可以推导默认值 | | 40 | | fractal | 分形大小；部分内存空间和数据类型可以推导默认值 | |
| 41 | | pad | 无效区域的填充模式 | | 41 | | pad | 无效区域的填充模式 | |
| 42 | -| compact | Tile有效数据在缓冲区中的紧凑排布方式 | | 42 | +| compact | Tile有效数据在缓冲区中的紧凑排布方式，默认使用紧凑排布方式 | |
| 43 | 43 | ||
| 44 | valid_shape、pad和compact主要用于尾块及特殊排布场景。它们不会改变make_tile或make_tile_group绑定的缓冲区大小。完整约束请参考[pypto_pro.language.TileType](../../../../api/pro_api/SIMD-API/basic_data_structures/TileType.md)。 | 44 | valid_shape、pad和compact主要用于尾块及特殊排布场景。它们不会改变make_tile或make_tile_group绑定的缓冲区大小。完整约束请参考[pypto_pro.language.TileType](../../../../api/pro_api/SIMD-API/basic_data_structures/TileType.md)。 |
| 45 | 45 | ||
| @@ -414,7 +414,7 @@ pad只声明填充值，不会单独产生填充操作。需要对无效区域 | |||
| 414 | | 矢量逐元素ND动态尾块 | [-1, -1]，逐块设置 | 不需要 | 通常不需要 | | 414 | | 矢量逐元素ND动态尾块 | [-1, -1]，逐块设置 | 不需要 | 通常不需要 | |
| 415 | | 尾块后执行求和 | [-1, -1] | 不需要 | 填充0 | | 415 | | 尾块后执行求和 | [-1, -1] | 不需要 | 填充0 | |
| 416 | | 尾块后执行最大值归约 | [-1, -1] | 不需要 | 填充数据类型最小值 | | 416 | | 尾块后执行最大值归约 | [-1, -1] | 不需要 | 填充数据类型最小值 | |
| 417 | -| Cube动态尾块 | 为参与矩阵乘的L1 Buffer、L0A Buffer、L0B Buffer和L0C Buffer中的Tile设置匹配的有效尺寸 | L0A Buffer、L0B Buffer和L0C Buffer通常设为1；特殊路径按接口要求配置 | 由具体数据路径和算子语义决定 | | 417 | +| Cube动态尾块 | 为参与矩阵乘的L1 Buffer、L0A Buffer、L0B Buffer和L0C Buffer中的Tile设置匹配的有效尺寸 | L0A Buffer、L0B Buffer和L0C Buffer通常沿用默认值1；特殊路径按接口要求配置 | 由具体数据路径和算子语义决定 | |
| 418 | 418 | ||
| 419 | ## 计算约束与建议 | 419 | ## 计算约束与建议 |
| 420 | 420 | ||