Snapshot 特性【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime1. 特性概述特性介绍Snapshot 特性支持 NPU 进程状态保存和恢复用于进程级快照备份/恢复场景故障恢复。通过锁定进程、备份关键状态、恢复资源实现进程状态的完整保存和恢复。问题背景进程在运行过程中需要保存完整状态以便后续恢复。大规模AI集群的故障恢复效率直接影响训练任务的可用性与资源利用率。传统故障恢复链路涉及容器调度、进程重建、主机与设备建链、算子编译、权重加载等多个串行环节单次恢复耗时可达十余分钟。设计目标支持进程锁定/解锁控制支持进程状态备份支持进程状态恢复提供多阶段回调机制2. 使用场景与对外接口2.1 使用场景场景一进程快照备份// 1. 锁定进程 aclError ret aclrtSnapShotProcessLock(pid, nullptr); // 2. 备份进程状态 aclrtSnapShotBackupArgs backupArgs; ret aclrtSnapShotProcessBackup(pid, backupArgs); // 3. 在目标端恢复进程状态 aclrtSnapShotRestoreArgs restoreArgs; ret aclrtSnapShotProcessRestore(pid, restoreArgs); // 4. 解锁进程 ret aclrtSnapShotProcessUnlock(pid, nullptr);场景二注册回调快照阶段// 注册备份前回调 aclrtSnapShotCallBack callback MyBackupPreCallback; aclrtSnapShotCallbackRegister(ACL_RT_SNAPSHOT_BACKUP_PRE, callback, nullptr); // 注册恢复后回调 aclrtSnapShotCallbackRegister(ACL_RT_SNAPSHOT_RESTORE_POST, MyRestorePostCallback, nullptr);2.2 对外接口接口文件位置说明aclrtSnapShotProcessLock()include/external/acl/acl_rt.h锁定进程aclrtSnapShotProcessUnlock()include/external/acl/acl_rt.h解锁进程aclrtSnapShotProcessBackup()include/external/acl/acl_rt.h备份进程状态aclrtSnapShotProcessRestore()include/external/acl/acl_rt.h从备份点恢复进程aclrtSnapShotCallbackRegister()include/external/acl/acl_rt.h注册快照阶段回调aclrtSnapShotCallbackUnregister()include/external/acl/acl_rt.h注销快照阶段回调2.3 快照阶段定义// 文件位置include/external/acl/acl_rt.h typedef enum { ACL_RT_SNAPSHOT_LOCK_PRE 0, ACL_RT_SNAPSHOT_BACKUP_PRE, ACL_RT_SNAPSHOT_BACKUP_POST, ACL_RT_SNAPSHOT_RESTORE_PRE, ACL_RT_SNAPSHOT_RESTORE_POST, ACL_RT_SNAPSHOT_UNLOCK_POST, } aclrtSnapShotStage;3. 架构总览整体设计思路Snapshot 特性采用分层架构设计ACL 接口层提供 C 语言接口aclrtSnapShot* 系列核心协调层GlobalStateManager 管理进程状态SnapshotCallbackManager 管理回调备份恢复协调层命名空间级别函数实现备份恢复流程协调设备操作层DeviceSnapshot 实现设备内存备份/恢复通过 IDeviceSnapshotOps 接口抽象架构分层图核心模块交互图4. 详细设计4.1 核心流程进程锁定流程功能说明回调触发触发 LOCK_PRE 阶段回调允许上层执行准备工作状态切换GlobalStateManager 将进程状态从 RUNNING 切换为 LOCKED线程同步等待所有注册的后台线程进入阻塞状态确保状态一致性错误处理若当前状态非 RUNNING 或等待超时则返回错误码关键文件位置src/runtime/core/src/api_impl/api_impl.cc进程备份流程功能说明预处理阶段触发 BACKUP_PRE 回调同步所有 Context确保没有任务在执行设备备份阶段遍历所有设备备份模型状态和算子内存模块保存阶段调用 Runtime::SaveModule 保存运行时模块状态后处理阶段触发 BACKUP_POST 回调将进程状态切换为 BACKED_UP关键文件位置src/runtime/core/src/api_impl/api_impl.ccsrc/runtime/feature/snapshot/snapshot_process_helper.cc进程恢复流程功能说明预处理阶段触发 RESTORE_PRE 回调准备恢复环境设备恢复阶段重新打开所有设备恢复页表信息资源恢复阶段清理并重新分配 Stream ID、Event ID、Notify ID内存恢复阶段恢复算子内存和参数池模型恢复阶段恢复模型状态和 ACL Graph后处理阶段触发 RESTORE_POST 回调将进程状态切换为 LOCKED关键文件位置src/runtime/core/src/api_impl/api_impl.ccsrc/runtime/feature/snapshot/snapshot_process_helper.cc4.2 核心组件详解GlobalStateManager 进程状态管理设计思想管理进程全局状态控制 API 调用阻塞协调后台线程锁定。位于cce::runtime命名空间。关键文件位置头文件src/runtime/core/inc/common/global_state_manager.hpp实现文件src/runtime/core/src/common/global_state_manager.ccSnapshotCallbackManager 回调管理器设计思想独立单例管理快照回调函数提供注册、注销、触发回调功能。位于cce::runtime命名空间。关键文件位置头文件src/runtime/feature/snapshot/snapshot_callback_manager.hpp实现文件src/runtime/feature/snapshot/snapshot_callback_manager.ccIDeviceSnapshotOps 设备快照操作接口设计思想抽象接口定义设备快照核心操作便于扩展和适配不同硬件版本。关键文件位置接口定义src/runtime/core/inc/common/idevice_snapshot_ops.hpp实现类头文件src/runtime/feature/snapshot/device_snapshot.hpp实现文件src/runtime/feature/snapshot/device_snapshot.ccSnapShotProcessHelper 快照处理辅助设计思想提供备份前处理、设备恢复、资源恢复、模型备份恢复、ACL Graph恢复等辅助函数。位于cce::runtime命名空间。关键文件位置头文件src/runtime/feature/snapshot/snapshot_process_helper.hpp实现文件src/runtime/feature/snapshot/snapshot_process_helper.cc4.3 模块职责划分模块职责位置GlobalStateManager进程状态管理、API调用阻塞控制core/inc/common/global_state_manager.hppSnapshotCallbackManager回调管理单例feature/snapshot/snapshot_callback_manager.hppIDeviceSnapshotOps设备快照操作抽象接口core/inc/common/idevice_snapshot_ops.hppDeviceSnapshot设备内存备份/恢复实现feature/snapshot/device_snapshot.hppSnapShotProcessHelper备份恢复辅助函数feature/snapshot/snapshot_process_helper.hppApiImplAPI 实现与流程协调core/src/api_impl/api_impl.ccTaskHandlers任务类型处理器feature/snapshot/device_snapshot.hpp4.4 核心数据结构5. 关键设计思想5.1 进程状态机状态定义进程状态由rtProcessState枚举定义共有三种状态状态说明允许的操作RT_PROCESS_STATE_RUNNING进程正常运行状态允许所有 API 正常执行可调用 Lock() 进入 LOCKED 状态RT_PROCESS_STATE_LOCKED进程已锁定状态允许 Backup() 进入 BACKED_UP 状态或 Unlock() 返回 RUNNING 状态RT_PROCESS_STATE_BACKED_UP进程已备份状态允许 Restore() 返回 LOCKED 状态或 Unlock() 返回 RUNNING 状态状态转换规则进程状态转换遵循严格的状态机状态转换约束正常转换路径RUNNING → LOCKED仅当当前状态为 RUNNING 时Lock() 才能成功LOCKED → BACKED_UP仅当当前状态为 LOCKED 时Backup() 才能成功BACKED_UP → LOCKED仅当当前状态为 BACKED_UP 时Restore() 才能成功LOCKED/BACKED_UP → RUNNING仅当状态为 LOCKED 或 BACKED_UP 时Unlock() 才能成功状态转换失败处理Lock 失败若当前状态非 RUNNING 或后台线程同步超时状态回退到 RUNNING并通知所有阻塞线程Unlock 失败若当前状态非 LOCKED 或 BACKED_UP返回错误码 RT_ERROR_SNAPSHOT_UNLOCK_FAILEDBackup/Restore 失败不影响状态转换由具体流程内部处理强制解锁场景ForceUnlocked()用于进程退出时强制解锁。触发时机进程退出main 函数返回、调用 exit()、进程终止通过atexit()注册为进程退出清理函数(void)atexit(ThreadGuard::ThreadExit);文件位置src/runtime/core/src/utils/osal.cc:218必要性若进程在退出时仍处于LOCKED或BACKED_UP状态其他线程可能阻塞在条件变量上等待解锁如果不强制解锁这些线程将永远无法退出导致进程无法正常结束强制解锁可以通知所有阻塞线程解除阻塞允许进程正常退出设计目的进程异常退出时的清理避免资源死锁和线程僵死关键文件位置src/runtime/core/src/common/global_state_manager.ccsrc/runtime/core/src/utils/osal.cc5.2 API 阻塞机制阻塞场景说明进程锁定后涉及设备资源修改的 API 会在Host 端调用线程中阻塞等待直到进程解锁。阻塞机制实现API 层通过GLOBAL_STATE_WAIT_IF_LOCKED()宏实现阻塞#define GLOBAL_STATE_WAIT_IF_LOCKED() \ GlobalStateManager::GetInstance().WaitIfLocked(__func__)阻塞逻辑阻塞条件进程状态为RT_PROCESS_STATE_LOCKED或RT_PROCESS_STATE_BACKED_UP阻塞行为Host 端调用线程阻塞在条件变量globalLockCv_上等待状态变为RT_PROCESS_STATE_RUNNING非阻塞场景若进程状态为RUNNING则直接返回继续执行关键文件位置src/runtime/core/inc/common/global_state_manager.hpp阻塞 API 示例涉及设备资源修改API 类别阻塞的接口示例Memory APIrtMalloc、rtFree、rtsMemcpy2D、rtsMallocHost、rtMallocHost、rtsHostRegister、rtHostRegisterV2、rtHostGetDevicePointerStream APIrtStreamCreate、rtStreamDestroy、rtStreamDestroyForce、rtStreamWaitEvent、rtStreamSwitchN、rtSetStreamSqLock、rtSetStreamSqUnlockKernel APIrtKernelLaunch、rtCccKernelLaunchDevice APIrtSetDevice、rtDeviceReset、rtsResetDeviceModel APIrtModelLoad、rtModelExecuteEvent APIrtsEventCreate、rtEventDestroyContext APIrtCtxCreate、rtCtxDestroy阻塞统计源码中共有 249 处 API 使用GLOBAL_STATE_WAIT_IF_LOCKED()宏。非阻塞 API 示例不涉及资源修改查询类 APIrtGetDeviceCount、rtGetDevice、rtGetDeviceIDsrtStreamQuery、rtStreamGetPriority、rtStreamGetFlagsrtSnapShotProcessGetState同步类 APIrtStreamSynchronize、rtStreamSynchronizeWithTimeoutrtEventSynchronizeSnapshot 管理类 APIrtSnapShotProcessLock、rtSnapShotProcessUnlockrtSnapShotProcessBackup、rtSnapShotProcessRestorertSnapShotCallbackRegister、rtSnapShotCallbackUnregister设计原则注释说明For any api that involves modifications to device resources, this should be added即仅涉及设备资源修改的 API 会阻塞查询和同步类 API 不阻塞。5.3 回调阶段设计回调在各关键阶段触发允许上层应用执行自定义逻辑阶段触发时机典型用途LOCK_PRE锁定前准备工作BACKUP_PRE备份前保存额外状态BACKUP_POST备份后确认备份完成RESTORE_PRE恢复前准备恢复环境RESTORE_POST恢复后确认恢复完成UNLOCK_POST解锁后清理工作5.4 后台线程管理锁定时需要等待所有后台线程进入阻塞状态IncBackgroundThreadCount(name)后台线程注册需要阻塞BackgroundThreadWaitIfLocked(name)后台线程检查并阻塞DecBackgroundThreadCount(name)后台线程退出时取消注册6. 关键文件索引模块文件路径核心内容API 头文件pkg_inc/runtime/rts/rts_snapshot.h对外接口定义、状态枚举ACL 实现src/acl/aclrt_impl/snapshot.cppACL 层接口封装Runtime APIsrc/runtime/api/api_c_snapshot.ccC API 实现API 实现src/runtime/core/src/api_impl/api_impl.ccSnapShotProcess 接口实现状态管理src/runtime/core/inc/common/global_state_manager.hppGlobalStateManager 类定义状态管理实现src/runtime/core/src/common/global_state_manager.cc进程状态管理实现回调管理src/runtime/feature/snapshot/snapshot_callback_manager.hppSnapshotCallbackManager 类定义回调管理实现src/runtime/feature/snapshot/snapshot_callback_manager.cc回调注册/注销/触发实现设备快照接口src/runtime/core/inc/common/idevice_snapshot_ops.hppIDeviceSnapshotOps 抽象接口设备快照src/runtime/feature/snapshot/device_snapshot.hppDeviceSnapshot 类定义设备快照实现src/runtime/feature/snapshot/device_snapshot.cc内存备份/恢复实现快照辅助src/runtime/feature/snapshot/snapshot_process_helper.hpp处理辅助函数声明快照辅助实现src/runtime/feature/snapshot/snapshot_process_helper.cc辅助函数实现设备适配 v100src/runtime/feature/snapshot/v100/device_snapshot_adapter.ccv100 版本适配设备适配 v200src/runtime/feature/snapshot/v200_base/device_snapshot_adapter.ccv200 版本适配7. 典型问题与排查7.1 关键日志点locked success.锁定成功unlocked success.解锁成功start to restore resource开始恢复资源the resource is restored successfully恢复成功current state is not the running state, current state is %s状态错误Timeout: only %u/%u background threads locked后台线程锁定超时7.2 问题定位方法锁定失败检查当前进程状态是否为 RUNNING锁定超时检查后台线程是否正确注册和阻塞备份失败检查 Context 同步是否成功检查模型是否为 AICPU 类型不支持恢复失败检查 Device ReOpen、Stream ID 重分配等步骤7.3 状态检查通过rtSnapShotProcessGetState()获取当前进程状态。本特性文档基于源码src/runtime/feature/snapshot/及src/runtime/core/src/common/global_state_manager.cc分析。【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
