Changeset 4012 in vbox for trunk/include/VBox

Timestamp:

Aug 2, 2007 11:48:45 PM (17 years ago)

Author:

vboxsync

Message:

Hooked up the PDMThread stuff.

Location:

trunk/include/VBox

Files:

• pdmdev.h (modified) (2 diffs)
• pdmdrv.h (modified) (2 diffs)
• pdmthread.h (modified) (1 diff)

trunk/include/VBox/pdmdev.h

@@ -2183 +2183 @@
     DECLR3CALLBACKMEMBER(PRTTIMESPEC, pfnUTCNow,(PPDMDEVINS pDevIns, PRTTIMESPEC pTime));
 
+    /**
+     * Creates a PDM thread.
+     * 
+     * This differs from the RTThreadCreate() API in that PDM takes care of suspending, 
+     * resuming, and destroying the thread as the VM state changes.
+     * 
+     * @returns VBox status code.
+     * @param   pDevIns     The device instance.
+     * @param   ppThread    Where to store the thread 'handle'.
+     * @param   pvUser      The user argument to the thread function.
+     * @param   pfnThread   The thread function.
+     * @param   pfnWakeup   The wakup callback. This is called on the EMT thread when
+     *                      a state change is pending.
+     * @param   cbStack     See RTThreadCreate.
+     * @param   enmType     See RTThreadCreate.
+     * @param   pszName     See RTThreadCreate.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnPDMThreadCreate,(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
+                                                  PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
+
+   
     /** Space reserved for future members.
      * @{ */
-    DECLR3CALLBACKMEMBER(void, pfnReserved1,(void));
     DECLR3CALLBACKMEMBER(void, pfnReserved2,(void));
     DECLR3CALLBACKMEMBER(void, pfnReserved3,(void));
@@ -3296 +3316 @@
     pDevIns->pDevHlp->pfnGetCpuId(pDevIns, iLeaf, pEax, pEbx, pEcx, pEdx);
 }
+
+/**
+ * @copydoc PDMDEVHLP::pfnPDMThreadCreate
+ */
+DECLINLINE(int) PDMDevHlpPDMThreadCreate(PPDMDEVINS pDevIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDEV pfnThread,
+                                         PFNPDMTHREADWAKEUPDEV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
+{
+    return pDevIns->pDevHlp->pfnPDMThreadCreate(pDevIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
+}
 #endif /* IN_RING3 */
 

trunk/include/VBox/pdmdrv.h

@@ -555 +555 @@
     DECLR3CALLBACKMEMBER(int, pfnUSBRegisterHub,(PPDMDRVINS pDrvIns, void *pvReservedIn, void **ppvReservedHlp));
 
+    /**
+     * Creates a PDM thread.
+     * 
+     * This differs from the RTThreadCreate() API in that PDM takes care of suspending, 
+     * resuming, and destroying the thread as the VM state changes.
+     * 
+     * @returns VBox status code.
+     * @param   pDrvIns     The driver instance.
+     * @param   ppThread    Where to store the thread 'handle'.
+     * @param   pvUser      The user argument to the thread function.
+     * @param   pfnThread   The thread function.
+     * @param   pfnWakeup   The wakup callback. This is called on the EMT thread when
+     *                      a state change is pending.
+     * @param   cbStack     See RTThreadCreate.
+     * @param   enmType     See RTThreadCreate.
+     * @param   pszName     See RTThreadCreate.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnPDMThreadCreate,(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
+                                                  PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName));
+
     /** Just a safety precaution. */
     uint32_t                        u32TheEnd;
@@ -702 +722 @@
     return pDrvIns->pDrvHlp->pfnUSBRegisterHub(pDrvIns, pvReservedIn, ppvReservedHlp);
 }
+
+/**
+ * @copydoc PDMDRVHLP::pfnPDMThreadCreate
+ */
+DECLINLINE(int) PDMDrvHlpPDMThreadCreate(PPDMDRVINS pDrvIns, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADDRV pfnThread,
+                                         PFNPDMTHREADWAKEUPDRV pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName)
+{
+    return pDrvIns->pDrvHlp->pfnPDMThreadCreate(pDrvIns, ppThread, pvUser, pfnThread, pfnWakeup, cbStack, enmType, pszName);
+}
 #endif /* IN_RING3 */
 

trunk/include/VBox/pdmthread.h

@@ -274 +274 @@
 #define PDMTHREAD_VERSION   0xef010000
 
+#ifdef IN_RING3
+/**
+ * Creates a PDM thread for internal use in the VM.
+ * 
+ * @returns VBox status code.
+ * @param   pVM         The VM handle. 
+ * @param   ppThread    Where to store the thread 'handle'.
+ * @param   pvUser      The user argument to the thread function.
+ * @param   pfnThread   The thread function.
+ * @param   pfnWakeup   The wakup callback. This is called on the EMT thread when
+ *                      a state change is pending.
+ * @param   cbStack     See RTThreadCreate.
+ * @param   enmType     See RTThreadCreate.
+ * @param   pszName     See RTThreadCreate.
+ */
+PDMR3DECL(int) PDMR3ThreadCreate(PVM pVM, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADINT pfnThread,
+                                 PFNPDMTHREADWAKEUPINT pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName);
+
+/**
+ * Creates a PDM thread for VM use by some external party.
+ * 
+ * @returns VBox status code.
+ * @param   pVM         The VM handle. 
+ * @param   ppThread    Where to store the thread 'handle'.
+ * @param   pvUser      The user argument to the thread function.
+ * @param   pfnThread   The thread function.
+ * @param   pfnWakeup   The wakup callback. This is called on the EMT thread when
+ *                      a state change is pending.
+ * @param   cbStack     See RTThreadCreate.
+ * @param   enmType     See RTThreadCreate.
+ * @param   pszName     See RTThreadCreate.
+ */
+PDMR3DECL(int) PDMR3ThreadCreateExternal(PVM pVM, PPPDMTHREAD ppThread, void *pvUser, PFNPDMTHREADEXT pfnThread,
+                                         PFNPDMTHREADWAKEUPEXT pfnWakeup, size_t cbStack, RTTHREADTYPE enmType, const char *pszName);
+
+/**
+ * Destroys a PDM thread.
+ *
+ * This will wakeup the thread, tell it to terminate, and wait for it terminate.
+ *
+ * @returns VBox status code.
+ *          This reflects the success off destroying the thread and not the exit code
+ *          of the thread as this is stored in *pRcThread.
+ * @param   pThread         The thread to destroy.
+ * @param   pRcThread       Where to store the thread exit code. Optional.
+ * @thread  The emulation thread (EMT).
+ */
+PDMR3DECL(int) PDMR3ThreadDestroy(PPDMTHREAD pThread, int *pRcThread);
+
+/**
+ * Called by the PDM thread in response to a wakeup call with
+ * suspending as the new state.
+ *
+ * The thread will block in side this call until the state is changed in
+ * response to a VM state change or to the device/driver/whatever calling the
+ * PDMR3ThreadResume API.
+ *
+ * @returns VBox status code.
+ *          On failure, terminate the thread.
+ * @param   pThread     The PDM thread.
+ */
+PDMR3DECL(int) PDMR3ThreadIAmSuspending(PPDMTHREAD pThread);
+
+/**
+ * Called by the PDM thread in response to a resuming state.
+ *
+ * The purpose of this API is to tell the PDMR3ThreadResume caller that
+ * the the PDM thread has successfully resumed. It will also do the
+ * state transition from the resuming to the running state.
+ *
+ * @returns VBox status code.
+ *          On failure, terminate the thread.
+ * @param   pThread     The PDM thread.
+ */
+PDMR3DECL(int) PDMR3ThreadIAmRunning(PPDMTHREAD pThread);
+
+/**
+ * Suspends the thread.
+ *
+ * This can be called at the power off / suspend notifications to suspend the
+ * PDM thread a bit early. The thread will be automatically suspend upon
+ * completion of the device/driver notification cycle.
+ *
+ * The caller is responsible for serializing the control operations on the
+ * thread. That basically means, always do these calls from the EMT.
+ *
+ * @returns VBox status code.
+ * @param   pThread     The PDM thread.
+ */
+PDMR3DECL(int) PDMR3ThreadSuspend(PPDMTHREAD pThread);
+
+/**
+ * Resumes the thread.
+ *
+ * This can be called the power on / resume notifications to resume the
+ * PDM thread a bit early. The thread will be automatically resumed upon
+ * return from these two notification callbacks (devices/drivers).
+ *
+ * The caller is responsible for serializing the control operations on the
+ * thread. That basically means, always do these calls from the EMT.
+ *
+ * @returns VBox status code.
+ * @param   pThread     The PDM thread.
+ */
+PDMR3DECL(int) PDMR3ThreadResume(PPDMTHREAD pThread);
+#endif /* IN_RING3 */
 
 /** @} */