runtime/docs · chenminghao11/runtime

文件	最后提交记录	最后更新时间
zh	feat: AICPU异常回调返回算子下发信息 Co-authored-by: xiangyang0909<huxiangyang1@huawei.com> # message auto-generated for no-merge-commit merge: !3495 merge feature/aicpu-exception-info into master feat: AICPU异常回调返回算子下发信息 Created-by: xiangyang0909 Commit-by: xiangyang0909 Merged-by: cann-robot Description: # Pull Request ## 描述 AICPU 算子执行异常后，ExceptionCallBack 需要向上层返回算子下发阶段的关键信息。本次修改在 Runtime exception expand info 中新增 AICPU 扩展类型和明细结构，并支持以下两类 AICPU kernel 下发路径： - `rtsLaunchKernelWithDevArgs`：module/global callback 和匹配的 per-bin callback 均可获得完整信息。 - `rtAicpuKernelLaunchExWithArgs`：module/global callback 返回 args、SO 和入口函数名；该接口没有 `binHandle/funcHandle`，因此 `funcHandle` 和 `kernelName` 均为 `nullptr`，不分发 per-bin callback。 `rtAicpuExDetailInfo_t` 最终字段来源： \| 字段 \| handle launch \| raw launch \| \| --- \| --- \| --- \| \| `funcHandle` \| `AicpuTaskInfo::kernelInnerHandle` \| `nullptr` \| \| `soName` \| `Kernel::GetCpuKernelSo()` \| `AicpuTaskInfo::soName` 对应的名称，失败为 `nullptr` \| \| `functionName` \| `Kernel::GetCpuFuncName()` \| `AicpuTaskInfo::funcName` 对应的名称，失败为 `nullptr` \| \| `kernelName` \| `Kernel::GetCpuOpType()` \| `nullptr` \| \| `argAddr` \| `AicpuTaskInfo::comm.args` \| `AicpuTaskInfo::comm.args` \| \| `argsize` \| `AicpuTaskInfo::comm.argsSize` \| `AicpuTaskInfo::comm.argsSize` \| 关键变更： - `tagRtExceptionExpandType` 新增 `RT_EXCEPTION_AICPU`。 - `rtExceptionExpandInfo` 新增 `rtAicpuExDetailInfo_t aicpuInfo`。 - ACL `aclrtGetArgsFromExceptionInfo` 支持返回 AICPU device args 地址和参数个数。 - Runtime `rtGetFuncHandleFromExceptionInfo` 支持校验并返回 handle launch 的 AICPU funcHandle；raw launch 返回参数无效。 - AICPU per-bin callback 通过 `funcHandle -> Kernel -> Program_()` 定位注册 callback。 - raw SO/入口函数名优先由 ArgLoader 反查；仅当地址位于 device args 范围内时执行有界 D2H，检查地址溢出、读取边界和字符串终止符。 - raw launch 不保存或映射接口入参 `opName`，不强行回填 `kernelName`；handle launch 的 `Kernel::GetCpuOpType()` 行为保持不变。 - callback 名称由 `TaskFailCallBack` 局部 `std::string` 保活到同步 callback 返回，不引入 task 级 `new[]/delete[]` 所有权。 - 补充 ACL、Runtime common、Runtime API、David/950 UT 和 Kernel 加载执行 API 文档。 ## 变更类型请选择本次引入的变更类型： <!-- [x] 表示选中 --> - [ ] 🐛 Bug 修复 - [x] ✨ 新功能 - [ ] 💄 代码风格更新（格式化，局部变量） - [ ] ♻️ 重构（既不修复错误也不增加功能的代码变动） - [ ] 📦 构建过程或辅助工具的变动 - [x] 📝 文档内容更新 ## 关联的Issue <!-- 如果这个PR是为了解决特定的Issue，请在当前页面的右侧'关联Issue'部分添加相应Issue链接，并勾选'合并后关闭已关联的 Issue'选项。 --> - #739 [Requirement\|需求建议]: AICPU异常回调返回算子下发信息 ## 如何测试以下结果覆盖本 PR 的完整功能变更，不仅是 rebase 或本次 raw kernelName 回退后的局部测试。 ### 1. 变更范围、格式和结构尺寸 - 测试基线/merge-base：`upstream/master@4956ca68ae0a3eed908cdf14a9d1e82fb8189bee`。 - 当前 PR head：`b140e17181278080c79be2209548677286b14329`。 - 当前目标分支：`upstream/master@a734357dd01015f804850d84a39d8279fe3ad342`。 - `git merge-tree --write-tree HEAD upstream/master`：PASS，无冲突。 - PR 相对 merge-base 仅 1 个提交、16 个预期文件；raw opName 传递链和对应 910B UT 已完全回退。 - `git diff --check upstream/master...HEAD`：PASS。 - 常规 `numstat` 与 `--ignore-space-at-eol` 一致，无 EOF、换行或行尾空白伪差异。 - `ApiImpl::GetFuncHandleFromExceptionInfo()`：35 行。 - `TaskFailCallBack()`：42 行。 - v200 `StreamLaunchCpuKernelExWithArgs()`：48 行。 - `AicpuTaskInfo`：120 -> 120；`TaskInfo`：440 -> 440。 - `rtAicpuExDetailInfo_t`：48。 - `rtExceptionExpandInfo_t`：2088 -> 2088；`rtExceptionInfo_t`：2112 -> 2112。 ### 2. ACL 与 Runtime 定向 UT \| 测试组 \| 结果 \| 覆盖内容 \| \| --- \| --- \| --- \| \| `TaskTest.TestGetAicpuExceptionDetailInfo`、`TaskTest.TestTaskFailCallBack` \| 13/13 PASS \| handle/raw detail、名称反查、有界 D2H、非法地址、空字段、AICORE 回归 \| \| `ApiExceptionTest.*` \| 5/5 PASS \| AICORE/AICPU func getter、空/非法 handle、Program 为空、per-bin 路由 \| \| David/950 `DavidTaskTest` 定向用例 \| 2/2 PASS \| v200 名称地址覆盖顺序、task uninit 清理 \| \| ACL exception getter 定向用例 \| 2/2 PASS \| AICPU args getter与 func getter \| Runtime core 增量可执行行覆盖率以 `git diff --unified=0 <merge-base> -- src/runtime/core/src` 为口径，并合并 common/API/David gcov 数据： `text CHANGED_EXECUTABLE_LINES=179 COVERED_LINES=173 COVERAGE=96.648%` 首次回退 opName 链后的结果为 170/179，94.972%；补充原有 AICORE callback 分支 UT 后达到 96.648%，没有为覆盖率增加生产逻辑。 ACL UT 使用 `build_acl/tests/depends/runtime` 等构建依赖前置到 `LD_LIBRARY_PATH`，避免系统旧 `libruntime_stub.so` 抢占。 ### 3. Runtime 包构建与安装命令： `bash bash build.sh --ascend_install_path=/home/developer/Ascend/cann-9.1.0 --version 9.0.0 ./build_out/cann-npu-runtime_9.1.0_linux-aarch64.run --quiet --upgrade \ --install-path=/home/developer/Ascend/cann-9.1.0` 结果： - 最终 commit tree 对应的完整包构建 PASS，包含 `runtime_v100`、`runtime_v200`、`runtime_v201`。 - 安装 PASS，升级进度 100%，安装路径 `/home/developer/Ascend/cann-9.1.0`。 - 产物：`build_out/cann-npu-runtime_9.1.0_linux-aarch64.run`。 - SHA256：`923c6a4ace918aee57e9aa38016107e0a2e276593c45439e356a70c39906af3c`。 ### 4. 910B 真实 NPU HLT 环境：Ascend910B3，容器逻辑设备 0；预编译包为 `/mnt/workspace/gitCode/xiangyang0909/cann/910b-testcase-9.0.0-aarch64`。 \| Runtime \| 用例 \| 结果 \| \| --- \| --- \| --- \| \| `upstream/master@4956ca68a` \| `RTS_ABNORMAL_0015B` \| PASS，`SUCCESS`，6 次 task failure callback \| \| `feature@b140e1718` \| `RTS_ABNORMAL_0015B` \| PASS，`SUCCESS`，6 次 task failure callback \| PR 开发过程中还执行过以下补充回归 HLT，均有成功日志： \| 用例 \| 结果 \| \| --- \| --- \| \| `RTS_AICPU_0815` \| PASS \| \| `RTS_AICPU_0819` \| PASS \| \| `RTS_AICPU_0836` \| PASS \| \| `RTS_STREAM_FAILURE_0005` \| PASS \| 最终 head 重新执行了直接覆盖 raw AICPU 异常的 `RTS_ABNORMAL_0015B` 和下述双路径 E2E。 ### 5. AICPU exception 双下发路径端到端验证独立 E2E 真实触发 AICPU 异常，在 callback 中读取最终值并逐项与 launch 输入比较；程序实际打印每个字段及 `match` 结果，不以无输出断言代替验证。 raw `rtAicpuKernelLaunchExWithArgs` + `rtRegTaskFailCallbackByModule`： text launch_opName=RawAicpuExceptionOp funcHandle=(nil), func_match=true argAddr=0x12c0c0017000, expected_argAddr=0x12c0c0017000, arg_match=true argSize=80, expected_argSize=80, size_match=true soName=librts_aicpulaunch.so, soName_match=true functionName=aicpu_illegal_func_device, functionName_match=true kernelName=<null>, expected_kernelName=<null>, kernelName_match=true aclrtGetArgsFromExceptionInfo ret=0, ptr_match=true, size_match=true aclrtGetFuncHandleFromExceptionInfo ret=107000, func_match=true rtStreamSynchronize ret=507018, match=true AICPU_RAW_EXCEPTION_DETAIL_E2E PASS 该结果明确证明：launch 传入非空 `opName`，callback 中 `kernelName` 仍为 `nullptr`。 handle `rtsLaunchKernelWithDevArgs` + per-bin callback： text funcHandle=0xaaaad1ba84d8, expected_func=0xaaaad1ba84d8, func_match=true argAddr=0x12c0c001b000, expected_argAddr=0x12c0c001b000, arg_match=true argSize=1024, expected_argSize=1024, size_match=true soName=librts_aicpulaunch_open.so, soName_match=true functionName=aicpu_return_fail_task, functionName_match=true kernelName=aicpu_return_fail_task, kernelName_match=true aclrtGetArgsFromExceptionInfo ret=0, ptr_match=true, size_match=true aclrtGetFuncHandleFromExceptionInfo ret=0, func_match=true rtStreamSynchronize ret=507018, match=true AICPU_HANDLE_EXCEPTION_DETAIL_E2E PASS AICPU_EXCEPTION_TWO_LAUNCH_PATHS_E2E PASS 地址仅用于证明同一次执行中的 launch/callback 一致，不作为跨次执行的固定值。 ### 6. 950/910C 均通过真实NPU环境的HLT验证 \| 用例 \| 结果 \| \| --- \| --- \| \| `RTS_AICPU_0815` \| PASS \| \| `RTS_AICPU_0819` \| PASS \| \| `RTS_AICPU_0836` \| PASS \| \| `RTS_STREAM_FAILURE_0005` \| PASS \| 独立 E2E 真实触发 AICPU 异常，在 callback 中读取最终值并逐项与 launch 输入比较。验证通过 ### 7. PR 流水线状态说明此前 head `8a8f0b285` 的流水线 #902961 已 SUCCESS，x86、ARM、Ubuntu24、ACL、RTS common、RTS 910B、 RTS David 等任务完成。由于本次已更新 head 为 `b140e1718`，该历史结果不作为最新 head 的 CI 结论；最新 head 的本地 UT、完整包构建和 910B 、910C、950HLT 结果如上，远端流水线状态以新触发结果为准。 ## 核对清单 <!-- [x] 表示选中 --> - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（如：`feat:`, `fix:`） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md），并遵守了其中的所有规定，包括但不限于commit message的格式、无效commit的合并等 ## 其他信息 - 当前 head：`b140e17181278080c79be2209548677286b14329`，tree： `d08d9af99c86413a562fa1d889e99e950dd98c1a`。 - `pkg_inc/runtime/runtime/base.h` 公共区 line guard 按同步新增 10 行由 524 更新为 534；两个公共头一致。 - raw launch 如需非空 `funcHandle`，必须另行设计显式 handle-aware API 或注册关联及完整 Kernel/Program 生命周期；本 PR 不通过全局扫描或临时 Kernel 伪造。 - raw `kernelName` 最终为 `nullptr`；handle `kernelName` 继续来自 `Kernel::GetCpuOpType()`。 See merge request: cann/runtime!3495	1 个月前
.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	1 个月前