PnP Tests (Device Fundamentals)
The Device Fundamentals PnP tests force a driver to handle almost all of the PnP IRPs; however, there are three areas that are stressed specifically: removal, rebalance, and surprise removal. The PnP test provides a mechanism to test each of these separately, or to test them all together (that is, as a stress test). This PnP testing is accomplished by using a combination of user-mode API calls (through the test application) and kernel-mode API calls (through an upper-filter driver).
PNP tests
The Plug and Play (PnP) tests execute various PnP-related code paths in the driver and user-mode components. The PnP tests should be run with Driver Verifier enabled on the test computer. For information about enabling Driver Verifier, see Driver Verifier properties for driver projects.
| Test | Description |
|---|---|
Disable Enhanced Device Testing (EDT) Support |
This test uninstalls the test filter driver (msdmfilt.sys) as an upper filter on devices specified using the DQ parameter. This test filter gets installed as part of running tests in this test category Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO IOType |
PNP (disable and enable) reboot with IO before and after |
This test performs basic PnP disable/enable and I/O on devices with a system reboot. Test binary: Devfund_PNP_DisableEnable_Reboot_With_IO_BeforeAndAfter.wsc Test method: PNP_DisableEnable_Reboot_With_IO_Before_And_After Parameters: - see Device Fundamentals Test Parameters DQ IOPeriod |
PNP (disable and enable) with I/O before and after |
This test performs I/O and basic PnP disable/enable on devices. This test does the following:
Test binary: Devfund_PNP_DisableEnable_With_IO_BeforeAndAfter.wsc Test method: PNP_DisableEnable_With_IO_Before_And_After Parameters: - see Device Fundamentals Test Parameters DQ IOPeriod |
PNP Cancel Remove Device test |
This test uses the EDT filter driver to send IRP_MN_CANCEL_REMOVE_DEVICE to target device stacks. For more information, see About the Device Removal tests. Test binary: Devfund_PnPDTest.dll Test method: PNPCancelRemoveDevice Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO |
PNP Cancel Stop Device test |
This test uses the EDT filter driver to send IRP_MN_CANCEL_STOP_DEVICE to target device stacks. For more information, see About the Rebalance tests. Test binary: Devfund_PnPDTest.dll Test method: PNPCancelStopDevice Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO |
PNP DIF Remove Device Test |
This test uses the SetupDi API to send a DIF_REMOVE request for the installers to remove the device. Test binary: Devfund_PnPDTest.dll Test method: PNPDIFRemoveAndRescanParentDevice Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO |
PNP Disable and Enable Device test |
This test disables and enables the target devices. Test binary: Devfund_PnPDTest.dll Test method: PNPDisableAndEnableDevice Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO IOType |
PNP Rebalance Fail Restart Device test |
This test uses the EDT filter driver to try to send IRP_MN_STOP_DEVICE to target device stacks. The EDT filter driver then fails IRP_MN_START_DEVICE requests (that follow IRP_MN_STOP_DEVICE requests) to trigger the surprise removal of target devices. For more information, see About the Rebalance tests. Test binary: Devfund_PnPDTest.dll Test method: PNPTryStopDeviceAndFailRestart Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO |
PNP Rebalance Request New Resources Device test |
This test uses the EDT filter driver to try to send IRP_MN_STOP_DEVICE to target device stacks. It also manipulates the resource requirements of the devices to maximize the chances that new resources are allocated to devices. For more information, see About the Rebalance tests. Test binary: Devfund_PnPDTest.dll Test method: PNPTryStopDeviceRequestNewResourcesAndRestartDevice Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO |
PNP Remove Device Test |
This test causes IRP_MN_QUERY_REMOVE_DEVICE and IRP_MN_REMOVE_DEVICE to be sent to target device stacks. For more information, see About the Device Removal tests. Test binary: Devfund_PnPDTest.dll Test method: PNPRemoveAndRestartDevice Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO |
PNP Stop (Rebalance) Device test |
This test uses the EDT filter driver to try to send IRP_MN_STOP_DEVICE to target device stacks. For more information, see About the Rebalance tests. Test binary: Devfund_PnPDTest.dll Test method: PNPTryStopAndRestartDevice Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO |
PNP Surprise Remove Device test |
This test uses the EDT filter driver to send IRP_MN_SURPRISE_REMOVAL to target device stacks. For more information, see About the Surprise Removal test. Test binary: Devfund_PnPDTest.dll Test method: PNPSurpriseRemoveAndRestartDevice Parameters: - see Device Fundamentals Test Parameters DQ TestCycles DoSimpleIO IOPeriod DoConcurrentIO |
About the Device Removal tests
- PNP Remove Device Test
- PNP Cancel Remove Device test
The Device Removal test encompasses IRP_MN_QUERY_REMOVE_DEVICE, IRP_MN_CANCEL_REMOVE_DEVICE, and IRP_MN_REMOVE_DEVICE.
The test attempts to install its upper-filter driver on the target device stack. This attempt results in a query-remove IRP.
If this query-remove IRP fails, the test restarts the computer to get the filter driver onto the device stack. If the remove request is not vetoed, the device stack will be removed and restarted with the filter driver on the device stack.
The test, by using setup APIs, causes a query-remove IRP to be sent to the device stack. The filter driver fails this remove request, so a cancel-remove IRP is sent. The filter driver will assert that the cancel-remove was successful.
Next, the test application calls the appropriate class installer and any registered co-installers to disable or enable and remove or reenumerate the device (this tests the class and co-installers handling of DIF_PROPERTYCHANGE with DICS_DISABLE, DICS_ENABLE, and DICS_PROPCHANGE). When receiving IRP_MN_REMOVE_DEVICE, the filter driver will assert that the lower drivers completed it successfully.
Each of these steps involves a preliminary remove request. If that request is vetoed, the device will not be removed. You can choose to veto a remove request when appropriate, such as while streaming video on a USB camera or if the target device is in the boot or paging path. Remember that simply failing all remove requests is generally not good practice. Failing all remove requests will not guarantee that driver will never receive a remove because a remove IRP will still be issued after a surprise removal, or if anyone in the device stack fails a start IRP.
About the Surprise Removal test
- PNP Surprise Remove Device test
The Surprise Removal test encompasses IRP_MN_SURPRISE_REMOVAL followed by IRP_MN_REMOVE_DEVICE.
As with the previous tests, the test application will attempt to add an upper filter to the target device stack and then restart the stack. If this attempt is not successful, the test restarts the computer.
When triggered by the test application, the filter driver will cause the system to send an IRP_MN_SURPRISE_REMOVAL to the device stack, followed by an IRP_MN_REMOVE_DEVICE. The filter driver will assert that both of these IRPs are completed successfully by lower drivers.
After the surprise removal test is complete, the device will be uninstalled and reenumerated, also removing the filter driver from the stack.
About the Rebalance Tests
- PNP Stop (Rebalance) Device test
- PNP Rebalance Request New Resources Device test
- PNP Rebalance Fail Restart Device test
- PNP Cancel Stop Device test
As with the removal test, the test application attempts to add an upper filter to the target device stack and then restart the device stack by using SetupDiCallClassInstaller with DIF_PROPERTYCHANGE. If this attempt is not successful (that is, if someone on the target device stack failed the query-remove IRP), the test restarts the computer to test rebalance.
Depending upon which rebalance test that you choose, the following events occur:
PNP Stop (Rebalance) Device test This test initiates a rebalance procedure which results in the IRP_MN_QUERY_STOP_DEVICE PnP IRP to the device driver.
If any driver in the stack fails this IRP the rebalance procedure is abandoned. Please note that in Windows Vista, there is support for multi-level rebalance. If a rebalance is started on a non-leaf device node, all of the device stacks that are present in the device tree with that device node as the root also go through rebalance. And if any of the child device stacks fails query stop, the whole rebalance procedure is abandoned. So drivers must not fail query stop without a genuine reason to do so. If this failure happens, the PnP manager sends cancel stop (IRP_MN_CANCEL_STOP) to all the device stacks that had been sent query stop.
If all of the device stacks involved pass query stop, the test continues with the rebalance and sends the IRP_MN_QUERY_RESOURCE_REQUIREMENTS and IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRPS to find the resource requirement of the devices.
After this point, two different paths are possible depending on whether the target device consumes any resources or not:
If the device does not consume any resources, the PnP manager itself sends a cancel stop (IRP_MN_CANCEL_STOP_DEVICE) as an optimization.
If the device actually consumes resources, the rebalance procedure is completed with the IRP_MN_STOP_DEVICE and IRP_MN_START_DEVICE IRPs.
With this option, the resources of the device do not change.
PNP Cancel Stop Device test: This test initiates a rebalance procedure, but the filter driver deliberately fails the query stop IRP. The order of IRPs looks like IRP_MN_QUERY_STOP_DEVICE (which is failed by the filter driver while coming up, causing a cancellation of rebalance) and IRP_MN_CANCEL_STOP_DEVICE.
With this option, the resources of the device do not change
PNP Rebalance Request New Resources Device test This test initiates a rebalance and also manipulates the resource requirement of the device to maximize the chances that actually new resources are allocated to the device. This option also helps a device with no resources to actually go through the complete rebalance procedure:
First the simple rebalance is started, causing the following IRPs:
- IRP_MN_QUERY_STOP_DEVICE (assuming this IRP is passed by all the drivers. The test already covered the case where this IRP is failed.)
- IRP_MN_QUERY_RESOURCE_REQUIREMENTS
- IRP_MN_FILTER_RESOURCE_REQUIREMENTS. In response to this IRP, while going up, filter driver takes action based on whether the device consumes any resources or not:
- If the device has no resource requirement, filter assigns a fake resource.
- If the device has a resource requirement, it tries to restructure the resource requirement list in such a way that maximizes the probability of changing the current assignment. For example, if a device needs 2 bytes of memory anywhere between 00 to FF and currently is assigned 3A-3B, modify such that the new resource requirement (in order of preference) looks like 00-39 or 3C-FF or 3A-3B. Similarly if the device resource requirement list has any alternate requirements, it will change their order so the alternate requirement comes earlier in the list.
Now the device should always complete the rebalance procedure.
IRP_MN_STOP_DEVICE
IRP_MN_START_DEVICE (The new allocated resources. If fake requirements were created, mask the new resources from the actual drivers.)
PNP Rebalance Fail Restart Device Test This test initiates a rebalance but when the filter driver gets the start after the rebalance, it deliberately fails it-which causes the surprise removal IRP followed by Removal IRP.
First, it starts the rebalance procedure and makes sure that the driver gets a stop and a start by generating fake resource requirement for a device which does not consume any resources.
- IRP_MN_QUERY_STOP_DEVICE (assuming this IRP is passed by all the drivers. The test already covered the case where this IRP is failed.)
- IRP_MN_QUERY_RESOURCE_REQUIREMENTS
- IRP_MN_FILTER_RESOURCE_REQUIREMENTS (If the actual resource requirement are null, filter assign fake resource requirement, so there is a stop and a start.)
- IRP_MN_STOP_DEVICE
- IRP_MN_START_DEVICE (The filter fails this IRP while going up. This action causes the surprise remove IRP.)
- IRP_MN_SURPRISE_REMOVAL
- IRP_MN_REMOVE
After the rebalance test is complete, the device will be uninstalled and reenumerated, also removing the filter driver from the stack.
Device Error Codes
If the test gives an error message saying that the device status is not OK, you can learn more about the device status through Device Manager. For a summary of the various device error codes, see Device Manager Error Messages.
Debug installation failures using the Setup API logs
The Setup API logs (setupapi.app.log and setupapi.dev.log) might contain useful information to debug driver installation failures logged by this test. The Setup API logs can be found under %windir%\inf\ directory on the test system.
To increase the verbosity and potential usefulness of these logs, set the following registry key to 0x2000FFFF before running the Reinstall test:
HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Setup\LogLevel
Related topics
How to How to test a driver at runtime using Visual Studio
How to select and configure the Device Fundamentals tests