ssm.h@ 32824

Last change on this file since 32824 was 31895, checked in by vboxsync, 14 years ago
FT updates
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 51.3 KB

Line
1	/** @file
2	* SSM - The Save State Manager. (VMM)
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 Oracle Corporation
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
26	#ifndef ___VBox_ssm_h
27	#define ___VBox_ssm_h
28
29	#include <VBox/cdefs.h>
30	#include <VBox/types.h>
31	#include <VBox/tm.h>
32	#include <VBox/vmapi.h>
33
34	RT_C_DECLS_BEGIN
35
36	/** @defgroup grp_ssm The Saved State Manager API
37	* @{
38	*/
39
40	/**
41	* Determine the major version of the SSM version. If the major SSM version of two snapshots is
42	* different, the snapshots are incompatible.
43	*/
44	#define SSM_VERSION_MAJOR(ver) ((ver) & 0xffff0000)
45
46	/**
47	* Determine the minor version of the SSM version. If the major SSM version of two snapshots is
48	* the same, the code must handle incompatibilies between minor version changes (e.g. use dummy
49	* values for non-existent fields).
50	*/
51	#define SSM_VERSION_MINOR(ver) ((ver) & 0x0000ffff)
52
53	/**
54	* Determine if the major version changed between two SSM versions.
55	*/
56	#define SSM_VERSION_MAJOR_CHANGED(ver1,ver2) (SSM_VERSION_MAJOR(ver1) != SSM_VERSION_MAJOR(ver2))
57
58	/** The special value for the final pass. */
59	#define SSM_PASS_FINAL UINT32_MAX
60
61
62	#ifdef IN_RING3
63	/** @defgroup grp_ssm_r3 The SSM Host Context Ring-3 API
64	* @{
65	*/
66
67
68	/**
69	* What to do after the save/load operation.
70	*/
71	typedef enum SSMAFTER
72	{
73	/** Invalid. */
74	SSMAFTER_INVALID = 0,
75	/** Will resume the loaded state. */
76	SSMAFTER_RESUME,
77	/** Will destroy the VM after saving. */
78	SSMAFTER_DESTROY,
79	/** Will continue execution after saving the VM. */
80	SSMAFTER_CONTINUE,
81	/** Will teleport the VM.
82	* The source VM will be destroyed (then one saving), the destination VM
83	* will continue execution. */
84	SSMAFTER_TELEPORT,
85	/** Will debug the saved state.
86	* This is used to drop some of the stricter consitentcy checks so it'll
87	* load fine in the debugger or animator. */
88	SSMAFTER_DEBUG_IT,
89	/** The file was opened using SSMR3Open() and we have no idea what the plan is. */
90	SSMAFTER_OPENED
91	} SSMAFTER;
92
93
94	/** Pointer to a structure field description. */
95	typedef struct SSMFIELD *PSSMFIELD;
96	/** Pointer to a const structure field description. */
97	typedef const struct SSMFIELD *PCSSMFIELD;
98
99	/**
100	* SSMFIELD Get/Put callback function.
101	*
102	* This is call for getting and putting the field it is associated with. It's
103	* up to the callback to work the saved state correctly.
104	*
105	* @returns VBox status code.
106	*
107	* @param pSSM The saved state handle.
108	* @param pField The field that is being processed.
109	* @param pvStruct Pointer to the structure.
110	* @param fFlags SSMSTRUCT_FLAGS_XXX.
111	* @param fGetOrPut True if getting, false if putting.
112	* @param pvUser The user argument specified to SSMR3GetStructEx or
113	* SSMR3PutStructEx.
114	*/
115	typedef DECLCALLBACK(int) FNSSMFIELDGETPUT(PSSMHANDLE pSSM, const struct SSMFIELD pField, void pvStruct,
116	uint32_t fFlags, bool fGetOrPut, void *pvUser);
117	/** Pointer to a SSMFIELD Get/Put callback. */
118	typedef FNSSMFIELDGETPUT *PFNSSMFIELDGETPUT;
119
120	/**
121	* SSM field transformers.
122	*
123	* These are stored in the SSMFIELD::pfnGetPutOrTransformer and must therefore
124	* have values outside the valid pointer range.
125	*/
126	typedef enum SSMFIELDTRANS
127	{
128	/** Invalid. */
129	SSMFIELDTRANS_INVALID = 0,
130	/** No transformation. */
131	SSMFIELDTRANS_NO_TRANSFORMATION,
132	/** Guest context (GC) physical address. */
133	SSMFIELDTRANS_GCPHYS,
134	/** Guest context (GC) virtual address. */
135	SSMFIELDTRANS_GCPTR,
136	/** Raw-mode context (RC) virtual address. */
137	SSMFIELDTRANS_RCPTR,
138	/** Array of raw-mode context (RC) virtual addresses. */
139	SSMFIELDTRANS_RCPTR_ARRAY,
140	/** Host context (HC) virtual address used as a NULL indicator. See
141	* SSMFIELD_ENTRY_HCPTR_NI. */
142	SSMFIELDTRANS_HCPTR_NI,
143	/** Array of SSMFIELDTRANS_HCPTR_NI. */
144	SSMFIELDTRANS_HCPTR_NI_ARRAY,
145	/** Host context (HC) virtual address used to hold a unsigned 32-bit value. */
146	SSMFIELDTRANS_HCPTR_HACK_U32,
147
148	/** Ignorable field. See SSMFIELD_ENTRY_IGNORE. */
149	SSMFIELDTRANS_IGNORE,
150	/** Ignorable guest context (GC) physical address. */
151	SSMFIELDTRANS_IGN_GCPHYS,
152	/** Ignorable guest context (GC) virtual address. */
153	SSMFIELDTRANS_IGN_GCPTR,
154	/** Ignorable raw-mode context (RC) virtual address. */
155	SSMFIELDTRANS_IGN_RCPTR,
156	/** Ignorable host context (HC) virtual address. */
157	SSMFIELDTRANS_IGN_HCPTR,
158
159	/** Old field.
160	* Save as zeros and skip on restore (nowhere to restore it any longer). */
161	SSMFIELDTRANS_OLD,
162	/** Old guest context (GC) physical address. */
163	SSMFIELDTRANS_OLD_GCPHYS,
164	/** Old guest context (GC) virtual address. */
165	SSMFIELDTRANS_OLD_GCPTR,
166	/** Old raw-mode context (RC) virtual address. */
167	SSMFIELDTRANS_OLD_RCPTR,
168	/** Old host context (HC) virtual address. */
169	SSMFIELDTRANS_OLD_HCPTR,
170	/** Old host context specific padding.
171	* The lower word is the size of 32-bit hosts, the upper for 64-bit hosts. */
172	SSMFIELDTRANS_OLD_PAD_HC,
173	/** Old padding specific to the 32-bit Microsoft C Compiler. */
174	SSMFIELDTRANS_OLD_PAD_MSC32,
175
176	/** Padding that differs between 32-bit and 64-bit hosts.
177	* The first byte of SSMFIELD::cb contains the size for 32-bit hosts.
178	* The second byte of SSMFIELD::cb contains the size for 64-bit hosts.
179	* The upper word of SSMFIELD::cb contains the actual field size.
180	*/
181	SSMFIELDTRANS_PAD_HC,
182	/** Padding for 32-bit hosts only.
183	* SSMFIELD::cb has the same format as for SSMFIELDTRANS_PAD_HC. */
184	SSMFIELDTRANS_PAD_HC32,
185	/** Padding for 64-bit hosts only.
186	* SSMFIELD::cb has the same format as for SSMFIELDTRANS_PAD_HC. */
187	SSMFIELDTRANS_PAD_HC64,
188	/** Automatic compiler padding that may differ between 32-bit and
189	* 64-bit hosts. SSMFIELD::cb has the same format as for
190	* SSMFIELDTRANS_PAD_HC. */
191	SSMFIELDTRANS_PAD_HC_AUTO,
192	/** Automatic compiler padding specific to the 32-bit Microsoft C
193	* compiler.
194	* SSMFIELD::cb has the same format as for SSMFIELDTRANS_PAD_HC. */
195	SSMFIELDTRANS_PAD_MSC32_AUTO
196	} SSMFIELDTRANS;
197
198	/** Tests if it's a padding field with the special SSMFIELD::cb format.
199	* @returns true / false.
200	* @param pfn The SSMFIELD::pfnGetPutOrTransformer value.
201	*/
202	#define SSMFIELDTRANS_IS_PADDING(pfn) \
203	( (uintptr_t)(pfn) >= SSMFIELDTRANS_PAD_HC && (uintptr_t)(pfn) <= SSMFIELDTRANS_PAD_MSC32_AUTO )
204
205	/** Tests if it's an entry for an old field.
206	*
207	* @returns true / false.
208	* @param pfn The SSMFIELD::pfnGetPutOrTransformer value.
209	*/
210	#define SSMFIELDTRANS_IS_OLD(pfn) \
211	( (uintptr_t)(pfn) >= SSMFIELDTRANS_OLD && (uintptr_t)(pfn) <= SSMFIELDTRANS_OLD_PAD_MSC32 )
212
213	/**
214	* A structure field description.
215	*/
216	typedef struct SSMFIELD
217	{
218	/** Getter and putter callback or transformer index. */
219	PFNSSMFIELDGETPUT pfnGetPutOrTransformer;
220	/** Field offset into the structure. */
221	uint32_t off;
222	/** The size of the field. */
223	uint32_t cb;
224	/** Field name. */
225	const char *pszName;
226	} SSMFIELD;
227
228	/** Emit a SSMFIELD array entry.
229	* @internal */
230	#define SSMFIELD_ENTRY_INT(Name, off, cb, enmTransformer) \
231	{ (PFNSSMFIELDGETPUT)(uintptr_t)(enmTransformer), (off), (cb), Name }
232	/** Emit a SSMFIELD array entry.
233	* @internal */
234	#define SSMFIELD_ENTRY_TF_INT(Type, Field, enmTransformer) \
235	SSMFIELD_ENTRY_INT(#Type "::" #Field, RT_OFFSETOF(Type, Field), RT_SIZEOFMEMB(Type, Field), enmTransformer)
236	/** Emit a SSMFIELD array entry for an old field.
237	* @internal */
238	#define SSMFIELD_ENTRY_OLD_INT(Field, cb, enmTransformer) \
239	SSMFIELD_ENTRY_INT("old::" #Field, UINT32_MAX / 2, (cb), enmTransformer)
240	/** Emit a SSMFIELD array entry for an alignment padding.
241	* @internal */
242	#define SSMFIELD_ENTRY_PAD_INT(Type, Field, cb32, cb64, enmTransformer) \
243	SSMFIELD_ENTRY_INT(#Type "::" #Field, RT_OFFSETOF(Type, Field), \
244	(RT_SIZEOFMEMB(Type, Field) << 16) \| (cb32) \| ((cb64) << 8), enmTransformer)
245	/** Emit a SSMFIELD array entry for an alignment padding.
246	* @internal */
247	#define SSMFIELD_ENTRY_PAD_OTHER_INT(Type, Field, cb32, cb64, enmTransformer) \
248	SSMFIELD_ENTRY_INT(#Type "::" #Field, UINT32_MAX / 2, 0 \| (cb32) \| ((cb64) << 8), enmTransformer)
249
250	/** Emit a SSMFIELD array entry. */
251	#define SSMFIELD_ENTRY(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_NO_TRANSFORMATION)
252	/** Emit a SSMFIELD array entry for a custom made field. This is intended
253	* for working around bitfields in old structures. */
254	#define SSMFIELD_ENTRY_CUSTOM(Field, off, cb) SSMFIELD_ENTRY_INT("custom::" #Field, off, cb, SSMFIELDTRANS_NO_TRANSFORMATION)
255	/** Emit a SSMFIELD array entry for a RTGCPHYS type. */
256	#define SSMFIELD_ENTRY_GCPHYS(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_GCPHYS)
257	/** Emit a SSMFIELD array entry for a RTGCPTR type. */
258	#define SSMFIELD_ENTRY_GCPTR(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_GCPTR)
259	/** Emit a SSMFIELD array entry for a raw-mode context pointer. */
260	#define SSMFIELD_ENTRY_RCPTR(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_RCPTR)
261	/** Emit a SSMFIELD array entry for a raw-mode context pointer. */
262	#define SSMFIELD_ENTRY_RCPTR_ARRAY(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_RCPTR_ARRAY)
263	/** Emit a SSMFIELD array entry for a ring-0 or ring-3 pointer type that is only
264	* of interest as a NULL indicator.
265	*
266	* This is always restored as a 0 (NULL) or 1 value. When
267	* SSMSTRUCT_FLAGS_DONT_IGNORE is set, the pointer will be saved in its
268	* entirety, when clear it will be saved as a boolean. */
269	#define SSMFIELD_ENTRY_HCPTR_NI(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_HCPTR_NI)
270	/** Same as SSMFIELD_ENTRY_HCPTR_NI, except it's an array of the buggers. */
271	#define SSMFIELD_ENTRY_HCPTR_NI_ARRAY(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_HCPTR_NI_ARRAY)
272	/** Emit a SSMFIELD array entry for a ring-0 or ring-3 pointer type that has
273	* been hacked such that it will never exceed 32-bit. No sign extenending. */
274	#define SSMFIELD_ENTRY_HCPTR_HACK_U32(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_HCPTR_HACK_U32)
275
276	/** Emit a SSMFIELD array entry for a field that can be ignored.
277	* It is stored as zeros if SSMSTRUCT_FLAGS_DONT_IGNORE is specified to
278	* SSMR3PutStructEx. The member is never touched upon restore. */
279	#define SSMFIELD_ENTRY_IGNORE(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_IGNORE)
280	/** Emit a SSMFIELD array entry for an ignorable RTGCPHYS type. */
281	#define SSMFIELD_ENTRY_IGN_GCPHYS(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_IGN_GCPHYS)
282	/** Emit a SSMFIELD array entry for an ignorable RTGCPHYS type. */
283	#define SSMFIELD_ENTRY_IGN_GCPTR(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_IGN_GCPTR)
284	/** Emit a SSMFIELD array entry for an ignorable raw-mode context pointer. */
285	#define SSMFIELD_ENTRY_IGN_RCPTR(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_IGN_RCPTR)
286	/** Emit a SSMFIELD array entry for an ignorable ring-3 or/and ring-0 pointer. */
287	#define SSMFIELD_ENTRY_IGN_HCPTR(Type, Field) SSMFIELD_ENTRY_TF_INT(Type, Field, SSMFIELDTRANS_IGN_HCPTR)
288
289	/** Emit a SSMFIELD array entry for an old field that should be ignored now.
290	* It is stored as zeros and skipped on load. */
291	#define SSMFIELD_ENTRY_OLD(Field, cb) SSMFIELD_ENTRY_OLD_INT(Field, cb, SSMFIELDTRANS_OLD)
292	/** Same as SSMFIELD_ENTRY_IGN_GCPHYS, except there is no structure field. */
293	#define SSMFIELD_ENTRY_OLD_GCPHYS(Field) SSMFIELD_ENTRY_OLD_INT(Field, sizeof(RTGCPHYS), SSMFIELDTRANS_OLD_GCPHYS)
294	/** Same as SSMFIELD_ENTRY_IGN_GCPTR, except there is no structure field. */
295	#define SSMFIELD_ENTRY_OLD_GCPTR(Field) SSMFIELD_ENTRY_OLD_INT(Field, sizeof(RTGCPTR), SSMFIELDTRANS_OLD_GCPTR)
296	/** Same as SSMFIELD_ENTRY_IGN_RCPTR, except there is no structure field. */
297	#define SSMFIELD_ENTRY_OLD_RCPTR(Field) SSMFIELD_ENTRY_OLD_INT(Field, sizeof(RTRCPTR), SSMFIELDTRANS_OLD_RCPTR)
298	/** Same as SSMFIELD_ENTRY_IGN_HCPTR, except there is no structure field. */
299	#define SSMFIELD_ENTRY_OLD_HCPTR(Field) SSMFIELD_ENTRY_OLD_INT(Field, sizeof(RTHCPTR), SSMFIELDTRANS_OLD_HCPTR)
300	/** Same as SSMFIELD_ENTRY_PAD_HC, except there is no structure field. */
301	#define SSMFIELD_ENTRY_OLD_PAD_HC(Field, cb32, cb64) \
302	SSMFIELD_ENTRY_OLD_INT(Field, RT_MAKE_U32((cb32), (cb64)), SSMFIELDTRANS_OLD_PAD_HC)
303	/** Same as SSMFIELD_ENTRY_PAD_HC64, except there is no structure field. */
304	#define SSMFIELD_ENTRY_OLD_PAD_HC64(Field, cb) SSMFIELD_ENTRY_OLD_PAD_HC(Field, 0, cb)
305	/** Same as SSMFIELD_ENTRY_PAD_HC32, except there is no structure field. */
306	#define SSMFIELD_ENTRY_OLD_PAD_HC32(Field, cb) SSMFIELD_ENTRY_OLD_PAD_HC(Field, cb, 0)
307	/** Same as SSMFIELD_ENTRY_PAD_HC, except there is no structure field. */
308	#define SSMFIELD_ENTRY_OLD_PAD_MSC32(Field, cb) SSMFIELD_ENTRY_OLD_INT(Field, cb, SSMFIELDTRANS_OLD_PAD_MSC32)
309
310	/** Emit a SSMFIELD array entry for a padding that differs in size between
311	* 64-bit and 32-bit hosts. */
312	#define SSMFIELD_ENTRY_PAD_HC(Type, Field, cb32, cb64) SSMFIELD_ENTRY_PAD_INT( Type, Field, cb32, cb64, SSMFIELDTRANS_PAD_HC)
313	/** Emit a SSMFIELD array entry for a padding that is exclusive to 64-bit hosts. */
314	#if HC_ARCH_BITS == 64
315	# define SSMFIELD_ENTRY_PAD_HC64(Type, Field, cb) SSMFIELD_ENTRY_PAD_INT( Type, Field, 0, cb, SSMFIELDTRANS_PAD_HC64)
316	#else
317	# define SSMFIELD_ENTRY_PAD_HC64(Type, Field, cb) SSMFIELD_ENTRY_PAD_OTHER_INT(Type, Field, 0, cb, SSMFIELDTRANS_PAD_HC64)
318	#endif
319	/** Emit a SSMFIELD array entry for a 32-bit padding for on 64-bits hosts. */
320	#if HC_ARCH_BITS == 32
321	# define SSMFIELD_ENTRY_PAD_HC32(Type, Field, cb) SSMFIELD_ENTRY_PAD_INT( Type, Field, cb, 0, SSMFIELDTRANS_PAD_HC32)
322	#else
323	# define SSMFIELD_ENTRY_PAD_HC32(Type, Field, cb) SSMFIELD_ENTRY_PAD_OTHER_INT(Type, Field, cb, 0, SSMFIELDTRANS_PAD_HC32)
324	#endif
325	/** Emit a SSMFIELD array entry for an automatic compiler padding that may
326	* differ in size between 64-bit and 32-bit hosts. */
327	#if HC_ARCH_BITS == 64
328	# define SSMFIELD_ENTRY_PAD_HC_AUTO(cb32, cb64) \
329	{ \
330	(PFNSSMFIELDGETPUT)(uintptr_t)(SSMFIELDTRANS_PAD_HC_AUTO), \
331	UINT32_MAX / 2, (cb64 << 16) \| (cb32) \| ((cb64) << 8), "<compiler-padding>" \
332	}
333	#else
334	# define SSMFIELD_ENTRY_PAD_HC_AUTO(cb32, cb64) \
335	{ \
336	(PFNSSMFIELDGETPUT)(uintptr_t)(SSMFIELDTRANS_PAD_HC_AUTO), \
337	UINT32_MAX / 2, (cb32 << 16) \| (cb32) \| ((cb64) << 8), "<compiler-padding>" \
338	}
339	#endif
340	/** Emit a SSMFIELD array entry for an automatic compiler padding that is unique
341	* to the 32-bit microsoft compiler. This is usually used together with
342	* SSMFIELD_ENTRY_PAD_HC. /
343	#if HC_ARCH_BITS == 32 && defined(_MSC_VER)
344	# define SSMFIELD_ENTRY_PAD_MSC32_AUTO(cb) \
345	{ \
346	(PFNSSMFIELDGETPUT)(uintptr_t)(SSMFIELDTRANS_PAD_MSC32_AUTO), \
347	UINT32_MAX / 2, ((cb) << 16) \| (cb), "<msc32-padding>" \
348	}
349	#else
350	# define SSMFIELD_ENTRY_PAD_MSC32_AUTO(cb) \
351	{ \
352	(PFNSSMFIELDGETPUT)(uintptr_t)(SSMFIELDTRANS_PAD_MSC32_AUTO), \
353	UINT32_MAX / 2, (cb), "<msc32-padding>" \
354	}
355	#endif
356
357	/** Emit a SSMFIELD array entry for a field with a custom callback. */
358	#define SSMFIELD_ENTRY_CALLBACK(Type, Field, pfnGetPut) \
359	{ (pfnGetPut), RT_OFFSETOF(Type, Field), RT_SIZEOFMEMB(Type, Field), #Type "::" #Field }
360	/** Emit the terminating entry of a SSMFIELD array. */
361	#define SSMFIELD_ENTRY_TERM() { (PFNSSMFIELDGETPUT)(uintptr_t)SSMFIELDTRANS_INVALID, UINT32_MAX, UINT32_MAX, NULL }
362
363
364	/** @name SSMR3GetStructEx and SSMR3PutStructEx flags.
365	* @{ */
366	/** The field descriptors must exactly cover the entire struct, A to Z. */
367	#define SSMSTRUCT_FLAGS_FULL_STRUCT RT_BIT_32(0)
368	/** No start and end markers, just the raw bits. */
369	#define SSMSTRUCT_FLAGS_NO_MARKERS RT_BIT_32(1)
370	/** Do not ignore any ignorable fields. */
371	#define SSMSTRUCT_FLAGS_DONT_IGNORE RT_BIT_32(2)
372	/** Saved using SSMR3PutMem, don't be too strict. */
373	#define SSMSTRUCT_FLAGS_SAVED_AS_MEM RT_BIT_32(3)
374	/** Band-aid for old SSMR3PutMem/SSMR3GetMem of structurs with host pointers. */
375	#define SSMSTRUCT_FLAGS_MEM_BAND_AID ( SSMSTRUCT_FLAGS_DONT_IGNORE \| SSMSTRUCT_FLAGS_FULL_STRUCT \
376	\| SSMSTRUCT_FLAGS_NO_MARKERS \| SSMSTRUCT_FLAGS_SAVED_AS_MEM)
377	/** Mask of the valid bits. */
378	#define SSMSTRUCT_FLAGS_VALID_MASK UINT32_C(0x0000000f)
379	/** @} */
380
381
382	/** The PDM Device callback variants.
383	* @{
384	*/
385
386	/**
387	* Prepare state live save operation.
388	*
389	* @returns VBox status code.
390	* @param pDevIns Device instance of the device which registered the data unit.
391	* @param pSSM SSM operation handle.
392	* @thread Any.
393	*/
394	typedef DECLCALLBACK(int) FNSSMDEVLIVEPREP(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
395	/** Pointer to a FNSSMDEVLIVEPREP() function. */
396	typedef FNSSMDEVLIVEPREP *PFNSSMDEVLIVEPREP;
397
398	/**
399	* Execute state live save operation.
400	*
401	* This will be called repeatedly until all units vote that the live phase has
402	* been concluded.
403	*
404	* @returns VBox status code.
405	* @param pDevIns Device instance of the device which registered the data unit.
406	* @param pSSM SSM operation handle.
407	* @param uPass The pass.
408	* @thread Any.
409	*/
410	typedef DECLCALLBACK(int) FNSSMDEVLIVEEXEC(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t uPass);
411	/** Pointer to a FNSSMDEVLIVEEXEC() function. */
412	typedef FNSSMDEVLIVEEXEC *PFNSSMDEVLIVEEXEC;
413
414	/**
415	* Vote on whether the live part of the saving has been concluded.
416	*
417	* The vote stops once a unit has vetoed the decision, so don't rely upon this
418	* being called every time.
419	*
420	* @returns VBox status code.
421	* @retval VINF_SUCCESS if done.
422	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
423	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
424	* done and there is not need calling it again before the final pass.
425	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
426	*
427	* @param pDevIns Device instance of the device which registered the data unit.
428	* @param pSSM SSM operation handle.
429	* @param uPass The data pass.
430	* @thread Any.
431	*/
432	typedef DECLCALLBACK(int) FNSSMDEVLIVEVOTE(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t uPass);
433	/** Pointer to a FNSSMDEVLIVEVOTE() function. */
434	typedef FNSSMDEVLIVEVOTE *PFNSSMDEVLIVEVOTE;
435
436	/**
437	* Prepare state save operation.
438	*
439	* @returns VBox status code.
440	* @param pDevIns Device instance of the device which registered the data unit.
441	* @param pSSM SSM operation handle.
442	*/
443	typedef DECLCALLBACK(int) FNSSMDEVSAVEPREP(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
444	/** Pointer to a FNSSMDEVSAVEPREP() function. */
445	typedef FNSSMDEVSAVEPREP *PFNSSMDEVSAVEPREP;
446
447	/**
448	* Execute state save operation.
449	*
450	* @returns VBox status code.
451	* @param pDevIns Device instance of the device which registered the data unit.
452	* @param pSSM SSM operation handle.
453	*/
454	typedef DECLCALLBACK(int) FNSSMDEVSAVEEXEC(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
455	/** Pointer to a FNSSMDEVSAVEEXEC() function. */
456	typedef FNSSMDEVSAVEEXEC *PFNSSMDEVSAVEEXEC;
457
458	/**
459	* Done state save operation.
460	*
461	* @returns VBox status code.
462	* @param pDevIns Device instance of the device which registered the data unit.
463	* @param pSSM SSM operation handle.
464	*/
465	typedef DECLCALLBACK(int) FNSSMDEVSAVEDONE(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
466	/** Pointer to a FNSSMDEVSAVEDONE() function. */
467	typedef FNSSMDEVSAVEDONE *PFNSSMDEVSAVEDONE;
468
469	/**
470	* Prepare state load operation.
471	*
472	* @returns VBox status code.
473	* @param pDevIns Device instance of the device which registered the data unit.
474	* @param pSSM SSM operation handle.
475	*/
476	typedef DECLCALLBACK(int) FNSSMDEVLOADPREP(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
477	/** Pointer to a FNSSMDEVLOADPREP() function. */
478	typedef FNSSMDEVLOADPREP *PFNSSMDEVLOADPREP;
479
480	/**
481	* Execute state load operation.
482	*
483	* @returns VBox status code.
484	* @param pDevIns Device instance of the device which registered the data unit.
485	* @param pSSM SSM operation handle.
486	* @param uVersion Data layout version.
487	* @param uPass The pass. This is always SSM_PASS_FINAL for units
488	* that doesn't specify a pfnSaveLive callback.
489	*/
490	typedef DECLCALLBACK(int) FNSSMDEVLOADEXEC(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass);
491	/** Pointer to a FNSSMDEVLOADEXEC() function. */
492	typedef FNSSMDEVLOADEXEC *PFNSSMDEVLOADEXEC;
493
494	/**
495	* Done state load operation.
496	*
497	* @returns VBox load code.
498	* @param pDevIns Device instance of the device which registered the data unit.
499	* @param pSSM SSM operation handle.
500	*/
501	typedef DECLCALLBACK(int) FNSSMDEVLOADDONE(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
502	/** Pointer to a FNSSMDEVLOADDONE() function. */
503	typedef FNSSMDEVLOADDONE *PFNSSMDEVLOADDONE;
504
505	/** @} */
506
507
508	/** The PDM USB device callback variants.
509	* @{
510	*/
511
512	/**
513	* Prepare state live save operation.
514	*
515	* @returns VBox status code.
516	* @param pUsbIns The USB device instance of the USB device which
517	* registered the data unit.
518	* @param pSSM SSM operation handle.
519	* @thread Any.
520	*/
521	typedef DECLCALLBACK(int) FNSSMUSBLIVEPREP(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM);
522	/** Pointer to a FNSSMUSBLIVEPREP() function. */
523	typedef FNSSMUSBLIVEPREP *PFNSSMUSBLIVEPREP;
524
525	/**
526	* Execute state live save operation.
527	*
528	* This will be called repeatedly until all units vote that the live phase has
529	* been concluded.
530	*
531	* @returns VBox status code.
532	* @param pUsbIns The USB device instance of the USB device which
533	* registered the data unit.
534	* @param pSSM SSM operation handle.
535	* @param uPass The pass.
536	* @thread Any.
537	*/
538	typedef DECLCALLBACK(int) FNSSMUSBLIVEEXEC(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM, uint32_t uPass);
539	/** Pointer to a FNSSMUSBLIVEEXEC() function. */
540	typedef FNSSMUSBLIVEEXEC *PFNSSMUSBLIVEEXEC;
541
542	/**
543	* Vote on whether the live part of the saving has been concluded.
544	*
545	* The vote stops once a unit has vetoed the decision, so don't rely upon this
546	* being called every time.
547	*
548	* @returns VBox status code.
549	* @retval VINF_SUCCESS if done.
550	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
551	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
552	* done and there is not need calling it again before the final pass.
553	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
554	*
555	* @param pUsbIns The USB device instance of the USB device which
556	* registered the data unit.
557	* @param pSSM SSM operation handle.
558	* @param uPass The data pass.
559	* @thread Any.
560	*/
561	typedef DECLCALLBACK(int) FNSSMUSBLIVEVOTE(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM, uint32_t uPass);
562	/** Pointer to a FNSSMUSBLIVEVOTE() function. */
563	typedef FNSSMUSBLIVEVOTE *PFNSSMUSBLIVEVOTE;
564
565	/**
566	* Prepare state save operation.
567	*
568	* @returns VBox status code.
569	* @param pUsbIns The USB device instance of the USB device which
570	* registered the data unit.
571	* @param pSSM SSM operation handle.
572	*/
573	typedef DECLCALLBACK(int) FNSSMUSBSAVEPREP(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM);
574	/** Pointer to a FNSSMUSBSAVEPREP() function. */
575	typedef FNSSMUSBSAVEPREP *PFNSSMUSBSAVEPREP;
576
577	/**
578	* Execute state save operation.
579	*
580	* @returns VBox status code.
581	* @param pUsbIns The USB device instance of the USB device which
582	* registered the data unit.
583	* @param pSSM SSM operation handle.
584	*/
585	typedef DECLCALLBACK(int) FNSSMUSBSAVEEXEC(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM);
586	/** Pointer to a FNSSMUSBSAVEEXEC() function. */
587	typedef FNSSMUSBSAVEEXEC *PFNSSMUSBSAVEEXEC;
588
589	/**
590	* Done state save operation.
591	*
592	* @returns VBox status code.
593	* @param pUsbIns The USB device instance of the USB device which
594	* registered the data unit.
595	* @param pSSM SSM operation handle.
596	*/
597	typedef DECLCALLBACK(int) FNSSMUSBSAVEDONE(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM);
598	/** Pointer to a FNSSMUSBSAVEDONE() function. */
599	typedef FNSSMUSBSAVEDONE *PFNSSMUSBSAVEDONE;
600
601	/**
602	* Prepare state load operation.
603	*
604	* @returns VBox status code.
605	* @param pUsbIns The USB device instance of the USB device which
606	* registered the data unit.
607	* @param pSSM SSM operation handle.
608	*/
609	typedef DECLCALLBACK(int) FNSSMUSBLOADPREP(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM);
610	/** Pointer to a FNSSMUSBLOADPREP() function. */
611	typedef FNSSMUSBLOADPREP *PFNSSMUSBLOADPREP;
612
613	/**
614	* Execute state load operation.
615	*
616	* @returns VBox status code.
617	* @param pUsbIns The USB device instance of the USB device which
618	* registered the data unit.
619	* @param pSSM SSM operation handle.
620	* @param uVersion Data layout version.
621	* @param uPass The pass. This is always SSM_PASS_FINAL for units
622	* that doesn't specify a pfnSaveLive callback.
623	*/
624	typedef DECLCALLBACK(int) FNSSMUSBLOADEXEC(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass);
625	/** Pointer to a FNSSMUSBLOADEXEC() function. */
626	typedef FNSSMUSBLOADEXEC *PFNSSMUSBLOADEXEC;
627
628	/**
629	* Done state load operation.
630	*
631	* @returns VBox load code.
632	* @param pUsbIns The USB device instance of the USB device which
633	* registered the data unit.
634	* @param pSSM SSM operation handle.
635	*/
636	typedef DECLCALLBACK(int) FNSSMUSBLOADDONE(PPDMUSBINS pUsbIns, PSSMHANDLE pSSM);
637	/** Pointer to a FNSSMUSBLOADDONE() function. */
638	typedef FNSSMUSBLOADDONE *PFNSSMUSBLOADDONE;
639
640	/** @} */
641
642
643	/** The PDM Driver callback variants.
644	* @{
645	*/
646
647	/**
648	* Prepare state live save operation.
649	*
650	* @returns VBox status code.
651	* @param pDrvIns Driver instance of the driver which registered the
652	* data unit.
653	* @param pSSM SSM operation handle.
654	* @thread Any.
655	*/
656	typedef DECLCALLBACK(int) FNSSMDRVLIVEPREP(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
657	/** Pointer to a FNSSMDRVLIVEPREP() function. */
658	typedef FNSSMDRVLIVEPREP *PFNSSMDRVLIVEPREP;
659
660	/**
661	* Execute state live save operation.
662	*
663	* This will be called repeatedly until all units vote that the live phase has
664	* been concluded.
665	*
666	* @returns VBox status code.
667	* @param pDrvIns Driver instance of the driver which registered the
668	* data unit.
669	* @param pSSM SSM operation handle.
670	* @param uPass The data pass.
671	* @thread Any.
672	*/
673	typedef DECLCALLBACK(int) FNSSMDRVLIVEEXEC(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM, uint32_t uPass);
674	/** Pointer to a FNSSMDRVLIVEEXEC() function. */
675	typedef FNSSMDRVLIVEEXEC *PFNSSMDRVLIVEEXEC;
676
677	/**
678	* Vote on whether the live part of the saving has been concluded.
679	*
680	* The vote stops once a unit has vetoed the decision, so don't rely upon this
681	* being called every time.
682	*
683	* @returns VBox status code.
684	* @retval VINF_SUCCESS if done.
685	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
686	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
687	* done and there is not need calling it again before the final pass.
688	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
689	*
690	* @param pDrvIns Driver instance of the driver which registered the
691	* data unit.
692	* @param pSSM SSM operation handle.
693	* @param uPass The data pass.
694	* @thread Any.
695	*/
696	typedef DECLCALLBACK(int) FNSSMDRVLIVEVOTE(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM, uint32_t uPass);
697	/** Pointer to a FNSSMDRVLIVEVOTE() function. */
698	typedef FNSSMDRVLIVEVOTE *PFNSSMDRVLIVEVOTE;
699
700
701	/**
702	* Prepare state save operation.
703	*
704	* @returns VBox status code.
705	* @param pDrvIns Driver instance of the driver which registered the data unit.
706	* @param pSSM SSM operation handle.
707	*/
708	typedef DECLCALLBACK(int) FNSSMDRVSAVEPREP(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
709	/** Pointer to a FNSSMDRVSAVEPREP() function. */
710	typedef FNSSMDRVSAVEPREP *PFNSSMDRVSAVEPREP;
711
712	/**
713	* Execute state save operation.
714	*
715	* @returns VBox status code.
716	* @param pDrvIns Driver instance of the driver which registered the data unit.
717	* @param pSSM SSM operation handle.
718	*/
719	typedef DECLCALLBACK(int) FNSSMDRVSAVEEXEC(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
720	/** Pointer to a FNSSMDRVSAVEEXEC() function. */
721	typedef FNSSMDRVSAVEEXEC *PFNSSMDRVSAVEEXEC;
722
723	/**
724	* Done state save operation.
725	*
726	* @returns VBox status code.
727	* @param pDrvIns Driver instance of the driver which registered the data unit.
728	* @param pSSM SSM operation handle.
729	*/
730	typedef DECLCALLBACK(int) FNSSMDRVSAVEDONE(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
731	/** Pointer to a FNSSMDRVSAVEDONE() function. */
732	typedef FNSSMDRVSAVEDONE *PFNSSMDRVSAVEDONE;
733
734	/**
735	* Prepare state load operation.
736	*
737	* @returns VBox status code.
738	* @param pDrvIns Driver instance of the driver which registered the data unit.
739	* @param pSSM SSM operation handle.
740	*/
741	typedef DECLCALLBACK(int) FNSSMDRVLOADPREP(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
742	/** Pointer to a FNSSMDRVLOADPREP() function. */
743	typedef FNSSMDRVLOADPREP *PFNSSMDRVLOADPREP;
744
745	/**
746	* Execute state load operation.
747	*
748	* @returns VBox status code.
749	* @param pDrvIns Driver instance of the driver which registered the data unit.
750	* @param pSSM SSM operation handle.
751	* @param uVersion Data layout version.
752	* @param uPass The pass. This is always SSM_PASS_FINAL for units
753	* that doesn't specify a pfnSaveLive callback.
754	*/
755	typedef DECLCALLBACK(int) FNSSMDRVLOADEXEC(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass);
756	/** Pointer to a FNSSMDRVLOADEXEC() function. */
757	typedef FNSSMDRVLOADEXEC *PFNSSMDRVLOADEXEC;
758
759	/**
760	* Done state load operation.
761	*
762	* @returns VBox load code.
763	* @param pDrvIns Driver instance of the driver which registered the data unit.
764	* @param pSSM SSM operation handle.
765	*/
766	typedef DECLCALLBACK(int) FNSSMDRVLOADDONE(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
767	/** Pointer to a FNSSMDRVLOADDONE() function. */
768	typedef FNSSMDRVLOADDONE *PFNSSMDRVLOADDONE;
769
770	/** @} */
771
772
773	/** The internal callback variants.
774	* @{
775	*/
776
777
778	/**
779	* Prepare state live save operation.
780	*
781	* @returns VBox status code.
782	* @param pVM VM Handle.
783	* @param pSSM SSM operation handle.
784	* @thread Any.
785	*/
786	typedef DECLCALLBACK(int) FNSSMINTLIVEPREP(PVM pVM, PSSMHANDLE pSSM);
787	/** Pointer to a FNSSMINTLIVEPREP() function. */
788	typedef FNSSMINTLIVEPREP *PFNSSMINTLIVEPREP;
789
790	/**
791	* Execute state live save operation.
792	*
793	* This will be called repeatedly until all units vote that the live phase has
794	* been concluded.
795	*
796	* @returns VBox status code.
797	* @param pVM VM Handle.
798	* @param pSSM SSM operation handle.
799	* @param uPass The data pass.
800	* @thread Any.
801	*/
802	typedef DECLCALLBACK(int) FNSSMINTLIVEEXEC(PVM pVM, PSSMHANDLE pSSM, uint32_t uPass);
803	/** Pointer to a FNSSMINTLIVEEXEC() function. */
804	typedef FNSSMINTLIVEEXEC *PFNSSMINTLIVEEXEC;
805
806	/**
807	* Vote on whether the live part of the saving has been concluded.
808	*
809	* The vote stops once a unit has vetoed the decision, so don't rely upon this
810	* being called every time.
811	*
812	* @returns VBox status code.
813	* @retval VINF_SUCCESS if done.
814	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
815	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
816	* done and there is not need calling it again before the final pass.
817	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
818	*
819	* @param pVM VM Handle.
820	* @param pSSM SSM operation handle.
821	* @param uPass The data pass.
822	* @thread Any.
823	*/
824	typedef DECLCALLBACK(int) FNSSMINTLIVEVOTE(PVM pVM, PSSMHANDLE pSSM, uint32_t uPass);
825	/** Pointer to a FNSSMINTLIVEVOTE() function. */
826	typedef FNSSMINTLIVEVOTE *PFNSSMINTLIVEVOTE;
827
828	/**
829	* Prepare state save operation.
830	*
831	* @returns VBox status code.
832	* @param pVM VM Handle.
833	* @param pSSM SSM operation handle.
834	*/
835	typedef DECLCALLBACK(int) FNSSMINTSAVEPREP(PVM pVM, PSSMHANDLE pSSM);
836	/** Pointer to a FNSSMINTSAVEPREP() function. */
837	typedef FNSSMINTSAVEPREP *PFNSSMINTSAVEPREP;
838
839	/**
840	* Execute state save operation.
841	*
842	* @returns VBox status code.
843	* @param pVM VM Handle.
844	* @param pSSM SSM operation handle.
845	*/
846	typedef DECLCALLBACK(int) FNSSMINTSAVEEXEC(PVM pVM, PSSMHANDLE pSSM);
847	/** Pointer to a FNSSMINTSAVEEXEC() function. */
848	typedef FNSSMINTSAVEEXEC *PFNSSMINTSAVEEXEC;
849
850	/**
851	* Done state save operation.
852	*
853	* @returns VBox status code.
854	* @param pVM VM Handle.
855	* @param pSSM SSM operation handle.
856	*/
857	typedef DECLCALLBACK(int) FNSSMINTSAVEDONE(PVM pVM, PSSMHANDLE pSSM);
858	/** Pointer to a FNSSMINTSAVEDONE() function. */
859	typedef FNSSMINTSAVEDONE *PFNSSMINTSAVEDONE;
860
861	/**
862	* Prepare state load operation.
863	*
864	* @returns VBox status code.
865	* @param pVM VM Handle.
866	* @param pSSM SSM operation handle.
867	*/
868	typedef DECLCALLBACK(int) FNSSMINTLOADPREP(PVM pVM, PSSMHANDLE pSSM);
869	/** Pointer to a FNSSMINTLOADPREP() function. */
870	typedef FNSSMINTLOADPREP *PFNSSMINTLOADPREP;
871
872	/**
873	* Execute state load operation.
874	*
875	* @returns VBox status code.
876	* @param pVM VM Handle.
877	* @param pSSM SSM operation handle.
878	* @param uVersion Data layout version.
879	* @param uPass The pass. This is always SSM_PASS_FINAL for units
880	* that doesn't specify a pfnSaveLive callback.
881	*/
882	typedef DECLCALLBACK(int) FNSSMINTLOADEXEC(PVM pVM, PSSMHANDLE pSSM, uint32_t uVersion, uint32_t uPass);
883	/** Pointer to a FNSSMINTLOADEXEC() function. */
884	typedef FNSSMINTLOADEXEC *PFNSSMINTLOADEXEC;
885
886	/**
887	* Done state load operation.
888	*
889	* @returns VBox load code.
890	* @param pVM VM Handle.
891	* @param pSSM SSM operation handle.
892	*/
893	typedef DECLCALLBACK(int) FNSSMINTLOADDONE(PVM pVM, PSSMHANDLE pSSM);
894	/** Pointer to a FNSSMINTLOADDONE() function. */
895	typedef FNSSMINTLOADDONE *PFNSSMINTLOADDONE;
896
897	/** @} */
898
899
900	/** The External callback variants.
901	* @{
902	*/
903
904	/**
905	* Prepare state live save operation.
906	*
907	* @returns VBox status code.
908	* @param pSSM SSM operation handle.
909	* @param pvUser User argument.
910	* @thread Any.
911	*/
912	typedef DECLCALLBACK(int) FNSSMEXTLIVEPREP(PSSMHANDLE pSSM, void *pvUser);
913	/** Pointer to a FNSSMEXTLIVEPREP() function. */
914	typedef FNSSMEXTLIVEPREP *PFNSSMEXTLIVEPREP;
915
916	/**
917	* Execute state live save operation.
918	*
919	* This will be called repeatedly until all units vote that the live phase has
920	* been concluded.
921	*
922	* @returns VBox status code.
923	* @param pSSM SSM operation handle.
924	* @param pvUser User argument.
925	* @param uPass The data pass.
926	* @thread Any.
927	*/
928	typedef DECLCALLBACK(int) FNSSMEXTLIVEEXEC(PSSMHANDLE pSSM, void *pvUser, uint32_t uPass);
929	/** Pointer to a FNSSMEXTLIVEEXEC() function. */
930	typedef FNSSMEXTLIVEEXEC *PFNSSMEXTLIVEEXEC;
931
932	/**
933	* Vote on whether the live part of the saving has been concluded.
934	*
935	* The vote stops once a unit has vetoed the decision, so don't rely upon this
936	* being called every time.
937	*
938	* @returns VBox status code.
939	* @retval VINF_SUCCESS if done.
940	* @retval VINF_SSM_VOTE_FOR_ANOTHER_PASS if another pass is needed.
941	* @retval VINF_SSM_VOTE_DONE_DONT_CALL_AGAIN if the live saving of the unit is
942	* done and there is not need calling it again before the final pass.
943	* @retval VERR_SSM_VOTE_FOR_GIVING_UP if its time to give up.
944	*
945	* @param pSSM SSM operation handle.
946	* @param pvUser User argument.
947	* @param uPass The data pass.
948	* @thread Any.
949	*/
950	typedef DECLCALLBACK(int) FNSSMEXTLIVEVOTE(PSSMHANDLE pSSM, void *pvUser, uint32_t uPass);
951	/** Pointer to a FNSSMEXTLIVEVOTE() function. */
952	typedef FNSSMEXTLIVEVOTE *PFNSSMEXTLIVEVOTE;
953
954	/**
955	* Prepare state save operation.
956	*
957	* @returns VBox status code.
958	* @param pSSM SSM operation handle.
959	* @param pvUser User argument.
960	*/
961	typedef DECLCALLBACK(int) FNSSMEXTSAVEPREP(PSSMHANDLE pSSM, void *pvUser);
962	/** Pointer to a FNSSMEXTSAVEPREP() function. */
963	typedef FNSSMEXTSAVEPREP *PFNSSMEXTSAVEPREP;
964
965	/**
966	* Execute state save operation.
967	*
968	* @param pSSM SSM operation handle.
969	* @param pvUser User argument.
970	* @author The lack of return code is for legacy reasons.
971	*/
972	typedef DECLCALLBACK(void) FNSSMEXTSAVEEXEC(PSSMHANDLE pSSM, void *pvUser);
973	/** Pointer to a FNSSMEXTSAVEEXEC() function. */
974	typedef FNSSMEXTSAVEEXEC *PFNSSMEXTSAVEEXEC;
975
976	/**
977	* Done state save operation.
978	*
979	* @returns VBox status code.
980	* @param pSSM SSM operation handle.
981	* @param pvUser User argument.
982	*/
983	typedef DECLCALLBACK(int) FNSSMEXTSAVEDONE(PSSMHANDLE pSSM, void *pvUser);
984	/** Pointer to a FNSSMEXTSAVEDONE() function. */
985	typedef FNSSMEXTSAVEDONE *PFNSSMEXTSAVEDONE;
986
987	/**
988	* Prepare state load operation.
989	*
990	* @returns VBox status code.
991	* @param pSSM SSM operation handle.
992	* @param pvUser User argument.
993	*/
994	typedef DECLCALLBACK(int) FNSSMEXTLOADPREP(PSSMHANDLE pSSM, void *pvUser);
995	/** Pointer to a FNSSMEXTLOADPREP() function. */
996	typedef FNSSMEXTLOADPREP *PFNSSMEXTLOADPREP;
997
998	/**
999	* Execute state load operation.
1000	*
1001	* @returns VBox status code.
1002	* @param pSSM SSM operation handle.
1003	* @param pvUser User argument.
1004	* @param uVersion Data layout version.
1005	* @param uPass The pass. This is always SSM_PASS_FINAL for units
1006	* that doesn't specify a pfnSaveLive callback.
1007	* @remark The odd return value is for legacy reasons.
1008	*/
1009	typedef DECLCALLBACK(int) FNSSMEXTLOADEXEC(PSSMHANDLE pSSM, void *pvUser, uint32_t uVersion, uint32_t uPass);
1010	/** Pointer to a FNSSMEXTLOADEXEC() function. */
1011	typedef FNSSMEXTLOADEXEC *PFNSSMEXTLOADEXEC;
1012
1013	/**
1014	* Done state load operation.
1015	*
1016	* @returns VBox load code.
1017	* @param pSSM SSM operation handle.
1018	* @param pvUser User argument.
1019	*/
1020	typedef DECLCALLBACK(int) FNSSMEXTLOADDONE(PSSMHANDLE pSSM, void *pvUser);
1021	/** Pointer to a FNSSMEXTLOADDONE() function. */
1022	typedef FNSSMEXTLOADDONE *PFNSSMEXTLOADDONE;
1023
1024	/** @} */
1025
1026
1027	/**
1028	* SSM stream method table.
1029	*
1030	* This is used by external parties for teleporting over TCP or any other media.
1031	* SSM also uses this internally for file access, thus the 2-3 file centric
1032	* methods.
1033	*/
1034	typedef struct SSMSTRMOPS
1035	{
1036	/** Struct magic + version (SSMSTRMOPS_VERSION). */
1037	uint32_t u32Version;
1038
1039	/**
1040	* Write bytes to the stream.
1041	*
1042	* @returns VBox status code.
1043	* @param pvUser The user argument.
1044	* @param offStream The stream offset we're (supposed to be) at.
1045	* @param pvBuf Pointer to the data.
1046	* @param cbToWrite The number of bytes to write.
1047	*/
1048	DECLCALLBACKMEMBER(int, pfnWrite)(void pvUser, uint64_t offStream, const void pvBuf, size_t cbToWrite);
1049
1050	/**
1051	* Read bytes to the stream.
1052	*
1053	* @returns VBox status code.
1054	* @param pvUser The user argument.
1055	* @param offStream The stream offset we're (supposed to be) at.
1056	* @param pvBuf Where to return the bytes.
1057	* @param cbToRead The number of bytes to read.
1058	* @param pcbRead Where to return the number of bytes actually
1059	* read. This may differ from cbToRead when the
1060	* end of the stream is encountered.
1061	*/
1062	DECLCALLBACKMEMBER(int, pfnRead)(void pvUser, uint64_t offStream, void pvBuf, size_t cbToRead, size_t *pcbRead);
1063
1064	/**
1065	* Seeks in the stream.
1066	*
1067	* @returns VBox status code.
1068	* @retval VERR_NOT_SUPPORTED if the stream doesn't support this action.
1069	*
1070	* @param pvUser The user argument.
1071	* @param offSeek The seek offset.
1072	* @param uMethod RTFILE_SEEK_BEGIN, RTFILE_SEEK_END or
1073	* RTFILE_SEEK_CURRENT.
1074	* @param poffActual Where to store the new file position. Optional.
1075	*/
1076	DECLCALLBACKMEMBER(int, pfnSeek)(void pvUser, int64_t offSeek, unsigned uMethod, uint64_t poffActual);
1077
1078	/**
1079	* Get the current stream position.
1080	*
1081	* @returns The correct stream position.
1082	* @param pvUser The user argument.
1083	*/
1084	DECLCALLBACKMEMBER(uint64_t, pfnTell)(void *pvUser);
1085
1086	/**
1087	* Get the size/length of the stream.
1088	*
1089	* @returns VBox status code.
1090	* @retval VERR_NOT_SUPPORTED if the stream doesn't support this action.
1091	*
1092	* @param pvUser The user argument.
1093	* @param pcb Where to return the size/length.
1094	*/
1095	DECLCALLBACKMEMBER(int, pfnSize)(void pvUser, uint64_t pcb);
1096
1097	/**
1098	* Check if the stream is OK or not (cancelled).
1099	*
1100	* @returns VBox status code.
1101	* @param pvUser The user argument.
1102	*
1103	* @remarks The method is expected to do a LogRel on failure.
1104	*/
1105	DECLCALLBACKMEMBER(int, pfnIsOk)(void *pvUser);
1106
1107	/**
1108	* Close the stream.
1109	*
1110	* @returns VBox status code.
1111	* @param pvUser The user argument.
1112	* @param fCancelled True if the operation was cancelled.
1113	*/
1114	DECLCALLBACKMEMBER(int, pfnClose)(void *pvUser, bool fCancelled);
1115
1116	/** Struct magic + version (SSMSTRMOPS_VERSION). */
1117	uint32_t u32EndVersion;
1118	} SSMSTRMOPS;
1119	/** Struct magic + version (SSMSTRMOPS_VERSION). */
1120	#define SSMSTRMOPS_VERSION UINT32_C(0x55aa0001)
1121
1122
1123	VMMR3_INT_DECL(void) SSMR3Term(PVM pVM);
1124	VMMR3DECL(int) SSMR3RegisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char pszName, uint32_t uInstance, uint32_t uVersion, size_t cbGuess, const char pszBefore,
1125	PFNSSMDEVLIVEPREP pfnLivePrep, PFNSSMDEVLIVEEXEC pfnLiveExec, PFNSSMDEVLIVEVOTE pfnLiveVote,
1126	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
1127	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone);
1128	VMMR3DECL(int) SSMR3RegisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName, uint32_t uInstance, uint32_t uVersion, size_t cbGuess,
1129	PFNSSMDRVLIVEPREP pfnLivePrep, PFNSSMDRVLIVEEXEC pfnLiveExec, PFNSSMDRVLIVEVOTE pfnLiveVote,
1130	PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
1131	PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone);
1132	VMMR3DECL(int) SSMR3RegisterInternal(PVM pVM, const char *pszName, uint32_t uInstance, uint32_t uVersion, size_t cbGuess,
1133	PFNSSMINTLIVEPREP pfnLivePrep, PFNSSMINTLIVEEXEC pfnLiveExec, PFNSSMINTLIVEVOTE pfnLiveVote,
1134	PFNSSMINTSAVEPREP pfnSavePrep, PFNSSMINTSAVEEXEC pfnSaveExec, PFNSSMINTSAVEDONE pfnSaveDone,
1135	PFNSSMINTLOADPREP pfnLoadPrep, PFNSSMINTLOADEXEC pfnLoadExec, PFNSSMINTLOADDONE pfnLoadDone);
1136	VMMR3DECL(int) SSMR3RegisterExternal(PVM pVM, const char *pszName, uint32_t uInstance, uint32_t uVersion, size_t cbGuess,
1137	PFNSSMEXTLIVEPREP pfnLivePrep, PFNSSMEXTLIVEEXEC pfnLiveExec, PFNSSMEXTLIVEVOTE pfnLiveVote,
1138	PFNSSMEXTSAVEPREP pfnSavePrep, PFNSSMEXTSAVEEXEC pfnSaveExec, PFNSSMEXTSAVEDONE pfnSaveDone,
1139	PFNSSMEXTLOADPREP pfnLoadPrep, PFNSSMEXTLOADEXEC pfnLoadExec, PFNSSMEXTLOADDONE pfnLoadDone, void *pvUser);
1140	VMMR3_INT_DECL(int) SSMR3DeregisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char *pszName, uint32_t uInstance);
1141	VMMR3_INT_DECL(int) SSMR3DeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName, uint32_t uInstance);
1142	VMMR3DECL(int) SSMR3DeregisterInternal(PVM pVM, const char *pszName);
1143	VMMR3DECL(int) SSMR3DeregisterExternal(PVM pVM, const char *pszName);
1144	VMMR3DECL(int) SSMR3Save(PVM pVM, const char pszFilename, PCSSMSTRMOPS pStreamOps, void pvStreamOpsUser, SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void *pvUser);
1145	VMMR3_INT_DECL(int) SSMR3LiveSave(PVM pVM, uint32_t cMsMaxDowntime,
1146	const char pszFilename, PCSSMSTRMOPS pStreamOps, void pvStreamOps,
1147	SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void *pvProgressUser,
1148	PSSMHANDLE *ppSSM);
1149	VMMR3_INT_DECL(int) SSMR3LiveDoStep1(PSSMHANDLE pSSM);
1150	VMMR3_INT_DECL(int) SSMR3LiveDoStep2(PSSMHANDLE pSSM);
1151	VMMR3_INT_DECL(int) SSMR3LiveDone(PSSMHANDLE pSSM);
1152	VMMR3DECL(int) SSMR3Load(PVM pVM, const char pszFilename, PCSSMSTRMOPS pStreamOps, void pvStreamOpsUser,
1153	SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void *pvProgressUser);
1154	VMMR3DECL(int) SSMR3ValidateFile(const char *pszFilename, bool fChecksumIt);
1155	VMMR3DECL(int) SSMR3Open(const char pszFilename, unsigned fFlags, PSSMHANDLE ppSSM);
1156	VMMR3DECL(int) SSMR3Close(PSSMHANDLE pSSM);
1157	VMMR3DECL(int) SSMR3Seek(PSSMHANDLE pSSM, const char pszUnit, uint32_t iInstance, uint32_t piVersion);
1158	VMMR3DECL(int) SSMR3HandleGetStatus(PSSMHANDLE pSSM);
1159	VMMR3DECL(int) SSMR3HandleSetStatus(PSSMHANDLE pSSM, int iStatus);
1160	VMMR3DECL(SSMAFTER) SSMR3HandleGetAfter(PSSMHANDLE pSSM);
1161	VMMR3DECL(bool) SSMR3HandleIsLiveSave(PSSMHANDLE pSSM);
1162	VMMR3DECL(uint32_t) SSMR3HandleMaxDowntime(PSSMHANDLE pSSM);
1163	VMMR3DECL(uint32_t) SSMR3HandleHostBits(PSSMHANDLE pSSM);
1164	VMMR3DECL(uint32_t) SSMR3HandleRevision(PSSMHANDLE pSSM);
1165	VMMR3DECL(uint32_t) SSMR3HandleVersion(PSSMHANDLE pSSM);
1166	VMMR3DECL(const char *) SSMR3HandleHostOSAndArch(PSSMHANDLE pSSM);
1167	VMMR3_INT_DECL(int) SSMR3HandleSetGCPtrSize(PSSMHANDLE pSSM, unsigned cbGCPtr);
1168	VMMR3DECL(void) SSMR3HandleReportLivePercent(PSSMHANDLE pSSM, unsigned uPercent);
1169	VMMR3DECL(int) SSMR3Cancel(PVM pVM);
1170
1171
1172	/** Save operations.
1173	* @{
1174	*/
1175	VMMR3DECL(int) SSMR3PutStruct(PSSMHANDLE pSSM, const void *pvStruct, PCSSMFIELD paFields);
1176	VMMR3DECL(int) SSMR3PutStructEx(PSSMHANDLE pSSM, const void pvStruct, size_t cbStruct, uint32_t fFlags, PCSSMFIELD paFields, void pvUser);
1177	VMMR3DECL(int) SSMR3PutBool(PSSMHANDLE pSSM, bool fBool);
1178	VMMR3DECL(int) SSMR3PutU8(PSSMHANDLE pSSM, uint8_t u8);
1179	VMMR3DECL(int) SSMR3PutS8(PSSMHANDLE pSSM, int8_t i8);
1180	VMMR3DECL(int) SSMR3PutU16(PSSMHANDLE pSSM, uint16_t u16);
1181	VMMR3DECL(int) SSMR3PutS16(PSSMHANDLE pSSM, int16_t i16);
1182	VMMR3DECL(int) SSMR3PutU32(PSSMHANDLE pSSM, uint32_t u32);
1183	VMMR3DECL(int) SSMR3PutS32(PSSMHANDLE pSSM, int32_t i32);
1184	VMMR3DECL(int) SSMR3PutU64(PSSMHANDLE pSSM, uint64_t u64);
1185	VMMR3DECL(int) SSMR3PutS64(PSSMHANDLE pSSM, int64_t i64);
1186	VMMR3DECL(int) SSMR3PutU128(PSSMHANDLE pSSM, uint128_t u128);
1187	VMMR3DECL(int) SSMR3PutS128(PSSMHANDLE pSSM, int128_t i128);
1188	VMMR3DECL(int) SSMR3PutUInt(PSSMHANDLE pSSM, RTUINT u);
1189	VMMR3DECL(int) SSMR3PutSInt(PSSMHANDLE pSSM, RTINT i);
1190	VMMR3DECL(int) SSMR3PutGCUInt(PSSMHANDLE pSSM, RTGCUINT u);
1191	VMMR3DECL(int) SSMR3PutGCUIntReg(PSSMHANDLE pSSM, RTGCUINTREG u);
1192	VMMR3DECL(int) SSMR3PutGCPhys32(PSSMHANDLE pSSM, RTGCPHYS32 GCPhys);
1193	VMMR3DECL(int) SSMR3PutGCPhys64(PSSMHANDLE pSSM, RTGCPHYS64 GCPhys);
1194	VMMR3DECL(int) SSMR3PutGCPhys(PSSMHANDLE pSSM, RTGCPHYS GCPhys);
1195	VMMR3DECL(int) SSMR3PutGCPtr(PSSMHANDLE pSSM, RTGCPTR GCPtr);
1196	VMMR3DECL(int) SSMR3PutGCUIntPtr(PSSMHANDLE pSSM, RTGCUINTPTR GCPtr);
1197	VMMR3DECL(int) SSMR3PutRCPtr(PSSMHANDLE pSSM, RTRCPTR RCPtr);
1198	VMMR3DECL(int) SSMR3PutIOPort(PSSMHANDLE pSSM, RTIOPORT IOPort);
1199	VMMR3DECL(int) SSMR3PutSel(PSSMHANDLE pSSM, RTSEL Sel);
1200	VMMR3DECL(int) SSMR3PutMem(PSSMHANDLE pSSM, const void *pv, size_t cb);
1201	VMMR3DECL(int) SSMR3PutStrZ(PSSMHANDLE pSSM, const char *psz);
1202	/** @} */
1203
1204
1205
1206	/** Load operations.
1207	* @{
1208	*/
1209	VMMR3DECL(int) SSMR3GetStruct(PSSMHANDLE pSSM, void *pvStruct, PCSSMFIELD paFields);
1210	VMMR3DECL(int) SSMR3GetStructEx(PSSMHANDLE pSSM, void pvStruct, size_t cbStruct, uint32_t fFlags, PCSSMFIELD paFields, void pvUser);
1211	VMMR3DECL(int) SSMR3GetBool(PSSMHANDLE pSSM, bool *pfBool);
1212	VMMR3DECL(int) SSMR3GetU8(PSSMHANDLE pSSM, uint8_t *pu8);
1213	VMMR3DECL(int) SSMR3GetS8(PSSMHANDLE pSSM, int8_t *pi8);
1214	VMMR3DECL(int) SSMR3GetU16(PSSMHANDLE pSSM, uint16_t *pu16);
1215	VMMR3DECL(int) SSMR3GetS16(PSSMHANDLE pSSM, int16_t *pi16);
1216	VMMR3DECL(int) SSMR3GetU32(PSSMHANDLE pSSM, uint32_t *pu32);
1217	VMMR3DECL(int) SSMR3GetS32(PSSMHANDLE pSSM, int32_t *pi32);
1218	VMMR3DECL(int) SSMR3GetU64(PSSMHANDLE pSSM, uint64_t *pu64);
1219	VMMR3DECL(int) SSMR3GetS64(PSSMHANDLE pSSM, int64_t *pi64);
1220	VMMR3DECL(int) SSMR3GetU128(PSSMHANDLE pSSM, uint128_t *pu128);
1221	VMMR3DECL(int) SSMR3GetS128(PSSMHANDLE pSSM, int128_t *pi128);
1222	VMMR3DECL(int) SSMR3GetUInt(PSSMHANDLE pSSM, PRTUINT pu);
1223	VMMR3DECL(int) SSMR3GetSInt(PSSMHANDLE pSSM, PRTINT pi);
1224	VMMR3DECL(int) SSMR3GetGCUInt(PSSMHANDLE pSSM, PRTGCUINT pu);
1225	VMMR3DECL(int) SSMR3GetGCUIntReg(PSSMHANDLE pSSM, PRTGCUINTREG pu);
1226	VMMR3DECL(int) SSMR3GetGCPhys32(PSSMHANDLE pSSM, PRTGCPHYS32 pGCPhys);
1227	VMMR3DECL(int) SSMR3GetGCPhys64(PSSMHANDLE pSSM, PRTGCPHYS64 pGCPhys);
1228	VMMR3DECL(int) SSMR3GetGCPhys(PSSMHANDLE pSSM, PRTGCPHYS pGCPhys);
1229	VMMR3DECL(int) SSMR3GetGCPtr(PSSMHANDLE pSSM, PRTGCPTR pGCPtr);
1230	VMMR3DECL(int) SSMR3GetGCUIntPtr(PSSMHANDLE pSSM, PRTGCUINTPTR pGCPtr);
1231	VMMR3DECL(int) SSMR3GetRCPtr(PSSMHANDLE pSSM, PRTRCPTR pRCPtr);
1232	VMMR3DECL(int) SSMR3GetIOPort(PSSMHANDLE pSSM, PRTIOPORT pIOPort);
1233	VMMR3DECL(int) SSMR3GetSel(PSSMHANDLE pSSM, PRTSEL pSel);
1234	VMMR3DECL(int) SSMR3GetMem(PSSMHANDLE pSSM, void *pv, size_t cb);
1235	VMMR3DECL(int) SSMR3GetStrZ(PSSMHANDLE pSSM, char *psz, size_t cbMax);
1236	VMMR3DECL(int) SSMR3GetStrZEx(PSSMHANDLE pSSM, char psz, size_t cbMax, size_t pcbStr);
1237	VMMR3DECL(int) SSMR3GetTimer(PSSMHANDLE pSSM, PTMTIMER pTimer);
1238	VMMR3DECL(int) SSMR3Skip(PSSMHANDLE pSSM, size_t cb);
1239	VMMR3DECL(int) SSMR3SkipToEndOfUnit(PSSMHANDLE pSSM);
1240	VMMR3DECL(int) SSMR3SetLoadError(PSSMHANDLE pSSM, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...);
1241	VMMR3DECL(int) SSMR3SetLoadErrorV(PSSMHANDLE pSSM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list va);
1242	VMMR3DECL(int) SSMR3SetCfgError(PSSMHANDLE pSSM, RT_SRC_POS_DECL, const char *pszFormat, ...);
1243
1244	/** @} */
1245
1246	/** @} */
1247	#endif /* IN_RING3 */
1248
1249
1250	/** @} */
1251
1252	RT_C_DECLS_END
1253
1254	#endif
1255

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

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

Download in other formats: