SAMPLE: IRPQ.exe Shows How to Manage IRP Queuing WinNT Driver

• Microsoft Win32 Device Driver Kit (DDK) for Windows NT, version 4.0

SUMMARY

IRPQ.exe is a sample that demonstrates one way you can set up your Windows NT kernel-mode driver to manage its own IRP queues.

MORE INFORMATION

The following file is available for download from the Microsoft Software Library:

~ IRPQ.exe

Release Date: Aug-27-1998

For more information about downloading files from the Microsoft Software Library, please see the following article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

   File         Description
   ----------------------------------------------------------------------

   .\sys        A full-duplex asynchronous driver with driver managed Irp
                queues and cancelable I/O.

   .\exe        A multithreaded asynchronous test application that uses
                APCs.

   .\filter     A transparent passthrough filter driver.

   .\kd         A WinDbg kernel debugger extension. 

   File             Description
   ------------------------------------------------------------------------

   Dirs
   Irpq.htm          Documentation for the sample (a copy of this text).
   Common.h          Common header file.

   Exe\Makefile
   Exe\Sources       Generic file for building the application.
   Exe\Parse.c       Command line parsing code.
   Exe\Stolen.h      Linked List manipulation macros borrowed from NTDDK.h
                     for the application's use.
   Exe\Testirpq.c    Main test application code.
   Exe\Testirpq.h    Application main header file.

   Filter\Makefile
   Filter\Sources    Generic file for building the driver.
   Filter\Filter.c   Main filter driver code.
   Filter\Filter.h   Main filter driver header file.
   Filter\Irpqf.ini  Install file for the filter driver.
   Filter\Irpqf.rc   Resource file.

   Kd\Makefile
   Kd\Sources        Generic file for building the WinDbg kernel debugger
                     extension.
   Kd\Help.c         Help display code for the extension.
   Kd\IRPQkd.c       Extension specific code.
   Kd\IRPQkd.def     Extension export definitions.
   Kd\IRPQkd.h       Main header file.
   Kd\IRPQkd.rc      Extension resource file.
   Kd\Kdexts.c       Generic extension routines.

   Sys\Makefile
   Sys\Sources       Generic file for building the driver.
   Sys\Debug.h       Driver debug definitions.
   Sys\Driver.c      Main driver file.
   Sys\Ioctl.c       IOCTL path.
   Sys\Irpq.c        IRP queuing code.
   Sys\Irpq.h        Main driver header.
   Sys\Irpq.ini      Install file for the driver.
   Sys\Irpq.rc       Resource file.
   Sys\Read.c        Read path.
   Sys\Write.c       Write path. 

Step-by-Step Procedures: Building the Sample

1. Build the modules in either the FREE or CHECKED build environment as follows:
   
   BLD
   
   NOTE: All of the modules are put in %NTDDK%\LIB\*\FREE | CHECKED on your build machine.



2. Copy the newly built drivers to your target computer's %SystemRoot%\system32\drivers directory. Copy the newly built application and IRPQ*.INI files to your target computer. Copy the debugger extension IRPQKD.DLL to the folder where you installed windbg.exe in your host computer.



3. Update the target computer's registry by running RegIni.exe on the IRPQ*.ini file. For example:
   
   REGINI IRPQ.ini
   REGINI IRPQF.ini
   
   This adds a driver keys to the following registry folder:
   

   
         HKLM\SYSTEM\CurrentControlSet\Services 

   
   You can verify that the key has been added by running RegEdit32.exe and looking at the \IRPQ* keys.



4. Restart the target machine so that the registry changes take effect. NOTE: Your drivers will not load until you restart.



5. Load the driver from the command line as follows:
   
   NET START IRPQ
   
   If you are using the Filter driver you could use the following:
   
   NET START IRPQF
   
   This will load the IRPQ.sys driver as well.



6. Run the test application from the command line.
   
   Usage: irpq [-r count] [-w count] [-i count] <-t> <-c> <-k>
   
   Options:
   
   [-r count] Number of Read requests to post.
   
   [-w count] Number of Write requests to post.
   
   [-i count] Number of DeviceIoControl requests to post.
   
   <-t> Test Loop. Continuously posts Read, Write, and/or DeviceIoControl requests until interrupted.
   
   If you use this option, <count> arguments are ignored.
   
   <-c> Tests the driver's Cancel path for the pending requests.
   
   All requests are posted, and then cancelled.
   
   NOTE: The <-c> and <-t> options are mutually exclusive.
   
   <-k> Tests the driver's IRP_MJ_CLEANUP path by posting the required requests, and then closing the file handle.
   
   For example:
   

   
      irpq -r 12 : post 12 Read requests.
   
      irpq -r 12 -c : post 12 Read requests, then cancel any outstanding
                      requests.
   
      irpq -r 12 -k : post 12 Read requests, then force IRP_MJ_CLEANUP.
   
      irpq -r 12 -t : continuously post Read requests.
   
      irpq -r 12 -w 12 -i 12 -t : continuously post Read, Write, and Ioctl
                                  requests. 




7. Unload the driver from the command line as follows:
   
   NET STOP IRPQ*

Keywords          : kbfile kbsample kbDDK kbNDIS kbNTOS400 
Version           : 
Platform          : 
Issue type        : 

Last Reviewed: March 5, 1999