Microsoft KB Archive/191813

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

Q191813

The information in this article applies to:

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 Download Center:

Irpq.exe

Release Date: Aug-27-1998

For additional information about how to download Microsoft Support files, click the article number below to view the article in the Microsoft Knowledge Base:

Q119591 How to Obtain Microsoft Support Files from Online Services

Microsoft used the most current virus detection software available on the date of posting to scan this file for viruses. Once posted, the file is housed on secure servers that prevent any unauthorized changes to the file.

IRPQ.exe is composed of four parts:

   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.

All are built using the Windows NT DDK. The current version of this sample does not support Plug and Play or Power Management.

   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

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.
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.
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.
Restart the target machine so that the registry changes take effect. NOTE: Your drivers will not load until you restart.
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.
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. 
```
Unload the driver from the command line as follows:

NET STOP IRPQ*

Additional query words:

Keywords : kbfile kbsample kbDDK kbNDIS kbOSWinNT400
Issue type :
Technology : kbAudDeveloper kbWinDDKSearch kbWin32sSearch kbWin32DDKSearch kbWin32DDKNT400 kbWin32DDKNTSearch