优化snapshot特性说明-runtime-AtomGit

Merged

优化snapshot特性说明 #2681

zhangxingxing_xxAdd on Jun 8Merged fromzhangxinxing_xx/runtime： 06082 into cann/runtime： master

优化snapshot特性说明 #2681

Merged

zhangxingxing_xxAdd on Jun 8

Merged fromzhangxinxing_xx/runtime 06082intocann/runtime master

Total: 1 files changed+179-106

Mdocs/design/features/snapshot.md+179-106

	@@ -67,58 +67,47 @@ typedef enum {
67	### 整体设计思路	67	### 整体设计思路
68		68
69	Snapshot 特性采用分层架构设计：	69	Snapshot 特性采用分层架构设计：
70	-- API 层：提供 C 语言接口	70	+- ACL 接口层：提供 C 语言接口（aclrtSnapShot* 系列）
71	- 核心协调层：GlobalStateManager 管理进程状态，SnapshotCallbackManager 管理回调	71	- 核心协调层：GlobalStateManager 管理进程状态，SnapshotCallbackManager 管理回调
72	-- 备份恢复层：命名空间级别函数实现备份恢复流程	72	+- 备份恢复协调层：命名空间级别函数实现备份恢复流程协调
73	- 设备操作层：DeviceSnapshot 实现设备内存备份/恢复，通过 IDeviceSnapshotOps 接口抽象	73	- 设备操作层：DeviceSnapshot 实现设备内存备份/恢复，通过 IDeviceSnapshotOps 接口抽象
74		74
75	### 架构分层图	75	### 架构分层图
76		76
77	```mermaid	77	```mermaid
78	graph TB	78	graph TB
79	-subgraph ACL["ACL 接口层"]	79	+ subgraph ACL["ACL 接口层"]
80	-ACLSnapshot["aclrtSnapShotProcessLock/Unlock<br/>aclrtSnapShotProcessBackup/Restore<br/>aclrtSnapShotCallbackRegister"]	80	+ ACL_API["aclrtSnapShot* 系列接口"]
81	-end	81	+ end
82	-subgraph API["Runtime API 层"]	82	+
83	-APISnapshot["rtSnapShotProcessLock/Unlock<br/>rtSnapShotProcessBackup/Restore<br/>rtSnapShotCallbackRegister"]	83	+ subgraph RT["Runtime API 层"]
84	-ApiImpl["ApiImpl::SnapShotProcess*"]	84	+ RT_API["rtSnapShot* 系列接口"]
85	-end	85	+ end
86	-subgraph Core["核心管理层"]	86	+
87	-GlobalStateManager["GlobalStateManager<br/>进程状态管理"]	87	+ subgraph Core["核心协调层"]
88	-SnapshotCallbackManager["SnapshotCallbackManager<br/>回调管理单例"]	88	+ GSM["GlobalStateManager<br/>进程状态管理"]
89	-end	89	+ SCM["SnapshotCallbackManager<br/>回调管理单例"]
90	-subgraph Process["备份恢复协调层"]	90	+ end
91	-SnapShotProcessBackup["SnapShotProcessBackup()<br/>进程备份流程"]	91	+
92	-SnapShotProcessRestore["SnapShotProcessRestore()<br/>进程恢复流程"]	92	+ subgraph Process["备份恢复协调层"]
93	-ModelBackupRestore["ModelBackup/ModelRestore()<br/>模型备份恢复"]	93	+ Backup["Backup 流程协调器<br/>负责进程状态备份"]
94	-SnapShotPreProcessBackup["SnapShotPreProcessBackup()<br/>备份前处理"]	94	+ Restore["Restore 流程协调器<br/>负责进程状态恢复"]
95	-SnapShotDeviceRestore["SnapShotDeviceRestore()<br/>设备恢复"]	95	+ end
96	-SnapShotResourceRestore["SnapShotResourceRestore()<br/>资源恢复"]	96	+
97	-SnapShotAclGraphRestore["SnapShotAclGraphRestore()<br/>ACL Graph恢复"]	97	+ subgraph Feature["设备操作层"]
98	-end	98	+ DevOps["IDeviceSnapshotOps 接口<br/>设备快照操作抽象"]
99	-subgraph Feature["特性实现层"]	99	+ DevImpl["DeviceSnapshot 实现<br/>内存备份/恢复"]
100	-IDeviceSnapshotOps["IDeviceSnapshotOps<br/>设备快照操作接口"]	100	+ end
101	-DeviceSnapshot["DeviceSnapshot<br/>内存备份/恢复实现"]	101	+
102	-TaskHandlers["TaskHandlers<br/>任务处理器"]	102	+ ACL_API --> RT_API
103	-end	103	+ RT_API --> Backup
104	-ACL --> APISnapshot	104	+ RT_API --> Restore
105	-APISnapshot --> ApiImpl	105	+ Backup --> GSM
106	-ApiImpl --> GlobalStateManager	106	+ Backup --> SCM
107	-ApiImpl --> SnapshotCallbackManager	107	+ Restore --> GSM
108	-ApiImpl --> SnapShotProcessBackup	108	+ Restore --> SCM
109	-ApiImpl --> SnapShotProcessRestore	109	+ Restore --> DevOps
110	-SnapshotCallbackManager --> GlobalStateManager	110	+ DevOps --> DevImpl
111	-SnapShotProcessBackup --> SnapShotPreProcessBackup
112	-SnapShotProcessBackup --> ModelBackupRestore
113	-SnapShotProcessBackup --> Runtime["Runtime::SaveModule"]
114	-SnapShotProcessRestore --> SnapShotDeviceRestore
115	-SnapShotProcessRestore --> SnapShotResourceRestore
116	-SnapShotProcessRestore --> IDeviceSnapshotOps
117	-SnapShotProcessRestore --> ModelBackupRestore
118	-SnapShotProcessRestore --> SnapShotAclGraphRestore
119	-SnapShotProcessRestore --> Runtime2["Runtime::RestoreModule"]
120	-DeviceSnapshot --> IDeviceSnapshotOps
121	-DeviceSnapshot --> TaskHandlers
122	```	111	```
123		112
124	### 核心模块交互图	113	### 核心模块交互图
	@@ -196,42 +185,38 @@ ApiImpl-->>App: 返回结果
196		185
197	```mermaid	186	```mermaid
198	flowchart TD	187	flowchart TD
199	-A[rtSnapShotProcessLock] --> B[ApiImpl::SnapShotProcessLock]	188	+ A[rtSnapShotProcessLock] --> B[触发 LOCK_PRE 回调]
200	-B --> C[SnapshotCallbackManager::InvokeCallbacks LOCK_PRE]	189	+ B --> C[状态切换 RUNNING→LOCKED]
201	-C --> D{回调是否成功}	190	+ C --> D[等待后台线程锁定]
202	-D -->\|失败\| E[返回错误]	191	+ D --> E[锁定成功]
203	-D -->\|成功\| F[GlobalStateManager.Locked]
204	-F --> G[检查当前状态是否为 RUNNING]
205	-G -->\|非 RUNNING\| H[返回锁定失败]
206	-G -->\|RUNNING\| I[状态切换为 LOCKED]
207	-I --> J[等待所有后台线程锁定]
208	-J --> K{等待超时}
209	-K -->\|超时\| L[返回锁定超时错误]
210	-K -->\|成功\| M[锁定成功]
211	```	192	```
212		193
		194	+功能说明：
		195	+- 回调触发：触发 LOCK_PRE 阶段回调，允许上层执行准备工作
		196	+- 状态切换：GlobalStateManager 将进程状态从 RUNNING 切换为 LOCKED
		197	+- 线程同步：等待所有注册的后台线程进入阻塞状态，确保状态一致性
		198	+- 错误处理：若当前状态非 RUNNING 或等待超时，则返回错误码
		199	+
213	关键文件位置：`src/runtime/core/src/api_impl/api_impl.cc`	200	关键文件位置：`src/runtime/core/src/api_impl/api_impl.cc`
214		201
215	#### 进程备份流程	202	#### 进程备份流程
216		203
217	```mermaid	204	```mermaid
218	flowchart TD	205	flowchart TD
219	-A[rtSnapShotProcessBackup] --> B[ApiImpl::SnapShotProcessBackup]	206	+ A[rtSnapShotProcessBackup] --> B[触发 BACKUP_PRE 回调]
220	-B --> C[SnapshotCallbackManager::InvokeCallbacks BACKUP_PRE]	207	+ B --> C[同步 Context 确保无任务执行]
221	-C --> D[cce::runtime::SnapShotProcessBackup]	208	+ C --> D[设备备份<br/>ModelBackup/OpMemoryBackup]
222	-D --> E[SnapShotPreProcessBackup]	209	+ D --> E[Runtime 模块保存]
223	-E --> F[同步所有 Context]	210	+ E --> F[触发 BACKUP_POST 回调]
224	-F --> G[确保没有任务执行]	211	+ F --> G[状态切换为 BACKED_UP]
225	-G --> H[遍历所有 Device]
226	-H --> I[ModelBackup]
227	-I --> J[SinkTaskMemoryBackup]
228	-J --> K[DeviceSnapshot::OpMemoryBackup]
229	-K --> L[Runtime::SaveModule]
230	-L --> M[NpuDriver::ProcessResBackup]
231	-M --> N[SnapshotCallbackManager::InvokeCallbacks BACKUP_POST]
232	-N --> O[GlobalStateManager::SetCurrentState BACKED_UP]
233	```	212	```
234		213
		214	+功能说明：
		215	+- 预处理阶段：触发 BACKUP_PRE 回调，同步所有 Context，确保没有任务在执行
		216	+- 设备备份阶段：遍历所有设备，备份模型状态和算子内存
		217	+- 模块保存阶段：调用 Runtime::SaveModule 保存运行时模块状态
		218	+- 后处理阶段：触发 BACKUP_POST 回调，将进程状态切换为 BACKED_UP
		219	+
235	关键文件位置：	220	关键文件位置：
236	- `src/runtime/core/src/api_impl/api_impl.cc`	221	- `src/runtime/core/src/api_impl/api_impl.cc`
237	- `src/runtime/feature/snapshot/snapshot_process_helper.cc`	222	- `src/runtime/feature/snapshot/snapshot_process_helper.cc`
	@@ -240,27 +225,24 @@ N --> O[GlobalStateManager::SetCurrentState BACKED_UP]
240		225
241	```mermaid	226	```mermaid
242	flowchart TD	227	flowchart TD
243	-A[rtSnapShotProcessRestore] --> B[ApiImpl::SnapShotProcessRestore]	228	+ A[rtSnapShotProcessRestore] --> B[触发 RESTORE_PRE 回调]
244	-B --> C[SnapshotCallbackManager::InvokeCallbacks RESTORE_PRE]	229	+ B --> C[设备恢复<br/>重新打开 Device/恢复页表]
245	-C --> D[cce::runtime::SnapShotProcessRestore]	230	+ C --> D[资源恢复<br/>Stream/Event/Notify ID 重分配]
246	-D --> E[SnapShotDeviceRestore]	231	+ D --> E[内存恢复<br/>OpMemory/ArgsPool 恢复]
247	-E --> F[重新打开所有 Device]	232	+ E --> F[模型恢复<br/>ModelRestore/AclGraph 恢复]
248	-F --> G[恢复页表信息]	233	+ F --> G[Runtime 模块恢复]
249	-G --> H[SnapShotResourceRestore]	234	+ G --> H[触发 RESTORE_POST 回调]
250	-H --> I[清理并重新分配 Stream ID]	235	+ H --> I[状态切换为 LOCKED]
251	-I --> J[重新分配 Event/Notify ID]
252	-J --> K[Device ResourceRestore]
253	-K --> L[遍历所有 Device]
254	-L --> M[DeviceSnapshot::OpMemoryRestore]
255	-M --> N[ArgsPoolRestore]
256	-N --> O[UbArgsPoolRestore]
257	-O --> P[ModelRestore]
258	-P --> Q[SnapShotAclGraphRestore]
259	-Q --> R[Runtime::RestoreModule]
260	-R --> S[SnapshotCallbackManager::InvokeCallbacks RESTORE_POST]
261	-S --> T[GlobalStateManager::SetCurrentState LOCKED]
262	```	236	```
263		237
		238	+功能说明：
		239	+- 预处理阶段：触发 RESTORE_PRE 回调，准备恢复环境
		240	+- 设备恢复阶段：重新打开所有设备，恢复页表信息
		241	+- 资源恢复阶段：清理并重新分配 Stream ID、Event ID、Notify ID
		242	+- 内存恢复阶段：恢复算子内存和参数池
		243	+- 模型恢复阶段：恢复模型状态和 ACL Graph
		244	+- 后处理阶段：触发 RESTORE_POST 回调，将进程状态切换为 LOCKED
		245	+
264	关键文件位置：	246	关键文件位置：
265	- `src/runtime/core/src/api_impl/api_impl.cc`	247	- `src/runtime/core/src/api_impl/api_impl.cc`
266	- `src/runtime/feature/snapshot/snapshot_process_helper.cc`	248	- `src/runtime/feature/snapshot/snapshot_process_helper.cc`
	@@ -450,24 +432,123 @@ DeviceSnapshot --> IDeviceSnapshotOps
450		432
451	### 5.1 进程状态机	433	### 5.1 进程状态机
452		434
		435	+#### 状态定义
		436	+
		437	+进程状态由 `rtProcessState` 枚举定义，共有三种状态：
		438	+
		439	+\| 状态 \| 说明 \| 允许的操作 \|
		440	+\|------\|------\|-----------\|
		441	+\| RT_PROCESS_STATE_RUNNING \| 进程正常运行状态 \| 允许所有 API 正常执行，可调用 Lock() 进入 LOCKED 状态 \|
		442	+\| RT_PROCESS_STATE_LOCKED \| 进程已锁定状态 \| 允许 Backup() 进入 BACKED_UP 状态，或 Unlock() 返回 RUNNING 状态 \|
		443	+\| RT_PROCESS_STATE_BACKED_UP \| 进程已备份状态 \| 允许 Restore() 返回 LOCKED 状态，或 Unlock() 返回 RUNNING 状态 \|
		444	+
		445	+#### 状态转换规则
		446	+
453	进程状态转换遵循严格的状态机：	447	进程状态转换遵循严格的状态机：
454		448
455	```mermaid	449	```mermaid
456	-stateDiagram-v2	450	+%%{init: {'flowchart': {'curve': 'basis'}}}%%
457	-[*] --> RUNNING: 初始化	451	+flowchart TD
458	-RUNNING --> LOCKED: rtSnapShotProcessLock()	452	+ Running[[RUNNING]]
459	-LOCKED --> BACKED_UP: rtSnapShotProcessBackup()	453	+
460	-BACKED_UP --> LOCKED: rtSnapShotProcessRestore()	454	+ Running -->\|rtSnapShotProcessLock\| Locked[[LOCKED]]
461	-LOCKED --> RUNNING: rtSnapShotProcessUnlock()	455	+ Locked -->\|rtSnapShotProcessBackup\| BackedUp[[BACKED_UP]]
462	-BACKED_UP --> RUNNING: rtSnapShotProcessUnlock()	456	+ BackedUp -->\|rtSnapShotProcessRestore\| Locked
		457	+
		458	+ Locked -->\|rtSnapShotProcessUnlock\| Running
		459	+ BackedUp -->\|rtSnapShotProcessUnlock\| Running
463	```	460	```
464		461
		462	+#### 状态转换约束
		463	+
		464	+正常转换路径：
		465	+- RUNNING → LOCKED：仅当当前状态为 RUNNING 时，Lock() 才能成功
		466	+- LOCKED → BACKED_UP：仅当当前状态为 LOCKED 时，Backup() 才能成功
		467	+- BACKED_UP → LOCKED：仅当当前状态为 BACKED_UP 时，Restore() 才能成功
		468	+- LOCKED/BACKED_UP → RUNNING：仅当状态为 LOCKED 或 BACKED_UP 时，Unlock() 才能成功
		469	+
		470	+状态转换失败处理：
		471	+- Lock 失败：若当前状态非 RUNNING 或后台线程同步超时，状态回退到 RUNNING，并通知所有阻塞线程
		472	+- Unlock 失败：若当前状态非 LOCKED 或 BACKED_UP，返回错误码 RT_ERROR_SNAPSHOT_UNLOCK_FAILED
		473	+- Backup/Restore 失败：不影响状态转换，由具体流程内部处理
		474	+
		475	+#### 强制解锁场景
		476	+
		477	+`ForceUnlocked()` 用于进程退出时强制解锁。
		478	+
		479	+触发时机：进程退出（main 函数返回、调用 exit()、进程终止）
		480	+
		481	+通过 `atexit()` 注册为进程退出清理函数：
		482	+```cpp
		483	+(void)atexit(&ThreadGuard::ThreadExit);
		484	+```
		485	+文件位置：`src/runtime/core/src/utils/osal.cc:218`
		486	+
		487	+必要性：
		488	+- 若进程在退出时仍处于 `LOCKED` 或 `BACKED_UP` 状态，其他线程可能阻塞在条件变量上等待解锁
		489	+- 如果不强制解锁，这些线程将永远无法退出，导致进程无法正常结束
		490	+- 强制解锁可以通知所有阻塞线程解除阻塞，允许进程正常退出
		491	+
		492	+设计目的：进程异常退出时的清理，避免资源死锁和线程僵死
		493	+
		494	+关键文件位置：
		495	+- `src/runtime/core/src/common/global_state_manager.cc`
		496	+- `src/runtime/core/src/utils/osal.cc`
		497	+
465	### 5.2 API 阻塞机制	498	### 5.2 API 阻塞机制
466		499
467	-进程锁定后，所有涉及设备资源修改的 API 会通过 `GLOBAL_STATE_WAIT_IF_LOCKED()` 宏阻塞等待。	500	+#### 阻塞场景说明
		501	+
		502	+进程锁定后，涉及设备资源修改的 API 会在 Host 端调用线程中阻塞等待，直到进程解锁。
		503	+
		504	+#### 阻塞机制实现
		505	+
		506	+API 层通过 `GLOBAL_STATE_WAIT_IF_LOCKED()` 宏实现阻塞：
		507	+
		508	+```cpp
		509	+#define GLOBAL_STATE_WAIT_IF_LOCKED() \
		510	+ GlobalStateManager::GetInstance().WaitIfLocked(__func__)
		511	+```
		512	+
		513	+阻塞逻辑：
		514	+- 阻塞条件：进程状态为 `RT_PROCESS_STATE_LOCKED` 或 `RT_PROCESS_STATE_BACKED_UP`
		515	+- 阻塞行为：Host 端调用线程阻塞在条件变量 `globalLockCv_` 上，等待状态变为 `RT_PROCESS_STATE_RUNNING`
		516	+- 非阻塞场景：若进程状态为 `RUNNING`，则直接返回继续执行
468		517
469	关键文件位置：`src/runtime/core/inc/common/global_state_manager.hpp`	518	关键文件位置：`src/runtime/core/inc/common/global_state_manager.hpp`
470		519
		520	+#### 阻塞 API 示例（涉及设备资源修改）
		521	+
		522	+\| API 类别 \| 阻塞的接口示例 \|
		523	+\|---------\|---------------\|
		524	+\| Memory API \| rtMalloc、rtFree、rtsMemcpy2D、rtsMallocHost、rtMallocHost、rtsHostRegister、rtHostRegisterV2、rtHostGetDevicePointer \|
		525	+\| Stream API \| rtStreamCreate、rtStreamDestroy、rtStreamDestroyForce、rtStreamWaitEvent、rtStreamSwitchN、rtSetStreamSqLock、rtSetStreamSqUnlock \|
		526	+\| Kernel API \| rtKernelLaunch、rtCccKernelLaunch \|
		527	+\| Device API \| rtSetDevice、rtDeviceReset、rtsResetDevice \|
		528	+\| Model API \| rtModelLoad、rtModelExecute \|
		529	+\| Event API \| rtsEventCreate、rtEventDestroy \|
		530	+\| Context API \| rtCtxCreate、rtCtxDestroy \|
		531	+
		532	+阻塞统计：源码中共有 249 处 API 使用 `GLOBAL_STATE_WAIT_IF_LOCKED()` 宏。
		533	+
		534	+#### 非阻塞 API 示例（不涉及资源修改）
		535	+
		536	+查询类 API：
		537	+- rtGetDeviceCount、rtGetDevice、rtGetDeviceIDs
		538	+- rtStreamQuery、rtStreamGetPriority、rtStreamGetFlags
		539	+- rtSnapShotProcessGetState
		540	+
		541	+同步类 API：
		542	+- rtStreamSynchronize、rtStreamSynchronizeWithTimeout
		543	+- rtEventSynchronize
		544	+
		545	+Snapshot 管理类 API：
		546	+- rtSnapShotProcessLock、rtSnapShotProcessUnlock
		547	+- rtSnapShotProcessBackup、rtSnapShotProcessRestore
		548	+- rtSnapShotCallbackRegister、rtSnapShotCallbackUnregister
		549	+
		550	+设计原则：注释说明"For any api that involves modifications to device resources, this should be added"，即仅涉及设备资源修改的 API 会阻塞，查询和同步类 API 不阻塞。
		551	+
471	### 5.3 回调阶段设计	552	### 5.3 回调阶段设计
472		553
473	回调在各关键阶段触发，允许上层应用执行自定义逻辑：	554	回调在各关键阶段触发，允许上层应用执行自定义逻辑：
	@@ -488,14 +569,6 @@ BACKED_UP --> RUNNING: rtSnapShotProcessUnlock()
488	- `BackgroundThreadWaitIfLocked(name)`：后台线程检查并阻塞	569	- `BackgroundThreadWaitIfLocked(name)`：后台线程检查并阻塞
489	- `DecBackgroundThreadCount(name)`：后台线程退出时取消注册	570	- `DecBackgroundThreadCount(name)`：后台线程退出时取消注册
490		571
491	-### 5.5 命名空间设计
492	-
493	-所有快照相关组件都在 `cce::runtime` 命名空间下：
494	-- `cce::runtime::GlobalStateManager`
495	-- `cce::runtime::SnapshotCallbackManager`
496	-- `cce::runtime::DeviceSnapshot`
497	-- `cce::runtime::SnapShotProcessBackup/Restore` 等辅助函数
498	-
499	## 6. 关键文件索引	572	## 6. 关键文件索引
500		573
501	\| 模块 \| 文件路径 \| 核心内容 \|	574	\| 模块 \| 文件路径 \| 核心内容 \|