Plug and Play Driver Test

  • Article

Type: Automated Test

Overview

The Plug and Play Driver Test (Pnpdtest) exercises various Plug and Play (PnP)-related code paths in the driver and user-mode components. This Plug and Play Driver test runs with Driver Verifier enabled.

Details

The Plug and Play Driver test provides you with a tool that exercises various PnP-related codes paths in the driver and user-mode components. If you use this test with Driver Verifier, you can feel more confident that your code is performing properly. This tool is for use on Microsoft Windows Vista, Windows Server 2003, Windows XP, and Windows 2000.

Although by using this tool a driver will be forced to handle almost all of the PnP IRPs, there are three areas that are stressed specifically: Removal, Rebalance, and Surprise Removal. The test provides a mechanism to test each of these separately or all together (that is, stress). This 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).

The first time the test is run, you will be prompted with a dialog box for the location of the test filter driver (pnpfiltr.sys). After you point to the proper location for the filter driver, its service will be installed and the driver copied. If you have run an older version of the test previously, you might need to restart the computer after the new filter driver is copied if the old driver is currently loaded.

Troubleshooting Note: If the Pnpfilter driver fails to install you may need to manually perform the following procedure:

  1. Using RegEdit, navigate to HKEY_LOCAL_MACHINE\System\CurrentControlSet\USB (or your appropriate bus)\<Your Hardware ID>\<Instance ID>\Device Parameters\WUDF
  2. Add a DWORD key "UpperDriverOK" and set it equal to "1".

  • Device removal
    Device removal is tested by selecting the target device and clicking the Test Removal button. This test encompasses IRP_MN_QUERY_REMOVE_DEVICE, IRP_MN_CANCEL_REMOVE_DEVICE, and IRP_MN_REMOVE_DEVICE.

    The test will attempt to install its upper filter driver on the target device stack. This attempt results in a query-remove IRP–if this query-remove is failed, you might need to restart 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, will cause a query-remove to be sent to the device stack. The filter driver will fail this remove request so a cancel-remove IRP will be 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.

    The test will again call the class or co-installers (this time with DIF_REMOVE) and then will reenumerate the device’s parent to attempt to restart the device. This step essentially uninstalls the device as if you had used Device Manager.

    Of course, each of these steps involves a preliminary remove request. If that request if 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–it 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.

  • Rebalance
    Rebalance is tested by selecting the target device and clicking the Test Rebalance button. When you press this button, a separate window will appear. Select your desired mode of rebalance from this window.

    As with the removal test, the test application will attempt 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), you might need to restart the computer to test rebalance.

    Depending on the mode of rebalance that you choose, the test might take the following possibilities:

    1. Simple: This option 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.

    2. FailQueryStop: This option initiates a rebalance procedure but the filter driver deliberately fails the query stop. So 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

    3. NewResources: This option 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.)

    4. Fail Restart: This option 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.

  • Double Start
    Double Start is tested by selecting the target device and clicking Test Double Start.

    As with the removal test, the test application will attempt 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), you might need to restart the computer to test double start.

    This option creates a scenario in which a driver gets two start IRPs without getting a stop in between. This option is not included as part of stress. This test should be run, if you think your driver should handle this case. In this case, the filter driver tells the PnP manager that resources have changed but does not want the device stack to be stopped. This action cause:

    • IRP_MN_START (When the device is started, it must have this IRP.)
    • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
    • IRP_MN_FILTER_RESOURCE_REQUIREMENTS
    • IRP_MN_START_DEVICE

    After the double start test is complete, the device will be uninstalled and reenumerated, also removing the filter driver from the stack.

  • Surprise Removal
    Surprise removal is tested by selecting the target device and clicking Test Surprise Removal. This 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, you might need to restart the computer to test surprise removal.

    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.

    Note On Windows 2000 only, after handling the surprise removal IRP, the device will be marked by the system with the status code DN_HAS_PRIVATE_PROBLEM. The device will still appear in the device tree in Device Manager because, because it has not actually been physically removed, it will still be reported by its bus driver in response to an IRP_MN_QUERY_DEVICE_RELATIONS for BusRelations. To restore the device to working order, the physical device object (PDO) for the device must be deleted. This deletion can be accomplished by rebooting the system, removing and reenumerating the device’s parent, or physically removing the device and reattaching it. On Windows XP and later operating system, the operating system can handle this properly and the test should be able restart the device successfully, unless an error occurred.

    After the surprise removal test is complete, the device will be uninstalled and reenumerated, also removing the filter driver from the stack.

  • Stress
    You can test all of the preceding scenarios (except for Double Start) together by selecting the target device and clicking Start Stress. The test application will keep choosing one of the preceding tests (remove, surprise remove, or one of the rebalance tests) and running it on the selected device for five minutes.

  • Device Error Code
    If the test gives an error 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 Explanation of error codes generated by Device Manager in Microsoft Windows XP Professional.

  • Automation
    Pnpdtest offers command-line options to run all of the preceding options and some other extra options for stress. For more information, see the following Command Syntax section.

    Pnpdtest uses WTTLogging to log results. The test reates two log files: one in plain text format called pnpdtest-log.txt and another one in XML formal called pnpdtest-log.xml.trace (to be used with WTT).

    Some example commands include the following:

    • pnpdtest /stress /device All /nodbgbreak /driverpath c:\pnpdstress
      Run stress on all devices one by one, copying filter driver from C:\pnpdstress and do not break in the debugger when a wrong PnP IRP is failed by the driver.
    • pnpdtest /remove /device “flpydisk” Run the remove test on all devices that have the service name as flpydisk.
    • pnpdtest /timedstress 120 /nodbgbreak /driverpath c:\pnpdstress**
      **Run random tests on random devices for two hours, copying filter driver from C:\pnpdstress and do not break in the debugger when a wrong PnP IRP is failed by the driver.
    • pnpdtest /rebalance NewResources /device “FDC\GENERIC_FLOPPY_DRIVE\5&c4ae404&1&0” Run the rebalance test with the newresources option on the device.

