vmapi.h revision e7e589ca404045e288030a4151e57b63976cb39d
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * VM - The Virtual Machine, API. (VMM)
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * available from http://www.virtualbox.org. This file is free software;
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * you can redistribute it and/or modify it under the terms of the GNU
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * General Public License (GPL) as published by the Free Software
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * The contents of this file may alternatively be used under the terms
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * of the Common Development and Distribution License Version 1.0
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * VirtualBox OSE distribution, in which case the provisions of the
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * CDDL are applicable instead of those of the GPL.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * You may elect to license modified versions of this file under the
43747b1f0bc8302a238fb35e55857a5e9aa1933dvboxsync * terms and conditions of either the GPL or the CDDL or both.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
ee4d840f54fd2dcea8a73b1b86d5ec0db370b05dvboxsync * additional information or have any questions.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync/** @defgroup grp_vmm_apis VM All Contexts API
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @ingroup grp_vm
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync/** @def VM_RC_ADDR
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * Converts a current context address of data within the VM structure to the equivalent
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * raw-mode address.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @returns raw-mode virtual address.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pVM Pointer to the VM.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pvInVM CC Pointer within the VM.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_RC_ADDR(pVM, pvInVM) ( (RTRCPTR)((RTRCUINTPTR)pVM->pVMRC + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMR3)) )
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_RC_ADDR(pVM, pvInVM) ( (RTRCPTR)((RTRCUINTPTR)pVM->pVMRC + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMR0)) )
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_RC_ADDR(pVM, pvInVM) ( (RTRCPTR)(pvInVM) )
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync/** @def VM_R3_ADDR
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync * Converts a current context address of data within the VM structure to the equivalent
e74eef731a813e4e06680c587a6759b9974b29c9vboxsync * ring-3 host address.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @returns host virtual address.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pVM Pointer to the VM.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pvInVM CC pointer within the VM.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_R3_ADDR(pVM, pvInVM) ( (RTR3PTR)((RTR3UINTPTR)pVM->pVMR3 + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMRC)) )
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_R3_ADDR(pVM, pvInVM) ( (RTR3PTR)((RTR3UINTPTR)pVM->pVMR3 + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMR0)) )
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_R3_ADDR(pVM, pvInVM) ( (RTR3PTR)(pvInVM) )
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync/** @def VM_R0_ADDR
ad77e3ec3cde24263bc7537575f5cae442bee3b1vboxsync * Converts a current context address of data within the VM structure to the equivalent
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * ring-0 host address.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @returns host virtual address.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pVM Pointer to the VM.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pvInVM CC pointer within the VM.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_R0_ADDR(pVM, pvInVM) ( (RTR0PTR)((RTR0UINTPTR)pVM->pVMR0 + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMRC)) )
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_R0_ADDR(pVM, pvInVM) ( (RTR0PTR)((RTR0UINTPTR)pVM->pVMR0 + (uint32_t)((uintptr_t)(pvInVM) - (uintptr_t)pVM->pVMR3)) )
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync# define VM_R0_ADDR(pVM, pvInVM) ( (RTR0PTR)(pvInVM) )
ad77e3ec3cde24263bc7537575f5cae442bee3b1vboxsync * VM error callback function.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pVM The VM handle. Can be NULL if an error occurred before
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * successfully creating a VM.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pvUser The user argument.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param rc VBox status code.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param RT_SRC_POS_DECL The source position arguments. See RT_SRC_POS and RT_SRC_POS_ARGS.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pszFormat Error message format string.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param args Error message arguments.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsynctypedef DECLCALLBACK(void) FNVMATERROR(PVM pVM, void *pvUser, int rc, RT_SRC_POS_DECL, const char *pszError, va_list args);
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync/** Pointer to a VM error callback. */
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsyncVMMDECL(int) VMSetError(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...);
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsyncVMMDECL(int) VMSetErrorV(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list args);
ad77e3ec3cde24263bc7537575f5cae442bee3b1vboxsync/** @def VM_SET_ERROR
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * Macro for setting a simple VM error message.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * Don't use '%' in the message!
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @returns rc. Meaning you can do:
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pVM VM handle.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param rc VBox status code.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pszMessage Error message string.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @thread Any
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync#define VM_SET_ERROR(pVM, rc, pszMessage) (VMSetError(pVM, rc, RT_SRC_POS, pszMessage))
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * VM runtime error callback function.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * See VMSetRuntimeError for the detailed description of parameters.
eb90548e8e40e597d65cdcc16ec958a3e09c1d73vboxsync * @param pVM The VM handle.
typedef DECLCALLBACK(void) FNVMATRUNTIMEERROR(PVM pVM, void *pvUser, uint32_t fFlags, const char *pszErrorId,
VMMDECL(int) VMSetRuntimeError(PVM pVM, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, ...);
VMMDECL(int) VMSetRuntimeErrorV(PVM pVM, uint32_t fFlags, const char *pszErrorId, const char *pszFormat, va_list args);
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