ssm.h@ 6561

Last change on this file since 6561 was 6401, checked in by vboxsync, 17 years ago
ssm: major, minor
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 36.5 KB

Line
1	/** @file
2	* SSM - The Save State Manager.
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 innotek GmbH
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	__BEGIN_DECLS
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
59	#ifdef IN_RING3
60	/** @defgroup grp_ssm_r3 The SSM Host Context Ring-3 API
61	* @{
62	*/
63
64
65	/**
66	* What to do after the save/load operation.
67	*/
68	typedef enum SSMAFTER
69	{
70	/** Will resume the loaded state. */
71	SSMAFTER_RESUME = 1,
72	/** Will destroy the VM after saving. */
73	SSMAFTER_DESTROY,
74	/** Will continue execution after saving the VM. */
75	SSMAFTER_CONTINUE,
76	/** Will debug the saved state.
77	* This is used to drop some of the stricter consitentcy checks so it'll
78	* load fine in the debugger or animator. */
79	SSMAFTER_DEBUG_IT,
80	/** The file was opened using SSMR3Open() and we have no idea what the plan is. */
81	SSMAFTER_OPENED
82	} SSMAFTER;
83
84
85	/**
86	* A structure field description.
87	*/
88	typedef struct SSMFIELD
89	{
90	/** Field offset into the structure. */
91	uint32_t off;
92	/** The size of the field. */
93	uint32_t cb;
94	} SSMFIELD;
95	/** Pointer to a structure field description. */
96	typedef SSMFIELD *PSSMFIELD;
97	/** Pointer to a const structure field description. */
98	typedef const SSMFIELD *PCSSMFIELD;
99
100	/** Emit a SSMFIELD array entry. */
101	#define SSMFIELD_ENTRY(Type, Field) { RT_OFFSETOF(Type, Field), RT_SIZEOFMEMB(Type, Field) }
102	/** Emit the terminating entry of a SSMFIELD array. */
103	#define SSMFIELD_ENTRY_TERM() { UINT32_MAX, UINT32_MAX }
104
105
106
107	/** The PDM Device callback variants.
108	* @{
109	*/
110
111	/**
112	* Prepare state save operation.
113	*
114	* @returns VBox status code.
115	* @param pDevIns Device instance of the device which registered the data unit.
116	* @param pSSM SSM operation handle.
117	*/
118	typedef DECLCALLBACK(int) FNSSMDEVSAVEPREP(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
119	/** Pointer to a FNSSMDEVSAVEPREP() function. */
120	typedef FNSSMDEVSAVEPREP *PFNSSMDEVSAVEPREP;
121
122	/**
123	* Execute state save operation.
124	*
125	* @returns VBox status code.
126	* @param pDevIns Device instance of the device which registered the data unit.
127	* @param pSSM SSM operation handle.
128	*/
129	typedef DECLCALLBACK(int) FNSSMDEVSAVEEXEC(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
130	/** Pointer to a FNSSMDEVSAVEEXEC() function. */
131	typedef FNSSMDEVSAVEEXEC *PFNSSMDEVSAVEEXEC;
132
133	/**
134	* Done state save operation.
135	*
136	* @returns VBox status code.
137	* @param pDevIns Device instance of the device which registered the data unit.
138	* @param pSSM SSM operation handle.
139	*/
140	typedef DECLCALLBACK(int) FNSSMDEVSAVEDONE(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
141	/** Pointer to a FNSSMDEVSAVEDONE() function. */
142	typedef FNSSMDEVSAVEDONE *PFNSSMDEVSAVEDONE;
143
144	/**
145	* Prepare state load operation.
146	*
147	* @returns VBox status code.
148	* @param pDevIns Device instance of the device which registered the data unit.
149	* @param pSSM SSM operation handle.
150	*/
151	typedef DECLCALLBACK(int) FNSSMDEVLOADPREP(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
152	/** Pointer to a FNSSMDEVLOADPREP() function. */
153	typedef FNSSMDEVLOADPREP *PFNSSMDEVLOADPREP;
154
155	/**
156	* Execute state load operation.
157	*
158	* @returns VBox status code.
159	* @param pDevIns Device instance of the device which registered the data unit.
160	* @param pSSM SSM operation handle.
161	* @param u32Version Data layout version.
162	*/
163	typedef DECLCALLBACK(int) FNSSMDEVLOADEXEC(PPDMDEVINS pDevIns, PSSMHANDLE pSSM, uint32_t u32Version);
164	/** Pointer to a FNSSMDEVLOADEXEC() function. */
165	typedef FNSSMDEVLOADEXEC *PFNSSMDEVLOADEXEC;
166
167	/**
168	* Done state load operation.
169	*
170	* @returns VBox load code.
171	* @param pDevIns Device instance of the device which registered the data unit.
172	* @param pSSM SSM operation handle.
173	*/
174	typedef DECLCALLBACK(int) FNSSMDEVLOADDONE(PPDMDEVINS pDevIns, PSSMHANDLE pSSM);
175	/** Pointer to a FNSSMDEVLOADDONE() function. */
176	typedef FNSSMDEVLOADDONE *PFNSSMDEVLOADDONE;
177
178	/** @} */
179
180
181	/** The PDM Driver callback variants.
182	* @{
183	*/
184
185	/**
186	* Prepare state save operation.
187	*
188	* @returns VBox status code.
189	* @param pDrvIns Driver instance of the driver which registered the data unit.
190	* @param pSSM SSM operation handle.
191	*/
192	typedef DECLCALLBACK(int) FNSSMDRVSAVEPREP(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
193	/** Pointer to a FNSSMDRVSAVEPREP() function. */
194	typedef FNSSMDRVSAVEPREP *PFNSSMDRVSAVEPREP;
195
196	/**
197	* Execute state save operation.
198	*
199	* @returns VBox status code.
200	* @param pDrvIns Driver instance of the driver which registered the data unit.
201	* @param pSSM SSM operation handle.
202	*/
203	typedef DECLCALLBACK(int) FNSSMDRVSAVEEXEC(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
204	/** Pointer to a FNSSMDRVSAVEEXEC() function. */
205	typedef FNSSMDRVSAVEEXEC *PFNSSMDRVSAVEEXEC;
206
207	/**
208	* Done state save operation.
209	*
210	* @returns VBox status code.
211	* @param pDrvIns Driver instance of the driver which registered the data unit.
212	* @param pSSM SSM operation handle.
213	*/
214	typedef DECLCALLBACK(int) FNSSMDRVSAVEDONE(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
215	/** Pointer to a FNSSMDRVSAVEDONE() function. */
216	typedef FNSSMDRVSAVEDONE *PFNSSMDRVSAVEDONE;
217
218	/**
219	* Prepare state load operation.
220	*
221	* @returns VBox status code.
222	* @param pDrvIns Driver instance of the driver which registered the data unit.
223	* @param pSSM SSM operation handle.
224	*/
225	typedef DECLCALLBACK(int) FNSSMDRVLOADPREP(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
226	/** Pointer to a FNSSMDRVLOADPREP() function. */
227	typedef FNSSMDRVLOADPREP *PFNSSMDRVLOADPREP;
228
229	/**
230	* Execute state load operation.
231	*
232	* @returns VBox status code.
233	* @param pDrvIns Driver instance of the driver which registered the data unit.
234	* @param pSSM SSM operation handle.
235	* @param u32Version Data layout version.
236	*/
237	typedef DECLCALLBACK(int) FNSSMDRVLOADEXEC(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM, uint32_t u32Version);
238	/** Pointer to a FNSSMDRVLOADEXEC() function. */
239	typedef FNSSMDRVLOADEXEC *PFNSSMDRVLOADEXEC;
240
241	/**
242	* Done state load operation.
243	*
244	* @returns VBox load code.
245	* @param pDrvIns Driver instance of the driver which registered the data unit.
246	* @param pSSM SSM operation handle.
247	*/
248	typedef DECLCALLBACK(int) FNSSMDRVLOADDONE(PPDMDRVINS pDrvIns, PSSMHANDLE pSSM);
249	/** Pointer to a FNSSMDRVLOADDONE() function. */
250	typedef FNSSMDRVLOADDONE *PFNSSMDRVLOADDONE;
251
252	/** @} */
253
254
255	/** The internal callback variants.
256	* @{
257	*/
258
259	/**
260	* Prepare state save operation.
261	*
262	* @returns VBox status code.
263	* @param pVM VM Handle.
264	* @param pSSM SSM operation handle.
265	*/
266	typedef DECLCALLBACK(int) FNSSMINTSAVEPREP(PVM pVM, PSSMHANDLE pSSM);
267	/** Pointer to a FNSSMINTSAVEPREP() function. */
268	typedef FNSSMINTSAVEPREP *PFNSSMINTSAVEPREP;
269
270	/**
271	* Execute state save operation.
272	*
273	* @returns VBox status code.
274	* @param pVM VM Handle.
275	* @param pSSM SSM operation handle.
276	*/
277	typedef DECLCALLBACK(int) FNSSMINTSAVEEXEC(PVM pVM, PSSMHANDLE pSSM);
278	/** Pointer to a FNSSMINTSAVEEXEC() function. */
279	typedef FNSSMINTSAVEEXEC *PFNSSMINTSAVEEXEC;
280
281	/**
282	* Done state save operation.
283	*
284	* @returns VBox status code.
285	* @param pVM VM Handle.
286	* @param pSSM SSM operation handle.
287	*/
288	typedef DECLCALLBACK(int) FNSSMINTSAVEDONE(PVM pVM, PSSMHANDLE pSSM);
289	/** Pointer to a FNSSMINTSAVEDONE() function. */
290	typedef FNSSMINTSAVEDONE *PFNSSMINTSAVEDONE;
291
292	/**
293	* Prepare state load operation.
294	*
295	* @returns VBox status code.
296	* @param pVM VM Handle.
297	* @param pSSM SSM operation handle.
298	*/
299	typedef DECLCALLBACK(int) FNSSMINTLOADPREP(PVM pVM, PSSMHANDLE pSSM);
300	/** Pointer to a FNSSMINTLOADPREP() function. */
301	typedef FNSSMINTLOADPREP *PFNSSMINTLOADPREP;
302
303	/**
304	* Execute state load operation.
305	*
306	* @returns VBox status code.
307	* @param pVM VM Handle.
308	* @param pSSM SSM operation handle.
309	* @param u32Version Data layout version.
310	*/
311	typedef DECLCALLBACK(int) FNSSMINTLOADEXEC(PVM pVM, PSSMHANDLE pSSM, uint32_t u32Version);
312	/** Pointer to a FNSSMINTLOADEXEC() function. */
313	typedef FNSSMINTLOADEXEC *PFNSSMINTLOADEXEC;
314
315	/**
316	* Done state load operation.
317	*
318	* @returns VBox load code.
319	* @param pVM VM Handle.
320	* @param pSSM SSM operation handle.
321	*/
322	typedef DECLCALLBACK(int) FNSSMINTLOADDONE(PVM pVM, PSSMHANDLE pSSM);
323	/** Pointer to a FNSSMINTLOADDONE() function. */
324	typedef FNSSMINTLOADDONE *PFNSSMINTLOADDONE;
325
326	/** @} */
327
328
329	/** The External callback variants.
330	* @{
331	*/
332
333	/**
334	* Prepare state save operation.
335	*
336	* @returns VBox status code.
337	* @param pSSM SSM operation handle.
338	* @param pvUser User argument.
339	*/
340	typedef DECLCALLBACK(int) FNSSMEXTSAVEPREP(PSSMHANDLE pSSM, void *pvUser);
341	/** Pointer to a FNSSMEXTSAVEPREP() function. */
342	typedef FNSSMEXTSAVEPREP *PFNSSMEXTSAVEPREP;
343
344	/**
345	* Execute state save operation.
346	*
347	* @param pSSM SSM operation handle.
348	* @param pvUser User argument.
349	* @author The lack of return code is for legacy reasons.
350	*/
351	typedef DECLCALLBACK(void) FNSSMEXTSAVEEXEC(PSSMHANDLE pSSM, void *pvUser);
352	/** Pointer to a FNSSMEXTSAVEEXEC() function. */
353	typedef FNSSMEXTSAVEEXEC *PFNSSMEXTSAVEEXEC;
354
355	/**
356	* Done state save operation.
357	*
358	* @returns VBox status code.
359	* @param pSSM SSM operation handle.
360	* @param pvUser User argument.
361	*/
362	typedef DECLCALLBACK(int) FNSSMEXTSAVEDONE(PSSMHANDLE pSSM, void *pvUser);
363	/** Pointer to a FNSSMEXTSAVEDONE() function. */
364	typedef FNSSMEXTSAVEDONE *PFNSSMEXTSAVEDONE;
365
366	/**
367	* Prepare state load operation.
368	*
369	* @returns VBox status code.
370	* @param pSSM SSM operation handle.
371	* @param pvUser User argument.
372	*/
373	typedef DECLCALLBACK(int) FNSSMEXTLOADPREP(PSSMHANDLE pSSM, void *pvUser);
374	/** Pointer to a FNSSMEXTLOADPREP() function. */
375	typedef FNSSMEXTLOADPREP *PFNSSMEXTLOADPREP;
376
377	/**
378	* Execute state load operation.
379	*
380	* @returns 0 on success.
381	* @returns Not 0 on failure.
382	* @param pSSM SSM operation handle.
383	* @param pvUser User argument.
384	* @param u32Version Data layout version.
385	* @remark The odd return value is for legacy reasons.
386	*/
387	typedef DECLCALLBACK(int) FNSSMEXTLOADEXEC(PSSMHANDLE pSSM, void *pvUser, uint32_t u32Version);
388	/** Pointer to a FNSSMEXTLOADEXEC() function. */
389	typedef FNSSMEXTLOADEXEC *PFNSSMEXTLOADEXEC;
390
391	/**
392	* Done state load operation.
393	*
394	* @returns VBox load code.
395	* @param pSSM SSM operation handle.
396	* @param pvUser User argument.
397	*/
398	typedef DECLCALLBACK(int) FNSSMEXTLOADDONE(PSSMHANDLE pSSM, void *pvUser);
399	/** Pointer to a FNSSMEXTLOADDONE() function. */
400	typedef FNSSMEXTLOADDONE *PFNSSMEXTLOADDONE;
401
402	/** @} */
403
404
405
406	/**
407	* Register a PDM Devices data unit.
408	*
409	* @returns VBox status.
410	* @param pVM The VM handle.
411	* @param pDevIns Device instance.
412	* @param pszName Data unit name.
413	* @param u32Instance The instance identifier of the data unit.
414	* This must together with the name be unique.
415	* @param u32Version Data layout version number.
416	* @param cbGuess The approximate amount of data in the unit.
417	* Only for progress indicators.
418	* @param pfnSavePrep Prepare save callback, optional.
419	* @param pfnSaveExec Execute save callback, optional.
420	* @param pfnSaveDone Done save callback, optional.
421	* @param pfnLoadPrep Prepare load callback, optional.
422	* @param pfnLoadExec Execute load callback, optional.
423	* @param pfnLoadDone Done load callback, optional.
424	*/
425	SSMR3DECL(int) SSMR3Register(PVM pVM, PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
426	PFNSSMDEVSAVEPREP pfnSavePrep, PFNSSMDEVSAVEEXEC pfnSaveExec, PFNSSMDEVSAVEDONE pfnSaveDone,
427	PFNSSMDEVLOADPREP pfnLoadPrep, PFNSSMDEVLOADEXEC pfnLoadExec, PFNSSMDEVLOADDONE pfnLoadDone);
428
429	/**
430	* Register a PDM driver data unit.
431	*
432	* @returns VBox status.
433	* @param pVM The VM handle.
434	* @param pDrvIns Driver instance.
435	* @param pszName Data unit name.
436	* @param u32Instance The instance identifier of the data unit.
437	* This must together with the name be unique.
438	* @param u32Version Data layout version number.
439	* @param cbGuess The approximate amount of data in the unit.
440	* Only for progress indicators.
441	* @param pfnSavePrep Prepare save callback, optional.
442	* @param pfnSaveExec Execute save callback, optional.
443	* @param pfnSaveDone Done save callback, optional.
444	* @param pfnLoadPrep Prepare load callback, optional.
445	* @param pfnLoadExec Execute load callback, optional.
446	* @param pfnLoadDone Done load callback, optional.
447	*/
448	SSMR3DECL(int) SSMR3RegisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
449	PFNSSMDRVSAVEPREP pfnSavePrep, PFNSSMDRVSAVEEXEC pfnSaveExec, PFNSSMDRVSAVEDONE pfnSaveDone,
450	PFNSSMDRVLOADPREP pfnLoadPrep, PFNSSMDRVLOADEXEC pfnLoadExec, PFNSSMDRVLOADDONE pfnLoadDone);
451
452	/**
453	* Register a internal data unit.
454	*
455	* @returns VBox status.
456	* @param pVM The VM handle.
457	* @param pszName Data unit name.
458	* @param u32Instance The instance identifier of the data unit.
459	* This must together with the name be unique.
460	* @param u32Version Data layout version number.
461	* @param cbGuess The approximate amount of data in the unit.
462	* Only for progress indicators.
463	* @param pfnSavePrep Prepare save callback, optional.
464	* @param pfnSaveExec Execute save callback, optional.
465	* @param pfnSaveDone Done save callback, optional.
466	* @param pfnLoadPrep Prepare load callback, optional.
467	* @param pfnLoadExec Execute load callback, optional.
468	* @param pfnLoadDone Done load callback, optional.
469	*/
470	SSMR3DECL(int) SSMR3RegisterInternal(PVM pVM, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
471	PFNSSMINTSAVEPREP pfnSavePrep, PFNSSMINTSAVEEXEC pfnSaveExec, PFNSSMINTSAVEDONE pfnSaveDone,
472	PFNSSMINTLOADPREP pfnLoadPrep, PFNSSMINTLOADEXEC pfnLoadExec, PFNSSMINTLOADDONE pfnLoadDone);
473
474	/**
475	* Register a unit.
476	*
477	* @returns VBox status.
478	* @param pVM The VM handle.
479	* @param pszName Data unit name.
480	* @param u32Instance The instance identifier of the data unit.
481	* This must together with the name be unique.
482	* @param u32Version Data layout version number.
483	* @param cbGuess The approximate amount of data in the unit.
484	* Only for progress indicators.
485	* @param pfnSavePrep Prepare save callback, optional.
486	* @param pfnSaveExec Execute save callback, optional.
487	* @param pfnSaveDone Done save callback, optional.
488	* @param pfnLoadPrep Prepare load callback, optional.
489	* @param pfnLoadExec Execute load callback, optional.
490	* @param pfnLoadDone Done load callback, optional.
491	* @param pvUser User argument.
492	*/
493	SSMR3DECL(int) SSMR3RegisterExternal(PVM pVM, const char *pszName, uint32_t u32Instance, uint32_t u32Version, size_t cbGuess,
494	PFNSSMEXTSAVEPREP pfnSavePrep, PFNSSMEXTSAVEEXEC pfnSaveExec, PFNSSMEXTSAVEDONE pfnSaveDone,
495	PFNSSMEXTLOADPREP pfnLoadPrep, PFNSSMEXTLOADEXEC pfnLoadExec, PFNSSMEXTLOADDONE pfnLoadDone, void *pvUser);
496
497	/**
498	* Deregister one or more PDM Device data units.
499	*
500	* @returns VBox status.
501	* @param pVM The VM handle.
502	* @param pDevIns Device instance.
503	* @param pszName Data unit name.
504	* Use NULL to deregister all data units for that device instance.
505	* @param u32Instance The instance identifier of the data unit.
506	* This must together with the name be unique. Ignored if pszName is NULL.
507	* @remark Only for dynmaic data units and dynamic unloaded modules.
508	*/
509	SSMR3DECL(int) SSMR3Deregister(PVM pVM, PPDMDEVINS pDevIns, const char *pszName, uint32_t u32Instance);
510
511	/**
512	* Deregister one or more PDM Driver data units.
513	*
514	* @returns VBox status.
515	* @param pVM The VM handle.
516	* @param pDrvIns Driver instance.
517	* @param pszName Data unit name.
518	* Use NULL to deregister all data units for that driver instance.
519	* @param u32Instance The instance identifier of the data unit.
520	* This must together with the name be unique. Ignored if pszName is NULL.
521	* @remark Only for dynmaic data units and dynamic unloaded modules.
522	*/
523	SSMR3DECL(int) SSMR3DeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName, uint32_t u32Instance);
524
525	/**
526	* Deregister a internal data unit.
527	*
528	* @returns VBox status.
529	* @param pVM The VM handle.
530	* @param pszName Data unit name.
531	* @remark Only for dynmaic data units.
532	*/
533	SSMR3DECL(int) SSMR3DeregisterInternal(PVM pVM, const char *pszName);
534
535	/**
536	* Deregister an external data unit.
537	*
538	* @returns VBox status.
539	* @param pVM The VM handle.
540	* @param pszName Data unit name.
541	* @remark Only for dynmaic data units.
542	*/
543	SSMR3DECL(int) SSMR3DeregisterExternal(PVM pVM, const char *pszName);
544
545	/**
546	* Start VM save operation.
547	*
548	* The caller must be the emulation thread!
549	*
550	* @returns VBox status.
551	* @param pVM The VM handle.
552	* @param pszFilename Name of the file to save the state in.
553	* @param enmAfter What is planned after a successful save operation.
554	* @param pfnProgress Progress callback. Optional.
555	* @param pvUser User argument for the progress callback.
556	*/
557	SSMR3DECL(int) SSMR3Save(PVM pVM, const char pszFilename, SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void pvUser);
558
559	/**
560	* Load VM save operation.
561	*
562	* The caller must be the emulation thread!
563	*
564	* @returns VBox status.
565	* @param pVM The VM handle.
566	* @param pszFilename Name of the file to save the state in.
567	* @param enmAfter What is planned after a successful load operation.
568	* Only acceptable values are SSMAFTER_RESUME and SSMAFTER_DEBUG_IT.
569	* @param pfnProgress Progress callback. Optional.
570	* @param pvUser User argument for the progress callback.
571	*/
572	SSMR3DECL(int) SSMR3Load(PVM pVM, const char pszFilename, SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void pvUser);
573
574	/**
575	* Validates a file as a validate SSM saved state.
576	*
577	* This will only verify the file format, the format and content of individual
578	* data units are not inspected.
579	*
580	* @returns VINF_SUCCESS if valid.
581	* @returns VBox status code on other failures.
582	* @param pszFilename The path to the file to validate.
583	*/
584	SSMR3DECL(int) SSMR3ValidateFile(const char *pszFilename);
585
586	/**
587	* Opens a saved state file for reading.
588	*
589	* @returns VBox status code.
590	* @param pszFilename The path to the saved state file.
591	* @param fFlags Open flags. Reserved, must be 0.
592	* @param ppSSM Where to store the SSM handle.
593	*/
594	SSMR3DECL(int) SSMR3Open(const char pszFilename, unsigned fFlags, PSSMHANDLE ppSSM);
595
596	/**
597	* Closes a saved state file opened by SSMR3Open().
598	*
599	* @returns VBox status code.
600	* @param pSSM The SSM handle returned by SSMR3Open().
601	*/
602	SSMR3DECL(int) SSMR3Close(PSSMHANDLE pSSM);
603
604	/**
605	* Seeks to a specific data unit.
606	*
607	* After seeking it's possible to use the getters to on
608	* that data unit.
609	*
610	* @returns VBox status code.
611	* @returns VERR_SSM_UNIT_NOT_FOUND if the unit+instance wasn't found.
612	* @param pSSM The SSM handle returned by SSMR3Open().
613	* @param pszUnit The name of the data unit.
614	* @param iInstance The instance number.
615	* @param piVersion Where to store the version number. (Optional)
616	*/
617	SSMR3DECL(int) SSMR3Seek(PSSMHANDLE pSSM, const char pszUnit, uint32_t iInstance, uint32_t piVersion);
618
619
620	/** Save operations.
621	* @{
622	*/
623
624	/**
625	* Puts a structure.
626	*
627	* @returns VBox status code.
628	* @param pSSM The saved state handle.
629	* @param pvStruct The structure address.
630	* @param paFields The array of structure fields descriptions.
631	* The array must be terminated by a SSMFIELD_ENTRY_TERM().
632	*/
633	SSMR3DECL(int) SSMR3PutStruct(PSSMHANDLE pSSM, const void *pvStruct, PCSSMFIELD paFields);
634
635	/**
636	* Saves a boolean item to the current data unit.
637	*
638	* @returns VBox status.
639	* @param pSSM SSM operation handle.
640	* @param fBool Item to save.
641	*/
642	SSMR3DECL(int) SSMR3PutBool(PSSMHANDLE pSSM, bool fBool);
643
644	/**
645	* Saves a 8-bit unsigned integer item to the current data unit.
646	*
647	* @returns VBox status.
648	* @param pSSM SSM operation handle.
649	* @param u8 Item to save.
650	*/
651	SSMR3DECL(int) SSMR3PutU8(PSSMHANDLE pSSM, uint8_t u8);
652
653	/**
654	* Saves a 8-bit signed integer item to the current data unit.
655	*
656	* @returns VBox status.
657	* @param pSSM SSM operation handle.
658	* @param i8 Item to save.
659	*/
660	SSMR3DECL(int) SSMR3PutS8(PSSMHANDLE pSSM, int8_t i8);
661
662	/**
663	* Saves a 16-bit unsigned integer item to the current data unit.
664	*
665	* @returns VBox status.
666	* @param pSSM SSM operation handle.
667	* @param u16 Item to save.
668	*/
669	SSMR3DECL(int) SSMR3PutU16(PSSMHANDLE pSSM, uint16_t u16);
670
671	/**
672	* Saves a 16-bit signed integer item to the current data unit.
673	*
674	* @returns VBox status.
675	* @param pSSM SSM operation handle.
676	* @param i16 Item to save.
677	*/
678	SSMR3DECL(int) SSMR3PutS16(PSSMHANDLE pSSM, int16_t i16);
679
680	/**
681	* Saves a 32-bit unsigned integer item to the current data unit.
682	*
683	* @returns VBox status.
684	* @param pSSM SSM operation handle.
685	* @param u32 Item to save.
686	*/
687	SSMR3DECL(int) SSMR3PutU32(PSSMHANDLE pSSM, uint32_t u32);
688
689	/**
690	* Saves a 32-bit signed integer item to the current data unit.
691	*
692	* @returns VBox status.
693	* @param pSSM SSM operation handle.
694	* @param i32 Item to save.
695	*/
696	SSMR3DECL(int) SSMR3PutS32(PSSMHANDLE pSSM, int32_t i32);
697
698	/**
699	* Saves a 64-bit unsigned integer item to the current data unit.
700	*
701	* @returns VBox status.
702	* @param pSSM SSM operation handle.
703	* @param u64 Item to save.
704	*/
705	SSMR3DECL(int) SSMR3PutU64(PSSMHANDLE pSSM, uint64_t u64);
706
707	/**
708	* Saves a 64-bit signed integer item to the current data unit.
709	*
710	* @returns VBox status.
711	* @param pSSM SSM operation handle.
712	* @param i64 Item to save.
713	*/
714	SSMR3DECL(int) SSMR3PutS64(PSSMHANDLE pSSM, int64_t i64);
715
716	/**
717	* Saves a 128-bit unsigned integer item to the current data unit.
718	*
719	* @returns VBox status.
720	* @param pSSM SSM operation handle.
721	* @param u128 Item to save.
722	*/
723	SSMR3DECL(int) SSMR3PutU128(PSSMHANDLE pSSM, uint128_t u128);
724
725	/**
726	* Saves a 128-bit signed integer item to the current data unit.
727	*
728	* @returns VBox status.
729	* @param pSSM SSM operation handle.
730	* @param i128 Item to save.
731	*/
732	SSMR3DECL(int) SSMR3PutS128(PSSMHANDLE pSSM, int128_t i128);
733
734	/**
735	* Saves a VBox unsigned integer item to the current data unit.
736	*
737	* @returns VBox status.
738	* @param pSSM SSM operation handle.
739	* @param u Item to save.
740	*/
741	SSMR3DECL(int) SSMR3PutUInt(PSSMHANDLE pSSM, RTUINT u);
742
743	/**
744	* Saves a VBox signed integer item to the current data unit.
745	*
746	* @returns VBox status.
747	* @param pSSM SSM operation handle.
748	* @param i Item to save.
749	*/
750	SSMR3DECL(int) SSMR3PutSInt(PSSMHANDLE pSSM, RTINT i);
751
752	/**
753	* Saves a GC natural unsigned integer item to the current data unit.
754	*
755	* @returns VBox status.
756	* @param pSSM SSM operation handle.
757	* @param u Item to save.
758	*/
759	SSMR3DECL(int) SSMR3PutGCUInt(PSSMHANDLE pSSM, RTGCUINT u);
760
761	/**
762	* Saves a GC natural signed integer item to the current data unit.
763	*
764	* @returns VBox status.
765	* @param pSSM SSM operation handle.
766	* @param i Item to save.
767	*/
768	SSMR3DECL(int) SSMR3PutGCSInt(PSSMHANDLE pSSM, RTGCINT i);
769
770	/**
771	* Saves a GC physical address item to the current data unit.
772	*
773	* @returns VBox status.
774	* @param pSSM SSM operation handle.
775	* @param GCPhys The item to save
776	*/
777	SSMR3DECL(int) SSMR3PutGCPhys(PSSMHANDLE pSSM, RTGCPHYS GCPhys);
778
779	/**
780	* Saves a GC virtual address item to the current data unit.
781	*
782	* @returns VBox status.
783	* @param pSSM SSM operation handle.
784	* @param GCPtr The item to save.
785	*/
786	SSMR3DECL(int) SSMR3PutGCPtr(PSSMHANDLE pSSM, RTGCPTR GCPtr);
787
788	/**
789	* Saves a GC virtual address (represented as an unsigned integer) item to the current data unit.
790	*
791	* @returns VBox status.
792	* @param pSSM SSM operation handle.
793	* @param GCPtr The item to save.
794	*/
795	SSMR3DECL(int) SSMR3PutGCUIntPtr(PSSMHANDLE pSSM, RTGCUINTPTR GCPtr);
796
797	/**
798	* Saves a HC natural unsigned integer item to the current data unit.
799	*
800	* @returns VBox status.
801	* @param pSSM SSM operation handle.
802	* @param u Item to save.
803	*/
804	SSMR3DECL(int) SSMR3PutHCUInt(PSSMHANDLE pSSM, RTHCUINT u);
805
806	/**
807	* Saves a HC natural signed integer item to the current data unit.
808	*
809	* @returns VBox status.
810	* @param pSSM SSM operation handle.
811	* @param i Item to save.
812	*/
813	SSMR3DECL(int) SSMR3PutHCSInt(PSSMHANDLE pSSM, RTHCINT i);
814
815	/**
816	* Saves a I/O port address item to the current data unit.
817	*
818	* @returns VBox status.
819	* @param pSSM SSM operation handle.
820	* @param IOPort The item to save.
821	*/
822	SSMR3DECL(int) SSMR3PutIOPort(PSSMHANDLE pSSM, RTIOPORT IOPort);
823
824	/**
825	* Saves a selector item to the current data unit.
826	*
827	* @returns VBox status.
828	* @param pSSM SSM operation handle.
829	* @param Sel The item to save.
830	*/
831	SSMR3DECL(int) SSMR3PutSel(PSSMHANDLE pSSM, RTSEL Sel);
832
833	/**
834	* Saves a memory item to the current data unit.
835	*
836	* @returns VBox status.
837	* @param pSSM SSM operation handle.
838	* @param pv Item to save.
839	* @param cb Size of the item.
840	*/
841	SSMR3DECL(int) SSMR3PutMem(PSSMHANDLE pSSM, const void *pv, size_t cb);
842
843	/**
844	* Saves a zero terminated string item to the current data unit.
845	*
846	* @returns VBox status.
847	* @param pSSM SSM operation handle.
848	* @param psz Item to save.
849	*/
850	SSMR3DECL(int) SSMR3PutStrZ(PSSMHANDLE pSSM, const char *psz);
851
852	/** @} */
853
854
855
856	/** Load operations.
857	* @{
858	*/
859
860	/**
861	* Gets a structure.
862	*
863	* @returns VBox status code.
864	* @param pSSM The saved state handle.
865	* @param pvStruct The structure address.
866	* @param paFields The array of structure fields descriptions.
867	* The array must be terminated by a SSMFIELD_ENTRY_TERM().
868	*/
869	SSMR3DECL(int) SSMR3GetStruct(PSSMHANDLE pSSM, void *pvStruct, PCSSMFIELD paFields);
870
871	/**
872	* Loads a boolean item from the current data unit.
873	*
874	* @returns VBox status.
875	* @param pSSM SSM operation handle.
876	* @param pfBool Where to store the item.
877	*/
878	SSMR3DECL(int) SSMR3GetBool(PSSMHANDLE pSSM, bool *pfBool);
879
880	/**
881	* Loads a 8-bit unsigned integer item from the current data unit.
882	*
883	* @returns VBox status.
884	* @param pSSM SSM operation handle.
885	* @param pu8 Where to store the item.
886	*/
887	SSMR3DECL(int) SSMR3GetU8(PSSMHANDLE pSSM, uint8_t *pu8);
888
889	/**
890	* Loads a 8-bit signed integer item from the current data unit.
891	*
892	* @returns VBox status.
893	* @param pSSM SSM operation handle.
894	* @param pi8 Where to store the item.
895	*/
896	SSMR3DECL(int) SSMR3GetS8(PSSMHANDLE pSSM, int8_t *pi8);
897
898	/**
899	* Loads a 16-bit unsigned integer item from the current data unit.
900	*
901	* @returns VBox status.
902	* @param pSSM SSM operation handle.
903	* @param pu16 Where to store the item.
904	*/
905	SSMR3DECL(int) SSMR3GetU16(PSSMHANDLE pSSM, uint16_t *pu16);
906
907	/**
908	* Loads a 16-bit signed integer item from the current data unit.
909	*
910	* @returns VBox status.
911	* @param pSSM SSM operation handle.
912	* @param pi16 Where to store the item.
913	*/
914	SSMR3DECL(int) SSMR3GetS16(PSSMHANDLE pSSM, int16_t *pi16);
915
916	/**
917	* Loads a 32-bit unsigned integer item from the current data unit.
918	*
919	* @returns VBox status.
920	* @param pSSM SSM operation handle.
921	* @param pu32 Where to store the item.
922	*/
923	SSMR3DECL(int) SSMR3GetU32(PSSMHANDLE pSSM, uint32_t *pu32);
924
925	/**
926	* Loads a 32-bit signed integer item from the current data unit.
927	*
928	* @returns VBox status.
929	* @param pSSM SSM operation handle.
930	* @param pi32 Where to store the item.
931	*/
932	SSMR3DECL(int) SSMR3GetS32(PSSMHANDLE pSSM, int32_t *pi32);
933
934	/**
935	* Loads a 64-bit unsigned integer item from the current data unit.
936	*
937	* @returns VBox status.
938	* @param pSSM SSM operation handle.
939	* @param pu64 Where to store the item.
940	*/
941	SSMR3DECL(int) SSMR3GetU64(PSSMHANDLE pSSM, uint64_t *pu64);
942
943	/**
944	* Loads a 64-bit signed integer item from the current data unit.
945	*
946	* @returns VBox status.
947	* @param pSSM SSM operation handle.
948	* @param pi64 Where to store the item.
949	*/
950	SSMR3DECL(int) SSMR3GetS64(PSSMHANDLE pSSM, int64_t *pi64);
951
952	/**
953	* Loads a 128-bit unsigned integer item from the current data unit.
954	*
955	* @returns VBox status.
956	* @param pSSM SSM operation handle.
957	* @param pu128 Where to store the item.
958	*/
959	SSMR3DECL(int) SSMR3GetU128(PSSMHANDLE pSSM, uint128_t *pu128);
960
961	/**
962	* Loads a 128-bit signed integer item from the current data unit.
963	*
964	* @returns VBox status.
965	* @param pSSM SSM operation handle.
966	* @param pi128 Where to store the item.
967	*/
968	SSMR3DECL(int) SSMR3GetS128(PSSMHANDLE pSSM, int128_t *pi128);
969
970	/**
971	* Loads a VBox unsigned integer item from the current data unit.
972	*
973	* @returns VBox status.
974	* @param pSSM SSM operation handle.
975	* @param pu Where to store the integer.
976	*/
977	SSMR3DECL(int) SSMR3GetUInt(PSSMHANDLE pSSM, PRTUINT pu);
978
979	/**
980	* Loads a VBox signed integer item from the current data unit.
981	*
982	* @returns VBox status.
983	* @param pSSM SSM operation handle.
984	* @param pi Where to store the integer.
985	*/
986	SSMR3DECL(int) SSMR3GetSInt(PSSMHANDLE pSSM, PRTINT pi);
987
988	/**
989	* Loads a GC natural unsigned integer item from the current data unit.
990	*
991	* @returns VBox status.
992	* @param pSSM SSM operation handle.
993	* @param pu Where to store the integer.
994	*/
995	SSMR3DECL(int) SSMR3GetGCUInt(PSSMHANDLE pSSM, PRTGCUINT pu);
996
997	/**
998	* Loads a GC natural signed integer item from the current data unit.
999	*
1000	* @returns VBox status.
1001	* @param pSSM SSM operation handle.
1002	* @param pi Where to store the integer.
1003	*/
1004	SSMR3DECL(int) SSMR3GetGCSInt(PSSMHANDLE pSSM, PRTGCINT pi);
1005
1006	/**
1007	* Loads a GC physical address item from the current data unit.
1008	*
1009	* @returns VBox status.
1010	* @param pSSM SSM operation handle.
1011	* @param pGCPhys Where to store the GC physical address.
1012	*/
1013	SSMR3DECL(int) SSMR3GetGCPhys(PSSMHANDLE pSSM, PRTGCPHYS pGCPhys);
1014
1015	/**
1016	* Loads a GC virtual address item from the current data unit.
1017	*
1018	* @returns VBox status.
1019	* @param pSSM SSM operation handle.
1020	* @param pGCPtr Where to store the GC virtual address.
1021	*/
1022	SSMR3DECL(int) SSMR3GetGCPtr(PSSMHANDLE pSSM, PRTGCPTR pGCPtr);
1023
1024	/**
1025	* Loads a GC virtual address (represented as unsigned integer) item from the current data unit.
1026	*
1027	* @returns VBox status.
1028	* @param pSSM SSM operation handle.
1029	* @param pGCPtr Where to store the GC virtual address.
1030	*/
1031	SSMR3DECL(int) SSMR3GetGCUIntPtr(PSSMHANDLE pSSM, PRTGCUINTPTR pGCPtr);
1032
1033	/**
1034	* Loads a I/O port address item from the current data unit.
1035	*
1036	* @returns VBox status.
1037	* @param pSSM SSM operation handle.
1038	* @param pIOPort Where to store the I/O port address.
1039	*/
1040	SSMR3DECL(int) SSMR3GetIOPort(PSSMHANDLE pSSM, PRTIOPORT pIOPort);
1041
1042	/**
1043	* Loads a HC natural unsigned integer item from the current data unit.
1044	*
1045	* @returns VBox status.
1046	* @param pSSM SSM operation handle.
1047	* @param pu Where to store the integer.
1048	*/
1049	SSMR3DECL(int) SSMR3GetHCUInt(PSSMHANDLE pSSM, PRTHCUINT pu);
1050
1051	/**
1052	* Loads a HC natural signed integer item from the current data unit.
1053	*
1054	* @returns VBox status.
1055	* @param pSSM SSM operation handle.
1056	* @param pi Where to store the integer.
1057	*/
1058	SSMR3DECL(int) SSMR3GetHCSInt(PSSMHANDLE pSSM, PRTHCINT pi);
1059
1060	/**
1061	* Loads a selector item from the current data unit.
1062	*
1063	* @returns VBox status.
1064	* @param pSSM SSM operation handle.
1065	* @param pSel Where to store the selector.
1066	*/
1067	SSMR3DECL(int) SSMR3GetSel(PSSMHANDLE pSSM, PRTSEL pSel);
1068
1069	/**
1070	* Loads a memory item from the current data unit.
1071	*
1072	* @returns VBox status.
1073	* @param pSSM SSM operation handle.
1074	* @param pv Where to store the item.
1075	* @param cb Size of the item.
1076	*/
1077	SSMR3DECL(int) SSMR3GetMem(PSSMHANDLE pSSM, void *pv, size_t cb);
1078
1079	/**
1080	* Loads a string item from the current data unit.
1081	*
1082	* @returns VBox status.
1083	* @param pSSM SSM operation handle.
1084	* @param psz Where to store the item.
1085	* @param cbMax Max size of the item (including '\\0').
1086	*/
1087	SSMR3DECL(int) SSMR3GetStrZ(PSSMHANDLE pSSM, char *psz, size_t cbMax);
1088
1089	/**
1090	* Loads a string item from the current data unit.
1091	*
1092	* @returns VBox status.
1093	* @param pSSM SSM operation handle.
1094	* @param psz Where to store the item.
1095	* @param cbMax Max size of the item (including '\\0').
1096	* @param pcbStr The length of the loaded string excluding the '\\0'. (optional)
1097	*/
1098	SSMR3DECL(int) SSMR3GetStrZEx(PSSMHANDLE pSSM, char psz, size_t cbMax, size_t pcbStr);
1099
1100	/**
1101	* Loads a timer item from the current data unit.
1102	*
1103	* @returns VBox status.
1104	* @param pSSM SSM operation handle.
1105	* @param PTMTIMER Where to store the item.
1106	*/
1107	SSMR3DECL(int) SSMR3GetTimer(PSSMHANDLE pSSM, PTMTIMER pTimer);
1108
1109	/** @} */
1110
1111
1112
1113	/**
1114	* Query what the VBox status code of the operation is.
1115	*
1116	* This can be used for putting and getting a batch of values
1117	* without bother checking the result till all the calls have
1118	* been made.
1119	*
1120	* @returns VBox status code.
1121	* @param pSSM SSM operation handle.
1122	*/
1123	SSMR3DECL(int) SSMR3HandleGetStatus(PSSMHANDLE pSSM);
1124
1125	/**
1126	* Fail the load operation.
1127	*
1128	* This is mainly intended for sub item loaders (like timers) which
1129	* return code isn't necessarily heeded by the caller but is important
1130	* to SSM.
1131	*
1132	* @returns SSMAFTER enum value.
1133	* @param pSSM SSM operation handle.
1134	* @param iStatus Failure status code. This MUST be a VERR_*.
1135	*/
1136	SSMR3DECL(int) SSMR3HandleSetStatus(PSSMHANDLE pSSM, int iStatus);
1137
1138	/**
1139	* Query what to do after this operation.
1140	*
1141	* @returns SSMAFTER enum value.
1142	* @param pSSM SSM operation handle.
1143	*/
1144	SSMR3DECL(SSMAFTER) SSMR3HandleGetAfter(PSSMHANDLE pSSM);
1145
1146	/** @} */
1147	#endif /* IN_RING3 */
1148
1149
1150	/** @} */
1151
1152	__END_DECLS
1153
1154	#endif
1155

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

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

Download in other formats: