Rolling Your Own

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

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

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

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

Allocation
　　可以用兩種方式分配IRPs。最簡單的方法是調用IoAllocateIrp(...)。I/O管理器將用適當的I/O棧單元(你在調用中指定的)分配一個IPR，這是最簡單的并且是大多數分配I/O請求的方法。警告注意：如何你調用IoAllocateIrp(...)不用調用IoInitializeIrp(...)。在這點上DDK文檔導致許多無辜的受害者誤入歧途。
　
　　你的驅動可能想要創建自己的IRPs。一個方法是用ExAllocatePool(...)在非分頁內存中分配內存。你通過IoInitializeIrp(...)初始化IRP的形式。你的驅動可以通過IoSizeOfIrp(...)計算出分配的IRP的大小。只要你在非分頁內存中分配了一個IRP，你就能調用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;
 }

　　一般地，驅動依賴于I/O管理器分配和管理IRPs。然而這些實例使你的驅動能更有效的分配和管理自己的IRPs。

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

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

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

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

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

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

　　Tail.Overlay.Thread數據結構僅僅用在明確的設備中，如可移動設備，所以系統知道如何操作"錯誤的彈出"如當媒體設備沒有在驅動中加載的時候abort/retry/cancel對話框的出現。

　　IRP有很多不同的標志，告訴下層驅動如何解釋這個I/O請求的內容。

 -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，因為這些標志將對下層驅動處理IRP請求產生一個根本的影響。
　　
　　如上所述，你的驅動還應該設置下一個I/O棧單元。它僅僅發生的處理第一個棧單元的時候。第一個棧單元的指針通過IoGetNextIrpStackLocation(...)得到。這個調用返回下一個將要調用的驅動的棧單元你的驅動要負責初始化這個棧單元的下面這個域：

 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.

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

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

Completion

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

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

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

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

Reuse

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

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

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

這三個調用都沒有初始化FileObject參數，因此如果你調用文件系統驅動，你的驅動需要設置這個域。既然你知道如何在你的驅動中構建IRP，你能擴充I/O管理器創建的IPRs來適用于你自己使用。

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

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