Rolling Your Own

　　在這篇文章中我將描述如何自己構(gòu)造IRP還有I/O管理器提供一些分配和管理IRPs的例程。

　　經(jīng)常聽(tīng)到NT驅(qū)動(dòng)程序開(kāi)發(fā)者問(wèn)的問(wèn)題是如何在他們自己所驅(qū)動(dòng)中執(zhí)行一個(gè)I/O操作。這個(gè)問(wèn)題可以總結(jié)為以下兩點(diǎn)：當(dāng)僅可用到一個(gè)文件對(duì)象但是ZwXXX例程需要一個(gè)文件句柄時(shí)如何處理I/O；為什么ZwCreateFile返回的句柄不能用在他們的驅(qū)動(dòng)中。實(shí)際的問(wèn)題是如何在他們的驅(qū)動(dòng)中處理I/O操作，典型的在多線程上下文中。

　　當(dāng)然，這有很多種可行的方法解決這個(gè)問(wèn)題，但一個(gè)重要的方法是在你的驅(qū)動(dòng)中自己構(gòu)造IRP。這個(gè)IRP包含一個(gè)I/O操作在任意上下文中完成所需要的任何信息。IRPs依賴于在任意上下文中都有效的FILE_OBJECTs和DEVICE_OBJECTs，而不是只在特定進(jìn)程上下文中有效的Fille Handle。這篇文章描述和示范了很多方法，每一種方法都是基于DDK的，你不必使用沒(méi)有文檔化的Kernels APIs。

　　有很多原因使你需要構(gòu)建一個(gè)IRPs?？赡艿脑蛴信c文件系統(tǒng)交互執(zhí)行一個(gè)文件的I/O操作，或者是文件系統(tǒng)支持的內(nèi)核特征。也許你的驅(qū)動(dòng)要增加一個(gè)存在設(shè)備的功能，如處理NT容錯(cuò)設(shè)備(FTDISK).也許你有兩個(gè)協(xié)作的驅(qū)動(dòng)需要要它們之間通信。或者也許是你在Windows NT上執(zhí)行一個(gè)物理文件系統(tǒng)需要和Media Driver或Transport Driver交互。不管什么原因，在Windows NT下完成這些任務(wù)最好的方法是自己構(gòu)建IPRs。

Allocation
　　可以用兩種方式分配IRPs。最簡(jiǎn)單的方法是調(diào)用IoAllocateIrp(...)。I/O管理器將用適當(dāng)?shù)腎/O棧單元(你在調(diào)用中指定的)分配一個(gè)IPR，這是最簡(jiǎn)單的并且是大多數(shù)分配I/O請(qǐng)求的方法。警告注意：如何你調(diào)用IoAllocateIrp(...)不用調(diào)用IoInitializeIrp(...)。在這點(diǎn)上DDK文檔導(dǎo)致許多無(wú)辜的受害者誤入歧途。
　
　　你的驅(qū)動(dòng)可能想要?jiǎng)?chuàng)建自己的IRPs。一個(gè)方法是用ExAllocatePool(...)在非分頁(yè)內(nèi)存中分配內(nèi)存。你通過(guò)IoInitializeIrp(...)初始化IRP的形式。你的驅(qū)動(dòng)可以通過(guò)IoSizeOfIrp(...)計(jì)算出分配的IRP的大小。只要你在非分頁(yè)內(nèi)存中分配了一個(gè)IRP，你就能調(diào)用IoInitializeIrp設(shè)置IRP中的域。請(qǐng)看下面的例子：
 PIRP MyAllocateIrp(CCHAR NumberOfStackLocations) {
 USHORT IrpSize = IoSizeOfIrp(NumberOfStackLocations);
 Irp = ExAllocatePool(NonPagedPool, IrpSize);
 if (!Irp) {
  return 0; // failureContent provided by OSR Open Systems Resources, Inc.
   }
 IoInitializeIrp(Irp, IrpSize, NumberOfStackLocations);
 return Irp;
 }

　　一般地，驅(qū)動(dòng)依賴于I/O管理器分配和管理IRPs。然而這些實(shí)例使你的驅(qū)動(dòng)能更有效的分配和管理自己的IRPs。

　　當(dāng)NT啟動(dòng)的時(shí)候，I/O管理器建立兩個(gè)旁視列表：一個(gè)對(duì)應(yīng)于一個(gè)I/O棧單元的IPRs，另一個(gè)對(duì)應(yīng)于四個(gè)I/O棧單元的IPRs。當(dāng)你分配大棧單元的IRPs或旁視列表為空時(shí)，I/O管理器在非分頁(yè)內(nèi)存中分配新的IRPs。如果你知道你將使用的IRPs多于四個(gè)棧單元，你能通過(guò)在你自己的自由列表中保持IRPs提高一些效率。換句話說(shuō)，你的驅(qū)動(dòng)在第一次運(yùn)行時(shí)能創(chuàng)建一個(gè)IRPs池并且保存它在一個(gè)私有列表中。當(dāng)你的驅(qū)動(dòng)需要IRP時(shí)能在這個(gè)列表中分配，當(dāng)I/O操作完成時(shí)能返回到這個(gè)列表中，從而消除了間接的分配和釋放內(nèi)存池。我們已經(jīng)在OSR網(wǎng)站上的"roll.c"展示了這方面的例子代碼。

　　你怎么確信I/O管理器將IRP返回到你的驅(qū)動(dòng)讓它能返回到你的旁視列表中？簡(jiǎn)單的方法是使用I/O完成例程。下面展示了I/O完成例程如何實(shí)際的工作即使你驅(qū)動(dòng)創(chuàng)建的IRP沒(méi)有棧單元也能注冊(cè)一個(gè)完成例程。

　　這是為什么？如果你考慮一下完成例程如何使用，你就會(huì)認(rèn)識(shí)到底層驅(qū)動(dòng)被調(diào)用不需要完成例程(畢竟，這將是驅(qū)動(dòng)完成I/O請(qǐng)求).所以，底層的I/O棧單元可以用來(lái)存儲(chǔ)下層驅(qū)動(dòng)的完成例程。繼續(xù)這個(gè)處理直到驅(qū)動(dòng)的頂層將給我們一個(gè)能把握的額外的完成例程，這個(gè)例程對(duì)原始的IRP創(chuàng)建者是有效的。

　　對(duì)于IRP的創(chuàng)建者，設(shè)置I/O完成例程等同于中間層驅(qū)動(dòng)的完成例程(簡(jiǎn)單的調(diào)用IoSetCompletionRoution(...)).我們將在這篇文章在后面描述如何構(gòu)建完成例程。

Building
　　只要你分配了自己的IRP，不管是使用IoAllocateIrp還是從自己的旁視列表中，你必須初始化I/O請(qǐng)求指示你需要低層驅(qū)動(dòng)的什么服務(wù)。當(dāng)你調(diào)用下層驅(qū)動(dòng)執(zhí)行的時(shí)候你的驅(qū)動(dòng)必須做同樣的工作。簡(jiǎn)單的設(shè)置下層驅(qū)動(dòng)的參數(shù)塊。你的驅(qū)動(dòng)要做的額外工作是初始化自己分配的IPR的其他域。

MdlAddress 
this field will point to the MDL containing the data (if any)

Flags 
any appropriate flags (c.f., ntddk.h for the IRP_ flags)

AssociatedIrp.SystemBuffer 
any data buffer for this I/O request

RequestorMode 
UserMode or KernelMode. Typically, this is UserMode if the arguments being passed should be validated, KernelMode otherwise.

UserBuffer 
any data buffer for this I/O request

Tail.Overlay.Thread the PETHREAD for the original requestor

當(dāng)然，其中的某些域?qū)τ谀愕腎/O操作可是不是必須的(如：MdlAddress,AoosciatedIrp.SystemBuffer，和UserBuffer參數(shù)，僅僅是它們中的一個(gè)可能被你的驅(qū)動(dòng)使用).當(dāng)然，你將用到的域用因I/O操作不同而變化。

　　Tail.Overlay.Thread數(shù)據(jù)結(jié)構(gòu)僅僅用在明確的設(shè)備中，如可移動(dòng)設(shè)備，所以系統(tǒng)知道如何操作"錯(cuò)誤的彈出"如當(dāng)媒體設(shè)備沒(méi)有在驅(qū)動(dòng)中加載的時(shí)候abort/retry/cancel對(duì)話框的出現(xiàn)。

　　IRP有很多不同的標(biāo)志，告訴下層驅(qū)動(dòng)如何解釋這個(gè)I/O請(qǐng)求的內(nèi)容。

 -IRP_NOCA CHE –  data for this I/O request should be read from the actual backing  media and not from cache.
 -IRP_PAGING_IO – the I/O operation in question is performing paging I/O. This bit  is used by the Memory Manager.
 -IRP_MOUNT_COMPLETION   –   the   I/O   operation   in   question   is   performing    a   mount
 operation.
 -IRP_SYNCHRONOUS_API   –   the   API   in   question   expects   synchronous    behavior.   While synchronous behavior is advised when this bit is set, it is not  required.
 -IRP_ASSOCIATED_IRP – the IRP in question is associated wit h some larger I/O  operation.
 -IRP_BUFFERED_IO  – the AssociatedIrp.SystemBuffer field is valid
 -IRP_DEALLOCATE_BUFFER  –  the  system  buffer  was  allocated  from  pool  and   should  be deallocated by the I/O Manager.
 -IRP_INPUT_OPERATION  –  the  I/O  operation  is  fo r  input.  This  is  used  by   the  Memory
 Manager to indicate a page in operation.
 -IRP_SYNCHRONOUS_PAGING_IO  –  the paging operation should complete synchronously.  This bit is used by the Memory Manager.
 -IRP_CREATE_OPERATION – the IRP represents a file system create operation.
 -IRP_READ_OPERATION – the IRP represents a read operation.
 -IRP_WRITE_OPERATION – the IRP represents a write operation.
 -IRP_CLOSE_OPERATION – the IRP represents a close operation.
 -IRP_DEFER_IO_COMPLETION  –  the  IRP  should  be  process ed  asynchronously.     While asynchronous behavior is advised when this bit is se, it is not required.

　　小心的使用這些標(biāo)志設(shè)置IPR，因?yàn)檫@些標(biāo)志將對(duì)下層驅(qū)動(dòng)處理IRP請(qǐng)求產(chǎn)生一個(gè)根本的影響。
　　
　　如上所述，你的驅(qū)動(dòng)還應(yīng)該設(shè)置下一個(gè)I/O棧單元。它僅僅發(fā)生的處理第一個(gè)棧單元的時(shí)候。第一個(gè)棧單元的指針通過(guò)IoGetNextIrpStackLocation(...)得到。這個(gè)調(diào)用返回下一個(gè)將要調(diào)用的驅(qū)動(dòng)的棧單元你的驅(qū)動(dòng)要負(fù)責(zé)初始化這個(gè)棧單元的下面這個(gè)域：

 MajorFunction 
 the function code for the I/O to be performed

 MinorFunction 
 a minor function code for the I/O. This field should be zero if there is no minor  function code.

 Flags 
 any  flags  needed  to  modify  the  behavior  of  the  I/O  operation
 (c.f., ntddk.h for the SL_* flags.)

 DeviceObject 
 the device to which your driver will pass the IRP.

　　標(biāo)志域用來(lái)修改低層驅(qū)動(dòng)的行為當(dāng)處理I/O請(qǐng)求的時(shí)候?？赡艿臉?biāo)志如下面所示：表３未畫(huà)

　　最后，你的驅(qū)動(dòng)必須初始化I/O操作指定的參數(shù)。如Read Write請(qǐng)求，需要初始化偏移，長(zhǎng)度等。

Completion

　　有時(shí)候，當(dāng)你構(gòu)建自己的IRPs時(shí)你需要提供一個(gè)完成例程。完成例程的特定規(guī)則是不明確的。但是如果你錯(cuò)誤的使用它將導(dǎo)致系統(tǒng)崩潰。

　　提供完成例程最重要的原因是你可以重新使用I/O操作。在DDK文檔中提到的不太重要的原因是你要釋放它。這排除了I/O管理器需要執(zhí)行I/O完成例程，你通過(guò)在你的完成例程中返回STATUS_MORE_PROCESSING_REQUIRED告訴I/O管理器停止繼續(xù)向上返回。

　　什么時(shí)候你不需要使用一個(gè)完成例程？當(dāng)你不需要考慮I/O操作的完成狀態(tài)，或者你不能在你的完成例程中釋放IRP。后面的情況沒(méi)有在DDK文檔中指出但是非常重要。典型的，I/O管理器為一個(gè)線程創(chuàng)建一個(gè)I/O操作，這個(gè)IRP存儲(chǔ)在線程的鏈表中(ThreadListEntry域).當(dāng)線程退出的時(shí)候允許NT清除IRP如果你的驅(qū)動(dòng)有一個(gè)完成例程并返回STATUS_MORE_PROCESSING_REQUIRED，這個(gè)IRP可能仍然存放于線程的I/O列表中，這可能產(chǎn)生嚴(yán)重的問(wèn)題。已經(jīng)證明I/O管理器的某些函數(shù)將創(chuàng)建的IRP添加到線程鏈表中，而其它的函數(shù)不添加。那么，當(dāng)構(gòu)建你的完成例程時(shí)，這將是一個(gè)好機(jī)會(huì)檢查你的IRP不在線程列表中！

　　只要你的完成例程返回STATUS_MORE_PROCESSING_REQUIRED，I/O管理器將停下來(lái)等待更多的處理。那么，你就可以做你想做的任何事情，此時(shí)你在I/O操作開(kāi)始時(shí)的線程上下文中，文件句柄和用戶地址都是不必須的。第二點(diǎn)，你不用假設(shè)你的完成例程在PASSIVE_LEVEL被調(diào)用，它可能在DISPATCH_LEVEL級(jí)被調(diào)用，原因是你完成例程的驅(qū)動(dòng)可能是一個(gè)DPC例程。將這些記在腦子里，當(dāng)你設(shè)計(jì)你自己的完成例程時(shí)，如果你需要在IRP完成后有更多的處理你可能需要設(shè)置一個(gè)工作例程確保它安全。

Reuse

　　我們描述了你的驅(qū)動(dòng)如何在旁視列表中保持IRPs。當(dāng)你不在需要IRP時(shí)你的驅(qū)動(dòng)可以在完成例程中設(shè)置將它返回到你的旁視列表中。然而，你可能需要做些額外的工作在IRP準(zhǔn)備重用的時(shí)候。

　　例如，如果你調(diào)用文件系統(tǒng)驅(qū)動(dòng)并指定了一個(gè)用戶緩沖區(qū)(通過(guò)設(shè)置Irp->Userbuffer)，文件系統(tǒng)驅(qū)動(dòng)可以創(chuàng)建一個(gè)MDL描述這個(gè)緩沖區(qū)。如果是那樣，因?yàn)槟阍谪?fù)責(zé)清除IRP，所以你有責(zé)任unmapping,unlocking并且釋放與IRP關(guān)聯(lián)的MDL。可以通過(guò)MmGetSystemAddressForMdl(...)得到MDL的地址，通過(guò)MmUnmapLockedPages(...)解除映射并通過(guò)MmUnlockPages(...)解除鎖定頁(yè)。

Short-cuts
　　現(xiàn)在我們已經(jīng)描述了如何構(gòu)建自己的IRPs，我們將提到I/O管理器提供的三個(gè)短小的調(diào)用來(lái)使你容易的完成這些。這些I/O管理器提供的函數(shù)不如你自己構(gòu)建IPRs的通用性好，但它們能快速的構(gòu)建一個(gè)IPR并且你能在你的驅(qū)動(dòng)中完成初始化工作，這些例程是：
 - IoBuildAsynchronousFsdRequest(...)
 - IoBuildSynchronousFsdRequest(...)
 - IoBuildDeviceIoControlRequest(...)

這三個(gè)調(diào)用都沒(méi)有初始化FileObject參數(shù)，因此如果你調(diào)用文件系統(tǒng)驅(qū)動(dòng)，你的驅(qū)動(dòng)需要設(shè)置這個(gè)域。既然你知道如何在你的驅(qū)動(dòng)中構(gòu)建IRP，你能擴(kuò)充I/O管理器創(chuàng)建的IPRs來(lái)適用于你自己使用。

　　前面提到的，在I/O管理器的幫助函數(shù)中使用完成例程不是那么容易。在IoBuildSynchronousFsdRequset(..)和IoBuildDeyiceIoControlRequest(...)中你不能在你的完成例程中釋放IRPs，但是在IoBuildAsynchronousFsdRequest(...)中你可以這樣做。這是因?yàn)榍懊娴膬蓚€(gè)例程把IRP增加到線程的IRP鏈表中。因?yàn)镮/O管理器不會(huì)在線程中移除IRP，所以唯一的選擇是允許完成請(qǐng)求。

　　用上面三個(gè)函數(shù)中的任何一個(gè)都可以簡(jiǎn)單的創(chuàng)建一個(gè)IPPs，但是對(duì)于你的驅(qū)動(dòng)的請(qǐng)求所需要的幫助例程仍有限制。IoBuildDeviceIoControlRequest僅用來(lái)構(gòu)建IRP_MJ_DEVICE_CONTROL請(qǐng)求，IoBuildSynchronousFsdRequset(...)僅用來(lái)支持IRP_MJ_INTERNAL_DEVICE_CONTROL，IoBuildAsynchronousFsdRequest(...)僅對(duì)IRP_MJ_READ,IRP_MJ_WRITE,IRP_MJ_FLUSH_BUFFERS和IRP_MJ_SHUTDOWN有效。