VirtualBox

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

Last change on this file since 4693 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 */
107typedef 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. */
109typedef 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 */
125VMDECL(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 */
141VMDECL(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 */
170typedef 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. */
174typedef 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 */
213VMDECL(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 */
230VMDECL(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 */
241typedef DECLCALLBACK(int) FNVMATRESET(PPDMDEVINS pDevInst, void *pvUser);
242/** VM reset callback. */
243typedef 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 */
252typedef DECLCALLBACK(int) FNVMATRESETINT(PVM pVM, void *pvUser);
253/** VM reset internal callback. */
254typedef FNVMATRESETINT *PFNVMATRESETINT;
255
256/**
257 * VM reset external callback.
258 *
259 * @param pvUser User argument.
260 */
261typedef DECLCALLBACK(void) FNVMATRESETEXT(void *pvUser);
262/** VM reset external callback. */
263typedef 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 */
277typedef DECLCALLBACK(void) FNVMATSTATE(PVM pVM, VMSTATE enmState, VMSTATE enmOldState, void *pvUser);
278/** Pointer to a VM state callback. */
279typedef FNVMATSTATE *PFNVMATSTATE;
280
281
282/**
283 * Request type.
284 */
285typedef 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 */
298typedef 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 */
317typedef 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 */
336typedef 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. */
373typedef 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 */
396typedef 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 */
426VMR3DECL(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 */
438VMR3DECL(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 */
449VMR3DECL(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 */
461VMR3DECL(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 */
472VMR3DECL(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 */
483VMR3DECL(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 */
495typedef DECLCALLBACK(int) FNVMPROGRESS(PVM pVM, unsigned uPercent, void *pvUser);
496/** Pointer to a FNVMPROGRESS function. */
497typedef 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 */
514VMR3DECL(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 */
532VMR3DECL(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 */
544VMR3DECL(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 */
558VMR3DECL(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 */
572VMR3DECL(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 */
582VMR3DECL(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 */
591VMR3DECL(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 */
599typedef DECLCALLBACK(void) FNVMATDTOR(PVM pVM, void *pvUser);
600/** Pointer to a VM destruction callback. */
601typedef 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 */
610VMR3DECL(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 */
618VMR3DECL(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 */
631VMR3DECL(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 */
642VMR3DECL(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 */
653VMR3DECL(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 */
664VMR3DECL(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 */
673VMR3DECL(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 */
682VMR3DECL(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 */
697VMR3DECL(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 */
708VMR3DECL(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 */
717VMR3DECL(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 */
725VMR3DECL(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 */
736VMR3DECL(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 */
747VMR3DECL(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 */
756VMR3DECL(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 */
767VMR3DECL(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 */
778VMR3DECL(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 */
787VMR3DECL(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 */
813VMR3DECL(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 */
838VMR3DECL(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 */
865VMR3DECL(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 */
892VMR3DECL(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 */
906VMR3DECL(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 */
916VMR3DECL(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 */
936VMR3DECL(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 */
949VMR3DECL(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 */
963VMR3DECL(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 */
976VMR3DECL(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 */
988VMR3DECL(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 */
1000VMR3DECL(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.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette