vmapi.h@ 4723

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

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

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

Download in other formats: