ssm.h@ 3291

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

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

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

Download in other formats: