Flow of Control for Cancel-Safe IRP Queuing

WinHEC 2004 Version - Ma 4! 2004

Abstract "#is $a$er $ro%i&es infor'ation a(out cancel-safe interru$t re)uest $ac*et +IRP, )ueues for t#e Microsoft- Win&ows- fa'il of o$erating s ste's. It $ro%i&es (ac*groun& infor'ation for &ri%er writers w#o see* a greater un&erstan&ing of #ow t#e new cancel-safe )ueue +CSQ, li(rar an& IoCs) routines i'$le'ent IRP )ueuing! &e)ueuing! an& cancellation. "#is infor'ation a$$lies for t#e following o$erating s ste's/ Microsoft Win&ows 012ME Microsoft Win&ows 2000 Microsoft Win&ows 3P Microsoft Win&ows Ser%er4 2005 Microsoft Win&ows Vista4 "#e current %ersion of t#is $a$er is 'aintaine& on t#e We( at/ #tt$/22www.'icrosoft.co'2w#&c2&ri%er2*ernel2&efault.'s$6 Contents
Intro&uction.............................................................................................................................. 5 Initiali7ing t#e Cancel-Safe IRP Queue Pac*age.....................................................................5 Queuing an IRP....................................................................................................................... 4 8sing IoCs)InsertIr$...........................................................................................................4 8sing IoCs)InsertIr$E6.......................................................................................................9 :e)ueuing an IRP.................................................................................................................... ; 8sing IoCs)Re'o%eIr$.......................................................................................................; 8sing IoCs)Re'o%e<e6tIr$................................................................................................= Canceling an IRP..................................................................................................................... 1 References............................................................................................................................... 1

Flow of Control for Cancel-Safe IRP Queuing - 2

Disclaimer
"#is is a $reli'inar &ocu'ent an& 'a (e c#ange& su(stantiall $rior to final co''ercial release of t#e software &escri(e& #erein. "#e infor'ation containe& in t#is &ocu'ent re$resents t#e current %iew of Microsoft Cor$oration on t#e issues &iscusse& as of t#e &ate of $u(lication. >ecause Microsoft 'ust res$on& to c#anging 'ar*et con&itions! it s#oul& not (e inter$rete& to (e a co''it'ent on t#e $art of Microsoft! an& Microsoft cannot guarantee t#e accurac of an infor'ation $resente& after t#e &ate of $u(lication. "#is W#ite Pa$er is for infor'ational $ur$oses onl . MICR?S?F" M@AES <? W@RR@<"IES! E3PRESS! IMPBIE: ?R S"@"8"?RC! @S "? "HE I<F?RM@"I?< I< "HIS :?C8ME<". Co'$l ing wit# all a$$lica(le co$ rig#t laws is t#e res$onsi(ilit of t#e user. Wit#out li'iting t#e rig#ts un&er co$ rig#t! no $art of t#is &ocu'ent 'a (e re$ro&uce&! store& in or intro&uce& into a retrie%al s ste'! or trans'itte& in an for' or ( an 'eans +electronic! 'ec#anical! $#otoco$ ing! recor&ing! or ot#erwise,! or for an $ur$ose! wit#out t#e e6$ress written $er'ission of Microsoft Cor$oration. Microsoft 'a #a%e $atents! $atent a$$lications! tra&e'ar*s! co$ rig#ts! or ot#er intellectual $ro$ert rig#ts co%ering su(Dect 'atter in t#is &ocu'ent. E6ce$t as e6$ressl $ro%i&e& in an written license agree'ent fro' Microsoft! t#e furnis#ing of t#is &ocu'ent &oes not gi%e ou an license to t#ese $atents! tra&e'ar*s! co$ rig#ts! or ot#er intellectual $ro$ert . 8nless ot#erwise note&! t#e e6a'$le co'$anies! organi7ations! $ro&ucts! &o'ain na'es! e-'ail a&&resses! logos! $eo$le! $laces an& e%ents &e$icte& #erein are fictitious! an& no association wit# an real co'$an ! organi7ation! $ro&uct! &o'ain na'e! e'ail a&&ress! logo! $erson! $lace or e%ent is inten&e& or s#oul& (e inferre&. E 2004 Microsoft Cor$oration. @ll rig#ts reser%e&. Microsoft! Win&ows! an& Win&ows <" are eit#er registere& tra&e'ar*s or tra&e'ar*s of Microsoft Cor$oration in t#e 8nite& States an&2or ot#er countries. "#e na'es of actual co'$anies an& $ro&ucts 'entione& #erein 'a (e t#e tra&e'ar*s of t#eir res$ecti%e owners.

WinHEC 2004 Version - Ma 4! 2004 E 2004 Microsoft Cor$oration. @ll rig#ts reser%e&.

Flow of Control for Cancel-Safe IRP Queuing - 3

Introduction
"#is $a$er $ro%i&es flowc#arts t#at s#ow t#e flow of control &uring use of t#e cancel-safe IRP )ueuing routines +t#e IoCsq $ac*age,. E6ce$t as note&! t#e IoCsq $ac*age is inclu&e& wit# t#e Win&ows- 3P an& later o$erating s ste's. :ri%ers for Win&ows 3P an& later %ersions can use t#e $ac*age ( inclu&ing nt&&*.# or w&'.#. :ri%ers t#at 'ust run on Win&ows 2000 an& Win&ows 012Me can use t#e $ac*age ( inclu&ing cs).# an& lin*ing wit# t#e csq.lib li(rar t#at is s#i$$e& wit# t#e Win&ows ::A for Win&ows 3P an& later %ersions. "#e csq.lib li(rar i'$le'ents t#is $ac*age for t#ese earlier o$erating s ste's.

Initiali ing t!e Cancel-Safe IRP Queue Pac"age

@ &ri%er initiali7es t#e IoCsq Pac*age ( calling one of t#e following fro' its AddDevice routine/ IoCsqInitiali e

IoCsqInitiali e#$! w#ic# su$$orts e6ten&e& conte6t an& status infor'ation for )ueue& IRPs "#e IoCsqInitiali e#$ routine is &eclare& in w&'.# an& nt&&*.# an& is a%aila(le in Win&ows Ser%er 2005 an& later %ersions. :ri%ers for Win&ows 3P! Win&ows 2000! an& Win&ows 012ME can use t#e routine! (ut 'ust inclu&e cs).# an& lin* wit# csq.lib.

WinHEC 2004 Version - Ma 4! 2004 E 2004 Microsoft Cor$oration. @ll rig#ts reser%e&.

Flow of Control for Cancel-Safe IRP Queuing - %

Queuing an IRP
"#e IoCsq $ac*age inclu&es two functions t#at )ueue IRPs/ IoCsqInsertIr& an& IoCsqInsertIr&#$.

'sing IoCsqInsertIr&
IoCsqInsertIr& inserts an IRP into t#e )ueue (ut &oes not return an <"S"@"8S %alue.
Queuing an IRP wit#out Returning Status
I2? Manager
Create IRPF sen& to &ri%er

CSQ Bi(rar
DispatchXxx IoCsqInsertIr& IoCsqInsertIr& @ssociate conte6t wit# IRP

:ri%er
Queue t#e IRP

Boc* )ueue

xxxAcquireLock

Insert IRP in )ueue

xxxInsertIrp

Mar* IRP $en&ing

Set CSQ li(rar Hs Cancel routine in IRP

<?

Has IRP (een cancele&G

CES

<?

Is Cancel routine still setG

CES

Re'o%e Cancel routine

Re'o%e IRP fro' )ueue

xxxRemoveIrp

8nloc* )ueue

xxxReleaseLock

Co'$lete cancele& IRP

xxxCompleteCanceledIrp

Return to &ri%er

S"@"8SIS8CCESS

8nloc* )ueue

xxxReleaseLock

Return to &ri%er

S"@"8SIS8CCESS

Figure () Flow of Control for IoCsqInsertIr&

WinHEC 2004 Version - Ma 4! 2004 E 2004 Microsoft Cor$oration. @ll rig#ts reser%e&.

Flow of Control for Cancel-Safe IRP Queuing - *

'sing IoCsqInsertIr&#$
IoCsqInsertIr&#$ inserts an IRP into t#e )ueue an& returns an <"S"@"8S %alue. "#is routine is &eclare& in w&'.# an& nt&&*.# an& is a%aila(le in Win&ows Ser%er 2005 an& later %ersions. :ri%ers for Win&ows 3P! Win&ows 2000! an& Win&ows 012ME can use t#e routine! (ut 'ust inclu&e cs).# an& lin* wit# cs).li(. :ri%ers t#at use t#is routine 'ust initiali7e t#e IoCsq $ac*age wit# IoCsqInitiali e#$.
Queuing an IRP an& Returning Status
I2? Manager
Create IRPF sen& to &ri%er

CSQ Bi(rar
DispatchXxx IoCsqInsertIr&#$ IoCsqInsertIr&#$ @ssociate conte6t wit# IRP

:ri%er
Queue t#e IRP

Boc* )ueue

xxxCsqAcquireLock

Insert IRP in )ueue

xxxCsqInsertIrpEx

<?

Insert succee&e&G

CES

Mar* IRP $en&ing

Set CSQ li(rar Hs Cancel routine in IRP

<?

Has IRP (een cancele&G

CES

<?

Is Cancel routine still setG

CES

Re'o%e Cancel routine

Re'o%e IRP fro' )ueue

xxxRemoveIrp

8nloc* )ueue

xxxCsqReleaseLock

Co'$lete cancele& IRP

xxxCompleteCanceledIrp

Return status 8nloc* )ueue

<"S"@"8S

xxxCsqReleaseLock

Return status

S"@"8SIS8CCESS

Figure 2) Flow of Control for IoCsqInsertIr&#$

WinHEC 2004 Version - Ma 4! 2004 E 2004 Microsoft Cor$oration. @ll rig#ts reser%e&.

Flow of Control for Cancel-Safe IRP Queuing - +

Dequeuing an IRP
"#e IoCs) $ac*age inclu&es two functions t#at &e)ueue IRPs/ IoCsqRemo,eIr& an& IoCsqRemo,e-e$tIr&.

'sing IoCsqRemo,eIr&
IoCsqRemo,eIr& &e)ueues an IRP t#at 'atc#es conte6t s$ecifie& ( t#e &ri%er.
:e)ueuing a S$ecific IRP
I2? Manager Cs) Bi(rar :ri%er

Jet a s$ecific IRP IoCsqRemo,eIr&

IoCsqRemo,eIr& Boc* )ueue xxxAcquireLock

<?

:oes conte6t i&entif an IRPG

CES

<?

Is Cancel routine still setG

CES

Re'o%e Cancel routine

Re'o%e IRP fro' )ueue

xxxRemoveIrp

>rea* association (etween IRP an& conte6t

8nloc* )ueue

xxxReleaseLock

Return

IRP

8nloc* )ueue

xxxReleaseLock

Return

<8BB

Figure 3) Flow of Control for IoCsqRemo,eIr&

WinHEC 2004 Version - Ma 4! 2004 E 2004 Microsoft Cor$oration. @ll rig#ts reser%e&.

Flow of Control for Cancel-Safe IRP Queuing - .

'sing IoCsqRemo,e-e$tIr&
IoCsqRemo,e-e$tIr& &e)ueues t#e ne6t IRP fro' t#e )ueue. "#e &ri%er can o$tionall s$ecif conte6t to i&entif t#e IRP.
:e)ueuing t#e <e6t IRP
I2? Manager Cs) Bi(rar :ri%er

Jet ne6t IRP IoCsqRemo,e-e$tIr& IoCsqRemo,e-e$tIr& Boc* )ueue xxxAcquireLock

Boo* for first IRP t#at 'atc#es conte6t

xxxPeek extIrp

<?

Foun& a 'atc#ing IRPG <?

CES

Is Cancel routine still setG

CES

Fin& ne6t IRP t#at 'atc#es conte6t

Re'o%e Cancel routine

Re'o%e IRP fro' )ueue

xxxRemoveIrp

>rea* association (etween IRP an& conte6t

8nloc* )ueue

xxxReleaseLock

Return to &ri%er

IRP

8nloc* )ueue

xxxReleaseLock

Return to &ri%er

<8BB

Figure %) Flow of Control for IoCsqRemo,e-e$tIr&

WinHEC 2004 Version - Ma 4! 2004 E 2004 Microsoft Cor$oration. @ll rig#ts reser%e&.

Flow of Control for Cancel-Safe IRP Queuing - /

Canceling an IRP
"#e IoCsq $ac*age inclu&es a Cancel routine t#at is calle& w#en an IRP in a cancel-safe )ueue is cancele&.
Canceling an IRP
I2? Manager Cs) Bi(rar :ri%er

Call CSQ li(rar Hs Cancel routine +set w#en IRP was )ueue&,

Release s ste'-wi&e cancel s$in loc*

Boc* )ueue

xxxAcquireLock

Re'o%e IRP fro' )ueue

xxxRemoveIrp

>rea* association (etween IRP an& conte6t

8nloc* )ueue

xxxReleaseLock

Cancel2co'$lete IRP

xxxCompleteCanceledIrp

Figure *) Flow of Control for IRP Cancellation

References
Resources 0!ite &a&ers I2? Co'$letion2Cancellation Jui&elines #tt$/22www.'icrosoft.co'2w#&c2&ri%er2*ernel2Iocancel.'s$6 Cancel Bogic in Win&ows :ri%ers #tt$/22www.'icrosoft.co'2w#&c2&ri%er2*ernel2cancelIlogic.'s$6 0indows DD1 Aernel-Mo&e :ri%er @rc#itectureK:esign Jui&eKHan&ling IRPsKQueuing an& :e)ueuing IRPsK:ri%er-Manage& IRP QueuesKCancel-Safe IRP Queues 0indows 2ardware and Dri,er Central Inclu&es Win&ows :ri%er :e%elo$'ent Aits L::AM! Win&ows Har&ware Co'$ati(ilit "est LHC"M Aits! an& Win&ows Bogo Progra' re)uire'ents #tt$/22www.'icrosoft.co'2w#&c2&efault.'s$6

WinHEC 2004 Version - Ma 4! 2004 E 2004 Microsoft Cor$oration. @ll rig#ts reser%e&.