VMAll.cpp revision d6882c5bec1c3d6d6a43d88a9fc8c2e2ee39f12d
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * VM - Virtual Machine All Contexts.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Copyright (C) 2006-2007 Sun Microsystems, Inc.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * This file is part of VirtualBox Open Source Edition (OSE), as
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * available from http://www.virtualbox.org. This file is free software;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * you can redistribute it and/or modify it under the terms of the GNU
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * General Public License (GPL) as published by the Free Software
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Foundation, in version 2 as it comes in the "COPYING" file of the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Clara, CA 95054 USA or visit http://www.sun.com if you need
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * additional information or have any questions.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync/*******************************************************************************
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync* Header Files *
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync*******************************************************************************/
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Sets the error message.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns rc. Meaning you can do:
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pVM VM handle. Must be non-NULL.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param rc VBox status code.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param RT_SRC_POS_DECL Use RT_SRC_POS.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pszFormat Error message format string.
7d6ce198fd361f58bd1ebdeee7772f76b4e58966vboxsync * @param ... Error message arguments.
2fce40121ae472df2fd959fbe19775ed43304a0bvboxsync * @thread Any
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncVMMDECL(int) VMSetError(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, ...)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync int rc2 = VMSetErrorV(pVM, rc, RT_SRC_POS_ARGS, pszFormat, args); Assert(rc == rc2); NOREF(rc2);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Sets the error message.
edde275acba04aca58db4172a163741e3abadfbcvboxsync * @returns rc. Meaning you can do:
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
edde275acba04aca58db4172a163741e3abadfbcvboxsync * @param pVM VM handle. Must be non-NULL.
edde275acba04aca58db4172a163741e3abadfbcvboxsync * @param rc VBox status code.
edde275acba04aca58db4172a163741e3abadfbcvboxsync * @param RT_SRC_POS_DECL Use RT_SRC_POS.
edde275acba04aca58db4172a163741e3abadfbcvboxsync * @param pszFormat Error message format string.
a1d9d394b49969e730c5a8e037ea2d672a48dbf6vboxsync * @param args Error message arguments.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @thread Any
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncVMMDECL(int) VMSetErrorV(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list args)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Switch to EMT.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync va_copy(va2, args); /* Have to make a copy here or GCC will break. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync VMR3ReqCall(pVM, &pReq, RT_INDEFINITE_WAIT, (PFNRT)vmR3SetErrorUV, 7, /* ASSUMES 3 source pos args! */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * We're already on the EMT thread and can safely create a VMERROR chunk.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync vmSetErrorCopy(pVM, rc, RT_SRC_POS_ARGS, pszFormat, args);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Copies the error to a VMERROR structure.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * This is mainly intended for Ring-0 and GC where the error must be copied to
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * memory accessible from ring-3. But it's just possible that we might add
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * APIs for retrieving the VMERROR copy later.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pVM VM handle. Must be non-NULL.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param rc VBox status code.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param RT_SRC_POS_DECL Use RT_SRC_POS.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pszFormat Error message format string.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param args Error message arguments.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @thread EMT
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncvoid vmSetErrorCopy(PVM pVM, int rc, RT_SRC_POS_DECL, const char *pszFormat, va_list args)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync#if 0 /// @todo implement Ring-0 and GC VMSetError
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Create the untranslated message copy.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* free any old message. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync MMHyperFree(pVM, MMHyperR32Ctx(pVM, pVM->vm.s.pError));
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync /* calc reasonable start size. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync size_t cchFunction = pszFunction ? strlen(pszFunction) : 0;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* allocate it */
eb259de2a9eac4b4dda56e89f5004671f926bd9bvboxsync int rc2 = MMHyperAlloc(pVM, cb, 0, MM_TAG_VM, &pv);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* initialize it. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync memcpy((uint8_t *)pErr + pErr->off, pszFile, cchFile + 1);
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync memcpy((uint8_t *)pErr + pErr->off, pszFunction, cchFunction + 1);
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync /* format the message (pErr might be reallocated) */
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync RTStrFormatV(vmSetErrorFmtOut, &pErr, NULL, NULL, &pszFormatTmp, args);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* done. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync pVM->vm.s.pErrorR3 = MMHyper2HC(pVM, (uintptr_t)pArgs.pErr);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Sets the runtime error message.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * As opposed VMSetError(), this method is intended to inform the VM user about
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * errors and error-like conditions that happen at an arbitrary point during VM
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * execution (like "host memory low" or "out of host disk space").
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * The @a fFatal parameter defines whether the error is fatal or not. If it is
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * true, then it is expected that the caller has already paused the VM execution
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * before calling this method. The VM user is supposed to power off the VM
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * immediately after it has received the runtime error notification via the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * FNVMATRUNTIMEERROR callback.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * If @a fFatal is false, then the paused state of the VM defines the kind of
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * the error. If the VM is paused before calling this method, it means that
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * the VM user may try to fix the error condition (i.e. free more host memory)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * and then resume the VM execution. If the VM is not paused before calling
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * this method, it means that the given error is a warning about an error
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * condition that may happen soon but that doesn't directly affect the
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * VM execution by the time of the call.
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * The @a pszErrorID parameter defines an unique error identificator.
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * It is used by the front-ends to show a proper message to the end user
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * containig possible actions (for example, Retry/Ignore). For this reason,
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * an error ID assigned once to some particular error condition should not
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * change in the future. The format of this parameter is "someErrorCondition".
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pVM VM handle. Must be non-NULL.
93e05ea894cefd56ca308d72372b4dd8045bd1eevboxsync * @param fFatal Whether it is a fatal error or not.
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * @param pszErrorID Error ID string.
93e05ea894cefd56ca308d72372b4dd8045bd1eevboxsync * @param pszFormat Error message format string.
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * @param ... Error message arguments.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @return VBox status code (whether the error has been successfully set
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * and delivered to callbacks or not).
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @thread Any
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @todo r=bird: The pausing/suspending of the VM should be done here, we'll just end
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * up duplicating code all over the place otherwise. In the case of
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * devices/drivers/etc they might not be trusted to pause/suspend the
a60be2c64ea23bb7ce4c9998bcd541c4db879fbavboxsync * vm even. Change fFatal to fFlags and define action flags and a fatal flag.
8302394f164acb4adb187954f6ac8ef7a9efa629vboxsync * Also, why a string ID and not an enum?
8302394f164acb4adb187954f6ac8ef7a9efa629vboxsyncVMMDECL(int) VMSetRuntimeError(PVM pVM, bool fFatal, const char *pszErrorID,
8302394f164acb4adb187954f6ac8ef7a9efa629vboxsync const char *pszFormat, ...)
beed5fc4d17b85d6d05516ae63e6308af82ad96fvboxsync int rc = VMSetRuntimeErrorV(pVM, fFatal, pszErrorID, pszFormat, args);
beed5fc4d17b85d6d05516ae63e6308af82ad96fvboxsync * va_list version of VMSetRuntimeError.
100b161379af7255c69e27587cc746e5f76ff050vboxsync * @param pVM VM handle. Must be non-NULL.
100b161379af7255c69e27587cc746e5f76ff050vboxsync * @param fFatal Whether it is a fatal error or not.
100b161379af7255c69e27587cc746e5f76ff050vboxsync * @param pszErrorID Error ID string.
100b161379af7255c69e27587cc746e5f76ff050vboxsync * @param pszFormat Error message format string.
100b161379af7255c69e27587cc746e5f76ff050vboxsync * @param args Error message arguments.
100b161379af7255c69e27587cc746e5f76ff050vboxsync * @return VBox status code (whether the error has been successfully set
100b161379af7255c69e27587cc746e5f76ff050vboxsync * and delivered to callbacks or not).
100b161379af7255c69e27587cc746e5f76ff050vboxsync * @thread Any
100b161379af7255c69e27587cc746e5f76ff050vboxsyncVMMDECL(int) VMSetRuntimeErrorV(PVM pVM, bool fFatal, const char *pszErrorID,
beed5fc4d17b85d6d05516ae63e6308af82ad96fvboxsync * Switch to EMT.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync va_copy(va2, args); /* Have to make a copy here or GCC will break. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync VMR3ReqCall(pVM, &pReq, RT_INDEFINITE_WAIT, (PFNRT)vmR3SetRuntimeErrorV, 5,
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * We're already on the EMT thread and can safely create a VMRUNTIMEERROR chunk.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync vmSetRuntimeErrorCopy(pVM, fFatal, pszErrorID, pszFormat, args);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync VMMGCCallHost(pVM, VMMCALLHOST_VM_SET_RUNTIME_ERROR, 0);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync VMMR0CallHost(pVM, VMMCALLHOST_VM_SET_RUNTIME_ERROR, 0);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Copies the error to a VMRUNTIMEERROR structure.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * This is mainly intended for Ring-0 and GC where the error must be copied to
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * memory accessible from ring-3. But it's just possible that we might add
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * APIs for retrieving the VMRUNTIMEERROR copy later.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pVM VM handle. Must be non-NULL.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param fFatal Whether it is a fatal error or not.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pszErrorID Error ID string.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param pszFormat Error message format string.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param args Error message arguments.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @thread EMT
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncvoid vmSetRuntimeErrorCopy(PVM pVM, bool fFatal, const char *pszErrorID,
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync#if 0 /// @todo implement Ring-0 and GC VMSetError
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Create the untranslated message copy.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* free any old message. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync MMHyperFree(pVM, MMHyperR32Ctx(pVM, pVM->vm.s.pRuntimeErrorR3));
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* calc reasonable start size. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync size_t cchErrorID = pszErrorID ? strlen(pszErrorID) : 0;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* allocate it */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync int rc2 = MMHyperAlloc(pVM, cb, 0, MM_TAG_VM, &pv);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* initialize it. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync memcpy((uint8_t *)pErr + pErr->off, pszErrorID, cchErrorID + 1);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* format the message (pErr might be reallocated) */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync RTStrFormatV(vmSetRuntimeErrorFmtOut, &pErr, NULL, NULL, &pszFormatTmp, args);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync /* done. */
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync pVM->vm.s.pErrorRuntimeR3 = MMHyper2HC(pVM, (uintptr_t)pArgs.pErr);
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * Gets the name of VM state.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @returns Pointer to a read-only string with the state name.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync * @param enmState The state.
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsyncVMMDECL(const char *) VMGetStateName(VMSTATE enmState)
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync#define MY_CASE(enm) case VMSTATE_##enm: return #enm;
13493ab7596e827b8d0caab2c89e635dd65f78f9vboxsync return "Unknown";