Changeset 81083 in vbox for trunk/src/VBox/HostDrivers/VBoxUSB

Timestamp:

Sep 30, 2019 3:35:52 PM (5 years ago)

Author:

vboxsync

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

133689

Message:

USB/win: Drill down to PDO base when looking up device objects. Solves problems with capturing when USBPcap is installed.

Location:

trunk/src/VBox/HostDrivers/VBoxUSB/win/mon

Files:

• VBoxUsbFlt.cpp (modified) (12 diffs)
• VBoxUsbMon.cpp (modified) (1 diff)

trunk/src/VBox/HostDrivers/VBoxUSB/win/mon/VBoxUsbFlt.cpp

@@ -47 +47 @@
 #include <devguid.h>
 
+
+/* We should be including ntifs.h but that's not as easy as it sounds. */
+extern "C" {
+NTKERNELAPI PDEVICE_OBJECT IoGetDeviceAttachmentBaseRef(__in PDEVICE_OBJECT DeviceObject);
+}
 
 /*
@@ -905 +910 @@
         for (ULONG k = 0; k < pDevRelations->Count; ++k)
         {
-            PDEVICE_OBJECT pDevObj = pDevRelations->Objects[k];
+            PDEVICE_OBJECT pDevObj;
+
+            /* Grab the PDO+reference. We won't need the upper layer device object
+             * anymore, so dereference that right here, and drop the PDO ref later.
+             */
+            pDevObj = IoGetDeviceAttachmentBaseRef(pDevRelations->Objects[k]);
+            LOG(("DevObj=%p, PDO=%p\n", pDevRelations->Objects[k], pDevObj));
+            ObDereferenceObject(pDevRelations->Objects[k]);
+            pDevRelations->Objects[k] = pDevObj;
 
             LOG(("Found existing USB PDO 0x%p", pDevObj));
@@ -1299 +1312 @@
     PVBOXUSBFLT_DEVICE pDevice;
 
+    /* Find the real PDO+reference. Dereference when we're done with it. Note that
+     * the input pPdo was not explicitly referenced so we're not dropping its ref.
+     */
+    PDEVICE_OBJECT pDevObj = IoGetDeviceAttachmentBaseRef(pPdo);
+    LOG(("DevObj=%p, real PDO=%p\n", pPdo, pDevObj));
+    pPdo = pDevObj;
+
     /* first check if device is in the a already */
     VBOXUSBFLT_LOCK_ACQUIRE();
@@ -1309 +1329 @@
         *pbFiltered = pDevice->enmState >= VBOXUSBFLT_DEVSTATE_CAPTURING;
         VBOXUSBFLT_LOCK_RELEASE();
+        ObDereferenceObject(pPdo);
         return STATUS_SUCCESS;
     }
@@ -1316 +1337 @@
     {
         WARN(("VBoxUsbMonMemAllocZ failed"));
+        ObDereferenceObject(pPdo);
         return STATUS_NO_MEMORY;
     }
