vmapi.h@ 4011

Last change on this file since 4011 was 3632, checked in by vboxsync, 17 years ago
VBox_hdr_h -> _VBox_hdr_h
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 33.3 KB

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

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

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

Download in other formats: