Changeset 38847 in vbox for trunk/include/VBox/vmm

Timestamp:

Sep 23, 2011 1:19:23 PM (14 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

74144

Message:

PDM: Enter the device critical section for PDM callback.

File:

• trunk/include/VBox/vmm/pdmdev.h (modified) (14 diffs)

trunk/include/VBox/vmm/pdmdev.h

@@ -76 +76 @@
  *
  * @returns VBox status.
- * @param   pDevIns     The device instance data.
+ * @param   pDevIns     The device instance data. 
+ *  
+ * @remarks The device critical section is not entered.  The routine may delete 
+ *          the critical section, so the caller cannot exit it.
  */
 typedef DECLCALLBACK(int)   FNPDMDEVDESTRUCT(PPDMDEVINS pDevIns);
@@ -96 +99 @@
  * @param   offDelta    The relocation delta relative to the old location.
  *
- * @remark  A relocation CANNOT fail.
+ * @remarks A relocation CANNOT fail.
+ *  
+ * @remarks The device critical section is not entered.  The relocations should 
+ *          not normally require any locking.
  */
 typedef DECLCALLBACK(void) FNPDMDEVRELOCATE(PPDMDEVINS pDevIns, RTGCINTPTR offDelta);
@@ -117 +123 @@
  * @param   cbOut       Size of output data.
  * @param   pcbOut      Where to store the actual size of the output data.
+ *  
+ * @remarks Not used.
  */
 typedef DECLCALLBACK(int) FNPDMDEVIOCTL(PPDMDEVINS pDevIns, RTUINT uFunction,
@@ -129 +137 @@
  * @returns VBox status.
  * @param   pDevIns     The device instance data.
+ *  
+ * @remarks Caller enters the device critical section.
  */
 typedef DECLCALLBACK(void)   FNPDMDEVPOWERON(PPDMDEVINS pDevIns);
@@ -139 +149 @@
  * @returns VBox status.
  * @param   pDevIns     The device instance data.
+ *  
+ * @remarks Caller enters the device critical section.
  */
 typedef DECLCALLBACK(void)  FNPDMDEVRESET(PPDMDEVINS pDevIns);
@@ -150 +162 @@
  * @param   pDevIns     The device instance data.
  * @thread  EMT(0)
+ *  
+ * @remarks Caller enters the device critical section.
  */
 typedef DECLCALLBACK(void)  FNPDMDEVSUSPEND(PPDMDEVINS pDevIns);
@@ -160 +174 @@
  * @returns VBox status.
  * @param   pDevIns     The device instance data.
+ *  
+ * @remarks Caller enters the device critical section.
  */
 typedef DECLCALLBACK(void)  FNPDMDEVRESUME(PPDMDEVINS pDevIns);
@@ -174 +190 @@
  * @param   pDevIns     The device instance data.
  * @thread  EMT(0)
+ *  
+ * @remarks Caller enters the device critical section.
  */
 typedef DECLCALLBACK(void)   FNPDMDEVPOWEROFF(PPDMDEVINS pDevIns);
@@ -192 +210 @@
  * @param   iLUN        The logical unit which is being detached.
  * @param   fFlags      Flags, combination of the PDM_TACH_FLAGS_* \#defines.
+ *  
+ * @remarks Caller enters the device critical section.
  */
 typedef DECLCALLBACK(int)  FNPDMDEVATTACH(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags);
@@ -209 +229 @@
  * @param   iLUN        The logical unit which is being detached.
  * @param   fFlags      Flags, combination of the PDMDEVATT_FLAGS_* \#defines.
+ *  
+ * @remarks Caller enters the device critical section.
  */
 typedef DECLCALLBACK(void)  FNPDMDEVDETACH(PPDMDEVINS pDevIns, unsigned iLUN, uint32_t fFlags);
@@ -221 +243 @@
  * @param   iLUN        The logicial unit to query.
  * @param   ppBase      Where to store the pointer to the base interface of the LUN.
+ *  
+ * @remarks The device critical section is not entered.
  */
 typedef DECLCALLBACK(int) FNPDMDEVQUERYINTERFACE(PPDMDEVINS pDevIns, unsigned iLUN, PPDMIBASE *ppBase);
@@ -233 +257 @@
  * @returns VBOX status code.
  * @param   pDevIns     The device instance.
+ *  
+ * @remarks Caller enters the device critical section.
  */
 typedef DECLCALLBACK(int) FNPDMDEVINITCOMPLETE(PPDMDEVINS pDevIns);
@@ -273 +299 @@
     /** Construct instance - required. */
     PFNPDMDEVCONSTRUCT  pfnConstruct;
-    /** Destruct instance - optional. */
+    /** Destruct instance - optional.
+     * Critical section NOT entered (will be destroyed).  */
     PFNPDMDEVDESTRUCT   pfnDestruct;
-    /** Relocation command - optional. */
+    /** Relocation command - optional.
+     * Critical section NOT entered. */ 
     PFNPDMDEVRELOCATE   pfnRelocate;
-    /** I/O Control interface - optional. */
+    /** I/O Control interface - optional.
+     * Not used.  */
     PFNPDMDEVIOCTL      pfnIOCtl;
-    /** Power on notification - optional. */
+    /** Power on notification - optional.
+     * Critical section is entered. */ 
     PFNPDMDEVPOWERON    pfnPowerOn;
-    /** Reset notification - optional. */
+    /** Reset notification - optional. 
+     * Critical section is entered. */ 
     PFNPDMDEVRESET      pfnReset;
-    /** Suspend notification  - optional. */
+    /** Suspend notification  - optional. 
+     * Critical section is entered. */ 
     PFNPDMDEVSUSPEND    pfnSuspend;
-    /** Resume notification - optional. */
+    /** Resume notification - optional. 
+     * Critical section is entered. */ 
     PFNPDMDEVRESUME     pfnResume;
-    /** Attach command - optional. */
+    /** Attach command - optional. 
+     * Critical section is entered. */ 
     PFNPDMDEVATTACH     pfnAttach;
-    /** Detach notification - optional. */
+    /** Detach notification - optional. 
+     * Critical section is entered. */ 
     PFNPDMDEVDETACH     pfnDetach;
-    /** Query a LUN base interface - optional. */
+    /** Query a LUN base interface - optional.
+     * Critical section is NOT entered. */ 
     PFNPDMDEVQUERYINTERFACE pfnQueryInterface;
-    /** Init complete notification - optional. */
+    /** Init complete notification - optional. 
+     * Critical section is entered. */ 
     PFNPDMDEVINITCOMPLETE   pfnInitComplete;
-    /** Power off notification - optional. */
+    /** Power off notification - optional. 
+     * Critical section is entered. */ 
     PFNPDMDEVPOWEROFF   pfnPowerOff;
     /** @todo */
@@ -3863 +3901 @@
     /** The critical section for the device.
      *
-     * TM and IOM will enter this critical section before calling into the
-     * device code.  SSM will currently not, but this will be changed later on.
+     * TM and IOM will enter this critical section before calling into the device 
+     * code.  PDM will when doing power on, power off, reset, suspend and resume 
+     * notifications.  SSM will currently not, but this will be changed later on. 
      *
      * The device gets a critical section automatically assigned to it before