@@ -1325 +1347 @@
     {
         WARN(("vboxUsbFltDevPopulate failed, Status 0x%x", Status));
+        ObDereferenceObject(pPdo);
         VBoxUsbMonMemFree(pDevice);
         return Status;
@@ -1337 +1360 @@
     /* (paranoia) re-check the device is still not here */
     pTmpDev = vboxUsbFltDevGetLocked(pPdo);
+
+    /* Drop the PDO ref, now we won't need it anymore. */
+    ObDereferenceObject(pPdo);
+
     if (pTmpDev)
     {
@@ -1385 +1412 @@
 {
     VBOXUSBFLT_DEVSTATE enmState = VBOXUSBFLT_DEVSTATE_REMOVED;
+
+    /* Find the real PDO+reference. Dereference when we're done with it. Note that
+     * the input pPdo was not explicitly referenced so we're not dropping its ref.
+     */
+    PDEVICE_OBJECT pDevObj = IoGetDeviceAttachmentBaseRef(pPdo);
+    LOG(("DevObj=%p, real PDO=%p\n", pPdo, pDevObj));
+    pPdo = pDevObj;
+
     VBOXUSBFLT_LOCK_ACQUIRE();
 
@@ -1392 +1427 @@
 
     VBOXUSBFLT_LOCK_RELEASE();
+    ObDereferenceObject(pPdo);
 
     return enmState >= VBOXUSBFLT_DEVSTATE_CAPTURING;
@@ -1400 +1436 @@
     PVBOXUSBFLT_DEVICE pDevice;
     VBOXUSBFLT_DEVSTATE enmOldState;
+
+    /* Find the real PDO+reference. Dereference when we're done with it. Note that
+     * the input pPdo was not explicitly referenced so we're not dropping its ref.
+     */
+    PDEVICE_OBJECT pDevObj = IoGetDeviceAttachmentBaseRef(pPdo);
+    LOG(("DevObj=%p, real PDO=%p\n", pPdo, pDevObj));
+    pPdo = pDevObj;
 
     VBOXUSBFLT_LOCK_ACQUIRE();
@@ -1410 +1453 @@
     }
     VBOXUSBFLT_LOCK_RELEASE();
+    ObDereferenceObject(pPdo);
     if (pDevice)
         vboxUsbFltDevRelease(pDevice);
@@ -1419 +1463 @@
     PVBOXUSBFLT_DEVICE pDevice;
     VBOXUSBFLT_LOCK_ACQUIRE();
+
+    /* NB: The USB proxy (VBoxUSB.sys) passes us the real PDO, not anything above that. */
     pDevice = vboxUsbFltDevGetLocked(pPdo);
     /*

trunk/src/VBox/HostDrivers/VBoxUSB/win/mon/VBoxUsbMon.cpp

@@ -23 +23 @@
  * You may elect to license modified versions of this file under the
  * terms and conditions of either the GPL or the CDDL or both.
+ */
+
+
+/*
+ *
+ *                        Theory of Operation
+ *                              - or -
+ *        The Document I Wish The Original Author Had Written
+ *
+ *
+ * The USB Monitor (VBoxUSBMon.sys) serves to capture and uncapture USB
+ * devices. Its job is to ensure that the USB proxy (VBoxUSB.sys) gets installed
+ * for captured devices and removed again when not needed, restoring the regular
+ * driver (if any).
+ *
+ * The USB Monitor does not handle any actual USB traffic; that is the role of
+ * VBoxUSB.sys, the USB proxy. A typical solution for installing such USB proxy
+ * is using a filter driver, but that approach was rejected because filter drivers
+ * cannot be dynamically added and removed. What VBoxUSBMon does instead is hook
+ * into the dispatch routine of the bus driver, i.e. USB hub driver, and alter
+ * the PnP information returned by the bus driver.
+ *
+ * The key functionality for capturing is cycling a USB port (which causes a USB
+ * device reset and triggers re-enumeration in the Windows USB driver stack), and
+ * then modifying IRP_MN_QUERY_ID / BusQueryHardwareIDs and related requests so
+ * that they return the synthetic USB VID/PID that VBoxUSB.sys handles rather than
+ * the true hardware VID/PID. That causes Windows to install VBoxUSB.sys for the
+ * device.
+ *
+ * Uncapturing again cycles the USB port but returns unmodified hardware IDs,
+ * causing Windows to load the normal driver for the device.
+ *
+ * Identifying devices to capture or release (uncapture) is done through USB filters,
+ * a cross-platform concept which matches USB device based on their VID/PID, class,
+ * and other criteria.
+ *
+ * There is an IOCTL interface for adding/removing USB filters and applying them.
+ * The IOCTLs are normally issued by VBoxSVC.
+ *
+ * USB devices are enumerated by finding all USB hubs (GUID_DEVINTERFACE_USB_HUB)
+ * and querying their child devices (i.e. USB devices or other hubs) by sending
+ * IRP_MJ_PNP / IRP_MN_QUERY_DEVICE_RELATIONS / BusRelations. This is done when
+ * applying existing filters.
+ *
+ * Newly arrived USB devices are intercepted early in their PnP enumeration
+ * through the hooked bus driver dispatch routine. Devices which satisty the
+ * filter matching criteria are morphed (see above) such that VBoxUSB.sys loads
+ * for them before any default driver does.
+ *
+ * There is an IDC interface to VBoxUSB.sys which allows the USB proxy to report
+ * that it's installed for a given USB device, and also report when the USB proxy
+ * is unloaded (typically caused by either unplugging the device or uncapturing
+ * and cycling the port). VBoxUSBMon.sys relies on these IDC calls to track
+ * captured devices and be informed when VBoxUSB.sys unloads.
+ *
+ * Windows 8+ complicates the USB Monitor's life by automatically putting some
+ * USB devices to a low-power state where they are unable to respond to any USB
+ * requests and VBoxUSBMon can't read any of their descriptors (note that in
+ * userland, the device descriptor can always be read, but string descriptors
+ * can't). Such devices'  USB VID/PID/revision is recovered using the Windows
+ * PnP Manager from their DevicePropertyHardwareID, but their USB class/subclass
+ * and protocol unfortunately cannot be unambiguously recovered from their
+ * DevicePropertyCompatibleIDs.
+ *
+ * Filter drivers add another complication. With filter drivers in place, the
+ * device objects returned by the BusRelations query (or passing through the PnP
+ * hooks) may not be PDOs but rather filter DOs higher in the stack. To avoid
+ * confusion, we flatten the references to their base, i.e. the real PDO, which
+ * should remain the same for the lifetime of a device. Note that VBoxUSB.sys
+ * always passes its own PDO in the proxy startup IOCTL.
  */