Rolling Your Own

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

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

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

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

Allocation
　　可以用兩種方式分配IRPs。最簡單的方法是調(diào)用IoAllocateIrp(...)。I/O管理器將用適當?shù)腎/O棧單元(你在調(diào)用中指定的)分配一個IPR，這是最簡單的并且是大多數(shù)分配I/O請求的方法。警告注意：如何你調(diào)用IoAllocateIrp(...)不用調(diào)用IoInitializeIrp(...)。在這點上DDK文檔導致許多無辜的受害者誤入歧途。
　
　　你的驅(qū)動可能想要創(chuàng)建自己的IRPs。一個方法是用ExAllocatePool(...)在非分頁內(nèi)存中分配內(nèi)存。你通過IoInitializeIrp(...)初始化IRP的形式。你的驅(qū)動可以通過IoSizeOfIrp(...)計算出分配的IRP的大小。只要你在非分頁內(nèi)存中分配了一個IRP，你就能調(diào)用IoInitializeIrp設置IRP中的域。請看下面的例子：
 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ū)動依賴于I/O管理器分配和管理IRPs。然而這些實例使你的驅(qū)動能更有效的分配和管理自己的IRPs。

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

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

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

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

Building
　　只要你分配了自己的IRP，不管是使用IoAllocateIrp還是從自己的旁視列表中，你必須初始化I/O請求指示你需要低層驅(qū)動的什么服務。當你調(diào)用下層驅(qū)動執(zhí)行的時候你的驅(qū)動必須做同樣的工作。簡單的設置下層驅(qū)動的參數(shù)塊。你的驅(qū)動要做的額外工作是初始化自己分配的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

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

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

　　IRP有很多不同的標志，告訴下層驅(qū)動如何解釋這個I/O請求的內(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.

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

 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.

　　標志域用來修改低層驅(qū)動的行為當處理I/O請求的時候。可能的標志如下面所示：表３未畫

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

Completion

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

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

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

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

Reuse

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

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

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

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

　　前面提到的，在I/O管理器的幫助函數(shù)中使用完成例程不是那么容易。在IoBuildSynchronousFsdRequset(..)和IoBuildDeyiceIoControlRequest(...)中你不能在你的完成例程中釋放IRPs，但是在IoBuildAsynchronousFsdRequest(...)中你可以這樣做。這是因為前面的兩個例程把IRP增加到線程的IRP鏈表中。因為I/O管理器不會在線程中移除IRP，所以唯一的選擇是允許完成請求。

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