Changeset 234 in vbox for trunk/include/VBox

Timestamp:

Jan 23, 2007 1:04:38 PM (18 years ago)

Author:

vboxsync

Message:

VMM: Added support for runtime error notifications (VMSetRuntimeError and friends).

Location:

trunk/include/VBox

Files:

• vmapi.h (modified) (5 diffs)
• vmm.h (modified) (1 diff)

trunk/include/VBox/vmapi.h

@@ -88 +88 @@
  *    @code
  *    return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
- *    @codeend
+ *    @endcode
  * @param   pVM             VM handle. Must be non-NULL.
  * @param   rc              VBox status code.
@@ -104 +104 @@
  *    @code
  *    return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
- *    @codeend
+ *    @endcode
  * @param   pVM             VM handle. Must be non-NULL.
  * @param   rc              VBox status code.
@@ -121 +121 @@
  *    @code
  *    return VM_SET_ERROR(pVM, VERR_OF_YOUR_CHOICE, "descriptive message");
- *    @codeend
+ *    @endcode
  * @param   pVM             VM handle.
  * @param   rc              VBox status code.
@@ -128 +128 @@
  */
 #define VM_SET_ERROR(pVM, rc, pszMessage)   (VMSetError(pVM, rc, RT_SRC_POS, pszMessage))
+
+
+/**
+ * VM runtime error callback function.
+ * See VMSetRuntimeError for the detailed description of parameters.
+ *
+ * @param   pVM             The VM handle.
+ * @param   pvUser          The user argument.
+ * @param   fFatal          Whether it is a fatal error or not.
+ * @param   pszErrorID      Error ID string.
+ * @param   pszFormat       Error message format string.
+ * @param   args            Error message arguments.
+ */
+typedef DECLCALLBACK(void) FNVMATRUNTIMEERROR(PVM pVM, void *pvUser, bool fFatal,
+                                              const char *pszErrorID,
+                                              const char *pszFormat, va_list args);
+/** Pointer to a VM runtime error callback. */
+typedef FNVMATRUNTIMEERROR *PFNVMATRUNTIMEERROR;
+
+/**
+ * Sets the runtime error message.
+ * As opposed VMSetError(), this method is intended to inform the VM user about
+ * errors and error-like conditions that happen at an arbitrary point during VM
+ * execution (like "host memory low" or "out of host disk space").
+ *
+ * The @a fFatal parameter defines whether the error is fatal or not. If it is
+ * true, then it is expected that the caller has already paused the VM execution
+ * before calling this method. The VM user is supposed to power off the VM
+ * immediately after it has received the runtime error notification via the
+ * FNVMATRUNTIMEERROR callback.
+ *
+ * If @a fFatal is false, then the paused state of the VM defines the kind of
+ * the error. If the VM is paused before calling this method, it means that
+ * the VM user may try to fix the error condition (i.e. free more host memory)
+ * and then resume the VM execution. If the VM is not paused before calling
+ * this method, it means that the given error is a warning about an error
+ * condition that may happen soon but that doesn't directly affect the
+ * VM execution by the time of the call.
+ *
+ * The @a pszErrorID parameter defines an unique error identificator.
+ * It is used by the front-ends to show a proper message to the end user
+ * containig possible actions (for example, Retry/Ignore). For this reason,
+ * an error ID assigned once to some particular error condition should not
+ * change in the future. The format of this parameter is "SomeErrorCondition". 
+ *
+ * @param   pVM             VM handle. Must be non-NULL.
+ * @param   fFatal          Whether it is a fatal error or not.
+ * @param   pszErrorID      Error ID string.
+ * @param   pszFormat       Error message format string.
+ * @param   ...             Error message arguments.
+ *
+ * @return  VBox status code (whether the error has been successfully set
+ *          and delivered to callbacks or not).
+ *
+ * @thread  Any
+ */
+VMDECL(int) VMSetRuntimeError(PVM pVM, bool fFatal, const char *pszErrorID,
+                              const char *pszFormat, ...);
+
+/**
+ * va_list version of VMSetRuntimeError.
+ *
+ * @param   pVM             VM handle. Must be non-NULL.
+ * @param   fFatal          Whether it is a fatal error or not.
+ * @param   pszErrorID      Error ID string.
+ * @param   pszFormat       Error message format string.
+ * @param   args            Error message arguments.
+ *
+ * @return  VBox status code (whether the error has been successfully set
+ *          and delivered to callbacks or not).
+ *
+ * @thread  Any
+ */
+VMDECL(int) VMSetRuntimeErrorV(PVM pVM, bool fFatal, const char *pszErrorID,
+                               const char *pszFormat, va_list args);
 
 
@@ -632 +707 @@
 VMR3DECL(void) VMR3SetErrorWorker(PVM pVM);
 
+/**
+ * Registers a VM runtime error callback.
+ *
+ * @returns VBox status code.
+ * @param   pVM                 The VM handle.
+ * @param   pfnAtRuntimeError   Pointer to callback.
+ * @param   pvUser              User argument.
+ * @thread  Any.
+ */
+VMR3DECL(int)   VMR3AtRuntimeErrorRegister(PVM pVM, PFNVMATRUNTIMEERROR pfnAtRuntimeError, void *pvUser);
+
+/**
+ * Deregisters a VM runtime error callback.
+ *
+ * @returns VBox status code.
+ * @param   pVM                 The VM handle.
+ * @param   pfnAtRuntimeError   Pointer to callback.
+ * @param   pvUser              User argument.
+ * @thread  Any.
+ */
+VMR3DECL(int)   VMR3AtRuntimeErrorDeregister(PVM pVM, PFNVMATRUNTIMEERROR pfnAtRuntimeError, void *pvUser);
+
+/**
+ * This is a worker function for GC and Ring-0 calls to VMSetRuntimeError and VMSetRuntimeErrorV.
+ * The message is found in VMINT.
+ *
+ * @param   pVM             The VM handle.
+ * @thread  EMT.
+ */
+VMR3DECL(void) VMR3SetRuntimeErrorWorker(PVM pVM);
+
 
 /**

trunk/include/VBox/vmm.h

@@ -86 +86 @@
     /** Set the VM error message. */
     VMMCALLHOST_VM_SET_ERROR,
+    /** Set the VM runtime error message. */
+    VMMCALLHOST_VM_SET_RUNTIME_ERROR,
     /** The usual 32-bit hack. */
     VMMCALLHOST_32BIT_HACK = 0x7fffffff