已合并
docs: 补充标量Cache Mode与饱和控制C API接口文档 #5176
yiming创建于 19 天前
docs: 补充标量Cache Mode与饱和控制C API接口文档 #5176
已合并
共 17 个文件变更+686-7
| @@ -838,6 +838,8 @@ | |||
| 838 | - [枚举](SIMD-API/c_api/defs/enum/enum.md) | 838 | - [枚举](SIMD-API/c_api/defs/enum/enum.md) |
| 839 | - [asc_hf32_round_mode](SIMD-API/c_api/defs/enum/asc_hf32_round_mode.md) | 839 | - [asc_hf32_round_mode](SIMD-API/c_api/defs/enum/asc_hf32_round_mode.md) |
| 840 | - [asc_load_l2_cache_mode](SIMD-API/c_api/defs/enum/asc_load_l2_cache_mode.md) | 840 | - [asc_load_l2_cache_mode](SIMD-API/c_api/defs/enum/asc_load_l2_cache_mode.md) |
| 841 | + - [asc_override_strategy](SIMD-API/c_api/defs/enum/asc_override_strategy.md) | ||
| 842 | + - [asc_saturation_mode](SIMD-API/c_api/defs/enum/asc_saturation_mode.md) | ||
| 841 | - [asc_store_l2_cache_mode](SIMD-API/c_api/defs/enum/asc_store_l2_cache_mode.md) | 843 | - [asc_store_l2_cache_mode](SIMD-API/c_api/defs/enum/asc_store_l2_cache_mode.md) |
| 842 | - [数据类型](SIMD-API/c_api/defs/type/type.md) | 844 | - [数据类型](SIMD-API/c_api/defs/type/type.md) |
| 843 | - [reg数据类型](SIMD-API/c_api/defs/type/data_type_definition.md) | 845 | - [reg数据类型](SIMD-API/c_api/defs/type/data_type_definition.md) |
| @@ -1334,7 +1336,10 @@ | |||
| 1334 | - [asc_dcci](SIMD-API/c_api/cache_ctrl/asc_dcci.md) | 1336 | - [asc_dcci](SIMD-API/c_api/cache_ctrl/asc_dcci.md) |
| 1335 | - [asc_dci](SIMD-API/c_api/cache_ctrl/asc_dci.md) | 1337 | - [asc_dci](SIMD-API/c_api/cache_ctrl/asc_dci.md) |
| 1336 | - [asc_get_icache_preload_status](SIMD-API/c_api/cache_ctrl/asc_get_icache_preload_status.md) | 1338 | - [asc_get_icache_preload_status](SIMD-API/c_api/cache_ctrl/asc_get_icache_preload_status.md) |
| 1339 | + - [asc_get_scalar_load_cache_mode](SIMD-API/c_api/cache_ctrl/asc_get_scalar_load_cache_mode.md) | ||
| 1340 | + - [asc_get_scalar_store_cache_mode](SIMD-API/c_api/cache_ctrl/asc_get_scalar_store_cache_mode.md) | ||
| 1337 | - [asc_icache_preload](SIMD-API/c_api/cache_ctrl/asc_icache_preload.md) | 1341 | - [asc_icache_preload](SIMD-API/c_api/cache_ctrl/asc_icache_preload.md) |
| 1342 | + - [asc_set_scalar_cache_mode](SIMD-API/c_api/cache_ctrl/asc_set_scalar_cache_mode.md) | ||
| 1338 | - [同步控制](SIMD-API/c_api/sync/sync.md) | 1343 | - [同步控制](SIMD-API/c_api/sync/sync.md) |
| 1339 | - [系统同步能力概述](SIMD-API/c_api/sync/system_sync_overview.md) | 1344 | - [系统同步能力概述](SIMD-API/c_api/sync/system_sync_overview.md) |
| 1340 | - [核内同步能力概述](SIMD-API/c_api/sync/intra_core_sync_overview.md) | 1345 | - [核内同步能力概述](SIMD-API/c_api/sync/intra_core_sync_overview.md) |
| @@ -1361,8 +1366,12 @@ | |||
| 1361 | - [指令发射队列空闲槽位查询](SIMD-API/c_api/experimental/asc_get_pipe_idle_slot_count.md) | 1366 | - [指令发射队列空闲槽位查询](SIMD-API/c_api/experimental/asc_get_pipe_idle_slot_count.md) |
| 1362 | - [特殊寄存器访问](SIMD-API/c_api/spr/spr.md) | 1367 | - [特殊寄存器访问](SIMD-API/c_api/spr/spr.md) |
| 1363 | - [asc_get_ctrl](SIMD-API/c_api/spr/asc_get_ctrl.md) | 1368 | - [asc_get_ctrl](SIMD-API/c_api/spr/asc_get_ctrl.md) |
| 1369 | + - [asc_get_saturation_flag](SIMD-API/c_api/spr/asc_get_saturation_flag.md) | ||
| 1370 | + - [asc_get_saturation_strategy](SIMD-API/c_api/spr/asc_get_saturation_strategy.md) | ||
| 1364 | - [asc_get_squeeze_status](SIMD-API/c_api/spr/asc_get_squeeze_status.md) | 1371 | - [asc_get_squeeze_status](SIMD-API/c_api/spr/asc_get_squeeze_status.md) |
| 1365 | - [asc_set_ctrl](SIMD-API/c_api/spr/asc_set_ctrl.md) | 1372 | - [asc_set_ctrl](SIMD-API/c_api/spr/asc_set_ctrl.md) |
| 1373 | + - [asc_set_saturation_flag](SIMD-API/c_api/spr/asc_set_saturation_flag.md) | ||
| 1374 | + - [asc_set_saturation_strategy](SIMD-API/c_api/spr/asc_set_saturation_strategy.md) | ||
| 1366 | - [asc_get_ar_spr (废弃)](SIMD-API/c_api/spr/asc_get_ar_spr_deprecated.md) | 1375 | - [asc_get_ar_spr (废弃)](SIMD-API/c_api/spr/asc_get_ar_spr_deprecated.md) |
| 1367 | - [废弃接口](SIMD-API/c_api/deprecated_interface/deprecated_interface.md) | 1376 | - [废弃接口](SIMD-API/c_api/deprecated_interface/deprecated_interface.md) |
| 1368 | - [asc_get_block_idx（废弃）](SIMD-API/c_api/deprecated_interface/asc_get_block_idx_deprecated.md) | 1377 | - [asc_get_block_idx（废弃）](SIMD-API/c_api/deprecated_interface/asc_get_block_idx_deprecated.md) |
| @@ -0,0 +1,78 @@ | |||
| 1 | +# asc_get_scalar_load_cache_mode | ||
| 2 | + | ||
| 3 | +## 产品支持情况 | ||
| 4 | + | ||
| 5 | +<!-- npu="950" id1 --> | ||
| 6 | +- Ascend 950PR/Ascend 950DT：支持 | ||
| 7 | +<!-- end id1 --> | ||
| 8 | +<!-- npu="A3" id2 --> | ||
| 9 | +- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持 | ||
| 10 | +<!-- end id2 --> | ||
| 11 | +<!-- npu="910b" id3 --> | ||
| 12 | +- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持 | ||
| 13 | +<!-- end id3 --> | ||
| 14 | +<!-- npu="310b" id4 --> | ||
| 15 | +- Atlas 200I/500 A2 推理产品：不支持 | ||
| 16 | +<!-- end id4 --> | ||
| 17 | +<!-- npu="310p" id5 --> | ||
| 18 | +- Atlas 推理系列产品AI Core：不支持 | ||
| 19 | +<!-- end id5 --> | ||
| 20 | +<!-- npu="310p" id6 --> | ||
| 21 | +- Atlas 推理系列产品Vector Core：不支持 | ||
| 22 | +<!-- end id6 --> | ||
| 23 | +<!-- npu="910" id7 --> | ||
| 24 | +- Atlas 训练系列产品：不支持 | ||
| 25 | +<!-- end id7 --> | ||
| 26 | + | ||
| 27 | +## 功能说明 | ||
| 28 | + | ||
| 29 | +读取当前标量读（load）路径的L2 Cache管理策略，并返回[asc_load_l2_cache_mode](../defs/enum/asc_load_l2_cache_mode.md)枚举值。 | ||
| 30 | + | ||
| 31 | +常用于临时切换策略前保存原配置，或在设置后做回读校验。 | ||
| 32 | + | ||
| 33 | +## 函数原型 | ||
| 34 | + | ||
| 35 | +```c | ||
| 36 | +__aicore__ inline asc_load_l2_cache_mode asc_get_scalar_load_cache_mode() | ||
| 37 | +``` | ||
| 38 | + | ||
| 39 | +## 参数说明 | ||
| 40 | + | ||
| 41 | +无 | ||
| 42 | + | ||
| 43 | +## 返回值说明 | ||
| 44 | + | ||
| 45 | +当前标量load路径的L2 Cache管理策略，类型为[asc_load_l2_cache_mode](../defs/enum/asc_load_l2_cache_mode.md)。 | ||
| 46 | + | ||
| 47 | +## 流水类型 | ||
| 48 | + | ||
| 49 | +PIPE_S | ||
| 50 | + | ||
| 51 | +## 约束说明 | ||
| 52 | + | ||
| 53 | +- 本接口仅反映标量load侧策略，与标量store侧以及向量搬运接口参数中的`l2_cache_mode`无关。 | ||
| 54 | + | ||
| 55 | +## 调用示例 | ||
| 56 | + | ||
| 57 | +场景：GM tiling表在tile循环内被多次标量读取（每tile读`length`与`offset`）；进入循环前查询并保存当前load策略，临时切换为`NORMAL_FIRST_VICTIM`，循环结束后恢复。若tiling只读一次，可改用`NOTALLOC_KEEP`或无需切换。 | ||
| 58 | + | ||
| 59 | +```cpp | ||
| 60 | +__gm__ int32_t* tiling_gm; // [tile_count, len[0..n-1], off[0..n-1]] | ||
| 61 | +__gm__ half* src_gm; | ||
| 62 | +__ubuf__ half* dst_ub; | ||
| 63 | + | ||
| 64 | +// 查询并保存当前标量load策略 | ||
| 65 | +asc_load_l2_cache_mode old_mode = asc_get_scalar_load_cache_mode(); | ||
| 66 | +asc_set_scalar_cache_mode(asc_load_l2_cache_mode::NORMAL_FIRST_VICTIM); | ||
| 67 | + | ||
| 68 | +int32_t tile_count = tiling_gm[0]; | ||
| 69 | +for (int32_t tile = 0; tile < tile_count; ++tile) { | ||
| 70 | + int32_t tile_len = tiling_gm[1 + tile]; // 每tile标量读GM | ||
| 71 | + int32_t tile_off = tiling_gm[1 + tile_count + tile]; // 每tile标量读GM | ||
| 72 | + asc_copy_gm2ub_align(dst_ub, src_gm + tile_off, tile_len * sizeof(half)); | ||
| 73 | + // ... 向量计算 ... | ||
| 74 | +} | ||
| 75 | + | ||
| 76 | +// 恢复进入本段逻辑前的标量load策略 | ||
| 77 | +asc_set_scalar_cache_mode(old_mode); | ||
| 78 | +``` | ||
| @@ -0,0 +1,72 @@ | |||
| 1 | +# asc_get_scalar_store_cache_mode | ||
| 2 | + | ||
| 3 | +## 产品支持情况 | ||
| 4 | + | ||
| 5 | +<!-- npu="950" id1 --> | ||
| 6 | +- Ascend 950PR/Ascend 950DT：支持 | ||
| 7 | +<!-- end id1 --> | ||
| 8 | +<!-- npu="A3" id2 --> | ||
| 9 | +- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持 | ||
| 10 | +<!-- end id2 --> | ||
| 11 | +<!-- npu="910b" id3 --> | ||
| 12 | +- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持 | ||
| 13 | +<!-- end id3 --> | ||
| 14 | +<!-- npu="310b" id4 --> | ||
| 15 | +- Atlas 200I/500 A2 推理产品：不支持 | ||
| 16 | +<!-- end id4 --> | ||
| 17 | +<!-- npu="310p" id5 --> | ||
| 18 | +- Atlas 推理系列产品AI Core：不支持 | ||
| 19 | +<!-- end id5 --> | ||
| 20 | +<!-- npu="310p" id6 --> | ||
| 21 | +- Atlas 推理系列产品Vector Core：不支持 | ||
| 22 | +<!-- end id6 --> | ||
| 23 | +<!-- npu="910" id7 --> | ||
| 24 | +- Atlas 训练系列产品：不支持 | ||
| 25 | +<!-- end id7 --> | ||
| 26 | + | ||
| 27 | +## 功能说明 | ||
| 28 | + | ||
| 29 | +读取当前标量写（store）路径的L2 Cache管理策略，并返回[asc_store_l2_cache_mode](../defs/enum/asc_store_l2_cache_mode.md)枚举值。 | ||
| 30 | + | ||
| 31 | +常用于临时切换策略前保存原配置，或在设置后做回读校验。 | ||
| 32 | + | ||
| 33 | +## 函数原型 | ||
| 34 | + | ||
| 35 | +```c | ||
| 36 | +__aicore__ inline asc_store_l2_cache_mode asc_get_scalar_store_cache_mode() | ||
| 37 | +``` | ||
| 38 | + | ||
| 39 | +## 参数说明 | ||
| 40 | + | ||
| 41 | +无 | ||
| 42 | + | ||
| 43 | +## 返回值说明 | ||
| 44 | + | ||
| 45 | +当前标量store路径的L2 Cache管理策略，类型为[asc_store_l2_cache_mode](../defs/enum/asc_store_l2_cache_mode.md)。 | ||
| 46 | + | ||
| 47 | +## 流水类型 | ||
| 48 | + | ||
| 49 | +PIPE_S | ||
| 50 | + | ||
| 51 | +## 约束说明 | ||
| 52 | + | ||
| 53 | +- 本接口仅反映标量store侧策略，与标量load侧以及向量搬运接口参数中的`l2_cache_mode`无关。 | ||
| 54 | + | ||
| 55 | +## 调用示例 | ||
| 56 | + | ||
| 57 | +场景：与[asc_set_scalar_cache_mode](asc_set_scalar_cache_mode.md)场景B一致。多核算子通过[asc_atomic_add](../atomic/scalar_atomic/asc_atomic_add.md)向GM统计counter做标量原子累加；进入累加前查询并保存当前store策略，临时切换为`NOTALLOC_CLEAN`避免不必要的L2分配，累加结束后恢复原策略。 | ||
| 58 | + | ||
| 59 | +```cpp | ||
| 60 | +__gm__ int32_t* counter_gm; // GM上的多核共享计数器 | ||
| 61 | + | ||
| 62 | +// 查询并保存当前标量store策略 | ||
| 63 | +asc_store_l2_cache_mode old_mode = asc_get_scalar_store_cache_mode(); | ||
| 64 | +// 标量原子写GM控制字段，避免额外L2分配 | ||
| 65 | +asc_set_scalar_cache_mode(asc_store_l2_cache_mode::NOTALLOC_CLEAN); | ||
| 66 | + | ||
| 67 | +asc_dcci_entire_all(); // 标量原子操作前保证DCache一致性 | ||
| 68 | +asc_atomic_add(counter_gm, 1); | ||
| 69 | + | ||
| 70 | +// 恢复进入本段逻辑前的标量store策略 | ||
| 71 | +asc_set_scalar_cache_mode(old_mode); | ||
| 72 | +``` | ||
| @@ -0,0 +1,98 @@ | |||
| 1 | +# asc_set_scalar_cache_mode | ||
| 2 | + | ||
| 3 | +## 产品支持情况 | ||
| 4 | + | ||
| 5 | +<!-- npu="950" id1 --> | ||
| 6 | +- Ascend 950PR/Ascend 950DT：支持 | ||
| 7 | +<!-- end id1 --> | ||
| 8 | +<!-- npu="A3" id2 --> | ||
| 9 | +- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持 | ||
| 10 | +<!-- end id2 --> | ||
| 11 | +<!-- npu="910b" id3 --> | ||
| 12 | +- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持 | ||
| 13 | +<!-- end id3 --> | ||
| 14 | +<!-- npu="310b" id4 --> | ||
| 15 | +- Atlas 200I/500 A2 推理产品：不支持 | ||
| 16 | +<!-- end id4 --> | ||
| 17 | +<!-- npu="310p" id5 --> | ||
| 18 | +- Atlas 推理系列产品AI Core：不支持 | ||
| 19 | +<!-- end id5 --> | ||
| 20 | +<!-- npu="310p" id6 --> | ||
| 21 | +- Atlas 推理系列产品Vector Core：不支持 | ||
| 22 | +<!-- end id6 --> | ||
| 23 | +<!-- npu="910" id7 --> | ||
| 24 | +- Atlas 训练系列产品：不支持 | ||
| 25 | +<!-- end id7 --> | ||
| 26 | + | ||
| 27 | +## 功能说明 | ||
| 28 | + | ||
| 29 | +配置标量单元访问Global Memory时的L2 Cache管理策略。接口通过修改CTRL寄存器对应比特域生效： | ||
| 30 | + | ||
| 31 | +- 传入[asc_load_l2_cache_mode](../defs/enum/asc_load_l2_cache_mode.md)时，设置标量读（load）策略。 | ||
| 32 | +- 传入[asc_store_l2_cache_mode](../defs/enum/asc_store_l2_cache_mode.md)时，设置标量写（store）策略。 | ||
| 33 | + | ||
| 34 | +设置后，后续标量路径上的GM读写将按该策略访问L2 Cache，直至再次调用本接口修改。 | ||
| 35 | + | ||
| 36 | +## 函数原型 | ||
| 37 | + | ||
| 38 | +```c | ||
| 39 | +__aicore__ inline void asc_set_scalar_cache_mode(asc_load_l2_cache_mode l2_cache_mode) | ||
| 40 | +__aicore__ inline void asc_set_scalar_cache_mode(asc_store_l2_cache_mode l2_cache_mode) | ||
| 41 | +``` | ||
| 42 | + | ||
| 43 | +## 参数说明 | ||
| 44 | + | ||
| 45 | +**表1** 参数说明 | ||
| 46 | + | ||
| 47 | +| 参数名 | 输入/输出 | 描述 | | ||
| 48 | +| :--- | :--- | :--- | | ||
| 49 | +| l2_cache_mode | 输入 | L2 Cache管理策略。load重载传入[asc_load_l2_cache_mode](../defs/enum/asc_load_l2_cache_mode.md)枚举值；store重载传入[asc_store_l2_cache_mode](../defs/enum/asc_store_l2_cache_mode.md)枚举值。 | | ||
| 50 | + | ||
| 51 | +## 返回值说明 | ||
| 52 | + | ||
| 53 | +无 | ||
| 54 | + | ||
| 55 | +## 流水类型 | ||
| 56 | + | ||
| 57 | +PIPE_S | ||
| 58 | + | ||
| 59 | +## 约束说明 | ||
| 60 | + | ||
| 61 | +- 本接口仅影响**标量访存路径**的L2 Cache默认策略，不会修改向量搬运类接口（如[asc_copy_gm2ub_align](../vector_datamove/asc_copy_gm2ub_align/asc_copy_gm2ub_align_arch_3510.md)、[asc_copy_ub2gm_align](../vector_datamove/asc_copy_ub2gm_align/asc_copy_ub2gm_align_arch_3510.md)、[asc_ndim_copy_gm2ub](../vector_datamove/asc_ndim_copy_gm2ub.md)等）参数中的`l2_cache_mode`；二者相互独立。大块tile数据的L2 Cache优化应通过向量搬运入参配置，参见[L2 Cache Mode最佳实践样例](../../../../../../examples/02_simd_c_api/02_features/03_c_api/01_data_movement/00_set_l2_cache_mode)。 | ||
| 62 | +- load与store策略分属CTRL不同比特域，设置其一不会覆盖另一侧已配置的值。 | ||
| 63 | + | ||
| 64 | +## 调用示例 | ||
| 65 | + | ||
| 66 | +- 场景A：标量load — `NORMAL_FIRST_VICTIM`+循环内重复读GM tiling表 | ||
| 67 | + | ||
| 68 | +动态tiling存放在GM上：`tiling_gm[0]`为`tile_count`，后续依次为各tile的`length`与`offset`。循环内每个tile都会标量读取tiling字段，同一tiling区域会被多次访问，适合启用L2复用。若tiling字段只读一次、后续不再访问，应改用`NOTALLOC_KEEP`或无需调用本接口。 | ||
| 69 | + | ||
| 70 | +```cpp | ||
| 71 | +__gm__ int32_t* tiling_gm; // [tile_count, len[0..n-1], off[0..n-1]] | ||
| 72 | +__gm__ half* src_gm; | ||
| 73 | +__ubuf__ half* dst_ub; | ||
| 74 | + | ||
| 75 | +// SIMD_VF外：tiling表将在循环内被多次标量读取 | ||
| 76 | +asc_set_scalar_cache_mode(asc_load_l2_cache_mode::NORMAL_FIRST_VICTIM); | ||
| 77 | + | ||
| 78 | +int32_t tile_count = tiling_gm[0]; | ||
| 79 | +for (int32_t tile = 0; tile < tile_count; ++tile) { | ||
| 80 | + int32_t tile_len = tiling_gm[1 + tile]; // 每tile标量读GM | ||
| 81 | + int32_t tile_off = tiling_gm[1 + tile_count + tile]; // 每tile标量读GM | ||
| 82 | + asc_copy_gm2ub_align(dst_ub, src_gm + tile_off, tile_len * sizeof(half)); | ||
| 83 | + // 向量搬运的l2_cache_mode由asc_copy_gm2ub_align单独配置，见set_l2_cache_mode样例 | ||
| 84 | + // ... 向量计算 ... | ||
| 85 | +} | ||
| 86 | +``` | ||
| 87 | + | ||
| 88 | +- 场景B：标量store — `NOTALLOC_CLEAN`+标量写GM | ||
| 89 | + | ||
| 90 | +多核算子向GM统计counter做标量原子累加时，临时关闭标量写路径的L2分配，避免对控制字段产生不必要的Cache Line分配。 | ||
| 91 | + | ||
| 92 | +```cpp | ||
| 93 | +__gm__ int32_t* counter_gm; // GM上的多核共享计数器 | ||
| 94 | + | ||
| 95 | +asc_set_scalar_cache_mode(asc_store_l2_cache_mode::NOTALLOC_CLEAN); | ||
| 96 | +asc_dcci_entire_all(); // 标量原子操作前保证DCache一致性 | ||
| 97 | +asc_atomic_add(counter_gm, 1); | ||
| 98 | +``` | ||
| @@ -4,4 +4,7 @@ | |||
| 4 | - **[asc_dcci](asc_dcci.md)** | 4 | - **[asc_dcci](asc_dcci.md)** |
| 5 | - **[asc_dci](asc_dci.md)** | 5 | - **[asc_dci](asc_dci.md)** |
| 6 | - **[asc_get_icache_preload_status](asc_get_icache_preload_status.md)** | 6 | - **[asc_get_icache_preload_status](asc_get_icache_preload_status.md)** |
| 7 | +- **[asc_get_scalar_load_cache_mode](asc_get_scalar_load_cache_mode.md)** | ||
| 8 | +- **[asc_get_scalar_store_cache_mode](asc_get_scalar_store_cache_mode.md)** | ||
| 7 | - **[asc_icache_preload](asc_icache_preload.md)** | 9 | - **[asc_icache_preload](asc_icache_preload.md)** |
| 10 | +- **[asc_set_scalar_cache_mode](asc_set_scalar_cache_mode.md)** | ||
| @@ -1,6 +1,11 @@ | |||
| 1 | # asc_load_l2_cache_mode | 1 | # asc_load_l2_cache_mode |
| 2 | 2 | ||
| 3 | -asc_load_l2_cache_mode用于表示数据从GM搬运到Unified Buffer（UB）时的L2 cache管理策略，在调用[asc_copy_gm2ub_align](../../vector_datamove/asc_copy_gm2ub_align/asc_copy_gm2ub_align_arch_3510.md)和[asc_ndim_copy_gm2ub](../../vector_datamove/asc_ndim_copy_gm2ub.md)时使用。L2 Cache管理策略的影响可见[L2 Cache Mode最佳实践](../../../../../../../examples/02_simd_c_api/02_features/03_c_api/01_data_movement/00_set_l2_cache_mode/README.md)。 | 3 | +asc_load_l2_cache_mode用于表示数据从GM搬运到Unified Buffer（UB）时的L2 cache管理策略，可用于： |
| 4 | + | ||
| 5 | +- 向量搬运接口，例如[asc_copy_gm2ub_align](../../vector_datamove/asc_copy_gm2ub_align/asc_copy_gm2ub_align_arch_3510.md)和[asc_ndim_copy_gm2ub](../../vector_datamove/asc_ndim_copy_gm2ub.md)。 | ||
| 6 | +- 标量访存路径的load策略配置与查询，例如[asc_set_scalar_cache_mode](../../cache_ctrl/asc_set_scalar_cache_mode.md)和[asc_get_scalar_load_cache_mode](../../cache_ctrl/asc_get_scalar_load_cache_mode.md)。 | ||
| 7 | + | ||
| 8 | +L2 Cache管理策略的影响可见[L2 Cache Mode最佳实践](../../../../../../../examples/02_simd_c_api/02_features/03_c_api/01_data_movement/00_set_l2_cache_mode/README.md)。 | ||
| 4 | 9 | ||
| 5 | ## 枚举类具体定义 | 10 | ## 枚举类具体定义 |
| 6 | 11 | ||
| @@ -0,0 +1,23 @@ | |||
| 1 | +# asc_override_strategy | ||
| 2 | + | ||
| 3 | +asc_override_strategy用于表示饱和控制策略，在调用[asc_set_saturation_strategy](../../spr/asc_set_saturation_strategy.md)和[asc_get_saturation_strategy](../../spr/asc_get_saturation_strategy.md)时使用。该策略影响CAST类全局饱和配置是否生效。 | ||
| 4 | + | ||
| 5 | +## 枚举类具体定义 | ||
| 6 | + | ||
| 7 | +```cpp | ||
| 8 | +enum class asc_override_strategy : uint8_t { | ||
| 9 | + USE_API = 0, | ||
| 10 | + USE_GLOBAL = 1 | ||
| 11 | +}; | ||
| 12 | +``` | ||
| 13 | + | ||
| 14 | +## 枚举值详解 | ||
| 15 | + | ||
| 16 | +**表1** 枚举值说明 | ||
| 17 | + | ||
| 18 | +| 枚举值 | 说明 | | ||
| 19 | +| ------ | ----------- | | ||
| 20 | +| USE_API | 按单指令/API路径配置饱和。此时通过[asc_set_saturation_flag](../../spr/asc_set_saturation_flag.md)配置的全局`CAST`饱和不生效。 | | ||
| 21 | +| USE_GLOBAL | 使用全局饱和配置。此时通过[asc_set_saturation_flag](../../spr/asc_set_saturation_flag.md)配置的`CAST`模式才会在精度转换中生效。 | | ||
| 22 | + | ||
| 23 | +典型用法：`USE_GLOBAL`配合CAST饱和做float→int32动态量化，参见[asc_set_saturation_strategy](../../spr/asc_set_saturation_strategy.md)调用示例及[Cast样例](../../../../../../../examples/02_simd_c_api/03_c_api/02_reg_vector_compute/cast)；`USE_API`配合单指令饱和参见[Cast](../../../basic_api/reg_vector_compute/type_conversion/Cast.md)中`SatMode`与饱和模式全局或单指令生效配置表。 | ||
| @@ -0,0 +1,27 @@ | |||
| 1 | +# asc_saturation_mode | ||
| 2 | + | ||
| 3 | +asc_saturation_mode用于表示饱和控制所作用的模式类型，在调用[asc_set_saturation_flag](../../spr/asc_set_saturation_flag.md)和[asc_get_saturation_flag](../../spr/asc_get_saturation_flag.md)时使用。 | ||
| 4 | + | ||
| 5 | +## 枚举类具体定义 | ||
| 6 | + | ||
| 7 | +```cpp | ||
| 8 | +enum class asc_saturation_mode : uint8_t { | ||
| 9 | + FLOAT, | ||
| 10 | + FLOAT8, | ||
| 11 | + INT, | ||
| 12 | + CAST | ||
| 13 | +}; | ||
| 14 | +``` | ||
| 15 | + | ||
| 16 | +## 枚举值详解 | ||
| 17 | + | ||
| 18 | +**表1** 枚举值说明 | ||
| 19 | + | ||
| 20 | +| 枚举值 | 说明 | | ||
| 21 | +| ------ | ----------- | | ||
| 22 | +| FLOAT | 浮点计算及部分浮点精度转换场景的饱和控制，浮点数计算时支持half数据类型；浮点数精度转换时支持hifloat8_t、fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t、half、bfloat16_t数据类型。 | | ||
| 23 | +| FLOAT8 | fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t相关场景的饱和控制。 | | ||
| 24 | +| INT | 整数计算溢出时的饱和/截断控制。 | | ||
| 25 | +| CAST | 浮点转整数或整数转整数时的精度转换饱和控制。仅在饱和策略为[asc_override_strategy::USE_GLOBAL](asc_override_strategy.md)时生效。 | | ||
| 26 | + | ||
| 27 | +各模式下开启/关闭饱和的行为差异，见[asc_set_saturation_flag](../../spr/asc_set_saturation_flag.md)中`enable_sat`参数说明。 | ||
| @@ -1,6 +1,9 @@ | |||
| 1 | # asc_store_l2_cache_mode | 1 | # asc_store_l2_cache_mode |
| 2 | 2 | ||
| 3 | -asc_store_l2_cache_mode用于表示数据从Unified Buffer（UB）搬运到GM时的L2 cache策略，在调用[asc_copy_ub2gm_align](../../vector_datamove/asc_copy_ub2gm_align/asc_copy_ub2gm_align_arch_3510.md)时使用。 | 3 | +asc_store_l2_cache_mode用于表示数据从Unified Buffer（UB）搬运到GM时的L2 cache策略，可用于： |
| 4 | + | ||
| 5 | +- 向量搬运接口，例如[asc_copy_ub2gm_align](../../vector_datamove/asc_copy_ub2gm_align/asc_copy_ub2gm_align_arch_3510.md)。 | ||
| 6 | +- 标量访存路径的store策略配置与查询，例如[asc_set_scalar_cache_mode](../../cache_ctrl/asc_set_scalar_cache_mode.md)和[asc_get_scalar_store_cache_mode](../../cache_ctrl/asc_get_scalar_store_cache_mode.md)。 | ||
| 4 | 7 | ||
| 5 | ## 枚举类具体定义 | 8 | ## 枚举类具体定义 |
| 6 | 9 | ||
| @@ -2,4 +2,6 @@ | |||
| 2 | 2 | ||
| 3 | - **[asc_hf32_round_mode](asc_hf32_round_mode.md)** | 3 | - **[asc_hf32_round_mode](asc_hf32_round_mode.md)** |
| 4 | - **[asc_load_l2_cache_mode](asc_load_l2_cache_mode.md)** | 4 | - **[asc_load_l2_cache_mode](asc_load_l2_cache_mode.md)** |
| 5 | +- **[asc_override_strategy](asc_override_strategy.md)** | ||
| 6 | +- **[asc_saturation_mode](asc_saturation_mode.md)** | ||
| 5 | - **[asc_store_l2_cache_mode](asc_store_l2_cache_mode.md)** | 7 | - **[asc_store_l2_cache_mode](asc_store_l2_cache_mode.md)** |
| @@ -0,0 +1,86 @@ | |||
| 1 | +# asc_get_saturation_flag | ||
| 2 | + | ||
| 3 | +## 产品支持情况 | ||
| 4 | + | ||
| 5 | +<!-- npu="950" id1 --> | ||
| 6 | +- Ascend 950PR/Ascend 950DT：支持 | ||
| 7 | +<!-- end id1 --> | ||
| 8 | +<!-- npu="A3" id2 --> | ||
| 9 | +- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持 | ||
| 10 | +<!-- end id2 --> | ||
| 11 | +<!-- npu="910b" id3 --> | ||
| 12 | +- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持 | ||
| 13 | +<!-- end id3 --> | ||
| 14 | +<!-- npu="310b" id4 --> | ||
| 15 | +- Atlas 200I/500 A2 推理产品：不支持 | ||
| 16 | +<!-- end id4 --> | ||
| 17 | +<!-- npu="310p" id5 --> | ||
| 18 | +- Atlas 推理系列产品AI Core：不支持 | ||
| 19 | +<!-- end id5 --> | ||
| 20 | +<!-- npu="310p" id6 --> | ||
| 21 | +- Atlas 推理系列产品Vector Core：不支持 | ||
| 22 | +<!-- end id6 --> | ||
| 23 | +<!-- npu="910" id7 --> | ||
| 24 | +- Atlas 训练系列产品：不支持 | ||
| 25 | +<!-- end id7 --> | ||
| 26 | + | ||
| 27 | +## 功能说明 | ||
| 28 | + | ||
| 29 | +按饱和模式类型读取当前是否开启饱和，并返回布尔类型的结果。 | ||
| 30 | + | ||
| 31 | +## 函数原型 | ||
| 32 | + | ||
| 33 | +```c | ||
| 34 | +__aicore__ inline bool asc_get_saturation_flag(asc_saturation_mode saturation_mode) | ||
| 35 | +``` | ||
| 36 | + | ||
| 37 | +## 参数说明 | ||
| 38 | + | ||
| 39 | +**表1** 参数说明 | ||
| 40 | + | ||
| 41 | +| 参数名 | 输入/输出 | 描述 | | ||
| 42 | +| :--- | :--- | :--- | | ||
| 43 | +| saturation_mode | 输入 | 饱和模式类型，取值见[asc_saturation_mode](../defs/enum/asc_saturation_mode.md)。 | | ||
| 44 | + | ||
| 45 | +## 返回值说明 | ||
| 46 | + | ||
| 47 | +`true`表示当前该模式下饱和已开启；`false`表示未开启（对INT为截断；对FLOAT/FLOAT8/CAST为非饱和或截断）。 | ||
| 48 | + | ||
| 49 | +## 流水类型 | ||
| 50 | + | ||
| 51 | +PIPE_S | ||
| 52 | + | ||
| 53 | +## 约束说明 | ||
| 54 | + | ||
| 55 | +- 返回值是API语义层结果：`true`表示该模式下饱和已开启，`false`表示未开启（对INT为截断；对FLOAT/FLOAT8/CAST为非饱和或截断）。各模式语义差异见[asc_set_saturation_flag](asc_set_saturation_flag.md)表1。 | ||
| 56 | +- 对`CAST`模式，即使本接口返回`true`，也需同时满足饱和策略为`USE_GLOBAL`，CAST饱和配置才会在精度转换中真正生效。详见[asc_set_saturation_strategy](asc_set_saturation_strategy.md)。 | ||
| 57 | + | ||
| 58 | +## 调用示例 | ||
| 59 | + | ||
| 60 | +场景：动态量化场景，溢出需饱和到±MAX而非截断。须先将策略设为`USE_GLOBAL`并开启CAST饱和。 | ||
| 61 | + | ||
| 62 | +```cpp | ||
| 63 | +// SIMD_VF外：asc_get_saturation_flag查询当前CAST饱和开关 | ||
| 64 | +bool cast_sat_enabled = asc_get_saturation_flag(asc_saturation_mode::CAST); | ||
| 65 | +asc_override_strategy old_strategy = asc_get_saturation_strategy(); | ||
| 66 | + | ||
| 67 | +if (!cast_sat_enabled) { | ||
| 68 | + asc_set_saturation_strategy(asc_override_strategy::USE_GLOBAL); | ||
| 69 | + asc_set_saturation_flag(asc_saturation_mode::CAST, true); | ||
| 70 | +} | ||
| 71 | + | ||
| 72 | +asc_copy_gm2ub_align(act_ub, act_gm, act_burst_bytes); | ||
| 73 | +asc_copy_gm2ub_align(bias_ub, bias_gm, bias_burst_bytes); | ||
| 74 | +asc_sync_notify(PIPE_MTE2, PIPE_V, EVENT_ID0); | ||
| 75 | +asc_sync_wait(PIPE_MTE2, PIPE_V, EVENT_ID0); | ||
| 76 | + | ||
| 77 | +// 矢量计算循环内：激活+bias加法后float→int32（全局CAST饱和生效） | ||
| 78 | + | ||
| 79 | +// SIMD_VF外：若本段临时开启过CAST饱和，则恢复进入本段前的配置 | ||
| 80 | +if (!cast_sat_enabled) { | ||
| 81 | + asc_set_saturation_flag(asc_saturation_mode::CAST, false); | ||
| 82 | + asc_set_saturation_strategy(old_strategy); | ||
| 83 | +} | ||
| 84 | +``` | ||
| 85 | + | ||
| 86 | +数据搬运与Reg cast模式可参考[Cast样例](../../../../../../examples/02_simd_c_api/03_c_api/02_reg_vector_compute/cast)。 | ||
| @@ -0,0 +1,79 @@ | |||
| 1 | +# asc_get_saturation_strategy | ||
| 2 | + | ||
| 3 | +## 产品支持情况 | ||
| 4 | + | ||
| 5 | +<!-- npu="950" id1 --> | ||
| 6 | +- Ascend 950PR/Ascend 950DT：支持 | ||
| 7 | +<!-- end id1 --> | ||
| 8 | +<!-- npu="A3" id2 --> | ||
| 9 | +- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持 | ||
| 10 | +<!-- end id2 --> | ||
| 11 | +<!-- npu="910b" id3 --> | ||
| 12 | +- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持 | ||
| 13 | +<!-- end id3 --> | ||
| 14 | +<!-- npu="310b" id4 --> | ||
| 15 | +- Atlas 200I/500 A2 推理产品：不支持 | ||
| 16 | +<!-- end id4 --> | ||
| 17 | +<!-- npu="310p" id5 --> | ||
| 18 | +- Atlas 推理系列产品AI Core：不支持 | ||
| 19 | +<!-- end id5 --> | ||
| 20 | +<!-- npu="310p" id6 --> | ||
| 21 | +- Atlas 推理系列产品Vector Core：不支持 | ||
| 22 | +<!-- end id6 --> | ||
| 23 | +<!-- npu="910" id7 --> | ||
| 24 | +- Atlas 训练系列产品：不支持 | ||
| 25 | +<!-- end id7 --> | ||
| 26 | + | ||
| 27 | +## 功能说明 | ||
| 28 | + | ||
| 29 | +读取当前饱和控制策略，默认为开启全局饱和配置： | ||
| 30 | + | ||
| 31 | +- 当前为单指令/API路径配置时，返回`asc_override_strategy::USE_API`。 | ||
| 32 | +- 当前为全局饱和配置时，返回`asc_override_strategy::USE_GLOBAL`。 | ||
| 33 | + | ||
| 34 | +常用于临时切换策略前保存原配置，或与[asc_set_saturation_strategy](asc_set_saturation_strategy.md)配合做回读校验。 | ||
| 35 | + | ||
| 36 | +## 函数原型 | ||
| 37 | + | ||
| 38 | +```c | ||
| 39 | +__aicore__ inline asc_override_strategy asc_get_saturation_strategy() | ||
| 40 | +``` | ||
| 41 | + | ||
| 42 | +## 参数说明 | ||
| 43 | + | ||
| 44 | +无 | ||
| 45 | + | ||
| 46 | +## 返回值说明 | ||
| 47 | + | ||
| 48 | +当前饱和控制策略，类型为[asc_override_strategy](../defs/enum/asc_override_strategy.md)。 | ||
| 49 | + | ||
| 50 | +## 流水类型 | ||
| 51 | + | ||
| 52 | +PIPE_S | ||
| 53 | + | ||
| 54 | +## 约束说明 | ||
| 55 | + | ||
| 56 | +无 | ||
| 57 | + | ||
| 58 | +## 调用示例 | ||
| 59 | + | ||
| 60 | +场景：动态量化场景，溢出需饱和到±MAX而非截断。须先将策略设为`USE_GLOBAL`并开启CAST饱和。 | ||
| 61 | + | ||
| 62 | +```cpp | ||
| 63 | +// SIMD_VF外：保存并切换饱和策略（动态量化段开始前） | ||
| 64 | +asc_override_strategy old_strategy = asc_get_saturation_strategy(); | ||
| 65 | +bool old_cast_sat = asc_get_saturation_flag(asc_saturation_mode::CAST); | ||
| 66 | +asc_set_saturation_strategy(asc_override_strategy::USE_GLOBAL); | ||
| 67 | +asc_set_saturation_flag(asc_saturation_mode::CAST, true); | ||
| 68 | + | ||
| 69 | +asc_copy_gm2ub_align(act_ub, act_gm, act_burst_bytes); | ||
| 70 | +asc_copy_gm2ub_align(bias_ub, bias_gm, bias_burst_bytes); | ||
| 71 | +asc_sync_notify(PIPE_MTE2, PIPE_V, EVENT_ID0); | ||
| 72 | +asc_sync_wait(PIPE_MTE2, PIPE_V, EVENT_ID0); | ||
| 73 | + | ||
| 74 | +// 矢量计算循环内：激活+bias加法后float→int32（全局CAST饱和生效） | ||
| 75 | + | ||
| 76 | +// SIMD_VF外：恢复进入本段前的配置 | ||
| 77 | +asc_set_saturation_flag(asc_saturation_mode::CAST, old_cast_sat); | ||
| 78 | +asc_set_saturation_strategy(old_strategy); | ||
| 79 | +``` | ||
| @@ -46,11 +46,13 @@ __aicore__ inline void asc_set_ctrl(uint64_t config) | |||
| 46 | 46 | ||
| 47 | |CTRL比特位 |功能| | 47 | |CTRL比特位 |功能| |
| 48 | | :------- | :---- | | 48 | | :------- | :---- | |
| 49 | -|CTRL[48] |用于控制整数计算指令的饱和模式 <br>- 1'b0：饱和模式，INF输出会被饱和为±MAX，NAN输出会被饱和为0；<br> - 1'b1：非饱和模式，INF/NAN保持原输出。<br> 该控制位仅支持如下数据类型：<br>- 浮点数计算时支持half数据类型；<br>- 浮点数精度转换时支持如下数据类型：hifloat8_t、fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t、half、bfloat16_t。| | 49 | +|CTRL[48] |用于控制浮点计算/部分浮点精度转换的饱和模式。<br>- 1'b0：饱和模式，INF输出会被饱和为±MAX，NAN输出会被饱和为0；<br> - 1'b1：非饱和模式，INF/NAN保持原输出。<br> 该控制位仅支持如下数据类型：<br>- 浮点数计算时支持half数据类型；<br>- 浮点数精度转换时支持如下数据类型：hifloat8_t、fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t、half、bfloat16_t。| |
| 50 | |CTRL[49] |用于控制标量单元读取数据时是否通过datacache读取。datacache的读取速度快于ub，因此在对ub进行大量读取，且ub中数据不被vector单元写入时，可选择开启该模式。<br>- 1'b0：标量单元读取数据时，直接从ub中读取；<br> - 1'b1：标量单元读取数据时，从datacache中读取。| | 50 | |CTRL[49] |用于控制标量单元读取数据时是否通过datacache读取。datacache的读取速度快于ub，因此在对ub进行大量读取，且ub中数据不被vector单元写入时，可选择开启该模式。<br>- 1'b0：标量单元读取数据时，直接从ub中读取；<br> - 1'b1：标量单元读取数据时，从datacache中读取。| |
| 51 | -|CTRL[53] |用于控制整数计算指令的饱和模式 <br>- 1'b0：截断模式，溢出值按目标数据类型位数截断，保留低位，舍弃高位；<br>- 1'b1：饱和模式，溢出值饱和到±MAX。| | 51 | +|CTRL[50] |用于控制fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t相关场景的饱和模式。<br>- 1'b0：饱和模式；<br> - 1'b1：非饱和模式。| |
| 52 | +|CTRL[53] |用于控制整数计算指令的饱和模式。<br>- 1'b0：截断模式，溢出值按目标数据类型位数截断，保留低位，舍弃高位；<br>- 1'b1：饱和模式，溢出值饱和到±MAX。| | ||
| 52 | |CTRL[56] |MASK模式控制位。MASK用于辅助SIMD指令执行，由于CTRL[56]指示两种模式：<br>- 1'b0：向量操作中的掩码寄存器。每位对应向量中一个元素，标记该元素是否参与计算。'1'表示对应元素将被计算；'0'表示对应元素将不被计算；<br>- 1'b1：MASK[31:0]用于指示SIMD指令实际操作的元素数量。实际重复次数由VECTOR自动推断，此时参数repeat time(Xt[63:56])被忽略。| | 53 | |CTRL[56] |MASK模式控制位。MASK用于辅助SIMD指令执行，由于CTRL[56]指示两种模式：<br>- 1'b0：向量操作中的掩码寄存器。每位对应向量中一个元素，标记该元素是否参与计算。'1'表示对应元素将被计算；'0'表示对应元素将不被计算；<br>- 1'b1：MASK[31:0]用于指示SIMD指令实际操作的元素数量。实际重复次数由VECTOR自动推断，此时参数repeat time(Xt[63:56])被忽略。| |
| 53 | |CTRL[59] |用于控制浮点数转整数或整数转整数时的精度转换饱和模式，仅在CTRL[60]开启时生效。<br>- 1'b0：饱和模式，溢出值饱和到±MAX；<br>- 1'b1：截断模式：溢出值按照目标数据类型位数截断，保留低位，舍弃高位。| | 54 | |CTRL[59] |用于控制浮点数转整数或整数转整数时的精度转换饱和模式，仅在CTRL[60]开启时生效。<br>- 1'b0：饱和模式，溢出值饱和到±MAX；<br>- 1'b1：截断模式：溢出值按照目标数据类型位数截断，保留低位，舍弃高位。| |
| 55 | +|CTRL[60] |饱和控制策略选择位。<br>- 1'b0：按单指令/API路径配置饱和（对应`asc_override_strategy::USE_API`）；<br>- 1'b1：使用全局CTRL饱和配置（对应`asc_override_strategy::USE_GLOBAL`），此时CTRL[59]的CAST配置才会生效。| | ||
| 54 | 56 | ||
| 55 | ## 返回值说明 | 57 | ## 返回值说明 |
| 56 | 58 | ||
| @@ -63,7 +65,7 @@ PIPE_S | |||
| 63 | ## 约束说明 | 65 | ## 约束说明 |
| 64 | 66 | ||
| 65 | - 使用前需要先用[asc_get_ctrl()](asc_get_ctrl.md)获取当前值，仅对需要变更的bit位进行修改。 | 67 | - 使用前需要先用[asc_get_ctrl()](asc_get_ctrl.md)获取当前值，仅对需要变更的bit位进行修改。 |
| 66 | -- 仅支持已设置CTRL[48]、CTRL[53]、CTRL[56]、CTRL[59]比特位。 | 68 | +- 常用可配置比特位包括CTRL[48]、CTRL[50]、CTRL[53]、CTRL[56]、CTRL[59]、CTRL[60]。 |
| 67 | 69 | ||
| 68 | ## 调用示例 | 70 | ## 调用示例 |
| 69 | 71 | ||
| @@ -0,0 +1,95 @@ | |||
| 1 | +# asc_set_saturation_flag | ||
| 2 | + | ||
| 3 | +## 产品支持情况 | ||
| 4 | + | ||
| 5 | +<!-- npu="950" id1 --> | ||
| 6 | +- Ascend 950PR/Ascend 950DT：支持 | ||
| 7 | +<!-- end id1 --> | ||
| 8 | +<!-- npu="A3" id2 --> | ||
| 9 | +- Atlas A3 训练系列产品/Atlas A3 推理系列产品：不支持 | ||
| 10 | +<!-- end id2 --> | ||
| 11 | +<!-- npu="910b" id3 --> | ||
| 12 | +- Atlas A2 训练系列产品/Atlas A2 推理系列产品：不支持 | ||
| 13 | +<!-- end id3 --> | ||
| 14 | +<!-- npu="310b" id4 --> | ||
| 15 | +- Atlas 200I/500 A2 推理产品：不支持 | ||
| 16 | +<!-- end id4 --> | ||
| 17 | +<!-- npu="310p" id5 --> | ||
| 18 | +- Atlas 推理系列产品AI Core：不支持 | ||
| 19 | +<!-- end id5 --> | ||
| 20 | +<!-- npu="310p" id6 --> | ||
| 21 | +- Atlas 推理系列产品Vector Core：不支持 | ||
| 22 | +<!-- end id6 --> | ||
| 23 | +<!-- npu="910" id7 --> | ||
| 24 | +- Atlas 训练系列产品：不支持 | ||
| 25 | +<!-- end id7 --> | ||
| 26 | + | ||
| 27 | +## 功能说明 | ||
| 28 | + | ||
| 29 | +按饱和模式类型设置对应饱和开关。`enable_sat`表示API语义上的“是否开启饱和”，接口内部会按模式处理不同语义。 | ||
| 30 | + | ||
| 31 | +各模式下`enable_sat`的含义如下： | ||
| 32 | + | ||
| 33 | +**表1** 饱和模式与enable_sat语义 | ||
| 34 | + | ||
| 35 | +| saturation_mode | enable_sat=true | enable_sat=false | 说明 | | ||
| 36 | +| :--- | :--- | :--- | :--- | | ||
| 37 | +| FLOAT | 饱和 | 非饱和 | 浮点计算及部分浮点精度转换场景的饱和控制，默认为非饱和状态。浮点数计算时支持half数据类型；浮点数精度转换时支持hifloat8_t、fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t、half、bfloat16_t数据类型。。 | | ||
| 38 | +| FLOAT8 | 饱和 | 非饱和 | fp8_e8m0_t、fp8_e5m2_t、fp8_e4m3fn_t相关场景的饱和控制，默认为饱和状态。 | | ||
| 39 | +| INT | 饱和 | 截断 | 整数计算溢出时的饱和/截断控制，默认为非饱和状态。 | | ||
| 40 | +| CAST | 饱和 | 截断 | 浮点转整数或整数转整数时的精度转换饱和控制，默认为饱和状态。仅在饱和策略为`USE_GLOBAL`时生效。 | | ||
| 41 | + | ||
| 42 | + | ||
| 43 | +## 函数原型 | ||
| 44 | + | ||
| 45 | +```c | ||
| 46 | +__aicore__ inline void asc_set_saturation_flag(asc_saturation_mode saturation_mode, bool enable_sat) | ||
| 47 | +``` | ||
| 48 | + | ||
| 49 | +## 参数说明 | ||
| 50 | + | ||
| 51 | +**表2** 参数说明 | ||
| 52 | + | ||
| 53 | +| 参数名 | 输入/输出 | 描述 | | ||
| 54 | +| :--- | :--- | :--- | | ||
| 55 | +| saturation_mode | 输入 | 饱和模式类型，取值见[asc_saturation_mode](../defs/enum/asc_saturation_mode.md)。 | | ||
| 56 | +| enable_sat | 输入 | 是否开启饱和。`true`表示开启饱和，`false`表示关闭饱和（对INT为截断；对FLOAT/FLOAT8/CAST为非饱和或截断，见上表）。 | | ||
| 57 | + | ||
| 58 | +## 返回值说明 | ||
| 59 | + | ||
| 60 | +无 | ||
| 61 | + | ||
| 62 | +## 流水类型 | ||
| 63 | + | ||
| 64 | +PIPE_S | ||
| 65 | + | ||
| 66 | +## 约束说明 | ||
| 67 | + | ||
| 68 | +- `enable_sat`是API语义参数：同一布尔值在不同模式下的关闭语义不同（INT为截断，FLOAT/FLOAT8/CAST为非饱和或截断），请以表1为准。 | ||
| 69 | +- 当`saturation_mode`为`CAST`时，还需将饱和策略设置为`asc_override_strategy::USE_GLOBAL`，CAST才会生效。可通过[asc_set_saturation_strategy](asc_set_saturation_strategy.md)配置。 | ||
| 70 | +- 本接口仅修改对应模式的饱和配置，不影响其他模式。 | ||
| 71 | + | ||
| 72 | +## 调用示例 | ||
| 73 | + | ||
| 74 | +场景：动态量化场景，溢出需饱和到±MAX而非截断。须先将策略设为`USE_GLOBAL`并开启CAST饱和。 | ||
| 75 | + | ||
| 76 | +```cpp | ||
| 77 | +// SIMD_VF外：保存并切换饱和策略（动态量化段开始前） | ||
| 78 | +asc_override_strategy old_strategy = asc_get_saturation_strategy(); | ||
| 79 | +bool old_cast_sat = asc_get_saturation_flag(asc_saturation_mode::CAST); | ||
| 80 | +asc_set_saturation_strategy(asc_override_strategy::USE_GLOBAL); | ||
| 81 | +asc_set_saturation_flag(asc_saturation_mode::CAST, true); | ||
| 82 | + | ||
| 83 | +asc_copy_gm2ub_align(act_ub, act_gm, act_burst_bytes); | ||
| 84 | +asc_copy_gm2ub_align(bias_ub, bias_gm, bias_burst_bytes); | ||
| 85 | +asc_sync_notify(PIPE_MTE2, PIPE_V, EVENT_ID0); | ||
| 86 | +asc_sync_wait(PIPE_MTE2, PIPE_V, EVENT_ID0); | ||
| 87 | + | ||
| 88 | +// 矢量计算循环内：激活+bias加法后float→int32（全局CAST饱和生效） | ||
| 89 | + | ||
| 90 | +// SIMD_VF外：恢复进入本段前的配置 | ||
| 91 | +asc_set_saturation_flag(asc_saturation_mode::CAST, old_cast_sat); | ||
| 92 | +asc_set_saturation_strategy(old_strategy); | ||
| 93 | +``` | ||
| 94 | + | ||
| 95 | +数据搬运与Reg cast模式可参考[Cast样例](../../../../../../examples/02_simd_c_api/03_c_api/02_reg_vector_compute/cast)。 | ||
| @@ -1,6 +1,10 @@ | |||
| 1 | # 特殊寄存器访问 | 1 | # 特殊寄存器访问 |
| 2 | 2 | ||
| 3 | - **[asc_get_ctrl](asc_get_ctrl.md)** | 3 | - **[asc_get_ctrl](asc_get_ctrl.md)** |
| 4 | +- **[asc_get_saturation_flag](asc_get_saturation_flag.md)** | ||
| 5 | +- **[asc_get_saturation_strategy](asc_get_saturation_strategy.md)** | ||
| 4 | - **[asc_get_squeeze_status](asc_get_squeeze_status.md)** | 6 | - **[asc_get_squeeze_status](asc_get_squeeze_status.md)** |
| 5 | - **[asc_set_ctrl](asc_set_ctrl.md)** | 7 | - **[asc_set_ctrl](asc_set_ctrl.md)** |
| 8 | +- **[asc_set_saturation_flag](asc_set_saturation_flag.md)** | ||
| 9 | +- **[asc_set_saturation_strategy](asc_set_saturation_strategy.md)** | ||
| 6 | - **[asc_get_ar_spr (废弃)](asc_get_ar_spr_deprecated.md)** | 10 | - **[asc_get_ar_spr (废弃)](asc_get_ar_spr_deprecated.md)** |