ssm.h@ 3641

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

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

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

Download in other formats: