ssm.h@ 659

Last change on this file since 659 was 1, checked in by vboxsync, 55 years ago
import
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 35.0 KB

Line
1	/** @file
2	* SSM - The Save State Manager.
3	*/
4
5	/*
6	* Copyright (C) 2006 InnoTek Systemberatung 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	* Start VM save operation.
510	*
511	* The caller must be the emulation thread!
512	*
513	* @returns VBox status.
514	* @param pVM The VM handle.
515	* @param pszFilename Name of the file to save the state in.
516	* @param enmAfter What is planned after a successful save operation.
517	* @param pfnProgress Progress callback. Optional.
518	* @param pvUser User argument for the progress callback.
519	*/
520	SSMR3DECL(int) SSMR3Save(PVM pVM, const char pszFilename, SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void pvUser);
521
522	/**
523	* Load VM save operation.
524	*
525	* The caller must be the emulation thread!
526	*
527	* @returns VBox status.
528	* @param pVM The VM handle.
529	* @param pszFilename Name of the file to save the state in.
530	* @param enmAfter What is planned after a successful save operation.
531	* @param pfnProgress Progress callback. Optional.
532	* @param pvUser User argument for the progress callback.
533	*/
534	SSMR3DECL(int) SSMR3Load(PVM pVM, const char pszFilename, SSMAFTER enmAfter, PFNVMPROGRESS pfnProgress, void pvUser);
535
536	/**
537	* Validates a file as a validate SSM saved state.
538	*
539	* This will only verify the file format, the format and content of individual
540	* data units are not inspected.
541	*
542	* @returns VINF_SUCCESS if valid.
543	* @returns VBox status code on other failures.
544	* @param pszFilename The path to the file to validate.
545	*/
546	SSMR3DECL(int) SSMR3ValidateFile(const char *pszFilename);
547
548	/**
549	* Opens a saved state file for reading.
550	*
551	* @returns VBox status code.
552	* @param pszFilename The path to the saved state file.
553	* @param fFlags Open flags. Reserved, must be 0.
554	* @param ppSSM Where to store the SSM handle.
555	*/
556	SSMR3DECL(int) SSMR3Open(const char pszFilename, unsigned fFlags, PSSMHANDLE ppSSM);
557
558	/**
559	* Closes a saved state file opened by SSMR3Open().
560	*
561	* @returns VBox status code.
562	* @param pSSM The SSM handle returned by SSMR3Open().
563	*/
564	SSMR3DECL(int) SSMR3Close(PSSMHANDLE pSSM);
565
566	/**
567	* Seeks to a specific data unit.
568	*
569	* After seeking it's possible to use the getters to on
570	* that data unit.
571	*
572	* @returns VBox status code.
573	* @returns VERR_SSM_UNIT_NOT_FOUND if the unit+instance wasn't found.
574	* @param pSSM The SSM handle returned by SSMR3Open().
575	* @param pszUnit The name of the data unit.
576	* @param iInstance The instance number.
577	* @param piVersion Where to store the version number. (Optional)
578	*/
579	SSMR3DECL(int) SSMR3Seek(PSSMHANDLE pSSM, const char pszUnit, uint32_t iInstance, uint32_t piVersion);
580
581
582	/** Save operations.
583	* @{
584	*/
585
586	/**
587	* Puts a structure.
588	*
589	* @returns VBox status code.
590	* @param pSSM The saved state handle.
591	* @param pvStruct The structure address.
592	* @param paFields The array of structure fields descriptions.
593	* The array must be terminated by a SSMFIELD_ENTRY_TERM().
594	*/
595	SSMR3DECL(int) SSMR3PutStruct(PSSMHANDLE pSSM, const void *pvStruct, PCSSMFIELD paFields);
596
597	/**
598	* Saves a boolean item to the current data unit.
599	*
600	* @returns VBox status.
601	* @param pSSM SSM operation handle.
602	* @param fBool Item to save.
603	*/
604	SSMR3DECL(int) SSMR3PutBool(PSSMHANDLE pSSM, bool fBool);
605
606	/**
607	* Saves a 8-bit unsigned integer item to the current data unit.
608	*
609	* @returns VBox status.
610	* @param pSSM SSM operation handle.
611	* @param u8 Item to save.
612	*/
613	SSMR3DECL(int) SSMR3PutU8(PSSMHANDLE pSSM, uint8_t u8);
614
615	/**
616	* Saves a 8-bit signed integer item to the current data unit.
617	*
618	* @returns VBox status.
619	* @param pSSM SSM operation handle.
620	* @param i8 Item to save.
621	*/
622	SSMR3DECL(int) SSMR3PutS8(PSSMHANDLE pSSM, int8_t i8);
623
624	/**
625	* Saves a 16-bit unsigned integer item to the current data unit.
626	*
627	* @returns VBox status.
628	* @param pSSM SSM operation handle.
629	* @param u16 Item to save.
630	*/
631	SSMR3DECL(int) SSMR3PutU16(PSSMHANDLE pSSM, uint16_t u16);
632
633	/**
634	* Saves a 16-bit signed integer item to the current data unit.
635	*
636	* @returns VBox status.
637	* @param pSSM SSM operation handle.
638	* @param i16 Item to save.
639	*/
640	SSMR3DECL(int) SSMR3PutS16(PSSMHANDLE pSSM, int16_t i16);
641
642	/**
643	* Saves a 32-bit unsigned integer item to the current data unit.
644	*
645	* @returns VBox status.
646	* @param pSSM SSM operation handle.
647	* @param u32 Item to save.
648	*/
649	SSMR3DECL(int) SSMR3PutU32(PSSMHANDLE pSSM, uint32_t u32);
650
651	/**
652	* Saves a 32-bit signed integer item to the current data unit.
653	*
654	* @returns VBox status.
655	* @param pSSM SSM operation handle.
656	* @param i32 Item to save.
657	*/
658	SSMR3DECL(int) SSMR3PutS32(PSSMHANDLE pSSM, int32_t i32);
659
660	/**
661	* Saves a 64-bit unsigned integer item to the current data unit.
662	*
663	* @returns VBox status.
664	* @param pSSM SSM operation handle.
665	* @param u64 Item to save.
666	*/
667	SSMR3DECL(int) SSMR3PutU64(PSSMHANDLE pSSM, uint64_t u64);
668
669	/**
670	* Saves a 64-bit signed integer item to the current data unit.
671	*
672	* @returns VBox status.
673	* @param pSSM SSM operation handle.
674	* @param i64 Item to save.
675	*/
676	SSMR3DECL(int) SSMR3PutS64(PSSMHANDLE pSSM, int64_t i64);
677
678	/**
679	* Saves a 128-bit unsigned integer item to the current data unit.
680	*
681	* @returns VBox status.
682	* @param pSSM SSM operation handle.
683	* @param u128 Item to save.
684	*/
685	SSMR3DECL(int) SSMR3PutU128(PSSMHANDLE pSSM, uint128_t u128);
686
687	/**
688	* Saves a 128-bit signed integer item to the current data unit.
689	*
690	* @returns VBox status.
691	* @param pSSM SSM operation handle.
692	* @param i128 Item to save.
693	*/
694	SSMR3DECL(int) SSMR3PutS128(PSSMHANDLE pSSM, int128_t i128);
695
696	/**
697	* Saves a VBox unsigned integer item to the current data unit.
698	*
699	* @returns VBox status.
700	* @param pSSM SSM operation handle.
701	* @param u Item to save.
702	*/
703	SSMR3DECL(int) SSMR3PutUInt(PSSMHANDLE pSSM, RTUINT u);
704
705	/**
706	* Saves a VBox signed integer item to the current data unit.
707	*
708	* @returns VBox status.
709	* @param pSSM SSM operation handle.
710	* @param i Item to save.
711	*/
712	SSMR3DECL(int) SSMR3PutSInt(PSSMHANDLE pSSM, RTINT i);
713
714	/**
715	* Saves a GC natural unsigned integer item to the current data unit.
716	*
717	* @returns VBox status.
718	* @param pSSM SSM operation handle.
719	* @param u Item to save.
720	*/
721	SSMR3DECL(int) SSMR3PutGCUInt(PSSMHANDLE pSSM, RTGCUINT u);
722
723	/**
724	* Saves a GC natural signed integer item to the current data unit.
725	*
726	* @returns VBox status.
727	* @param pSSM SSM operation handle.
728	* @param i Item to save.
729	*/
730	SSMR3DECL(int) SSMR3PutGCSInt(PSSMHANDLE pSSM, RTGCINT i);
731
732	/**
733	* Saves a GC physical address item to the current data unit.
734	*
735	* @returns VBox status.
736	* @param pSSM SSM operation handle.
737	* @param GCPhys The item to save
738	*/
739	SSMR3DECL(int) SSMR3PutGCPhys(PSSMHANDLE pSSM, RTGCPHYS GCPhys);
740
741	/**
742	* Saves a GC virtual address item to the current data unit.
743	*
744	* @returns VBox status.
745	* @param pSSM SSM operation handle.
746	* @param GCPtr The item to save.
747	*/
748	SSMR3DECL(int) SSMR3PutGCPtr(PSSMHANDLE pSSM, RTGCPTR GCPtr);
749
750	/**
751	* Saves a GC virtual address (represented as an unsigned integer) 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) SSMR3PutGCUIntPtr(PSSMHANDLE pSSM, RTGCUINTPTR GCPtr);
758
759	/**
760	* Saves a HC natural unsigned integer item to the current data unit.
761	*
762	* @returns VBox status.
763	* @param pSSM SSM operation handle.
764	* @param u Item to save.
765	*/
766	SSMR3DECL(int) SSMR3PutHCUInt(PSSMHANDLE pSSM, RTHCUINT u);
767
768	/**
769	* Saves a HC natural signed integer item to the current data unit.
770	*
771	* @returns VBox status.
772	* @param pSSM SSM operation handle.
773	* @param i Item to save.
774	*/
775	SSMR3DECL(int) SSMR3PutHCSInt(PSSMHANDLE pSSM, RTHCINT i);
776
777	/**
778	* Saves a I/O port address item to the current data unit.
779	*
780	* @returns VBox status.
781	* @param pSSM SSM operation handle.
782	* @param IOPort The item to save.
783	*/
784	SSMR3DECL(int) SSMR3PutIOPort(PSSMHANDLE pSSM, RTIOPORT IOPort);
785
786	/**
787	* Saves a selector item to the current data unit.
788	*
789	* @returns VBox status.
790	* @param pSSM SSM operation handle.
791	* @param Sel The item to save.
792	*/
793	SSMR3DECL(int) SSMR3PutSel(PSSMHANDLE pSSM, RTSEL Sel);
794
795	/**
796	* Saves a memory item to the current data unit.
797	*
798	* @returns VBox status.
799	* @param pSSM SSM operation handle.
800	* @param pv Item to save.
801	* @param cb Size of the item.
802	*/
803	SSMR3DECL(int) SSMR3PutMem(PSSMHANDLE pSSM, const void *pv, size_t cb);
804
805	/**
806	* Saves a zero terminated string item to the current data unit.
807	*
808	* @returns VBox status.
809	* @param pSSM SSM operation handle.
810	* @param psz Item to save.
811	*/
812	SSMR3DECL(int) SSMR3PutStrZ(PSSMHANDLE pSSM, const char *psz);
813
814	/** @} */
815
816
817
818	/** Load operations.
819	* @{
820	*/
821
822	/**
823	* Gets a structure.
824	*
825	* @returns VBox status code.
826	* @param pSSM The saved state handle.
827	* @param pvStruct The structure address.
828	* @param paFields The array of structure fields descriptions.
829	* The array must be terminated by a SSMFIELD_ENTRY_TERM().
830	*/
831	SSMR3DECL(int) SSMR3GetStruct(PSSMHANDLE pSSM, void *pvStruct, PCSSMFIELD paFields);
832
833	/**
834	* Loads a boolean item from the current data unit.
835	*
836	* @returns VBox status.
837	* @param pSSM SSM operation handle.
838	* @param pfBool Where to store the item.
839	*/
840	SSMR3DECL(int) SSMR3GetBool(PSSMHANDLE pSSM, bool *pfBool);
841
842	/**
843	* Loads a 8-bit unsigned integer item from the current data unit.
844	*
845	* @returns VBox status.
846	* @param pSSM SSM operation handle.
847	* @param pu8 Where to store the item.
848	*/
849	SSMR3DECL(int) SSMR3GetU8(PSSMHANDLE pSSM, uint8_t *pu8);
850
851	/**
852	* Loads a 8-bit signed integer item from the current data unit.
853	*
854	* @returns VBox status.
855	* @param pSSM SSM operation handle.
856	* @param pi8 Where to store the item.
857	*/
858	SSMR3DECL(int) SSMR3GetS8(PSSMHANDLE pSSM, int8_t *pi8);
859
860	/**
861	* Loads a 16-bit unsigned integer item from the current data unit.
862	*
863	* @returns VBox status.
864	* @param pSSM SSM operation handle.
865	* @param pu16 Where to store the item.
866	*/
867	SSMR3DECL(int) SSMR3GetU16(PSSMHANDLE pSSM, uint16_t *pu16);
868
869	/**
870	* Loads a 16-bit signed integer item from the current data unit.
871	*
872	* @returns VBox status.
873	* @param pSSM SSM operation handle.
874	* @param pi16 Where to store the item.
875	*/
876	SSMR3DECL(int) SSMR3GetS16(PSSMHANDLE pSSM, int16_t *pi16);
877
878	/**
879	* Loads a 32-bit unsigned integer item from the current data unit.
880	*
881	* @returns VBox status.
882	* @param pSSM SSM operation handle.
883	* @param pu32 Where to store the item.
884	*/
885	SSMR3DECL(int) SSMR3GetU32(PSSMHANDLE pSSM, uint32_t *pu32);
886
887	/**
888	* Loads a 32-bit signed integer item from the current data unit.
889	*
890	* @returns VBox status.
891	* @param pSSM SSM operation handle.
892	* @param pi32 Where to store the item.
893	*/
894	SSMR3DECL(int) SSMR3GetS32(PSSMHANDLE pSSM, int32_t *pi32);
895
896	/**
897	* Loads a 64-bit unsigned integer item from the current data unit.
898	*
899	* @returns VBox status.
900	* @param pSSM SSM operation handle.
901	* @param pu64 Where to store the item.
902	*/
903	SSMR3DECL(int) SSMR3GetU64(PSSMHANDLE pSSM, uint64_t *pu64);
904
905	/**
906	* Loads a 64-bit signed integer item from the current data unit.
907	*
908	* @returns VBox status.
909	* @param pSSM SSM operation handle.
910	* @param pi64 Where to store the item.
911	*/
912	SSMR3DECL(int) SSMR3GetS64(PSSMHANDLE pSSM, int64_t *pi64);
913
914	/**
915	* Loads a 128-bit unsigned integer item from the current data unit.
916	*
917	* @returns VBox status.
918	* @param pSSM SSM operation handle.
919	* @param pu128 Where to store the item.
920	*/
921	SSMR3DECL(int) SSMR3GetU128(PSSMHANDLE pSSM, uint128_t *pu128);
922
923	/**
924	* Loads a 128-bit signed integer item from the current data unit.
925	*
926	* @returns VBox status.
927	* @param pSSM SSM operation handle.
928	* @param pi128 Where to store the item.
929	*/
930	SSMR3DECL(int) SSMR3GetS128(PSSMHANDLE pSSM, int128_t *pi128);
931
932	/**
933	* Loads a VBox unsigned integer item from the current data unit.
934	*
935	* @returns VBox status.
936	* @param pSSM SSM operation handle.
937	* @param pu Where to store the integer.
938	*/
939	SSMR3DECL(int) SSMR3GetUInt(PSSMHANDLE pSSM, PRTUINT pu);
940
941	/**
942	* Loads a VBox signed integer item from the current data unit.
943	*
944	* @returns VBox status.
945	* @param pSSM SSM operation handle.
946	* @param pi Where to store the integer.
947	*/
948	SSMR3DECL(int) SSMR3GetSInt(PSSMHANDLE pSSM, PRTINT pi);
949
950	/**
951	* Loads a GC natural unsigned integer item from the current data unit.
952	*
953	* @returns VBox status.
954	* @param pSSM SSM operation handle.
955	* @param pu Where to store the integer.
956	*/
957	SSMR3DECL(int) SSMR3GetGCUInt(PSSMHANDLE pSSM, PRTGCUINT pu);
958
959	/**
960	* Loads a GC natural signed integer item from the current data unit.
961	*
962	* @returns VBox status.
963	* @param pSSM SSM operation handle.
964	* @param pi Where to store the integer.
965	*/
966	SSMR3DECL(int) SSMR3GetGCSInt(PSSMHANDLE pSSM, PRTGCINT pi);
967
968	/**
969	* Loads a GC physical address item from the current data unit.
970	*
971	* @returns VBox status.
972	* @param pSSM SSM operation handle.
973	* @param pGCPhys Where to store the GC physical address.
974	*/
975	SSMR3DECL(int) SSMR3GetGCPhys(PSSMHANDLE pSSM, PRTGCPHYS pGCPhys);
976
977	/**
978	* Loads a GC virtual address item from the current data unit.
979	*
980	* @returns VBox status.
981	* @param pSSM SSM operation handle.
982	* @param pGCPtr Where to store the GC virtual address.
983	*/
984	SSMR3DECL(int) SSMR3GetGCPtr(PSSMHANDLE pSSM, PRTGCPTR pGCPtr);
985
986	/**
987	* Loads a GC virtual address (represented as unsigned integer) 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) SSMR3GetGCUIntPtr(PSSMHANDLE pSSM, PRTGCUINTPTR pGCPtr);
994
995	/**
996	* Loads a I/O port address item from the current data unit.
997	*
998	* @returns VBox status.
999	* @param pSSM SSM operation handle.
1000	* @param pIOPort Where to store the I/O port address.
1001	*/
1002	SSMR3DECL(int) SSMR3GetIOPort(PSSMHANDLE pSSM, PRTIOPORT pIOPort);
1003
1004	/**
1005	* Loads a HC natural unsigned integer item from the current data unit.
1006	*
1007	* @returns VBox status.
1008	* @param pSSM SSM operation handle.
1009	* @param pu Where to store the integer.
1010	*/
1011	SSMR3DECL(int) SSMR3GetHCUInt(PSSMHANDLE pSSM, PRTHCUINT pu);
1012
1013	/**
1014	* Loads a HC natural signed integer item from the current data unit.
1015	*
1016	* @returns VBox status.
1017	* @param pSSM SSM operation handle.
1018	* @param pi Where to store the integer.
1019	*/
1020	SSMR3DECL(int) SSMR3GetHCSInt(PSSMHANDLE pSSM, PRTHCINT pi);
1021
1022	/**
1023	* Loads a selector item from the current data unit.
1024	*
1025	* @returns VBox status.
1026	* @param pSSM SSM operation handle.
1027	* @param pSel Where to store the selector.
1028	*/
1029	SSMR3DECL(int) SSMR3GetSel(PSSMHANDLE pSSM, PRTSEL pSel);
1030
1031	/**
1032	* Loads a memory item from the current data unit.
1033	*
1034	* @returns VBox status.
1035	* @param pSSM SSM operation handle.
1036	* @param pv Where to store the item.
1037	* @param cb Size of the item.
1038	*/
1039	SSMR3DECL(int) SSMR3GetMem(PSSMHANDLE pSSM, void *pv, size_t cb);
1040
1041	/**
1042	* Loads a string item from the current data unit.
1043	*
1044	* @returns VBox status.
1045	* @param pSSM SSM operation handle.
1046	* @param psz Where to store the item.
1047	* @param cbMax Max size of the item (including '\\0').
1048	*/
1049	SSMR3DECL(int) SSMR3GetStrZ(PSSMHANDLE pSSM, char *psz, size_t cbMax);
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	* @param pcbStr The length of the loaded string excluding the '\\0'. (optional)
1059	*/
1060	SSMR3DECL(int) SSMR3GetStrZEx(PSSMHANDLE pSSM, char psz, size_t cbMax, size_t pcbStr);
1061
1062	/**
1063	* Loads a timer item from the current data unit.
1064	*
1065	* @returns VBox status.
1066	* @param pSSM SSM operation handle.
1067	* @param PTMTIMER Where to store the item.
1068	*/
1069	SSMR3DECL(int) SSMR3GetTimer(PSSMHANDLE pSSM, PTMTIMER pTimer);
1070
1071	/** @} */
1072
1073
1074
1075	/**
1076	* Query what the VBox status code of the operation is.
1077	*
1078	* This can be used for putting and getting a batch of values
1079	* without bother checking the result till all the calls have
1080	* been made.
1081	*
1082	* @returns VBox status code.
1083	* @param pSSM SSM operation handle.
1084	*/
1085	SSMR3DECL(int) SSMR3HandleGetStatus(PSSMHANDLE pSSM);
1086
1087	/**
1088	* Fail the load operation.
1089	*
1090	* This is mainly intended for sub item loaders (like timers) which
1091	* return code isn't necessarily heeded by the caller but is important
1092	* to SSM.
1093	*
1094	* @returns SSMAFTER enum value.
1095	* @param pSSM SSM operation handle.
1096	* @param iStatus Failure status code. This MUST be a VERR_*.
1097	*/
1098	SSMR3DECL(int) SSMR3HandleSetStatus(PSSMHANDLE pSSM, int iStatus);
1099
1100	/**
1101	* Query what to do after this operation.
1102	*
1103	* @returns SSMAFTER enum value.
1104	* @param pSSM SSM operation handle.
1105	*/
1106	SSMR3DECL(int) SSMR3HandleGetAfter(PSSMHANDLE pSSM);
1107
1108
1109	#endif /* IN_RING3 */
1110
1111
1112	/** @} */
1113
1114	__END_DECLS
1115
1116	#endif
1117

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

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

Download in other formats: