Changeset 12986 in vbox for trunk/include

Timestamp:

Oct 4, 2008 11:41:17 PM (16 years ago)

Author:

vboxsync

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

37419

Message:

More PDM cleanup.

Location:

trunk/include/VBox

Files:

• pdmdrv.h (modified) (1 diff)
• pdmthread.h (modified) (1 diff)
• pdmusb.h (modified) (1 diff)

trunk/include/VBox/pdmdrv.h

@@ -921 +921 @@
 typedef DECLCALLBACK(int) FNPDMVBOXDRIVERSREGISTER(PCPDMDRVREGCB pCallbacks, uint32_t u32Version);
 
-/**
- * Register external drivers
- *
- * @returns VBox status code.
- * @param   pVM         The VM to operate on.
- * @param   pfnCallback Driver registration callback
- */
 PDMR3DECL(int) PDMR3RegisterDrivers(PVM pVM, FNPDMVBOXDRIVERSREGISTER pfnCallback);
 

trunk/include/VBox/pdmthread.h

@@ -284 +284 @@
 
 #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);
-
-/**
- * Called by the PDM thread instead of RTThreadSleep.
- *
- * The difference is that the sleep will be interrupted on state change. The
- * thread must be in the running state, otherwise it will return immediately.
- *
- * @returns VBox status code.
- * @retval  VINF_SUCCESS on success or state change.
- * @retval  VERR_INTERRUPTED on signal or APC.
- *
- * @param   pThread     The PDM thread.
- * @param   cMillies    The number of milliseconds to sleep.
- */
 PDMR3DECL(int) PDMR3ThreadSleep(PPDMTHREAD pThread, unsigned cMillies);
-
-/**
- * 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 */

trunk/include/VBox/pdmusb.h

@@ -763 +763 @@
 typedef DECLCALLBACK(int) FNPDMVBOXUSBREGISTER(PCPDMUSBREGCB pCallbacks, uint32_t u32Version);
 
-
-/**
- * Creates a USB proxy device instance.
- *
- * This will find an appropriate HUB for the USB device, create the necessary CFGM stuff
- * and try instantiate the proxy device.
- *
- * @returns VBox status code.
- * @param   pVM             The VM handle.
- * @param   pUuid           The UUID thats to be associated with the device.
- * @param   fRemote         Whether it's a remove or local device.
- * @param   pszAddress      The address string.
- * @param   pvBackend       Pointer to the backend.
- * @param   iUsbVersion     The preferred USB version.
- * @param   fMaskedIfs      The interfaces to hide from the guest.
- */
-PDMR3DECL(int) PDMR3USBCreateProxyDevice(PVM pVM, PCRTUUID pUuid, bool fRemote, const char *pszAddress, void *pvBackend,
-                                         uint32_t iUsbVersion, uint32_t fMaskedIfs);
-
-/**
- * Detaches and destroys a USB device.
- *
- * @returns VBox status code.
- * @param   pVM             The VM handle.
- * @param   pUuid           The UUID associated with the device to detach.
- * @thread  EMT
- */
-PDMR3DECL(int) PDMR3USBDetachDevice(PVM pVM, PCRTUUID pUuid);
-
-/**
- * Checks if there are any USB hubs attached.
- *
- * @returns true / false accordingly.
- * @param   pVM     Pointer to the shared VM structure.
- */
+PDMR3DECL(int)  PDMR3USBCreateProxyDevice(PVM pVM, PCRTUUID pUuid, bool fRemote, const char *pszAddress, void *pvBackend,
+                                          uint32_t iUsbVersion, uint32_t fMaskedIfs);
+PDMR3DECL(int)  PDMR3USBDetachDevice(PVM pVM, PCRTUUID pUuid);
 PDMR3DECL(bool) PDMR3USBHasHub(PVM pVM);