Changeset 10075 in vbox

Timestamp:

Jul 1, 2008 3:37:13 PM (17 years ago)

Author:

vboxsync

Message:

Simplified it a bit by introducing a out-bound lock on the trunk port.

File:

• trunk/include/VBox/intnet.h (modified) (12 diffs)

trunk/include/VBox/intnet.h

@@ -391 +391 @@
  *
  * This is only used for the in-kernel trunk connections.
+ *
+ * @remarks The internal network side is responsible for serializing all calls
+ *          to this interface. This is (assumed) to be implemented using a lock
+ *          that is only ever taken before a call to this interface. The lock
+ *          is referred to as the out-bound trunk port lock.
  */
 typedef struct INTNETTRUNKIFPORT
@@ -404 +409 @@
      * @param   pIfPort     Pointer to this structure.
      *
-     * @remarks The caller may own any locks.
+     * @remarks The caller may own any locks or none at all, we don't care.
      */
     DECLR0CALLBACKMEMBER(void, pfnRetain,(PINTNETTRUNKIFPORT pIfPort));
@@ -416 +421 @@
      * @param   pIfPort     Pointer to this structure.
      *
-     * @remarks Where possible, it should be executed without holding any locks
-     *          unless the caller is certain it is not going to trigger the destructor.
+     * @remarks Only the out-bound trunk port lock, unless the caller is certain the
+     *          call is not going to cause destruction (wont happen).
      */
     DECLR0CALLBACKMEMBER(void, pfnRelease,(PINTNETTRUNKIFPORT pIfPort));
@@ -429 +434 @@
      * @param   pIfPort     Pointer to this structure.
      *
-     * @remarks Called without holding any locks.
+     * @remarks Called holding the out-bound trunk port lock.
      */
     DECLR0CALLBACKMEMBER(void, pfnDisconnectAndRelease,(PINTNETTRUNKIFPORT pIfPort));
@@ -453 +458 @@
      * @param   fActive     True if the new state is 'active', false if the new state is 'suspended'.
      *
-     * @remarks Called while *not* owning any semaphores. Will not grab anything.
+     * @remarks Called holding the out-bound trunk port lock.
      */
     DECLR0CALLBACKMEMBER(bool, pfnSetActive,(PINTNETTRUNKIFPORT pIfPort, bool fActive));
@@ -469 +474 @@
      *                      an indefinite wait.
      *
-     * @remarks Called while *not* owning any semaphores. Will not grab anything.
+     * @remarks Called holding the out-bound trunk port lock.
      */
     DECLR0CALLBACKMEMBER(bool, pfnWaitForIdle,(PINTNETTRUNKIFPORT pIfPort, uint32_t cMillies));
@@ -482 +487 @@
      * @param   pMac        Pointer to the mac address.
      *
-     * @remarks Called while owning the network semaphore.
+     * @remarks Called while owning the network and the out-bound trunk port semaphores.
      *
      * @remarks TAP and NAT will compare with their own MAC address and let all their
@@ -504 +509 @@
      * @param   pIfPort     Pointer to this structure.
      *
-     * @remarks Called while owning the network semaphore.
+     * @remarks Called while owning the network and the out-bound trunk port semaphores.
      */
     DECLR0CALLBACKMEMBER(bool, pfnIsPromiscuous,(PINTNETTRUNKIFPORT pIfPort));
@@ -523 +528 @@
      *                      allocating and copying.
      *
-     * @remarks Called while owning the network semaphore.
-     *          (Works on darwin, but may have to be relaxed later on other hosts.)
+     * @remarks Called holding the out-bound trunk port lock.
      *
      * @remarks TAP and NAT will use this interface for all their traffic, see pfnIsHostMac.
@@ -545 +549 @@
      *                      allocating and copying.
      *
-     * @remarks Called while owning the network semaphore.
-     *          (Works on darwin, but may have to be relaxed later on other hosts.)
+     * @remarks Called holding the out-bound trunk port lock.
      *
      * @remarks TAP and NAT will call pfnSGRelease and return successfully.
@@ -567 +570 @@
 {
     /**
-     * Create an instance for the specfied host interface.
+     * Create an instance for the specfied host interface and connects it
+     * to the internal network trunk port.
      *
      * The initial interface active state is false (suspended).
@@ -585 +589 @@
      *                              on success.
      *
-     * @remarks Called while owning the network semaphore.
-     */
-    DECLR0CALLBACKMEMBER(int, pfnCreate,(struct INTNETTRUNKNETFLTFACTORY *pIfFactory, const char *pszName,
-                                         PINTNETTRUNKSWPORT pSwitchPort, PINTNETTRUNKIFPORT *ppIfPort));
+     * @remarks Called while owning the network and the out-bound trunk semaphores.
+     */
+    DECLR0CALLBACKMEMBER(int, pfnCreateAndConnect,(struct INTNETTRUNKNETFLTFACTORY *pIfFactory, const char *pszName,
+                                                   PINTNETTRUNKSWPORT pSwitchPort, PINTNETTRUNKIFPORT *ppIfPort));
 } INTNETTRUNKNETFLTFACTORY;
 /** Pointer to the trunk factory. */