vmapi.h@ 5999

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

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

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

Download in other formats: