runtime/docs · CANN/runtime

cann-robot【PR】: Feat：扩展 DETERMINISTIC 系统参数 value 范围至 [0,4)，废弃 ACL_OPT_STRONG_CONSISTENCY

Files	Last commit	Last update
zh	【PR】: Feat：扩展 DETERMINISTIC 系统参数 value 范围至 [0,4)，废弃 ACL_OPT_STRONG_CONSISTENCY Co-authored-by: liguochao1<liguochao1@huawei.com> # message auto-generated for no-merge-commit merge: !3555 merge batch-consistency-dev into master 【PR】: Feat：扩展 DETERMINISTIC 系统参数 value 范围至 [0,4)，废弃 ACL_OPT_STRONG_CONSISTENCY Created-by: liguochao1 Commit-by: liguochao1 Merged-by: cann-robot Description: # Pull Request ## 描述 ### 一、需求背景当前 `ACL_OPT_DETERMINISTIC` 的 value 合法范围为 [0, 2)，仅支持 0=关闭、1=开启两档语义。随着 batch 一致性等更细粒度确定性级别的需求出现，原有两档 value 无法承载多级语义。同时 `ACL_OPT_STRONG_CONSISTENCY` 作为独立枚举项与 `ACL_OPT_DETERMINISTIC` 语义割裂，增加 API 维护成本。本特性将 `ACL_OPT_DETERMINISTIC` 的 value 合法范围从 [0, 2) 扩展到 [0, 4)，通过单一 value 字段承载多级确定性语义；同时废弃 `ACL_OPT_STRONG_CONSISTENCY` 枚举项（保留兼容，编译时告警 + 运行时告警）。 ### 二、修改内容 #### 1. 枚举定义 \| 文件 \| 修改内容 \| \|------\|---------\| \| `include/external/acl/acl_base_rt.h` \| `ACL_OPT_STRONG_CONSISTENCY` 添加 `ACL_DEPRECATED_MESSAGE` 标注；`ACL_OPT_DETERMINISTIC` 行内注释补充 value 0-3 语义说明 \| \| `pkg_inc/runtime/rt_external_base.h` \| `SYS_OPT_DETERMINISTIC` 注释更新为 `0:disable, 1:deterministic, 2:strong consistency, 3:batch consistency`；新增 `SYS_OPT_DETERMINISTIC_MAX = 4`；同步行守卫 544→546 \| \| `pkg_inc/runtime/runtime/base.h` \| 与 `rt_external_base.h` 同步修改；行守卫 524→526 \| #### 2. ACL 层校验与废弃告警（`src/acl/aclrt_impl/context.cpp`） - `GetSysParamOpt` / `SetSysParamOpt`：opt 白名单校验中 `ACL_OPT_STRONG_CONSISTENCY` 替换为 `STRONG_CONSISTENCY_OPT`（`static_cast<aclSysParamOpt>(2)`），避免 `-Werror` 下废弃告警 - `GetSysParamOpt` / `SetSysParamOpt`：新增 `ACL_OPT_STRONG_CONSISTENCY` 废弃 WARN 日志 - `SetSysParamOpt`：不新增 ACL 层 value 范围校验（由 Runtime 层双层校验保证，避免高频接口引入堆分配开销） #### 3. 描述映射表（`src/acl/utils/data_type_utils.h`） - `GetSysParamOptDesc`：map key `ACL_OPT_STRONG_CONSISTENCY` 替换为 `STRONG_CONSISTENCY_OPT`，避免废弃告警 #### 4. Runtime 层 value 分支校验 \| 文件 \| 修改内容 \| \|------\|---------\| \| `src/runtime/api/api_c.cc` \| `rtSetSysParamOpt`：value 校验从统一 `[0, SYS_OPT_MAX)` 改为按 opt 分支（DETERMINISTIC → `[0, SYS_OPT_DETERMINISTIC_MAX)`，其他 → `[0, SYS_OPT_MAX)`） \| \| `src/runtime/core/src/api_impl/api_error.cc` \| `ApiErrorDecorator::CtxSetSysParamOpt`：同上分支校验 \| #### 5. UT 用例 \| 文件 \| 修改内容 \| \|------\|---------\| \| `tests/ut/acl/testcase/acl_common_unittest.cpp` \| 删除 4 组无用 `#pragma GCC diagnostic`（编译选项已含 `-Wno-deprecated-declarations`）；`AclrtCtxSetSysParamOpt` / `AclrtSetSysParamOpt` 各新增合法值断言（DET=0/1/2/3、EK=0/1、SC=0/1）和 opt 白名单边界断言（opt=3、opt=-1） \| \| `tests/ut/acl/testcase/compatibility/enum_check.cpp` \| 删除 1 组无用 `#pragma GCC diagnostic` \| \| `tests/ut/runtime/.../rt_utest_api_cloud_disable_thread.cc` \| 新增 6 个 TEST_F：value 往返测试、Runtime 层 value 分支校验（含 INT64_MAX/INT64_MIN/SC=2 越界）、进程级与 Context 级隔离性、槽位隔离性、进程级并发、Context 级并发 \| ### 三、DETERMINISTIC value 语义映射 \| value \| 语义 \| \|-------\|------\| \| 0 \| disable（关闭，默认） \| \| 1 \| deterministic（确定性计算） \| \| 2 \| strong consistency（强一致性计算，等价于 `ACL_OPT_STRONG_CONSISTENCY=1`） \| \| 3 \| batch consistency（batch 一致性计算） \| Batch 一致性计算的定义是：在机器学习或高性能计算中，将一个样本放入任意大小的 Batch（批次）中、或者调整其在 Batch 中的排列顺序，该样本最终输出的计算结果都必须保持位级（Bit-wise）的完全相同。简单来说，就是：“单样本的计算结果，与它和谁一组（Batch Size）、排在第几个（Batch Index）毫无关系。” ### 四、兼容性 - 源码兼容：`ACL_OPT_STRONG_CONSISTENCY` 枚举值保留，编译通过（产生 `-Wdeprecated-declarations` 告警） - 二进制兼容：枚举值数值不变，函数签名不变，存储结构不变 - 运行时兼容：`ACL_OPT_DETERMINISTIC` value=0/1 行为不变；`ACL_OPT_STRONG_CONSISTENCY` 行为不变（新增 WARN 日志） - 迁移指南：`aclrtSetSysParamOpt(ACL_OPT_STRONG_CONSISTENCY, 1)` → `aclrtSetSysParamOpt(ACL_OPT_DETERMINISTIC, 2)`，语义等价，写入不同槽位 ### 五、涉及接口 \| 接口 \| 签名变更 \| 行为变更 \| \|------\|---------\|---------\| \| `aclrtSetSysParamOpt` \| 无 \| 新增废弃告警；value 校验下沉至 Runtime 层 \| \| `aclrtCtxSetSysParamOpt` \| 无 \| 同上 \| \| `aclrtGetSysParamOpt` \| 无 \| 新增废弃告警 \| \| `aclrtCtxGetSysParamOpt` \| 无 \| 同上 \| \| `rtSetSysParamOpt` \| 无 \| value 校验改为按 opt 分支 \| \| `rtCtxSetSysParamOpt` \| 无 \| 同上 \| \| `rtGetSysParamOpt` \| 无 \| 新增废弃告警 \| \| `rtCtxGetSysParamOpt` \| 无 \| 同上 \| ## 变更类型请选择本次引入的变更类型： <!-- [x] 表示选中 --> - [ ] 🐛 Bug 修复 - [x] ✨ 新功能 - [ ] 💄 代码风格更新（格式化，局部变量） - [ ] ♻️ 重构（既不修复错误也不增加功能的代码变动） - [ ] 📦 构建过程或辅助工具的变动 - [x] 📝 文档内容更新 ## 关联的Issue <!-- 如果这个PR是为了解决特定的Issue，请在当前页面的右侧'关联Issue'部分添加相应Issue链接，并勾选'合并后关闭已关联的 Issue'选项。 --> ## 如何测试描述测试此变更的步骤和前提条件： 1. 2. ## 核对清单 <!-- [x] 表示选中 --> - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（如：`feat:`, `fix:`） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md），并遵守了其中的所有规定，包括但不限于commit message的格式、无效commit的合并等 ## 其他信息在此添加任何其他关于本次 PR 的说明。 See merge request: cann/runtime!3555	11 hours ago
.gitattributes	【PR】: 简要描述Docs下增加zh目录，更新api_ref目录下的md文件 Co-authored-by: ycm0028<yechengmei@huawei.com> # message auto-generated for no-merge-commit merge: !3548 merge master into master 【PR】: 简要描述Docs下增加zh目录，更新api_ref目录下的md文件 Created-by: ycm0028 Commit-by: ycm0028 Merged-by: cann-robot Description: # Pull Request ## 描述 1、在Docs下增加zh目录，将现有目录移入zh中，同时，调整目录名称，去掉目录中的编号。 2、更新api_ref目录下的md文件，在产品支持情况以及约束说明中增加过滤标签，便于按指定范围过滤md内容。 ## 变更类型请选择本次引入的变更类型： <!-- [x] 表示选中 --> - [ ] 🐛 Bug 修复 - [ ] ✨ 新功能 - [ ] 💄 代码风格更新（格式化，局部变量） - [ ] ♻️ 重构（既不修复错误也不增加功能的代码变动） - [ ] 📦 构建过程或辅助工具的变动 - [x] 📝 文档内容更新 ## 关联的Issue <!-- 如果这个PR是为了解决特定的Issue，请在当前页面的右侧'关联Issue'部分添加相应Issue链接，并勾选'合并后关闭已关联的 Issue'选项。 --> ## 如何测试描述测试此变更的步骤和前提条件： 1.检查各md的内容显示是否正确。 2.检查目录之间的跳转是否正确。 ## 核对清单 <!-- [x] 表示选中 --> - [ ] 我的代码遵循了项目的代码风格 - [ ] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [ ] 我在标题中使用了合适的类型标签（如：`feat:`, `fix:`） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md），并遵守了其中的所有规定，包括但不限于commit message的格式、无效commit的合并等 ## 其他信息在此添加任何其他关于本次 PR 的说明。 See merge request: cann/runtime!3548	13 days ago