vmapi.h@ 1227

Last change on this file since 1227 was 869, checked in by vboxsync, 18 years ago
Added VMR3SuspendNoSave.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 32.1 KB

Line
1	/** @file
2	* VM - The Virtual Machine, API.
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	#ifndef __VBox_vmapi_h__
22	#define __VBox_vmapi_h__
23
24	#include <VBox/cdefs.h>
25	#include <VBox/types.h>
26	#include <VBox/cpum.h>
27	#include <VBox/stam.h>
28	#include <VBox/cfgm.h>
29
30	#include <iprt/stdarg.h>
31
32	__BEGIN_DECLS
33
34	/** @defgroup grp_vmm_apis VM All Contexts API
35	* @ingroup grp_vm
36	* @{ */
37
38	/** @def VM_PHYS_ADDR
39	* Converts address of data within the VM structure to the equivalent
40	* physical address.
41	*
42	* @returns physical address.
43	* @param pVM Pointer to the VM.
44	* @param pvInVM Pointer within the VM.
45	*/
46	#define VM_PHYS_ADDR(pVM, pvInVM) ( pVM->PhysVM + (uint32_t)((uintptr_t)pvInVM - (uintptr_t)pVM) )
47
48	/** @def VM_GUEST_ADDR
49	* Converts host address of data within the VM structure to the equivalent
50	* guest address.
51	*
52	* @returns guest virtual address.
53	* @param pVM Pointer to the VM.
54	* @param pvInVM HC Pointer within the VM.
55	*/
56	#define VM_GUEST_ADDR(pVM, pvInVM) ( (RTGCPTR)((RTGCUINTPTR)pVM->pVMGC + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMHC)) )
57
58	/** @def VM_HOST_ADDR
59	* Converts guest address of data within the VM structure to the equivalent
60	* host address.
61	*
62	* @returns host virtual address.
63	* @param pVM Pointer to the VM.
64	* @param pvInVM GC Pointer within the VM.
65	*/
66	#define VM_HOST_ADDR(pVM, pvInVM) ( (RTHCPTR)((RTHCUINTPTR)pVM->pVMHC + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMGC)) )
67
68
69	/**
70	* VM error callback function.
71	*
72	* @param pVM The VM handle. Can be NULL if an error occurred before
73	* successfully creating a VM.
74	* @param pvUser The user argument.
75	* @param rc VBox status code.
76	* @param RT_SRC_POS_DECL The source position arguments. See RT_SRC_POS and RT_SRC_POS_ARGS.
77	* @param pszFormat Error message format string.
78	* @param args Error message arguments.
79	*/
80	typedef DECLCALLBACK(void) FNVMATERROR(PVM pVM, void pvUser, int rc, RT_SRC_POS_DECL, const char pszError, va_list args);
81	/** Pointer to a VM error callback. */
82	typedef FNVMATERROR *PFNVMATERROR;
83
84	/**
85	* Sets the error message.
86	*
87	* @returns rc. Meaning you can do:
88	* @code
89	* return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
90	* @endcode
91	* @param pVM VM handle. Must be non-NULL.
92	* @param rc VBox status code.
93	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
94	* @param pszFormat Error message format string.
95	* @param ... Error message arguments.
96	* @thread Any
97	*/
98	VMDECL(int) VMSetError(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...);
99
100	/**
101	* Sets the error message.
102	*
103	* @returns rc. Meaning you can do:
104	* @code
105	* return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
106	* @endcode
107	* @param pVM VM handle. Must be non-NULL.
108	* @param rc VBox status code.
109	* @param RT_SRC_POS_DECL Use RT_SRC_POS.
110	* @param pszFormat Error message format string.
111	* @param args Error message arguments.
112	* @thread Any
113	*/
114	VMDECL(int) VMSetErrorV(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list args);
115
116	/** @def VM_SET_ERROR
117	* Macro for setting a simple VM error message.
118	* Don't use '%' in the message!
119	*
120	* @returns rc. Meaning you can do:
121	* @code
122	* return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
123	* @endcode
124	* @param pVM VM handle.
125	* @param rc VBox status code.
126	* @param pszMessage Error message string.
127	* @thread Any
128	*/
129	#define VM_SET_ERROR(pVM, rc, pszMessage) (VMSetError(pVM, rc, RT_SRC_POS, pszMessage))
130
131
132	/**
133	* VM runtime error callback function.
134	* See VMSetRuntimeError for the detailed description of parameters.
135	*
136	* @param pVM The VM handle.
137	* @param pvUser The user argument.
138	* @param fFatal Whether it is a fatal error or not.
139	* @param pszErrorID Error ID string.
140	* @param pszFormat Error message format string.
141	* @param args Error message arguments.
142	*/
143	typedef DECLCALLBACK(void) FNVMATRUNTIMEERROR(PVM pVM, void *pvUser, bool fFatal,
144	const char *pszErrorID,
145	const char *pszFormat, va_list args);
146	/** Pointer to a VM runtime error callback. */
147	typedef FNVMATRUNTIMEERROR *PFNVMATRUNTIMEERROR;
148
149	/**
150	* Sets the runtime error message.
151	* As opposed VMSetError(), this method is intended to inform the VM user about
152	* errors and error-like conditions that happen at an arbitrary point during VM
153	* execution (like "host memory low" or "out of host disk space").
154	*
155	* The @a fFatal parameter defines whether the error is fatal or not. If it is
156	* true, then it is expected that the caller has already paused the VM execution
157	* before calling this method. The VM user is supposed to power off the VM
158	* immediately after it has received the runtime error notification via the
159	* FNVMATRUNTIMEERROR callback.
160	*
161	* If @a fFatal is false, then the paused state of the VM defines the kind of
162	* the error. If the VM is paused before calling this method, it means that
163	* the VM user may try to fix the error condition (i.e. free more host memory)
164	* and then resume the VM execution. If the VM is not paused before calling
165	* this method, it means that the given error is a warning about an error
166	* condition that may happen soon but that doesn't directly affect the
167	* VM execution by the time of the call.
168	*
169	* The @a pszErrorID parameter defines an unique error identificator.
170	* It is used by the front-ends to show a proper message to the end user
171	* containig possible actions (for example, Retry/Ignore). For this reason,
172	* an error ID assigned once to some particular error condition should not
173	* change in the future. The format of this parameter is "SomeErrorCondition".
174	*
175	* @param pVM VM handle. Must be non-NULL.
176	* @param fFatal Whether it is a fatal error or not.
177	* @param pszErrorID Error ID string.
178	* @param pszFormat Error message format string.
179	* @param ... Error message arguments.
180	*
181	* @return VBox status code (whether the error has been successfully set
182	* and delivered to callbacks or not).
183	*
184	* @thread Any
185	*/
186	VMDECL(int) VMSetRuntimeError(PVM pVM, bool fFatal, const char *pszErrorID,
187	const char *pszFormat, ...);
188
189	/**
190	* va_list version of VMSetRuntimeError.
191	*
192	* @param pVM VM handle. Must be non-NULL.
193	* @param fFatal Whether it is a fatal error or not.
194	* @param pszErrorID Error ID string.
195	* @param pszFormat Error message format string.
196	* @param args Error message arguments.
197	*
198	* @return VBox status code (whether the error has been successfully set
199	* and delivered to callbacks or not).
200	*
201	* @thread Any
202	*/
203	VMDECL(int) VMSetRuntimeErrorV(PVM pVM, bool fFatal, const char *pszErrorID,
204	const char *pszFormat, va_list args);
205
206
207	/**
208	* VM reset callback.
209	*
210	* @returns VBox status code.
211	* @param pDevInst Device instance of the device which registered the callback.
212	* @param pvUser User argument.
213	*/
214	typedef DECLCALLBACK(int) FNVMATRESET(PPDMDEVINS pDevInst, void *pvUser);
215	/** VM reset callback. */
216	typedef FNVMATRESET *PFNVMATRESET;
217
218	/**
219	* VM reset internal callback.
220	*
221	* @returns VBox status code.
222	* @param pVM The VM which is begin reset.
223	* @param pvUser User argument.
224	*/
225	typedef DECLCALLBACK(int) FNVMATRESETINT(PVM pVM, void *pvUser);
226	/** VM reset internal callback. */
227	typedef FNVMATRESETINT *PFNVMATRESETINT;
228
229	/**
230	* VM reset external callback.
231	*
232	* @param pvUser User argument.
233	*/
234	typedef DECLCALLBACK(void) FNVMATRESETEXT(void *pvUser);
235	/** VM reset external callback. */
236	typedef FNVMATRESETEXT *PFNVMATRESETEXT;
237
238
239	/**
240	* VM state callback function.
241	*
242	* You are not allowed to call any function which changes the VM state from a
243	* state callback, except VMR3Destroy().
244	*
245	* @param pVM The VM handle.
246	* @param enmState The new state.
247	* @param enmOldState The old state.
248	* @param pvUser The user argument.
249	*/
250	typedef DECLCALLBACK(void) FNVMATSTATE(PVM pVM, VMSTATE enmState, VMSTATE enmOldState, void *pvUser);
251	/** Pointer to a VM state callback. */
252	typedef FNVMATSTATE *PFNVMATSTATE;
253
254
255	/**
256	* Request type.
257	*/
258	typedef enum VMREQTYPE
259	{
260	/** Invalid request. */
261	VMREQTYPE_INVALID = 0,
262	/** VM: Internal. */
263	VMREQTYPE_INTERNAL,
264	/** Maximum request type (exclusive). Used for validation. */
265	VMREQTYPE_MAX
266	} VMREQTYPE;
267
268	/**
269	* Request state.
270	*/
271	typedef enum VMREQSTATE
272	{
273	/** The state is invalid. */
274	VMREQSTATE_INVALID = 0,
275	/** The request have been allocated and is in the process of being filed. */
276	VMREQSTATE_ALLOCATED,
277	/** The request is queued by the requester. */
278	VMREQSTATE_QUEUED,
279	/** The request is begin processed. */
280	VMREQSTATE_PROCESSING,
281	/** The request is completed, the requester is begin notified. */
282	VMREQSTATE_COMPLETED,
283	/** The request packet is in the free chain. (The requester */
284	VMREQSTATE_FREE
285	} VMREQSTATE;
286
287	/**
288	* Request flags.
289	*/
290	typedef enum VMREQFLAGS
291	{
292	/** The request returns a VBox status code. */
293	VMREQFLAGS_VBOX_STATUS = 0,
294	/** The request is a void request and have no status code. */
295	VMREQFLAGS_VOID = 1,
296	/** Return type mask. */
297	VMREQFLAGS_RETURN_MASK = 1,
298	/** Caller does not wait on the packet, EMT will free it. */
299	VMREQFLAGS_NO_WAIT = 2
300	} VMREQFLAGS;
301
302	/**
303	* VM Request packet.
304	*
305	* This is used to request an action in the EMT. Usually the requester is
306	* another thread, but EMT can also end up being the requester in which case
307	* it's carried out synchronously.
308	*/
309	typedef struct VMREQ
310	{
311	/** Pointer to the next request in the chain. */
312	struct VMREQ * volatile pNext;
313	/** Pointer to the VM this packet belongs to. */
314	PVM pVM;
315	/** Request state. */
316	volatile VMREQSTATE enmState;
317	/** VBox status code for the completed request. */
318	volatile int iStatus;
319	/** Requester event sem.
320	* The request can use this event semaphore to wait/poll for completion
321	* of the request.
322	*/
323	RTSEMEVENT EventSem;
324	/** Set if the event semaphore is clear. */
325	volatile bool fEventSemClear;
326	/** Flags, VMR3REQ_FLAGS_. /
327	unsigned fFlags;
328	/** Request type. */
329	VMREQTYPE enmType;
330	/** Request specific data. */
331	union VMREQ_U
332	{
333	/** VMREQTYPE_INTERNAL. */
334	struct
335	{
336	/** Pointer to the function to be called. */
337	PFNRT pfn;
338	/** Number of arguments. */
339	unsigned cArgs;
340	/** Array of arguments. */
341	uintptr_t aArgs[64];
342	} Internal;
343	} u;
344	} VMREQ;
345	/** Pointer to a VM request packet. */
346	typedef VMREQ *PVMREQ;
347
348	/** @} */
349
350
351	#ifndef IN_GC
352	/** @defgroup grp_vmm_apis_hc VM Host Context API
353	* @ingroup grp_vm
354	* @{ */
355
356	/** @} */
357	#endif
358
359
360	#ifdef IN_RING3
361	/** @defgroup grp_vmm_apis_r3 VM Host Context Ring 3 API
362	* This interface is a _draft_!
363	* @ingroup grp_vm
364	* @{ */
365
366	/**
367	* Completion notification codes.
368	*/
369	typedef enum VMINITCOMPLETED
370	{
371	/** The Ring3 init is completed. */
372	VMINITCOMPLETED_RING3 = 1,
373	/** The Ring0 init is completed. */
374	VMINITCOMPLETED_RING0,
375	/** The GC init is completed. */
376	VMINITCOMPLETED_GC
377	} VMINITCOMPLETED;
378
379
380	/**
381	* Creates a virtual machine by calling the supplied configuration constructor.
382	*
383	* On successful return the VM is powered off, i.e. VMR3PowerOn() should be
384	* called to start the execution.
385	*
386	* @returns 0 on success.
387	* @returns VBox error code on failure.
388	* @param pfnVMAtError Pointer to callback function for setting VM errors.
389	* This is called in the EM.
390	* @param pvUserVM The user argument passed to pfnVMAtError.
391	* @param pfnCFGMConstructor Pointer to callback function for constructing the VM configuration tree.
392	* This is called in the EM.
393	* @param pvUserCFGM The user argument passed to pfnCFGMConstructor.
394	* @param ppVM Where to store the 'handle' of the created VM.
395	* @thread Any thread.
396	* @vmstate N/A
397	* @vmstateto Created
398	*/
399	VMR3DECL(int) VMR3Create(PFNVMATERROR pfnVMAtError, void pvUserVM, PFNCFGMCONSTRUCTOR pfnCFGMConstructor, void pvUserCFGM, PVM *ppVM);
400
401	/**
402	* Power on a virtual machine.
403	*
404	* @returns 0 on success.
405	* @returns VBox error code on failure.
406	* @param pVM VM to power on.
407	* @thread Any thread.
408	* @vmstate Created
409	* @vmstateto Running
410	*/
411	VMR3DECL(int) VMR3PowerOn(PVM pVM);
412
413	/**
414	* Suspend a running VM.
415	*
416	* @returns VBox status.
417	* @param pVM VM to suspend.
418	* @thread Any thread.
419	* @vmstate Running
420	* @vmstateto Suspended
421	*/
422	VMR3DECL(int) VMR3Suspend(PVM pVM);
423
424	/**
425	* Suspends a running VM and prevent state saving until the VM is resumed or stopped.
426	*
427	* @returns 0 on success.
428	* @returns VBox error code on failure.
429	* @param pVM VM to suspend.
430	* @thread Any thread.
431	* @vmstate Running
432	* @vmstateto Suspended
433	*/
434	VMR3DECL(int) VMR3SuspendNoSave(PVM pVM);
435
436	/**
437	* Resume VM execution.
438	*
439	* @returns VBox status.
440	* @param pVM The VM to resume.
441	* @thread Any thread.
442	* @vmstate Suspended
443	* @vmstateto Running
444	*/
445	VMR3DECL(int) VMR3Resume(PVM pVM);
446
447	/**
448	* Reset the current VM.
449	*
450	* @returns VBox status code.
451	* @param pVM VM to reset.
452	* @thread Any thread.
453	* @vmstate Suspended, Running
454	* @vmstateto Unchanged state.
455	*/
456	VMR3DECL(int) VMR3Reset(PVM pVM);
457
458	/**
459	* Progress callback.
460	* This will report the completion percentage of an operation.
461	*
462	* @returns VINF_SUCCESS.
463	* @returns Error code to cancel the operation with.
464	* @param pVM The VM handle.
465	* @param uPercent Completetion precentage (0-100).
466	* @param pvUser User specified argument.
467	*/
468	typedef DECLCALLBACK(int) FNVMPROGRESS(PVM pVM, unsigned uPercent, void *pvUser);
469	/** Pointer to a FNVMPROGRESS function. */
470	typedef FNVMPROGRESS *PFNVMPROGRESS;
471
472	/**
473	* Save current VM state.
474	*
475	* To save and terminate the VM, the VM must be suspended before the call.
476	*
477	* @returns 0 on success.
478	* @returns VBox error code on failure.
479	* @param pVM VM which state should be saved.
480	* @param pszFilename Name of the save state file.
481	* @param pfnProgress Progress callback. Optional.
482	* @param pvUser User argument for the progress callback.
483	* @thread Any thread.
484	* @vmstate Suspended
485	* @vmstateto Unchanged state.
486	*/
487	VMR3DECL(int) VMR3Save(PVM pVM, const char pszFilename, PFNVMPROGRESS pfnProgress, void pvUser);
488
489	/**
490	* Load a new VM state.
491	*
492	* To restore a saved state on VM startup, call this function and then
493	* resume the VM instead of powering it on.
494	*
495	* @returns 0 on success.
496	* @returns VBox error code on failure.
497	* @param pVM VM which state should be saved.
498	* @param pszFilename Name of the save state file.
499	* @param pfnProgress Progress callback. Optional.
500	* @param pvUser User argument for the progress callback.
501	* @thread Any thread.
502	* @vmstate Created, Suspended
503	* @vmstateto Suspended
504	*/
505	VMR3DECL(int) VMR3Load(PVM pVM, const char pszFilename, PFNVMPROGRESS pfnProgress, void pvUser);
506
507	/**
508	* Power off a VM.
509	*
510	* @returns 0 on success.
511	* @returns VBox error code on failure.
512	* @param pVM VM which should be destroyed.
513	* @thread Any thread.
514	* @vmstate Suspended, Running, Guru Mediation, Load Failure
515	* @vmstateto Off
516	*/
517	VMR3DECL(int) VMR3PowerOff(PVM pVM);
518
519	/**
520	* Destroy a VM.
521	* The VM must be powered off (or never really powered on) to call this function.
522	* The VM handle is destroyed and can no longer be used up successful return.
523	*
524	* @returns 0 on success.
525	* @returns VBox error code on failure.
526	* @param pVM VM which should be destroyed.
527	* @thread Any thread but the emulation thread.
528	* @vmstate Off, Created
529	* @vmstateto N/A
530	*/
531	VMR3DECL(int) VMR3Destroy(PVM pVM);
532
533	/**
534	* Calls the relocation functions for all VMM components so they can update
535	* any GC pointers. When this function is called all the basic VM members
536	* have been updated and the actual memory relocation have been done
537	* by the PGM/MM.
538	*
539	* This is used both on init and on runtime relocations.
540	*
541	* @param pVM VM handle.
542	* @param offDelta Relocation delta relative to old location.
543	* @thread The emulation thread.
544	*/
545	VMR3DECL(void) VMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
546
547	/**
548	* Enumerates the VMs in this process.
549	*
550	* @returns Pointer to the next VM.
551	* @returns NULL when no more VMs.
552	* @param pVMPrev The previous VM
553	* Use NULL to start the enumeration.
554	*/
555	VMR3DECL(PVM) VMR3EnumVMs(PVM pVMPrev);
556
557	/**
558	* Wait for VM to be resumed. Handle events like vmR3EmulationThread does.
559	* In case the VM is stopped, clean up and long jump to the main EMT loop.
560	*
561	* @returns VINF_SUCCESS or doesn't return
562	* @param pVM VM handle.
563	*/
564	VMR3DECL(int) VMR3WaitForResume(PVM pVM);
565
566
567	/**
568	* VM destruction callback.
569	* @param pVM The VM which is about to be destroyed.
570	* @param pvUser The user parameter specified at registration.
571	*/
572	typedef DECLCALLBACK(void) FNVMATDTOR(PVM pVM, void *pvUser);
573	/** Pointer to a VM destruction callback. */
574	typedef FNVMATDTOR *PFNVMATDTOR;
575
576	/**
577	* Registers an at VM destruction callback.
578	*
579	* @returns VBox status code.
580	* @param pfnAtDtor Pointer to callback.
581	* @param pvUser User argument.
582	*/
583	VMR3DECL(int) VMR3AtDtorRegister(PFNVMATDTOR pfnAtDtor, void *pvUser);
584
585	/**
586	* Deregisters an at VM destruction callback.
587	*
588	* @returns VBox status code.
589	* @param pfnAtDtor Pointer to callback.
590	*/
591	VMR3DECL(int) VMR3AtDtorDeregister(PFNVMATDTOR pfnAtDtor);
592
593
594	/**
595	* Registers an at VM reset callback.
596	*
597	* @returns VBox status code.
598	* @param pVM The VM.
599	* @param pDevInst Device instance.
600	* @param pfnCallback Callback function.
601	* @param pvUser User argument.
602	* @param pszDesc Description (optional).
603	*/
604	VMR3DECL(int) VMR3AtResetRegister(PVM pVM, PPDMDEVINS pDevInst, PFNVMATRESET pfnCallback, void pvUser, const char pszDesc);
605
606	/**
607	* Registers an at VM reset internal callback.
608	*
609	* @returns VBox status code.
610	* @param pVM The VM.
611	* @param pfnCallback Callback function.
612	* @param pvUser User argument.
613	* @param pszDesc Description (optional).
614	*/
615	VMR3DECL(int) VMR3AtResetRegisterInternal(PVM pVM, PFNVMATRESETINT pfnCallback, void pvUser, const char pszDesc);
616
617	/**
618	* Registers an at VM reset external callback.
619	*
620	* @returns VBox status code.
621	* @param pVM The VM.
622	* @param pfnCallback Callback function.
623	* @param pvUser User argument.
624	* @param pszDesc Description (optional).
625	*/
626	VMR3DECL(int) VMR3AtResetRegisterExternal(PVM pVM, PFNVMATRESETEXT pfnCallback, void pvUser, const char pszDesc);
627
628
629	/**
630	* Deregisters an at VM reset callback.
631	*
632	* @returns VBox status code.
633	* @param pVM The VM.
634	* @param pDevInst Device instance.
635	* @param pfnCallback Callback function.
636	*/
637	VMR3DECL(int) VMR3AtResetDeregister(PVM pVM, PPDMDEVINS pDevInst, PFNVMATRESET pfnCallback);
638
639	/**
640	* Deregisters an at VM reset internal callback.
641	*
642	* @returns VBox status code.
643	* @param pVM The VM.
644	* @param pfnCallback Callback function.
645	*/
646	VMR3DECL(int) VMR3AtResetDeregisterInternal(PVM pVM, PFNVMATRESETINT pfnCallback);
647
648	/**
649	* Deregisters an at VM reset external callback.
650	*
651	* @returns VBox status code.
652	* @param pVM The VM.
653	* @param pfnCallback Callback function.
654	*/
655	VMR3DECL(int) VMR3AtResetDeregisterExternal(PVM pVM, PFNVMATRESETEXT pfnCallback);
656
657
658	/**
659	* Registers a VM state change callback.
660	*
661	* You are not allowed to call any function which changes the VM state from a
662	* state callback, except VMR3Destroy().
663	*
664	* @returns VBox status code.
665	* @param pVM VM handle.
666	* @param pfnAtState Pointer to callback.
667	* @param pvUser User argument.
668	* @thread Any.
669	*/
670	VMR3DECL(int) VMR3AtStateRegister(PVM pVM, PFNVMATSTATE pfnAtState, void *pvUser);
671
672	/**
673	* Deregisters a VM state change callback.
674	*
675	* @returns VBox status code.
676	* @param pVM The VM handle.
677	* @param pfnAtState Pointer to callback.
678	* @param pvUser User argument.
679	* @thread Any.
680	*/
681	VMR3DECL(int) VMR3AtStateDeregister(PVM pVM, PFNVMATSTATE pfnAtState, void *pvUser);
682
683	/**
684	* Gets the current VM state.
685	*
686	* @returns The current VM state.
687	* @param pVM The VM handle.
688	* @thread Any
689	*/
690	VMR3DECL(VMSTATE) VMR3GetState(PVM pVM);
691
692	/**
693	* Gets the state name string for a VM state.
694	*
695	* @returns Pointer to the state name. (readonly)
696	* @param enmState The state.
697	*/
698	VMR3DECL(const char *) VMR3GetStateName(VMSTATE enmState);
699
700	/**
701	* Registers a VM error callback.
702	*
703	* @returns VBox status code.
704	* @param pVM The VM handle.
705	* @param pfnAtError Pointer to callback.
706	* @param pvUser User argument.
707	* @thread Any.
708	*/
709	VMR3DECL(int) VMR3AtErrorRegister(PVM pVM, PFNVMATERROR pfnAtError, void *pvUser);
710
711	/**
712	* Deregisters a VM error callback.
713	*
714	* @returns VBox status code.
715	* @param pVM The VM handle.
716	* @param pfnAtError Pointer to callback.
717	* @param pvUser User argument.
718	* @thread Any.
719	*/
720	VMR3DECL(int) VMR3AtErrorDeregister(PVM pVM, PFNVMATERROR pfnAtError, void *pvUser);
721
722	/**
723	* This is a worker function for GC and Ring-0 calls to VMSetError and VMSetErrorV.
724	* The message is found in VMINT.
725	*
726	* @param pVM The VM handle.
727	* @thread EMT.
728	*/
729	VMR3DECL(void) VMR3SetErrorWorker(PVM pVM);
730
731	/**
732	* Registers a VM runtime error callback.
733	*
734	* @returns VBox status code.
735	* @param pVM The VM handle.
736	* @param pfnAtRuntimeError Pointer to callback.
737	* @param pvUser User argument.
738	* @thread Any.
739	*/
740	VMR3DECL(int) VMR3AtRuntimeErrorRegister(PVM pVM, PFNVMATRUNTIMEERROR pfnAtRuntimeError, void *pvUser);
741
742	/**
743	* Deregisters a VM runtime error callback.
744	*
745	* @returns VBox status code.
746	* @param pVM The VM handle.
747	* @param pfnAtRuntimeError Pointer to callback.
748	* @param pvUser User argument.
749	* @thread Any.
750	*/
751	VMR3DECL(int) VMR3AtRuntimeErrorDeregister(PVM pVM, PFNVMATRUNTIMEERROR pfnAtRuntimeError, void *pvUser);
752
753	/**
754	* This is a worker function for GC and Ring-0 calls to VMSetRuntimeError and VMSetRuntimeErrorV.
755	* The message is found in VMINT.
756	*
757	* @param pVM The VM handle.
758	* @thread EMT.
759	*/
760	VMR3DECL(void) VMR3SetRuntimeErrorWorker(PVM pVM);
761
762
763	/**
764	* Allocate and queue a call request.
765	*
766	* If it's desired to poll on the completion of the request set cMillies
767	* to 0 and use VMR3ReqWait() to check for completation. In the other case
768	* use RT_INDEFINITE_WAIT.
769	* The returned request packet must be freed using VMR3ReqFree().
770	*
771	* @returns VBox status code.
772	* Will not return VERR_INTERRUPTED.
773	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
774	*
775	* @param pVM The VM handle.
776	* @param ppReq Where to store the pointer to the request.
777	* This will be NULL or a valid request pointer not matter what happends.
778	* @param cMillies Number of milliseconds to wait for the request to
779	* be completed. Use RT_INDEFINITE_WAIT to only
780	* wait till it's completed.
781	* @param pfnFunction Pointer to the function to call.
782	* @param cArgs Number of arguments following in the ellipsis.
783	* Not possible to pass 64-bit arguments!
784	* @param ... Function arguments.
785	*/
786	VMR3DECL(int) VMR3ReqCall(PVM pVM, PVMREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
787
788	/**
789	* Allocate and queue a call request to a void function.
790	*
791	* If it's desired to poll on the completion of the request set cMillies
792	* to 0 and use VMR3ReqWait() to check for completation. In the other case
793	* use RT_INDEFINITE_WAIT.
794	* The returned request packet must be freed using VMR3ReqFree().
795	*
796	* @returns VBox status code.
797	* Will not return VERR_INTERRUPTED.
798	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
799	*
800	* @param pVM The VM handle.
801	* @param ppReq Where to store the pointer to the request.
802	* This will be NULL or a valid request pointer not matter what happends.
803	* @param cMillies Number of milliseconds to wait for the request to
804	* be completed. Use RT_INDEFINITE_WAIT to only
805	* wait till it's completed.
806	* @param pfnFunction Pointer to the function to call.
807	* @param cArgs Number of arguments following in the ellipsis.
808	* Not possible to pass 64-bit arguments!
809	* @param ... Function arguments.
810	*/
811	VMR3DECL(int) VMR3ReqCallVoid(PVM pVM, PVMREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
812
813	/**
814	* Allocate and queue a call request to a void function.
815	*
816	* If it's desired to poll on the completion of the request set cMillies
817	* to 0 and use VMR3ReqWait() to check for completation. In the other case
818	* use RT_INDEFINITE_WAIT.
819	* The returned request packet must be freed using VMR3ReqFree().
820	*
821	* @returns VBox status code.
822	* Will not return VERR_INTERRUPTED.
823	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
824	*
825	* @param pVM The VM handle.
826	* @param ppReq Where to store the pointer to the request.
827	* This will be NULL or a valid request pointer not matter what happends, unless fFlags
828	* contains VMREQFLAGS_NO_WAIT when it will be optional and always NULL.
829	* @param cMillies Number of milliseconds to wait for the request to
830	* be completed. Use RT_INDEFINITE_WAIT to only
831	* wait till it's completed.
832	* @param fFlags A combination of the VMREQFLAGS values.
833	* @param pfnFunction Pointer to the function to call.
834	* @param cArgs Number of arguments following in the ellipsis.
835	* Not possible to pass 64-bit arguments!
836	* @param ... Function arguments.
837	*/
838	VMR3DECL(int) VMR3ReqCallEx(PVM pVM, PVMREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
839
840	/**
841	* Allocate and queue a call request.
842	*
843	* If it's desired to poll on the completion of the request set cMillies
844	* to 0 and use VMR3ReqWait() to check for completation. In the other case
845	* use RT_INDEFINITE_WAIT.
846	* The returned request packet must be freed using VMR3ReqFree().
847	*
848	* @returns VBox status code.
849	* Will not return VERR_INTERRUPTED.
850	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
851	*
852	* @param pVM The VM handle.
853	* @param ppReq Where to store the pointer to the request.
854	* This will be NULL or a valid request pointer not matter what happends, unless fFlags
855	* contains VMREQFLAGS_NO_WAIT when it will be optional and always NULL.
856	* @param cMillies Number of milliseconds to wait for the request to
857	* be completed. Use RT_INDEFINITE_WAIT to only
858	* wait till it's completed.
859	* @param fFlags A combination of the VMREQFLAGS values.
860	* @param pfnFunction Pointer to the function to call.
861	* @param cArgs Number of arguments following in the ellipsis.
862	* Not possible to pass 64-bit arguments!
863	* @param pvArgs Pointer to function arguments.
864	*/
865	VMR3DECL(int) VMR3ReqCallV(PVM pVM, PVMREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
866
867	/**
868	* Allocates a request packet.
869	*
870	* The caller allocates a request packet, fills in the request data
871	* union and queues the request.
872	*
873	* @returns VBox status code.
874	*
875	* @param pVM VM handle.
876	* @param ppReq Where to store the pointer to the allocated packet.
877	* @param enmType Package type.
878	*/
879	VMR3DECL(int) VMR3ReqAlloc(PVM pVM, PVMREQ *ppReq, VMREQTYPE enmType);
880
881	/**
882	* Free a request packet.
883	*
884	* @returns VBox status code.
885	*
886	* @param pReq Package to free.
887	* @remark The request packet must be in allocated or completed state!
888	*/
889	VMR3DECL(int) VMR3ReqFree(PVMREQ pReq);
890
891	/**
892	* Queue a request.
893	*
894	* The quest must be allocated using VMR3ReqAlloc() and contain
895	* all the required data.
896	* If it's disired to poll on the completion of the request set cMillies
897	* to 0 and use VMR3ReqWait() to check for completation. In the other case
898	* use RT_INDEFINITE_WAIT.
899	*
900	* @returns VBox status code.
901	* Will not return VERR_INTERRUPTED.
902	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
903	*
904	* @param pReq The request to queue.
905	* @param cMillies Number of milliseconds to wait for the request to
906	* be completed. Use RT_INDEFINITE_WAIT to only
907	* wait till it's completed.
908	*/
909	VMR3DECL(int) VMR3ReqQueue(PVMREQ pReq, unsigned cMillies);
910
911	/**
912	* Wait for a request to be completed.
913	*
914	* @returns VBox status code.
915	* Will not return VERR_INTERRUPTED.
916	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
917	*
918	* @param pReq The request to wait for.
919	* @param cMillies Number of milliseconds to wait.
920	* Use RT_INDEFINITE_WAIT to only wait till it's completed.
921	*/
922	VMR3DECL(int) VMR3ReqWait(PVMREQ pReq, unsigned cMillies);
923
924
925
926	/**
927	* Process pending request(s).
928	*
929	* This function is called from a forced action handler in
930	* the EMT.
931	*
932	* @returns VBox status code.
933	*
934	* @param pVM VM handle.
935	*/
936	VMR3DECL(int) VMR3ReqProcess(PVM pVM);
937
938
939	/**
940	* Notify the emulation thread (EMT) about pending Forced Action (FF).
941	*
942	* This function is called by thread other than EMT to make
943	* sure EMT wakes up and promptly service a FF request.
944	*
945	* @param pVM VM handle.
946	* @param fNotifiedREM Set if REM have already been notified. If clear the
947	* generic REMR3NotifyFF() method is called.
948	*/
949	VMR3DECL(void) VMR3NotifyFF(PVM pVM, bool fNotifiedREM);
950
951	/**
952	* Halted VM Wait.
953	* Any external event will unblock the thread.
954	*
955	* @returns VINF_SUCCESS unless a fatal error occured. In the latter
956	* case an appropriate status code is returned.
957	* @param pVM VM handle.
958	* @param fIgnoreInterrupts If set the VM_FF_INTERRUPT flags is ignored.
959	* @thread The emulation thread.
960	*/
961	VMR3DECL(int) VMR3WaitHalted(PVM pVM, bool fIgnoreInterrupts);
962
963	/**
964	* Suspended VM Wait.
965	* Only a handful of forced actions will cause the function to
966	* return to the caller.
967	*
968	* @returns VINF_SUCCESS unless a fatal error occured. In the latter
969	* case an appropriate status code is returned.
970	* @param pVM VM handle.
971	* @thread The emulation thread.
972	*/
973	VMR3DECL(int) VMR3Wait(PVM pVM);
974
975	/** @} */
976	#endif /* IN_RING3 */
977
978
979	#ifdef IN_GC
980	/** @defgroup grp_vmm_apis_gc VM Guest Context APIs
981	* @ingroup grp_vm
982	* @{ */
983
984	/** @} */
985	#endif
986
987	__END_DECLS
988
989	/** @} */
990
991	#endif
992
993

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

source: vbox/trunk/include/VBox/vmapi.h@ 1227

Download in other formats: