ssm.h@ 23746

Last change on this file since 23746 was 23709, checked in by vboxsync, 15 years ago
SSM: VINF_SSM_VOTE_FOR_ANOTHER_PASS - for pushing config data in pass 0.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 31.7 KB

Line
1	/** @file
2	* SSM - The Save State Manager. (VMM)
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 Sun Microsystems, Inc.
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*
25	* Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26	* Clara, CA 95054 USA or visit http://www.sun.com if you need
27	* additional information or have any questions.
28	*/
29
30	#ifndef ___VBox_ssm_h
31	#define ___VBox_ssm_h
32
33	#include <VBox/cdefs.h>
34	#include <VBox/types.h>
35	#include <VBox/tm.h>
36	#include <VBox/vmapi.h>
37
38	RT_C_DECLS_BEGIN
39
40	/** @defgroup grp_ssm The Saved State Manager API
41	* @{
42	*/
43
44	/**
45	* Determine the major version of the SSM version. If the major SSM version of two snapshots is
46	* different, the snapshots are incompatible.
47	*/
48	#define SSM_VERSION_MAJOR(ver) ((ver) & 0xffff0000)
49
50	/**
51	* Determine the minor version of the SSM version. If the major SSM version of two snapshots is
52	* the same, the code must handle incompatibilies between minor version changes (e.g. use dummy
53	* values for non-existent fields).
54	*/
55	#define SSM_VERSION_MINOR(ver) ((ver) & 0x0000ffff)
56
57	/**
58	* Determine if the major version changed between two SSM versions.
59	*/
60	#define SSM_VERSION_MAJOR_CHANGED(ver1,ver2) (SSM_VERSION_MAJOR(ver1) != SSM_VERSION_MAJOR(ver2))
61
62	/** The special value for the final pass. */
63	#define SSM_PASS_FINAL UINT32_MAX
64
65
66	#ifdef IN_RING3
67	/** @defgroup grp_ssm_r3 The SSM Host Context Ring-3 API
68	* @{
69	*/
70
71
72	/**
73	* What to do after the save/load operation.
74	*/
75	typedef enum SSMAFTER
76	{
77	/** Invalid. */
78	SSMAFTER_INVALID = 0,
79	/** Will resume the loaded state. */
80	SSMAFTER_RESUME,
81	/** Will destroy the VM after saving. */
82	SSMAFTER_DESTROY,
83	/** Will continue execution after saving the VM. */
84	SSMAFTER_CONTINUE,
85	/** Will migrate the VM.
86	* The source VM will be destroyed (then one saving), the destination VM
87	* will continue execution. */
88	SSMAFTER_MIGRATE,
89	/** Will debug the saved state.
90	* This is used to drop some of the stricter consitentcy checks so it'll
91	* load fine in the debugger or animator. */
92	SSMAFTER_DEBUG_IT,
93	/** The file was opened using SSMR3Open() and we have no idea what the plan is. */
94	SSMAFTER_OPENED
95	} SSMAFTER;
96
97
98	/**
99	* A structure field description.
100	*
101	* @todo Add an type field here for recording what's a GCPtr, GCPhys or anything
102	* else that may change and is expected to continue to work.
103	* @todo Later we need to add load transformations to this structure. I think a
104	* callback with a number of default transformations in SIG_DEF style
105	* would be good enough. The callback would take a user context from a new
106	* SSMR3GetStruct parameter or something.
107	*/
108	typedef struct SSMFIELD
109	{
110	/** Field offset into the structure. */
111	uint32_t off;
112	/** The size of the field. */
113	uint32_t cb;
114	} SSMFIELD;
115	/** Pointer to a structure field description. */
116	typedef SSMFIELD *PSSMFIELD;
117	/** Pointer to a const structure field description. */
118	typedef const SSMFIELD *PCSSMFIELD;
119
120	/** Emit a SSMFIELD array entry. */
121	#define SSMFIELD_ENTRY(Type, Field) { RT_OFFSETOF(Type, Field), RT_SIZEOFMEMB(Type, Field) }
122	/** Emit a SSMFIELD array entry for a RTGCPTR type. */
123	#define SSMFIELD_ENTRY_GCPTR(Type, Field) SSMFIELD_ENTRY(Type, Field)
124	/** Emit a SSMFIELD array entry for a RTGCPHYS type. */
125	#define SSMFIELD_ENTRY_GCPHYS(Type, Field) SSMFIELD_ENTRY(Type, Field)
126	/** Emit the terminating entry of a SSMFIELD array. */
127	#define SSMFIELD_ENTRY_TERM() { UINT32_MAX, UINT32_MAX }
128
129
130
131	/** The PDM Device callback variants.
132	* @{
133	*/
134
135	/**
136	* Prepare state live save operation.
137	*
138	* @returns VBox status code.
139	* @param pDevIns Device instance of the device which registered the data unit.
140	* @param pSSM SSM operation handle.
141	* @thread Any.
142	*/
143	typedef DECLCALLBACK(int) FNSSMDEVLIVEPREP(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
144	/** Pointer to a FNSSMDEVLIVEPREP() function. */
145	typedef FNSSMDEVLIVEPREP *PFNSSMDEVLIVEPREP;
146
147	/**
148	* Execute state live save operation.
149	*
150	* This will be called repeatedly until all units vote that the live phase has
151	* been concluded.
152	*
153	* @returns VBox status code.
154	* @param pDevIns Device instance of the device which registered the data unit.
155	* @param pSSM SSM operation handle.
156	* @param uPass The pass.
157	* @thread Any.
158	*/
159	typedef DECLCALLBACK(int) FNSSMDEVLIVEEXEC(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t uPass);
160	/** Pointer to a FNSSMDEVLIVEEXEC() function. */
161	typedef FNSSMDEVLIVEEXEC *PFNSSMDEVLIVEEXEC;
162
163	/**
164	* Vote on whether the live part of the saving has been concluded.
165	*
166	* The vote stops once a unit has vetoed the decision, so don't rely upon this
167	* being called every time.
168	*
169	* @returns VBox status code.
170	* @retval VINF_SUCCESS if done.
171	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
172	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
173	* done and there is not need calling it again before the final pass.
174	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
175	*
176	* @param pDevIns Device instance of the device which registered the data unit.
177	* @param pSSM SSM operation handle.
178	* @thread Any.
179	*/
180	typedef DECLCALLBACK(int) FNSSMDEVLIVEVOTE(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
181	/** Pointer to a FNSSMDEVLIVEVOTE() function. */
182	typedef FNSSMDEVLIVEVOTE *PFNSSMDEVLIVEVOTE;
183
184	/**
185	* Prepare state save operation.
186	*
187	* @returns VBox status code.
188	* @param pDevIns Device instance of the device which registered the data unit.
189	* @param pSSM SSM operation handle.
190	*/
191	typedef DECLCALLBACK(int) FNSSMDEVSAVEPREP(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
192	/** Pointer to a FNSSMDEVSAVEPREP() function. */
193	typedef FNSSMDEVSAVEPREP *PFNSSMDEVSAVEPREP;
194
195	/**
196	* Execute state save operation.
197	*
198	* @returns VBox status code.
199	* @param pDevIns Device instance of the device which registered the data unit.
200	* @param pSSM SSM operation handle.
201	*/
202	typedef DECLCALLBACK(int) FNSSMDEVSAVEEXEC(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
203	/** Pointer to a FNSSMDEVSAVEEXEC() function. */
204	typedef FNSSMDEVSAVEEXEC *PFNSSMDEVSAVEEXEC;
205
206	/**
207	* Done state save operation.
208	*
209	* @returns VBox status code.
210	* @param pDevIns Device instance of the device which registered the data unit.
211	* @param pSSM SSM operation handle.
212	*/
213	typedef DECLCALLBACK(int) FNSSMDEVSAVEDONE(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
214	/** Pointer to a FNSSMDEVSAVEDONE() function. */
215	typedef FNSSMDEVSAVEDONE *PFNSSMDEVSAVEDONE;
216
217	/**
218	* Prepare state load operation.
219	*
220	* @returns VBox status code.
221	* @param pDevIns Device instance of the device which registered the data unit.
222	* @param pSSM SSM operation handle.
223	*/
224	typedef DECLCALLBACK(int) FNSSMDEVLOADPREP(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
225	/** Pointer to a FNSSMDEVLOADPREP() function. */
226	typedef FNSSMDEVLOADPREP *PFNSSMDEVLOADPREP;
227
228	/**
229	* Execute state load operation.
230	*
231	* @returns VBox status code.
232	* @param pDevIns Device instance of the device which registered the data unit.
233	* @param pSSM SSM operation handle.
234	* @param uVersion Data layout version.
235	* @param uPass The pass. This is always SSM_PASS_FINAL for units
236	* that doesn't specify a pfnSaveLive callback.
237	*/
238	typedef DECLCALLBACK(int) FNSSMDEVLOADEXEC(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass);
239	/** Pointer to a FNSSMDEVLOADEXEC() function. */
240	typedef FNSSMDEVLOADEXEC *PFNSSMDEVLOADEXEC;
241
242	/**
243	* Done state load operation.
244	*
245	* @returns VBox load code.
246	* @param pDevIns Device instance of the device which registered the data unit.
247	* @param pSSM SSM operation handle.
248	*/
249	typedef DECLCALLBACK(int) FNSSMDEVLOADDONE(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
250	/** Pointer to a FNSSMDEVLOADDONE() function. */
251	typedef FNSSMDEVLOADDONE *PFNSSMDEVLOADDONE;
252
253	/** @} */
254
255
256	/** The PDM Driver callback variants.
257	* @{
258	*/
259
260	/**
261	* Prepare state live save operation.
262	*
263	* @returns VBox status code.
264	* @param pDrvIns Driver instance of the device which registered the
265	* data unit.
266	* @param pSSM SSM operation handle.
267	* @thread Any.
268	*/
269	typedef DECLCALLBACK(int) FNSSMDRVLIVEPREP(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
270	/** Pointer to a FNSSMDRVLIVEPREP() function. */
271	typedef FNSSMDRVLIVEPREP *PFNSSMDRVLIVEPREP;
272
273	/**
274	* Execute state live save operation.
275	*
276	* This will be called repeatedly until all units vote that the live phase has
277	* been concluded.
278	*
279	* @returns VBox status code.
280	* @param pDrvIns Driver instance of the device which registered the
281	* data unit.
282	* @param pSSM SSM operation handle.
283	* @param uPass The data pass.
284	* @thread Any.
285	*/
286	typedef DECLCALLBACK(int) FNSSMDRVLIVEEXEC(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM, uint32_t uPass);
287	/** Pointer to a FNSSMDRVLIVEEXEC() function. */
288	typedef FNSSMDRVLIVEEXEC *PFNSSMDRVLIVEEXEC;
289
290	/**
291	* Vote on whether the live part of the saving has been concluded.
292	*
293	* The vote stops once a unit has vetoed the decision, so don't rely upon this
294	* being called every time.
295	*
296	* @returns VBox status code.
297	* @retval VINF_SUCCESS if done.
298	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
299	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
300	* done and there is not need calling it again before the final pass.
301	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
302	*
303	* @param pDrvIns Driver instance of the device which registered the
304	* data unit.
305	* @param pSSM SSM operation handle.
306	* @thread Any.
307	*/
308	typedef DECLCALLBACK(int) FNSSMDRVLIVEVOTE(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
309	/** Pointer to a FNSSMDRVLIVEVOTE() function. */
310	typedef FNSSMDRVLIVEVOTE *PFNSSMDRVLIVEVOTE;
311
312
313	/**
314	* Prepare state save operation.
315	*
316	* @returns VBox status code.
317	* @param pDrvIns Driver instance of the driver which registered the data unit.
318	* @param pSSM SSM operation handle.
319	*/
320	typedef DECLCALLBACK(int) FNSSMDRVSAVEPREP(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
321	/** Pointer to a FNSSMDRVSAVEPREP() function. */
322	typedef FNSSMDRVSAVEPREP *PFNSSMDRVSAVEPREP;
323
324	/**
325	* Execute state save operation.
326	*
327	* @returns VBox status code.
328	* @param pDrvIns Driver instance of the driver which registered the data unit.
329	* @param pSSM SSM operation handle.
330	*/
331	typedef DECLCALLBACK(int) FNSSMDRVSAVEEXEC(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
332	/** Pointer to a FNSSMDRVSAVEEXEC() function. */
333	typedef FNSSMDRVSAVEEXEC *PFNSSMDRVSAVEEXEC;
334
335	/**
336	* Done state save operation.
337	*
338	* @returns VBox status code.
339	* @param pDrvIns Driver instance of the driver which registered the data unit.
340	* @param pSSM SSM operation handle.
341	*/
342	typedef DECLCALLBACK(int) FNSSMDRVSAVEDONE(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
343	/** Pointer to a FNSSMDRVSAVEDONE() function. */
344	typedef FNSSMDRVSAVEDONE *PFNSSMDRVSAVEDONE;
345
346	/**
347	* Prepare state load operation.
348	*
349	* @returns VBox status code.
350	* @param pDrvIns Driver instance of the driver which registered the data unit.
351	* @param pSSM SSM operation handle.
352	*/
353	typedef DECLCALLBACK(int) FNSSMDRVLOADPREP(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
354	/** Pointer to a FNSSMDRVLOADPREP() function. */
355	typedef FNSSMDRVLOADPREP *PFNSSMDRVLOADPREP;
356
357	/**
358	* Execute state load operation.
359	*
360	* @returns VBox status code.
361	* @param pDrvIns Driver instance of the driver which registered the data unit.
362	* @param pSSM SSM operation handle.
363	* @param uVersion Data layout version.
364	* @param uPass The pass. This is always SSM_PASS_FINAL for units
365	* that doesn't specify a pfnSaveLive callback.
366	*/
367	typedef DECLCALLBACK(int) FNSSMDRVLOADEXEC(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass);
368	/** Pointer to a FNSSMDRVLOADEXEC() function. */
369	typedef FNSSMDRVLOADEXEC *PFNSSMDRVLOADEXEC;
370
371	/**
372	* Done state load operation.
373	*
374	* @returns VBox load code.
375	* @param pDrvIns Driver instance of the driver which registered the data unit.
376	* @param pSSM SSM operation handle.
377	*/
378	typedef DECLCALLBACK(int) FNSSMDRVLOADDONE(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
379	/** Pointer to a FNSSMDRVLOADDONE() function. */
380	typedef FNSSMDRVLOADDONE *PFNSSMDRVLOADDONE;
381
382	/** @} */
383
384
385	/** The internal callback variants.
386	* @{
387	*/
388
389
390	/**
391	* Prepare state live save operation.
392	*
393	* @returns VBox status code.
394	* @param pVM VM Handle.
395	* @param pSSM SSM operation handle.
396	* @thread Any.
397	*/
398	typedef DECLCALLBACK(int) FNSSMINTLIVEPREP(PVM pVM, PSSMHANDLE pSSM);
399	/** Pointer to a FNSSMINTLIVEPREP() function. */
400	typedef FNSSMINTLIVEPREP *PFNSSMINTLIVEPREP;
401
402	/**
403	* Execute state live save operation.
404	*
405	* This will be called repeatedly until all units vote that the live phase has
406	* been concluded.
407	*
408	* @returns VBox status code.
409	* @param pVM VM Handle.
410	* @param pSSM SSM operation handle.
411	* @param uPass The data pass.
412	* @thread Any.
413	*/
414	typedef DECLCALLBACK(int) FNSSMINTLIVEEXEC(PVM pVM, PSSMHANDLE pSSM, uint32_t uPass);
415	/** Pointer to a FNSSMINTLIVEEXEC() function. */
416	typedef FNSSMINTLIVEEXEC *PFNSSMINTLIVEEXEC;
417
418	/**
419	* Vote on whether the live part of the saving has been concluded.
420	*
421	* The vote stops once a unit has vetoed the decision, so don't rely upon this
422	* being called every time.
423	*
424	* @returns VBox status code.
425	* @retval VINF_SUCCESS if done.
426	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
427	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
428	* done and there is not need calling it again before the final pass.
429	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
430	*
431	* @param pVM VM Handle.
432	* @param pSSM SSM operation handle.
433	* @thread Any.
434	*/
435	typedef DECLCALLBACK(int) FNSSMINTLIVEVOTE(PVM pVM, PSSMHANDLE pSSM);
436	/** Pointer to a FNSSMINTLIVEVOTE() function. */
437	typedef FNSSMINTLIVEVOTE *PFNSSMINTLIVEVOTE;
438
439	/**
440	* Prepare state save operation.
441	*
442	* @returns VBox status code.
443	* @param pVM VM Handle.
444	* @param pSSM SSM operation handle.
445	*/
446	typedef DECLCALLBACK(int) FNSSMINTSAVEPREP(PVM pVM, PSSMHANDLE pSSM);
447	/** Pointer to a FNSSMINTSAVEPREP() function. */
448	typedef FNSSMINTSAVEPREP *PFNSSMINTSAVEPREP;
449
450	/**
451	* Execute state save operation.
452	*
453	* @returns VBox status code.
454	* @param pVM VM Handle.
455	* @param pSSM SSM operation handle.
456	*/
457	typedef DECLCALLBACK(int) FNSSMINTSAVEEXEC(PVM pVM, PSSMHANDLE pSSM);
458	/** Pointer to a FNSSMINTSAVEEXEC() function. */
459	typedef FNSSMINTSAVEEXEC *PFNSSMINTSAVEEXEC;
460
461	/**
462	* Done state save operation.
463	*
464	* @returns VBox status code.
465	* @param pVM VM Handle.
466	* @param pSSM SSM operation handle.
467	*/
468	typedef DECLCALLBACK(int) FNSSMINTSAVEDONE(PVM pVM, PSSMHANDLE pSSM);
469	/** Pointer to a FNSSMINTSAVEDONE() function. */
470	typedef FNSSMINTSAVEDONE *PFNSSMINTSAVEDONE;
471
472	/**
473	* Prepare state load operation.
474	*
475	* @returns VBox status code.
476	* @param pVM VM Handle.
477	* @param pSSM SSM operation handle.
478	*/
479	typedef DECLCALLBACK(int) FNSSMINTLOADPREP(PVM pVM, PSSMHANDLE pSSM);
480	/** Pointer to a FNSSMINTLOADPREP() function. */
481	typedef FNSSMINTLOADPREP *PFNSSMINTLOADPREP;
482
483	/**
484	* Execute state load operation.
485	*
486	* @returns VBox status code.
487	* @param pVM VM Handle.
488	* @param pSSM SSM operation handle.
489	* @param uVersion Data layout version.
490	* @param uPass The pass. This is always SSM_PASS_FINAL for units
491	* that doesn't specify a pfnSaveLive callback.
492	*/
493	typedef DECLCALLBACK(int) FNSSMINTLOADEXEC(PVM pVM, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass);
494	/** Pointer to a FNSSMINTLOADEXEC() function. */
495	typedef FNSSMINTLOADEXEC *PFNSSMINTLOADEXEC;
496
497	/**
498	* Done state load operation.
499	*
500	* @returns VBox load code.
501	* @param pVM VM Handle.
502	* @param pSSM SSM operation handle.
503	*/
504	typedef DECLCALLBACK(int) FNSSMINTLOADDONE(PVM pVM, PSSMHANDLE pSSM);
505	/** Pointer to a FNSSMINTLOADDONE() function. */
506	typedef FNSSMINTLOADDONE *PFNSSMINTLOADDONE;
507
508	/** @} */
509
510
511	/** The External callback variants.
512	* @{
513	*/
514
515	/**
516	* Prepare state live save operation.
517	*
518	* @returns VBox status code.
519	* @param pSSM SSM operation handle.
520	* @param pvUser User argument.
521	* @thread Any.
522	*/
523	typedef DECLCALLBACK(int) FNSSMEXTLIVEPREP(PSSMHANDLE pSSM, void *pvUser);
524	/** Pointer to a FNSSMEXTLIVEPREP() function. */
525	typedef FNSSMEXTLIVEPREP *PFNSSMEXTLIVEPREP;
526
527	/**
528	* Execute state live save operation.
529	*
530	* This will be called repeatedly until all units vote that the live phase has
531	* been concluded.
532	*
533	* @returns VBox status code.
534	* @param pSSM SSM operation handle.
535	* @param pvUser User argument.
536	* @param uPass The data pass.
537	* @thread Any.
538	*/
539	typedef DECLCALLBACK(int) FNSSMEXTLIVEEXEC(PSSMHANDLE pSSM, void *pvUser, uint32_t uPass);
540	/** Pointer to a FNSSMEXTLIVEEXEC() function. */
541	typedef FNSSMEXTLIVEEXEC *PFNSSMEXTLIVEEXEC;
542
543	/**
544	* Vote on whether the live part of the saving has been concluded.
545	*
546	* The vote stops once a unit has vetoed the decision, so don't rely upon this
547	* being called every time.
548	*
549	* @returns VBox status code.
550	* @retval VINF_SUCCESS if done.
551	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
552	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
553	* done and there is not need calling it again before the final pass.
554	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
555	*
556	* @param pSSM SSM operation handle.
557	* @param pvUser User argument.
558	* @thread Any.
559	*/
560	typedef DECLCALLBACK(int) FNSSMEXTLIVEVOTE(PSSMHANDLE pSSM, void *pvUser);
561	/** Pointer to a FNSSMEXTLIVEVOTE() function. */
562	typedef FNSSMEXTLIVEVOTE *PFNSSMEXTLIVEVOTE;
563
564	/**
565	* Prepare state save operation.
566	*
567	* @returns VBox status code.
568	* @param pSSM SSM operation handle.
569	* @param pvUser User argument.
570	*/
571	typedef DECLCALLBACK(int) FNSSMEXTSAVEPREP(PSSMHANDLE pSSM, void *pvUser);
572	/** Pointer to a FNSSMEXTSAVEPREP() function. */
573	typedef FNSSMEXTSAVEPREP *PFNSSMEXTSAVEPREP;
574
575	/**
576	* Execute state save operation.
577	*
578	* @param pSSM SSM operation handle.
579	* @param pvUser User argument.
580	* @author The lack of return code is for legacy reasons.
581	*/
582	typedef DECLCALLBACK(void) FNSSMEXTSAVEEXEC(PSSMHANDLE pSSM, void *pvUser);
583	/** Pointer to a FNSSMEXTSAVEEXEC() function. */
584	typedef FNSSMEXTSAVEEXEC *PFNSSMEXTSAVEEXEC;
585
586	/**
587	* Done state save operation.
588	*
589	* @returns VBox status code.
590	* @param pSSM SSM operation handle.
591	* @param pvUser User argument.
592	*/
593	typedef DECLCALLBACK(int) FNSSMEXTSAVEDONE(PSSMHANDLE pSSM, void *pvUser);
594	/** Pointer to a FNSSMEXTSAVEDONE() function. */
595	typedef FNSSMEXTSAVEDONE *PFNSSMEXTSAVEDONE;
596
597	/**
598	* Prepare state load operation.
599	*
600	* @returns VBox status code.
601	* @param pSSM SSM operation handle.
602	* @param pvUser User argument.
603	*/
604	typedef DECLCALLBACK(int) FNSSMEXTLOADPREP(PSSMHANDLE pSSM, void *pvUser);
605	/** Pointer to a FNSSMEXTLOADPREP() function. */
606	typedef FNSSMEXTLOADPREP *PFNSSMEXTLOADPREP;
607
608	/**
609	* Execute state load operation.
610	*
611	* @returns VBox status code.
612	* @param pSSM SSM operation handle.
613	* @param pvUser User argument.
614	* @param uVersion Data layout version.
615	* @param uPass The pass. This is always SSM_PASS_FINAL for units
616	* that doesn't specify a pfnSaveLive callback.
617	* @remark The odd return value is for legacy reasons.
618	*/
619	typedef DECLCALLBACK(int) FNSSMEXTLOADEXEC(PSSMHANDLE pSSM, void *pvUser, uint32_t uVersion, uint32_t uPass);
620	/** Pointer to a FNSSMEXTLOADEXEC() function. */
621	typedef FNSSMEXTLOADEXEC *PFNSSMEXTLOADEXEC;
622
623	/**
624	* Done state load operation.
625	*
626	* @returns VBox load code.
627	* @param pSSM SSM operation handle.
628	* @param pvUser User argument.
629	*/
630	typedef DECLCALLBACK(int) FNSSMEXTLOADDONE(PSSMHANDLE pSSM, void *pvUser);
631	/** Pointer to a FNSSMEXTLOADDONE() function. */
632	typedef FNSSMEXTLOADDONE *PFNSSMEXTLOADDONE;
633
634	/** @} */
635
636
637	/**
638	* SSM stream method table.
639	*
640	* This is used for live migration as well as internally in SSM.
641	*/
642	typedef struct SSMSTRMOPS
643	{
644	/** Struct magic + version (SSMSTRMOPS_VERSION). */
645	uint32_t u32Version;
646
647	/**
648	* Write bytes to the stream.
649	*
650	* @returns VBox status code.
651	* @param pvUser The user argument.
652	* @param offStream The stream offset we're (supposed to be) at.
653	* @param pvBuf Pointer to the data.
654	* @param cbToWrite The number of bytes to write.
655	*/
656	DECLCALLBACKMEMBER(int, pfnWrite)(void pvUser, uint64_t offStream, const void pvBuf, size_t cbToWrite);
657
658	/**
659	* Read bytes to the stream.
660	*
661	* @returns VBox status code.
662	* @param pvUser The user argument.
663	* @param offStream The stream offset we're (supposed to be) at.
664	* @param pvBuf Where to return the bytes.
665	* @param cbToRead The number of bytes to read.
666	* @param pcbRead Where to return the number of bytes actually
667	* read. This may differ from cbToRead when the
668	* end of the stream is encountered.
669	*/
670	DECLCALLBACKMEMBER(int, pfnRead)(void pvUser, uint64_t offStream, void pvBuf, size_t cbToRead, size_t *pcbRead);
671
672	/**
673	* Seeks in the stream.
674	*
675	* @returns VBox status code.
676	* @retval VERR_NOT_SUPPORTED if the stream doesn't support this action.
677	*
678	* @param pvUser The user argument.
679	* @param offSeek The seek offset.
680	* @param uMethod RTFILE_SEEK_BEGIN, RTFILE_SEEK_END or
681	* RTFILE_SEEK_CURRENT.
682	* @param poffActual Where to store the new file position. Optional.
683	*/
684	DECLCALLBACKMEMBER(int, pfnSeek)(void pvUser, int64_t offSeek, unsigned uMethod, uint64_t poffActual);
685
686	/**
687	* Get the current stream position.
688	*
689	* @returns The correct stream position.
690	* @param pvUser The user argument.
691	*/
692	DECLCALLBACKMEMBER(uint64_t, pfnTell)(void *pvUser);
693
694	/**
695	* Get the size/length of the stream.
696	*
697	* @returns VBox status code.
698	* @retval VERR_NOT_SUPPORTED if the stream doesn't support this action.
699	*
700	* @param pvUser The user argument.
701	* @param pcb Where to return the size/length.
702	*/
703	DECLCALLBACKMEMBER(int, pfnSize)(void pvUser, uint64_t pcb);
704
705	/**
706	* Close the stream.
707	*
708	* @returns VBox status code.
709	* @param pvUser The user argument.
710	*/
711	DECLCALLBACKMEMBER(int, pfnClose)(void *pvUser);
712
713	/** Struct magic + version (SSMSTRMOPS_VERSION). */
714	uint32_t u32EndVersion;
715	} SSMSTRMOPS;
716	/** Struct magic + version (SSMSTRMOPS_VERSION). */
717	#define SSMSTRMOPS_VERSION UINT32_C(0x55aa0001)
718
719
720	VMMR3_INT_DECL(void) SSMR3Term(PVM pVM);
721	VMMR3DECL(int) SSMR3RegisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char pszName, uint32_t uInstance, uint32_t uVersion, size_t cbGuess, const char pszBefore,
722	PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
723	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
724	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone);
725	VMMR3DECL(int) SSMR3RegisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName, uint32_t uInstance, uint32_t uVersion, size_t cbGuess,
726	PFNSSMDRVLIVEPREP pfnLivePrep, PFNSSMDRVLIVEEXEC pfnLiveExec, PFNSSMDRVLIVEVOTE pfnLiveVote,
727	PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
728	PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone);
729	VMMR3DECL(int) SSMR3RegisterInternal(PVM pVM, const char *pszName, uint32_t uInstance, uint32_t uVersion, size_t cbGuess,
730	PFNSSMINTLIVEPREP pfnLivePrep, PFNSSMINTLIVEEXEC pfnLiveExec, PFNSSMINTLIVEVOTE pfnLiveVote,
731	PFNSSMINTSAVEPREP pfnSavePrep, PFNSSMINTSAVEEXEC pfnSaveExec, PFNSSMINTSAVEDONE pfnSaveDone,
732	PFNSSMINTLOADPREP pfnLoadPrep, PFNSSMINTLOADEXEC pfnLoadExec, PFNSSMINTLOADDONE pfnLoadDone);
733	VMMR3DECL(int) SSMR3RegisterExternal(PVM pVM, const char *pszName, uint32_t uInstance, uint32_t uVersion, size_t cbGuess,
734	PFNSSMEXTLIVEPREP pfnLivePrep, PFNSSMEXTLIVEEXEC pfnLiveExec, PFNSSMEXTLIVEVOTE pfnLiveVote,
735	PFNSSMEXTSAVEPREP pfnSavePrep, PFNSSMEXTSAVEEXEC pfnSaveExec, PFNSSMEXTSAVEDONE pfnSaveDone,
736	PFNSSMEXTLOADPREP pfnLoadPrep, PFNSSMEXTLOADEXEC pfnLoadExec, PFNSSMEXTLOADDONE pfnLoadDone, void *pvUser);
737	VMMR3_INT_DECL(int) SSMR3DeregisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char *pszName, uint32_t uInstance);
738	VMMR3_INT_DECL(int) SSMR3DeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName, uint32_t uInstance);
739	VMMR3DECL(int) SSMR3DeregisterInternal(PVM pVM, const char *pszName);
740	VMMR3DECL(int) SSMR3DeregisterExternal(PVM pVM, const char *pszName);
741	VMMR3DECL(int) SSMR3Save(PVM pVM, const char pszFilename, SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void pvUser);
742	VMMR3_INT_DECL(int) SSMR3LiveSave(PVM pVM, const char pszFilename, PCSSMSTRMOPS pStreamOps, void pvStreamOps,
743	SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void pvProgressUser, PSSMHANDLE ppSSM);
744	VMMR3_INT_DECL(int) SSMR3LiveDoStep1(PSSMHANDLE pSSM);
745	VMMR3_INT_DECL(int) SSMR3LiveDoStep2(PSSMHANDLE pSSM);
746	VMMR3_INT_DECL(int) SSMR3LiveDone(PSSMHANDLE pSSM);
747	VMMR3DECL(int) SSMR3Load(PVM pVM, const char pszFilename, PCSSMSTRMOPS pStreamOps, void pvStreamOpsUser,
748	SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void *pvProgressUser);
749	VMMR3DECL(int) SSMR3ValidateFile(const char *pszFilename, bool fChecksumIt);
750	VMMR3DECL(int) SSMR3Open(const char pszFilename, unsigned fFlags, PSSMHANDLE ppSSM);
751	VMMR3DECL(int) SSMR3Close(PSSMHANDLE pSSM);
752	VMMR3DECL(int) SSMR3Seek(PSSMHANDLE pSSM, const char pszUnit, uint32_t iInstance, uint32_t piVersion);
753	VMMR3DECL(int) SSMR3HandleGetStatus(PSSMHANDLE pSSM);
754	VMMR3DECL(int) SSMR3HandleSetStatus(PSSMHANDLE pSSM, int iStatus);
755	VMMR3DECL(SSMAFTER) SSMR3HandleGetAfter(PSSMHANDLE pSSM);
756	VMMR3DECL(bool) SSMR3HandleIsLiveSave(PSSMHANDLE pSSM);
757	VMMR3_INT_DECL(int) SSMR3SetGCPtrSize(PSSMHANDLE pSSM, unsigned cbGCPtr);
758	VMMR3DECL(int) SSMR3Cancel(PVM pVM);
759
760
761	/** Save operations.
762	* @{
763	*/
764	VMMR3DECL(int) SSMR3PutStruct(PSSMHANDLE pSSM, const void *pvStruct, PCSSMFIELD paFields);
765	VMMR3DECL(int) SSMR3PutBool(PSSMHANDLE pSSM, bool fBool);
766	VMMR3DECL(int) SSMR3PutU8(PSSMHANDLE pSSM, uint8_t u8);
767	VMMR3DECL(int) SSMR3PutS8(PSSMHANDLE pSSM, int8_t i8);
768	VMMR3DECL(int) SSMR3PutU16(PSSMHANDLE pSSM, uint16_t u16);
769	VMMR3DECL(int) SSMR3PutS16(PSSMHANDLE pSSM, int16_t i16);
770	VMMR3DECL(int) SSMR3PutU32(PSSMHANDLE pSSM, uint32_t u32);
771	VMMR3DECL(int) SSMR3PutS32(PSSMHANDLE pSSM, int32_t i32);
772	VMMR3DECL(int) SSMR3PutU64(PSSMHANDLE pSSM, uint64_t u64);
773	VMMR3DECL(int) SSMR3PutS64(PSSMHANDLE pSSM, int64_t i64);
774	VMMR3DECL(int) SSMR3PutU128(PSSMHANDLE pSSM, uint128_t u128);
775	VMMR3DECL(int) SSMR3PutS128(PSSMHANDLE pSSM, int128_t i128);
776	VMMR3DECL(int) SSMR3PutUInt(PSSMHANDLE pSSM, RTUINT u);
777	VMMR3DECL(int) SSMR3PutSInt(PSSMHANDLE pSSM, RTINT i);
778	VMMR3DECL(int) SSMR3PutGCUInt(PSSMHANDLE pSSM, RTGCUINT u);
779	VMMR3DECL(int) SSMR3PutGCUIntReg(PSSMHANDLE pSSM, RTGCUINTREG u);
780	VMMR3DECL(int) SSMR3PutGCPhys32(PSSMHANDLE pSSM, RTGCPHYS32 GCPhys);
781	VMMR3DECL(int) SSMR3PutGCPhys64(PSSMHANDLE pSSM, RTGCPHYS64 GCPhys);
782	VMMR3DECL(int) SSMR3PutGCPhys(PSSMHANDLE pSSM, RTGCPHYS GCPhys);
783	VMMR3DECL(int) SSMR3PutGCPtr(PSSMHANDLE pSSM, RTGCPTR GCPtr);
784	VMMR3DECL(int) SSMR3PutGCUIntPtr(PSSMHANDLE pSSM, RTGCUINTPTR GCPtr);
785	VMMR3DECL(int) SSMR3PutRCPtr(PSSMHANDLE pSSM, RTRCPTR RCPtr);
786	VMMR3DECL(int) SSMR3PutIOPort(PSSMHANDLE pSSM, RTIOPORT IOPort);
787	VMMR3DECL(int) SSMR3PutSel(PSSMHANDLE pSSM, RTSEL Sel);
788	VMMR3DECL(int) SSMR3PutMem(PSSMHANDLE pSSM, const void *pv, size_t cb);
789	VMMR3DECL(int) SSMR3PutStrZ(PSSMHANDLE pSSM, const char *psz);
790	/** @} */
791
792
793
794	/** Load operations.
795	* @{
796	*/
797	VMMR3DECL(int) SSMR3GetStruct(PSSMHANDLE pSSM, void *pvStruct, PCSSMFIELD paFields);
798	VMMR3DECL(int) SSMR3GetBool(PSSMHANDLE pSSM, bool *pfBool);
799	VMMR3DECL(int) SSMR3GetU8(PSSMHANDLE pSSM, uint8_t *pu8);
800	VMMR3DECL(int) SSMR3GetS8(PSSMHANDLE pSSM, int8_t *pi8);
801	VMMR3DECL(int) SSMR3GetU16(PSSMHANDLE pSSM, uint16_t *pu16);
802	VMMR3DECL(int) SSMR3GetS16(PSSMHANDLE pSSM, int16_t *pi16);
803	VMMR3DECL(int) SSMR3GetU32(PSSMHANDLE pSSM, uint32_t *pu32);
804	VMMR3DECL(int) SSMR3GetS32(PSSMHANDLE pSSM, int32_t *pi32);
805	VMMR3DECL(int) SSMR3GetU64(PSSMHANDLE pSSM, uint64_t *pu64);
806	VMMR3DECL(int) SSMR3GetS64(PSSMHANDLE pSSM, int64_t *pi64);
807	VMMR3DECL(int) SSMR3GetU128(PSSMHANDLE pSSM, uint128_t *pu128);
808	VMMR3DECL(int) SSMR3GetS128(PSSMHANDLE pSSM, int128_t *pi128);
809	VMMR3DECL(int) SSMR3GetUInt(PSSMHANDLE pSSM, PRTUINT pu);
810	VMMR3DECL(int) SSMR3GetSInt(PSSMHANDLE pSSM, PRTINT pi);
811	VMMR3DECL(int) SSMR3GetGCUInt(PSSMHANDLE pSSM, PRTGCUINT pu);
812	VMMR3DECL(int) SSMR3GetGCUIntReg(PSSMHANDLE pSSM, PRTGCUINTREG pu);
813	VMMR3DECL(int) SSMR3GetGCPhys32(PSSMHANDLE pSSM, PRTGCPHYS32 pGCPhys);
814	VMMR3DECL(int) SSMR3GetGCPhys64(PSSMHANDLE pSSM, PRTGCPHYS64 pGCPhys);
815	VMMR3DECL(int) SSMR3GetGCPhys(PSSMHANDLE pSSM, PRTGCPHYS pGCPhys);
816	VMMR3DECL(int) SSMR3GetGCPtr(PSSMHANDLE pSSM, PRTGCPTR pGCPtr);
817	VMMR3DECL(int) SSMR3GetGCUIntPtr(PSSMHANDLE pSSM, PRTGCUINTPTR pGCPtr);
818	VMMR3DECL(int) SSMR3GetRCPtr(PSSMHANDLE pSSM, PRTRCPTR pRCPtr);
819	VMMR3DECL(int) SSMR3GetIOPort(PSSMHANDLE pSSM, PRTIOPORT pIOPort);
820	VMMR3DECL(int) SSMR3GetSel(PSSMHANDLE pSSM, PRTSEL pSel);
821	VMMR3DECL(int) SSMR3GetMem(PSSMHANDLE pSSM, void *pv, size_t cb);
822	VMMR3DECL(int) SSMR3GetStrZ(PSSMHANDLE pSSM, char *psz, size_t cbMax);
823	VMMR3DECL(int) SSMR3GetStrZEx(PSSMHANDLE pSSM, char psz, size_t cbMax, size_t pcbStr);
824	VMMR3DECL(int) SSMR3GetTimer(PSSMHANDLE pSSM, PTMTIMER pTimer);
825	VMMR3DECL(int) SSMR3Skip(PSSMHANDLE pSSM, size_t cb);
826	VMMR3DECL(int) SSMR3SkipToEndOfUnit(PSSMHANDLE pSSM);
827
828	/** @} */
829
830	/** @} */
831	#endif /* IN_RING3 */
832
833
834	/** @} */
835
836	RT_C_DECLS_END
837
838	#endif
839

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/include/VBox/ssm.h@ 23746

Download in other formats: