vmapi.h revision 70e70d246c1b592db31d93071c48bb43ea61100e
486a57e2622e0076c60148ad1634608afdefc9degryzor * VM - The Virtual Machine, API. (VMM)
486a57e2622e0076c60148ad1634608afdefc9degryzor * Copyright (C) 2006-2007 Sun Microsystems, Inc.
486a57e2622e0076c60148ad1634608afdefc9degryzor * This file is part of VirtualBox Open Source Edition (OSE), as
486a57e2622e0076c60148ad1634608afdefc9degryzor * available from http://www.virtualbox.org. This file is free software;
486a57e2622e0076c60148ad1634608afdefc9degryzor * you can redistribute it and/or modify it under the terms of the GNU
486a57e2622e0076c60148ad1634608afdefc9degryzor * General Public License (GPL) as published by the Free Software
486a57e2622e0076c60148ad1634608afdefc9degryzor * Foundation, in version 2 as it comes in the "COPYING" file of the
486a57e2622e0076c60148ad1634608afdefc9degryzor * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
486a57e2622e0076c60148ad1634608afdefc9degryzor * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
486a57e2622e0076c60148ad1634608afdefc9degryzor * The contents of this file may alternatively be used under the terms
486a57e2622e0076c60148ad1634608afdefc9degryzor * of the Common Development and Distribution License Version 1.0
486a57e2622e0076c60148ad1634608afdefc9degryzor * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
486a57e2622e0076c60148ad1634608afdefc9degryzor * VirtualBox OSE distribution, in which case the provisions of the
486a57e2622e0076c60148ad1634608afdefc9degryzor * CDDL are applicable instead of those of the GPL.
486a57e2622e0076c60148ad1634608afdefc9degryzor * You may elect to license modified versions of this file under the
486a57e2622e0076c60148ad1634608afdefc9degryzor * terms and conditions of either the GPL or the CDDL or both.
486a57e2622e0076c60148ad1634608afdefc9degryzor * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
486a57e2622e0076c60148ad1634608afdefc9degryzor * Clara, CA 95054 USA or visit http://www.sun.com if you need
486a57e2622e0076c60148ad1634608afdefc9degryzor * additional information or have any questions.
486a57e2622e0076c60148ad1634608afdefc9degryzor/** @defgroup grp_vmm_apis VM All Contexts API
3841a292dc897875faf23e639807abcc90082f3clgentis * @ingroup grp_vm
3841a292dc897875faf23e639807abcc90082f3clgentis/** @def VM_RC_ADDR
3841a292dc897875faf23e639807abcc90082f3clgentis * Converts a current context address of data within the VM structure to the equivalent
3841a292dc897875faf23e639807abcc90082f3clgentis * raw-mode address.
3841a292dc897875faf23e639807abcc90082f3clgentis * @returns raw-mode virtual address.
a52bc627e27a94219f06896ac183d90deb79ad31lgentis * @param pVM Pointer to the VM.
3841a292dc897875faf23e639807abcc90082f3clgentis * @param pvInVM CC Pointer within the VM.
3841a292dc897875faf23e639807abcc90082f3clgentis# define VM_RC_ADDR(pVM, pvInVM) ( (RTRCPTR)((RTRCUINTPTR)pVM->pVMRC + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMR3)) )
3841a292dc897875faf23e639807abcc90082f3clgentis# define VM_RC_ADDR(pVM, pvInVM) ( (RTRCPTR)((RTRCUINTPTR)pVM->pVMRC + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMR0)) )
3841a292dc897875faf23e639807abcc90082f3clgentis# define VM_RC_ADDR(pVM, pvInVM) ( (RTRCPTR)(pvInVM) )
3841a292dc897875faf23e639807abcc90082f3clgentis/** @def VM_R3_ADDR
3841a292dc897875faf23e639807abcc90082f3clgentis * Converts a current context address of data within the VM structure to the equivalent
3841a292dc897875faf23e639807abcc90082f3clgentis * ring-3 host address.
3841a292dc897875faf23e639807abcc90082f3clgentis * @returns host virtual address.
3841a292dc897875faf23e639807abcc90082f3clgentis * @param pVM Pointer to the VM.
3841a292dc897875faf23e639807abcc90082f3clgentis * @param pvInVM CC pointer within the VM.
3841a292dc897875faf23e639807abcc90082f3clgentis# define VM_R3_ADDR(pVM, pvInVM) ( (RTR3PTR)((RTR3UINTPTR)pVM->pVMR3 + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMRC)) )
3841a292dc897875faf23e639807abcc90082f3clgentis# define VM_R3_ADDR(pVM, pvInVM) ( (RTR3PTR)((RTR3UINTPTR)pVM->pVMR3 + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMR0)) )
3841a292dc897875faf23e639807abcc90082f3clgentis# define VM_R3_ADDR(pVM, pvInVM) ( (RTR3PTR)(pvInVM) )
486a57e2622e0076c60148ad1634608afdefc9degryzor/** @def VM_R0_ADDR
486a57e2622e0076c60148ad1634608afdefc9degryzor * Converts a current context address of data within the VM structure to the equivalent
486a57e2622e0076c60148ad1634608afdefc9degryzor * ring-0 host address.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @returns host virtual address.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pVM Pointer to the VM.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pvInVM CC pointer within the VM.
486a57e2622e0076c60148ad1634608afdefc9degryzor# define VM_R0_ADDR(pVM, pvInVM) ( (RTR0PTR)((RTR0UINTPTR)pVM->pVMR0 + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMRC)) )
486a57e2622e0076c60148ad1634608afdefc9degryzor# define VM_R0_ADDR(pVM, pvInVM) ( (RTR0PTR)((RTR0UINTPTR)pVM->pVMR0 + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMR3)) )
486a57e2622e0076c60148ad1634608afdefc9degryzor# define VM_R0_ADDR(pVM, pvInVM) ( (RTR0PTR)(pvInVM) )
486a57e2622e0076c60148ad1634608afdefc9degryzor * VM error callback function.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pVM The VM handle. Can be NULL if an error occurred before
486a57e2622e0076c60148ad1634608afdefc9degryzor * successfully creating a VM.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pvUser The user argument.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param rc VBox status code.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param RT_SRC_POS_DECL The source position arguments. See RT_SRC_POS and RT_SRC_POS_ARGS.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pszFormat Error message format string.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param args Error message arguments.
486a57e2622e0076c60148ad1634608afdefc9degryzortypedef DECLCALLBACK(void) FNVMATERROR(PVM pVM, void *pvUser, int rc, RT_SRC_POS_DECL, const char *pszError, va_list args);
486a57e2622e0076c60148ad1634608afdefc9degryzor/** Pointer to a VM error callback. */
486a57e2622e0076c60148ad1634608afdefc9degryzorVMMDECL(int) VMSetError(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...);
486a57e2622e0076c60148ad1634608afdefc9degryzorVMMDECL(int) VMSetErrorV(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list args);
486a57e2622e0076c60148ad1634608afdefc9degryzor/** @def VM_SET_ERROR
486a57e2622e0076c60148ad1634608afdefc9degryzor * Macro for setting a simple VM error message.
486a57e2622e0076c60148ad1634608afdefc9degryzor * Don't use '%' in the message!
486a57e2622e0076c60148ad1634608afdefc9degryzor * @returns rc. Meaning you can do:
486a57e2622e0076c60148ad1634608afdefc9degryzor * return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pVM VM handle.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param rc VBox status code.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pszMessage Error message string.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @thread Any
486a57e2622e0076c60148ad1634608afdefc9degryzor#define VM_SET_ERROR(pVM, rc, pszMessage) (VMSetError(pVM, rc, RT_SRC_POS, pszMessage))
486a57e2622e0076c60148ad1634608afdefc9degryzor * VM runtime error callback function.
486a57e2622e0076c60148ad1634608afdefc9degryzor * See VMSetRuntimeError for the detailed description of parameters.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pVM The VM handle.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pvUser The user argument.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param fFlags The error flags.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pszErrorId Error ID string.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pszFormat Error message format string.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param va Error message arguments.
486a57e2622e0076c60148ad1634608afdefc9degryzortypedef DECLCALLBACK(void) FNVMATRUNTIMEERROR(PVM pVM, void *pvUser, uint32_t fFlags, const char *pszErrorId,
486a57e2622e0076c60148ad1634608afdefc9degryzor/** Pointer to a VM runtime error callback. */
486a57e2622e0076c60148ad1634608afdefc9degryzorVMMDECL(int) VMSetRuntimeError(PVM pVM, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, ...);
486a57e2622e0076c60148ad1634608afdefc9degryzorVMMDECL(int) VMSetRuntimeErrorV(PVM pVM, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list args);
486a57e2622e0076c60148ad1634608afdefc9degryzor/** @name VMSetRuntimeError fFlags
486a57e2622e0076c60148ad1634608afdefc9degryzor * When no flags are given the VM will continue running and it's up to the front
486a57e2622e0076c60148ad1634608afdefc9degryzor * end to take action on the error condition.
486a57e2622e0076c60148ad1634608afdefc9degryzor/** The error is fatal.
486a57e2622e0076c60148ad1634608afdefc9degryzor * The VM is not in a state where it can be saved and will enter a state
486a57e2622e0076c60148ad1634608afdefc9degryzor * where it can no longer execute code. The caller <b>must</b> propagate status
486a57e2622e0076c60148ad1634608afdefc9degryzor * codes. */
486a57e2622e0076c60148ad1634608afdefc9degryzor/** Suspend the VM after, or if possible before, raising the error on EMT. The
486a57e2622e0076c60148ad1634608afdefc9degryzor * caller <b>must</b> propagate status codes. */
486a57e2622e0076c60148ad1634608afdefc9degryzor/** Don't wait for the EMT to handle the request.
486a57e2622e0076c60148ad1634608afdefc9degryzor * Only valid when on a worker thread and there is a high risk of a dead
486a57e2622e0076c60148ad1634608afdefc9degryzor * lock. Be careful not to flood the user with errors. */
486a57e2622e0076c60148ad1634608afdefc9degryzor * VM state callback function.
486a57e2622e0076c60148ad1634608afdefc9degryzor * You are not allowed to call any function which changes the VM state from a
486a57e2622e0076c60148ad1634608afdefc9degryzor * state callback, except VMR3Destroy().
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pVM The VM handle.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param enmState The new state.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param enmOldState The old state.
486a57e2622e0076c60148ad1634608afdefc9degryzor * @param pvUser The user argument.
typedef DECLCALLBACK(void) FNVMATSTATE(PVM pVM, VMSTATE enmState, VMSTATE enmOldState, void *pvUser);
typedef enum VMREQTYPE
VMREQTYPE_INVALID = 0,
} VMREQTYPE;
typedef enum VMREQSTATE
VMREQSTATE_INVALID = 0,
} VMREQSTATE;
typedef enum VMREQFLAGS
} VMREQFLAGS;
typedef struct VMREQ
volatile int iStatus;
volatile bool fEventSemClear;
unsigned fFlags;
union VMREQ_U
unsigned cArgs;
} Internal;
} VMREQ;
#ifndef IN_RC
#ifdef IN_RING3
typedef enum VMINITCOMPLETED
VMMR3DECL(int) VMR3Create(uint32_t cCpus, PFNVMATERROR pfnVMAtError, void *pvUserVM, PFNCFGMCONSTRUCTOR pfnCFGMConstructor, void *pvUserCFGM, PVM *ppVM);
VMMR3DECL(int) VMR3Save(PVM pVM, const char *pszFilename, bool fContinueAfterwards, PFNVMPROGRESS pfnProgress, void *pvUser, bool *pfSuspended);
VMMR3DECL(int) VMR3Teleport(PVM pVM, uint32_t cMsDowntime, PCSSMSTRMOPS pStreamOps, void *pvStreamOpsUser, PFNVMPROGRESS pfnProgress, void *pvProgressUser, bool *pfSuspended);
VMMR3DECL(int) VMR3LoadFromFile(PVM pVM, const char *pszFilename, PFNVMPROGRESS pfnProgress, void *pvUser);
VMMR3DECL(int) VMR3AtRuntimeErrorRegister(PVM pVM, PFNVMATRUNTIMEERROR pfnAtRuntimeError, void *pvUser);
VMMR3DECL(int) VMR3AtRuntimeErrorDeregister(PVM pVM, PFNVMATRUNTIMEERROR pfnAtRuntimeError, void *pvUser);
VMMR3DECL(int) VMR3ReqCall(PVM pVM, VMCPUID idDstCpu, PVMREQ *ppReq, RTMSINTERVAL cMillies, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3ReqCallU(PUVM pUVM, VMCPUID idDstCpu, PVMREQ *ppReq, RTMSINTERVAL cMillies, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3ReqCallVU(PUVM pUVM, VMCPUID idDstCpu, PVMREQ *ppReq, RTMSINTERVAL cMillies, uint32_t fFlags, PFNRT pfnFunction, unsigned cArgs, va_list Args);
VMMR3DECL(int) VMR3ReqCallWaitU(PUVM pUVM, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3ReqCallNoWait(PVM pVM, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3ReqCallNoWaitU(PUVM pUVM, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3ReqCallVoidWait(PVM pVM, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3ReqCallVoidWaitU(PUVM pUVM, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3ReqCallVoidNoWait(PVM pVM, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3ReqCallVoidNoWaitU(PUVM pUVM, VMCPUID idDstCpu, PFNRT pfnFunction, unsigned cArgs, ...);
VMMR3DECL(int) VMR3GetCpuCoreAndPackageIdFromCpuId(PVM pVM, VMCPUID idCpu, uint32_t *pidCpuCore, uint32_t *pidCpuPackage);
#ifdef IN_RC