Run Time:
Log File:
System Restart Required: No
Test Category:
Supported operating systems for Logo or Signature testing:

  • Windows 7
  • Windows Server 2008 R2
  • Windows Vista
  • Windows Server 2003
  • Windows XP

Program: 

Requirements

Software Requirements

The test tool requires the following software:

  • Supported operating system (see list above)
  • Software components included with the device that is being tested

Hardware Requirements

The test tool requires the following hardware:

  • Device to be tested
  • Computer that meets the minimum software requirements
  • Windows keyboard
  • Two-button pointing device
  • Color display monitor capable of at least 1024 by 768 resolution, 32-bits per pixel, 60 Hz
  • Hard drive with a minimum of 20 GB available on partition C:

Running Plug and Play Driver Test

Before you can run the DRS - Plug and Play Driver Test job in Driver Test Manager (DTM), install the device and driver on the test client. Next, install and configure DTM.

To run the DRS - Plug and Play Driver Test job, do the following:

  1. Open DTM Studio.
  2. Open or switch to the Device Console window, and then select the machine pool that contains the computer where you want to run the test
  3. In the Available Devices pane, expand the type of device that is associated with your driver, and then select the specific device on which to run the test.
  4. In the Available Jobs pane, click DRS - Plug and Play Driver Test.
  5. Click Add Selected in the lower-left corner of the Device Console window to add the jobs to the schedule of jobs to be run.
  6. Click Schedule Jobs.
  7. Follow the progress of the DRS - Plug and Play Driver Test job by using the Job Monitor window. Use the Result Explorer window to examine the results of jobs that have completed. The test creates additional log files that contain detailed information about what the test is doing. You can use these log files to help you determine why a test failed.

Command Syntax

Command option Description
Pnpdtest [ /device <service> | <HW ID> | <Device Instance> | <All> ][ /driverpath <Filter driver directory> ] [ /stress ] [ /rebalance [mode] ][/surprise] [/remove] [/doublestart] [ /timedstress <minutes> ] [ /NoDbgBreak ] [ /? ]
/device Specifies the device (by either its Service name, Hardware ID, or Device instance Id) on which to carry out the tests. If you specify “All”, the selected test is run on all of the devices on the system. This parameter is necessary for automation.
/driverpath Specifies the path of the directory where the filter driver file is present. The driver file name should not be included in the path. If the path is not correct, the test will look in the system32\drivers directory. And if it cannot find the driver there also, it will display the open file dialog box.
/nodbgbreak The test does not break into the debugger when the filter driver detects that a Plug and Play (PnP) IRP has failed, which should have been succeeded. The test logs an error in the log file.
/remove Run the Remove test.
/surprise Run the Surprise Remove test.
/rebalance Run the Rebalance test, where the optional mode can be FailQueryStop (fail the Query Stop Irp), NewResources (try to change allocated resources or create fake requirement), or FailRestart (fail the start IRP that comes after stop).
/doublestart Run the Double Start test (which is not run as part of the stress test).
/stress Run the stress option. This option will run different tests (remove, surprise remove, or one of the rebalance tests) on the selected device for five minutes. If you specify “All” as an option, the test will go through the device list and run stress (5 minutes on each device) on those devices that a filter driver can be installed on without requiring a restart.
/timedstress Run stress for the specified amount of time in minutes. With this option, the test first creates a list of devices that a filter driver can be installed on without a restart. This part of the test can take some time, depending on the number of devices in the system. Then, the test continuously selects a random device from that pruned list and runs a random test on it. The only other options that can be used with this option are /driverpath and /nodbgbreak.
/? Display Help for this test.

Send feedback on this topic
Built on December 10, 2009