vmapi.h@ 659

Last change on this file since 659 was 246, checked in by vboxsync, 18 years ago
Added VMR3WaitForResume
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 31.8 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	* Resume VM execution.
426	*
427	* @returns VBox status.
428	* @param pVM The VM to resume.
429	* @thread Any thread.
430	* @vmstate Suspended
431	* @vmstateto Running
432	*/
433	VMR3DECL(int) VMR3Resume(PVM pVM);
434
435	/**
436	* Reset the current VM.
437	*
438	* @returns VBox status code.
439	* @param pVM VM to reset.
440	* @thread Any thread.
441	* @vmstate Suspended, Running
442	* @vmstateto Unchanged state.
443	*/
444	VMR3DECL(int) VMR3Reset(PVM pVM);
445
446	/**
447	* Progress callback.
448	* This will report the completion percentage of an operation.
449	*
450	* @returns VINF_SUCCESS.
451	* @returns Error code to cancel the operation with.
452	* @param pVM The VM handle.
453	* @param uPercent Completetion precentage (0-100).
454	* @param pvUser User specified argument.
455	*/
456	typedef DECLCALLBACK(int) FNVMPROGRESS(PVM pVM, unsigned uPercent, void *pvUser);
457	/** Pointer to a FNVMPROGRESS function. */
458	typedef FNVMPROGRESS *PFNVMPROGRESS;
459
460	/**
461	* Save current VM state.
462	*
463	* To save and terminate the VM, the VM must be suspended before the call.
464	*
465	* @returns 0 on success.
466	* @returns VBox error code on failure.
467	* @param pVM VM which state should be saved.
468	* @param pszFilename Name of the save state file.
469	* @param pfnProgress Progress callback. Optional.
470	* @param pvUser User argument for the progress callback.
471	* @thread Any thread.
472	* @vmstate Suspended
473	* @vmstateto Unchanged state.
474	*/
475	VMR3DECL(int) VMR3Save(PVM pVM, const char pszFilename, PFNVMPROGRESS pfnProgress, void pvUser);
476
477	/**
478	* Load a new VM state.
479	*
480	* To restore a saved state on VM startup, call this function and then
481	* resume the VM instead of powering it on.
482	*
483	* @returns 0 on success.
484	* @returns VBox error code on failure.
485	* @param pVM VM which state should be saved.
486	* @param pszFilename Name of the save state file.
487	* @param pfnProgress Progress callback. Optional.
488	* @param pvUser User argument for the progress callback.
489	* @thread Any thread.
490	* @vmstate Created, Suspended
491	* @vmstateto Suspended
492	*/
493	VMR3DECL(int) VMR3Load(PVM pVM, const char pszFilename, PFNVMPROGRESS pfnProgress, void pvUser);
494
495	/**
496	* Power off a VM.
497	*
498	* @returns 0 on success.
499	* @returns VBox error code on failure.
500	* @param pVM VM which should be destroyed.
501	* @thread Any thread.
502	* @vmstate Suspended, Running, Guru Mediation, Load Failure
503	* @vmstateto Off
504	*/
505	VMR3DECL(int) VMR3PowerOff(PVM pVM);
506
507	/**
508	* Destroy a VM.
509	* The VM must be powered off (or never really powered on) to call this function.
510	* The VM handle is destroyed and can no longer be used up successful return.
511	*
512	* @returns 0 on success.
513	* @returns VBox error code on failure.
514	* @param pVM VM which should be destroyed.
515	* @thread Any thread but the emulation thread.
516	* @vmstate Off, Created
517	* @vmstateto N/A
518	*/
519	VMR3DECL(int) VMR3Destroy(PVM pVM);
520
521	/**
522	* Calls the relocation functions for all VMM components so they can update
523	* any GC pointers. When this function is called all the basic VM members
524	* have been updated and the actual memory relocation have been done
525	* by the PGM/MM.
526	*
527	* This is used both on init and on runtime relocations.
528	*
529	* @param pVM VM handle.
530	* @param offDelta Relocation delta relative to old location.
531	* @thread The emulation thread.
532	*/
533	VMR3DECL(void) VMR3Relocate(PVM pVM, RTGCINTPTR offDelta);
534
535	/**
536	* Enumerates the VMs in this process.
537	*
538	* @returns Pointer to the next VM.
539	* @returns NULL when no more VMs.
540	* @param pVMPrev The previous VM
541	* Use NULL to start the enumeration.
542	*/
543	VMR3DECL(PVM) VMR3EnumVMs(PVM pVMPrev);
544
545	/**
546	* Wait for VM to be resumed. Handle events like vmR3EmulationThread does.
547	* In case the VM is stopped, clean up and long jump to the main EMT loop.
548	*
549	* @returns VINF_SUCCESS or doesn't return
550	* @param pVM VM handle.
551	*/
552	VMR3DECL(int) VMR3WaitForResume(PVM pVM);
553
554
555	/**
556	* VM destruction callback.
557	* @param pVM The VM which is about to be destroyed.
558	* @param pvUser The user parameter specified at registration.
559	*/
560	typedef DECLCALLBACK(void) FNVMATDTOR(PVM pVM, void *pvUser);
561	/** Pointer to a VM destruction callback. */
562	typedef FNVMATDTOR *PFNVMATDTOR;
563
564	/**
565	* Registers an at VM destruction callback.
566	*
567	* @returns VBox status code.
568	* @param pfnAtDtor Pointer to callback.
569	* @param pvUser User argument.
570	*/
571	VMR3DECL(int) VMR3AtDtorRegister(PFNVMATDTOR pfnAtDtor, void *pvUser);
572
573	/**
574	* Deregisters an at VM destruction callback.
575	*
576	* @returns VBox status code.
577	* @param pfnAtDtor Pointer to callback.
578	*/
579	VMR3DECL(int) VMR3AtDtorDeregister(PFNVMATDTOR pfnAtDtor);
580
581
582	/**
583	* Registers an at VM reset callback.
584	*
585	* @returns VBox status code.
586	* @param pVM The VM.
587	* @param pDevInst Device instance.
588	* @param pfnCallback Callback function.
589	* @param pvUser User argument.
590	* @param pszDesc Description (optional).
591	*/
592	VMR3DECL(int) VMR3AtResetRegister(PVM pVM, PPDMDEVINS pDevInst, PFNVMATRESET pfnCallback, void pvUser, const char pszDesc);
593
594	/**
595	* Registers an at VM reset internal callback.
596	*
597	* @returns VBox status code.
598	* @param pVM The VM.
599	* @param pfnCallback Callback function.
600	* @param pvUser User argument.
601	* @param pszDesc Description (optional).
602	*/
603	VMR3DECL(int) VMR3AtResetRegisterInternal(PVM pVM, PFNVMATRESETINT pfnCallback, void pvUser, const char pszDesc);
604
605	/**
606	* Registers an at VM reset external callback.
607	*
608	* @returns VBox status code.
609	* @param pVM The VM.
610	* @param pfnCallback Callback function.
611	* @param pvUser User argument.
612	* @param pszDesc Description (optional).
613	*/
614	VMR3DECL(int) VMR3AtResetRegisterExternal(PVM pVM, PFNVMATRESETEXT pfnCallback, void pvUser, const char pszDesc);
615
616
617	/**
618	* Deregisters an at VM reset callback.
619	*
620	* @returns VBox status code.
621	* @param pVM The VM.
622	* @param pDevInst Device instance.
623	* @param pfnCallback Callback function.
624	*/
625	VMR3DECL(int) VMR3AtResetDeregister(PVM pVM, PPDMDEVINS pDevInst, PFNVMATRESET pfnCallback);
626
627	/**
628	* Deregisters an at VM reset internal callback.
629	*
630	* @returns VBox status code.
631	* @param pVM The VM.
632	* @param pfnCallback Callback function.
633	*/
634	VMR3DECL(int) VMR3AtResetDeregisterInternal(PVM pVM, PFNVMATRESETINT pfnCallback);
635
636	/**
637	* Deregisters an at VM reset external callback.
638	*
639	* @returns VBox status code.
640	* @param pVM The VM.
641	* @param pfnCallback Callback function.
642	*/
643	VMR3DECL(int) VMR3AtResetDeregisterExternal(PVM pVM, PFNVMATRESETEXT pfnCallback);
644
645
646	/**
647	* Registers a VM state change callback.
648	*
649	* You are not allowed to call any function which changes the VM state from a
650	* state callback, except VMR3Destroy().
651	*
652	* @returns VBox status code.
653	* @param pVM VM handle.
654	* @param pfnAtState Pointer to callback.
655	* @param pvUser User argument.
656	* @thread Any.
657	*/
658	VMR3DECL(int) VMR3AtStateRegister(PVM pVM, PFNVMATSTATE pfnAtState, void *pvUser);
659
660	/**
661	* Deregisters a VM state change callback.
662	*
663	* @returns VBox status code.
664	* @param pVM The VM handle.
665	* @param pfnAtState Pointer to callback.
666	* @param pvUser User argument.
667	* @thread Any.
668	*/
669	VMR3DECL(int) VMR3AtStateDeregister(PVM pVM, PFNVMATSTATE pfnAtState, void *pvUser);
670
671	/**
672	* Gets the current VM state.
673	*
674	* @returns The current VM state.
675	* @param pVM The VM handle.
676	* @thread Any
677	*/
678	VMR3DECL(VMSTATE) VMR3GetState(PVM pVM);
679
680	/**
681	* Gets the state name string for a VM state.
682	*
683	* @returns Pointer to the state name. (readonly)
684	* @param enmState The state.
685	*/
686	VMR3DECL(const char *) VMR3GetStateName(VMSTATE enmState);
687
688	/**
689	* Registers a VM error callback.
690	*
691	* @returns VBox status code.
692	* @param pVM The VM handle.
693	* @param pfnAtError Pointer to callback.
694	* @param pvUser User argument.
695	* @thread Any.
696	*/
697	VMR3DECL(int) VMR3AtErrorRegister(PVM pVM, PFNVMATERROR pfnAtError, void *pvUser);
698
699	/**
700	* Deregisters a VM error callback.
701	*
702	* @returns VBox status code.
703	* @param pVM The VM handle.
704	* @param pfnAtError Pointer to callback.
705	* @param pvUser User argument.
706	* @thread Any.
707	*/
708	VMR3DECL(int) VMR3AtErrorDeregister(PVM pVM, PFNVMATERROR pfnAtError, void *pvUser);
709
710	/**
711	* This is a worker function for GC and Ring-0 calls to VMSetError and VMSetErrorV.
712	* The message is found in VMINT.
713	*
714	* @param pVM The VM handle.
715	* @thread EMT.
716	*/
717	VMR3DECL(void) VMR3SetErrorWorker(PVM pVM);
718
719	/**
720	* Registers a VM runtime error callback.
721	*
722	* @returns VBox status code.
723	* @param pVM The VM handle.
724	* @param pfnAtRuntimeError Pointer to callback.
725	* @param pvUser User argument.
726	* @thread Any.
727	*/
728	VMR3DECL(int) VMR3AtRuntimeErrorRegister(PVM pVM, PFNVMATRUNTIMEERROR pfnAtRuntimeError, void *pvUser);
729
730	/**
731	* Deregisters a VM runtime error callback.
732	*
733	* @returns VBox status code.
734	* @param pVM The VM handle.
735	* @param pfnAtRuntimeError Pointer to callback.
736	* @param pvUser User argument.
737	* @thread Any.
738	*/
739	VMR3DECL(int) VMR3AtRuntimeErrorDeregister(PVM pVM, PFNVMATRUNTIMEERROR pfnAtRuntimeError, void *pvUser);
740
741	/**
742	* This is a worker function for GC and Ring-0 calls to VMSetRuntimeError and VMSetRuntimeErrorV.
743	* The message is found in VMINT.
744	*
745	* @param pVM The VM handle.
746	* @thread EMT.
747	*/
748	VMR3DECL(void) VMR3SetRuntimeErrorWorker(PVM pVM);
749
750
751	/**
752	* Allocate and queue a call request.
753	*
754	* If it's desired to poll on the completion of the request set cMillies
755	* to 0 and use VMR3ReqWait() to check for completation. In the other case
756	* use RT_INDEFINITE_WAIT.
757	* The returned request packet must be freed using VMR3ReqFree().
758	*
759	* @returns VBox status code.
760	* Will not return VERR_INTERRUPTED.
761	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
762	*
763	* @param pVM The VM handle.
764	* @param ppReq Where to store the pointer to the request.
765	* This will be NULL or a valid request pointer not matter what happends.
766	* @param cMillies Number of milliseconds to wait for the request to
767	* be completed. Use RT_INDEFINITE_WAIT to only
768	* wait till it's completed.
769	* @param pfnFunction Pointer to the function to call.
770	* @param cArgs Number of arguments following in the ellipsis.
771	* Not possible to pass 64-bit arguments!
772	* @param ... Function arguments.
773	*/
774	VMR3DECL(int) VMR3ReqCall(PVM pVM, PVMREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
775
776	/**
777	* Allocate and queue a call request to a void function.
778	*
779	* If it's desired to poll on the completion of the request set cMillies
780	* to 0 and use VMR3ReqWait() to check for completation. In the other case
781	* use RT_INDEFINITE_WAIT.
782	* The returned request packet must be freed using VMR3ReqFree().
783	*
784	* @returns VBox status code.
785	* Will not return VERR_INTERRUPTED.
786	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
787	*
788	* @param pVM The VM handle.
789	* @param ppReq Where to store the pointer to the request.
790	* This will be NULL or a valid request pointer not matter what happends.
791	* @param cMillies Number of milliseconds to wait for the request to
792	* be completed. Use RT_INDEFINITE_WAIT to only
793	* wait till it's completed.
794	* @param pfnFunction Pointer to the function to call.
795	* @param cArgs Number of arguments following in the ellipsis.
796	* Not possible to pass 64-bit arguments!
797	* @param ... Function arguments.
798	*/
799	VMR3DECL(int) VMR3ReqCallVoid(PVM pVM, PVMREQ *ppReq, unsigned cMillies, PFNRT pfnFunction, unsigned cArgs, ...);
800
801	/**
802	* Allocate and queue a call request to a void function.
803	*
804	* If it's desired to poll on the completion of the request set cMillies
805	* to 0 and use VMR3ReqWait() to check for completation. In the other case
806	* use RT_INDEFINITE_WAIT.
807	* The returned request packet must be freed using VMR3ReqFree().
808	*
809	* @returns VBox status code.
810	* Will not return VERR_INTERRUPTED.
811	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
812	*
813	* @param pVM The VM handle.
814	* @param ppReq Where to store the pointer to the request.
815	* This will be NULL or a valid request pointer not matter what happends, unless fFlags
816	* contains VMREQFLAGS_NO_WAIT when it will be optional and always NULL.
817	* @param cMillies Number of milliseconds to wait for the request to
818	* be completed. Use RT_INDEFINITE_WAIT to only
819	* wait till it's completed.
820	* @param fFlags A combination of the VMREQFLAGS values.
821	* @param pfnFunction Pointer to the function to call.
822	* @param cArgs Number of arguments following in the ellipsis.
823	* Not possible to pass 64-bit arguments!
824	* @param ... Function arguments.
825	*/
826	VMR3DECL(int) VMR3ReqCallEx(PVM pVM, PVMREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
827
828	/**
829	* Allocate and queue a call request.
830	*
831	* If it's desired to poll on the completion of the request set cMillies
832	* to 0 and use VMR3ReqWait() to check for completation. In the other case
833	* use RT_INDEFINITE_WAIT.
834	* The returned request packet must be freed using VMR3ReqFree().
835	*
836	* @returns VBox status code.
837	* Will not return VERR_INTERRUPTED.
838	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
839	*
840	* @param pVM The VM handle.
841	* @param ppReq Where to store the pointer to the request.
842	* This will be NULL or a valid request pointer not matter what happends, unless fFlags
843	* contains VMREQFLAGS_NO_WAIT when it will be optional and always NULL.
844	* @param cMillies Number of milliseconds to wait for the request to
845	* be completed. Use RT_INDEFINITE_WAIT to only
846	* wait till it's completed.
847	* @param fFlags A combination of the VMREQFLAGS values.
848	* @param pfnFunction Pointer to the function to call.
849	* @param cArgs Number of arguments following in the ellipsis.
850	* Not possible to pass 64-bit arguments!
851	* @param pvArgs Pointer to function arguments.
852	*/
853	VMR3DECL(int) VMR3ReqCallV(PVM pVM, PVMREQ *ppReq, unsigned cMillies, unsigned fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
854
855	/**
856	* Allocates a request packet.
857	*
858	* The caller allocates a request packet, fills in the request data
859	* union and queues the request.
860	*
861	* @returns VBox status code.
862	*
863	* @param pVM VM handle.
864	* @param ppReq Where to store the pointer to the allocated packet.
865	* @param enmType Package type.
866	*/
867	VMR3DECL(int) VMR3ReqAlloc(PVM pVM, PVMREQ *ppReq, VMREQTYPE enmType);
868
869	/**
870	* Free a request packet.
871	*
872	* @returns VBox status code.
873	*
874	* @param pReq Package to free.
875	* @remark The request packet must be in allocated or completed state!
876	*/
877	VMR3DECL(int) VMR3ReqFree(PVMREQ pReq);
878
879	/**
880	* Queue a request.
881	*
882	* The quest must be allocated using VMR3ReqAlloc() and contain
883	* all the required data.
884	* If it's disired to poll on the completion of the request set cMillies
885	* to 0 and use VMR3ReqWait() to check for completation. In the other case
886	* use RT_INDEFINITE_WAIT.
887	*
888	* @returns VBox status code.
889	* Will not return VERR_INTERRUPTED.
890	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
891	*
892	* @param pReq The request to queue.
893	* @param cMillies Number of milliseconds to wait for the request to
894	* be completed. Use RT_INDEFINITE_WAIT to only
895	* wait till it's completed.
896	*/
897	VMR3DECL(int) VMR3ReqQueue(PVMREQ pReq, unsigned cMillies);
898
899	/**
900	* Wait for a request to be completed.
901	*
902	* @returns VBox status code.
903	* Will not return VERR_INTERRUPTED.
904	* @returns VERR_TIMEOUT if cMillies was reached without the packet being completed.
905	*
906	* @param pReq The request to wait for.
907	* @param cMillies Number of milliseconds to wait.
908	* Use RT_INDEFINITE_WAIT to only wait till it's completed.
909	*/
910	VMR3DECL(int) VMR3ReqWait(PVMREQ pReq, unsigned cMillies);
911
912
913
914	/**
915	* Process pending request(s).
916	*
917	* This function is called from a forced action handler in
918	* the EMT.
919	*
920	* @returns VBox status code.
921	*
922	* @param pVM VM handle.
923	*/
924	VMR3DECL(int) VMR3ReqProcess(PVM pVM);
925
926
927	/**
928	* Notify the emulation thread (EMT) about pending Forced Action (FF).
929	*
930	* This function is called by thread other than EMT to make
931	* sure EMT wakes up and promptly service a FF request.
932	*
933	* @param pVM VM handle.
934	* @param fNotifiedREM Set if REM have already been notified. If clear the
935	* generic REMR3NotifyFF() method is called.
936	*/
937	VMR3DECL(void) VMR3NotifyFF(PVM pVM, bool fNotifiedREM);
938
939	/**
940	* Halted VM Wait.
941	* Any external event will unblock the thread.
942	*
943	* @returns VINF_SUCCESS unless a fatal error occured. In the latter
944	* case an appropriate status code is returned.
945	* @param pVM VM handle.
946	* @param fIgnoreInterrupts If set the VM_FF_INTERRUPT flags is ignored.
947	* @thread The emulation thread.
948	*/
949	VMR3DECL(int) VMR3WaitHalted(PVM pVM, bool fIgnoreInterrupts);
950
951	/**
952	* Suspended VM Wait.
953	* Only a handful of forced actions will cause the function to
954	* return to the caller.
955	*
956	* @returns VINF_SUCCESS unless a fatal error occured. In the latter
957	* case an appropriate status code is returned.
958	* @param pVM VM handle.
959	* @thread The emulation thread.
960	*/
961	VMR3DECL(int) VMR3Wait(PVM pVM);
962
963	/** @} */
964	#endif /* IN_RING3 */
965
966
967	#ifdef IN_GC
968	/** @defgroup grp_vmm_apis_gc VM Guest Context APIs
969	* @ingroup grp_vm
970	* @{ */
971
972	/** @} */
973	#endif
974
975	__END_DECLS
976
977	/** @} */
978
979	#endif
980
981

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

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

Download in other formats: