Flow of Control for Cancel-Safe IRP Queuing

Flow of Control for Cancel-Safe IRP Queuing - 1

WinHEC 2004 Version - May 4, 2004

Abstract

This paper provides information about cancel-safe interrupt request packet (IRP) queues for the Microsoft® Windows® family of operating systems. It provides background information for driver writers who seek a greater understanding of how the new cancel-safe queue (CSQ) library and IoCsq routines implement IRP queuing, dequeuing, and cancellation.

This information applies for the following operating systems:
Microsoft Windows 98/ME
Microsoft Windows 2000
Microsoft Windows XP
Microsoft Windows Server™ 2003
Microsoft Windows Vista™

The current version of this paper is maintained on the Web at:

Contents

Introduction

Initializing the Cancel-Safe IRP Queue Package

Queuing an IRP

Using IoCsqInsertIrp

Using IoCsqInsertIrpEx

Dequeuing an IRP

Using IoCsqRemoveIrp

Using IoCsqRemoveNextIrp

Canceling an IRP

References

Disclaimer

This is a preliminary document and may be changed substantially prior to final commercial release of the software described herein.

The information contained in this document represents the current view of Microsoft Corporation on the issues discussed as of the date of publication. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information presented after the date of publication.

This White Paper is for informational purposes only. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS DOCUMENT.

Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Unless otherwise noted, the example companies, organizations, products, domain names, e-mail addresses, logos, people, places and events depicted herein are fictitious, and no association with any real company, organization, product, domain name, email address, logo, person, place or event is intended or should be inferred.

Microsoft, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Introduction

This paper provides flowcharts that show the flow of control during use of the cancel-safe IRP queuing routines (theIoCsq package).

Except as noted, the IoCsq packageis included with the Windows®XP and later operating systems. Drivers for Windows XP and later versions can use the package by including ntddk.h or wdm.h.

Drivers that must run on Windows2000 and Windows98/Me can use the package by including csq.h and linkingwith the csq.lib library that is shipped with the Windows DDK for WindowsXP and later versions. The csq.lib library implements this package for these earlier operating systems.

Initializing the Cancel-Safe IRP Queue Package

A driver initializes the IoCsq Package by calling one of the following from its AddDevice routine:

IoCsqInitialize
IoCsqInitializeEx, which supports extended context and status information for queued IRPs

The IoCsqInitializeEx routine is declared in wdm.h and ntddk.h and is available in Windows Server 2003 and later versions. Drivers for Windows XP, Windows 2000, and Windows 98/ME can use the routine, but must include csq.h and link with csq.lib.

Queuing an IRP

The IoCsq package includes two functions that queue IRPs:IoCsqInsertIrp and IoCsqInsertIrpEx.

Using IoCsqInsertIrp

IoCsqInsertIrp inserts an IRP into the queue but does not return an NTSTATUS value.

Figure 1. Flow of Control for IoCsqInsertIrp

Using IoCsqInsertIrpEx

IoCsqInsertIrpEx inserts an IRP into the queue and returns an NTSTATUS value. This routine is declared in wdm.h and ntddk.h and is available in Windows Server 2003 and later versions. Drivers for Windows XP, Windows 2000, and Windows 98/ME can use the routine, but must include csq.h and link with csq.lib.

Drivers that use this routine must initialize the IoCsq package with IoCsqInitializeEx.

Figure 2. Flow of Control for IoCsqInsertIrpEx

Dequeuing an IRP

The IoCsq package includes two functions that dequeue IRPs: IoCsqRemoveIrp and IoCsqRemoveNextIrp.

Using IoCsqRemoveIrp

IoCsqRemoveIrp dequeues an IRP that matches context specified by the driver.

Figure 3. Flow of Control for IoCsqRemoveIrp

Using IoCsqRemoveNextIrp

IoCsqRemoveNextIrp dequeues the next IRP from the queue. The driver can optionally specify context to identify the IRP.

Figure 4. Flow of Control for IoCsqRemoveNextIrp

Canceling an IRP

The IoCsq package includes a Cancel routine that is called when an IRP in a cancel-safe queue is canceled.

Figure 5. Flow of Control for IRP Cancellation

References

Resources

White papers

I/O Completion/Cancellation Guidelines

Cancel Logic in Windows Drivers

Windows DDK

Kernel-Mode Driver Architecture\Design Guide\Handling IRPs\Queuing and Dequeuing IRPs\Driver-Managed IRP Queues\Cancel-Safe IRP Queues

Windows Hardware and Driver Central

Includes WindowsDriver Development Kits [DDK], WindowsHardware Compatibility Test [HCT] Kits, and Windows Logo Program requirements